Test.ASYNCH( )

Syntax

Test("Basic syntax", Test.ASYNCH( [gameSeconds[, numResults]] ), function() {
	// Test will keep running until it times-out, passes or fails...
});

Parameters

Parameter	Type	Mandatory	Notes	API Version
gameSeconds	Number		The number of game seconds before the test will time out. Game seconds are affected by game speed - so if you slow down the game, the test will run for longer to compensate. Default: 60	1.0
numResults	Number		A non-negative integer stating how many results the test must produce. If specified, and the test does not provide the specified number of results, the test will fail regardless of any other criteria. Default: Wait until test times-out, fails or a Test Signal is sent.	1.0

Return values

Effect on test

A Test.ASYNCH( ) Unit Tests initiates an "asynchronous testing session".

While the session is active, applicable unit tests using mode Test.APPEND( ) can provide additional results to the unit test that initiated the session.

Note that Test.APPEND( ) unit tests are treated as extensions to the initiating Test.ASYNCH( ) unit test:

• Only the initiating Test.ASYNCH( ) unit test will have a pass/fail state
• Test.APPEND( ) unit tests merely contribute towards the Test.ASYNCH( ) unit test's pass/fail state

The session remains active until a definite pass/fail state is determined, or until it times-out, whichever is sooner.

All other Test.ANY( ), Test.EXPECT( ) and Test.ASYNCH( ) tests will be queued until the current session has ended.

Immediate fail conditions

The following conditions will cause the initiating test to fail immediately if triggered at any point during the session:

• An uncaught exception is thrown
• An ABORT( ) or REQUIRE( ) signal is thrown

As soon as one of these happen, the session will be terminated – it will not time-out and no further units will append the session.

End-of-unit pass/fail conditions

If no immediate fail conditions have occurred, the initiating test state will be reviewed at the end of each unit test processed during the session as defined below:

1. If one or more Test Assertions have failed, the initiating test will be marked as failed
2. If the initiating test is not marked as failed:
   1. If numResults was specified, and more than that number of results have been logged, the initiating test will be marked as failed
   2. If numResults was specified, and that exact number of results have been logged, the initiating test will be marked as passed
3. If the test is marked as passed or failed, the session will be terminated – it will not time-out and no further unit tests will append the session
4. Otherwise the session will remain active, waiting for more results to be appended or a time-out

Time-out pass/fail conditions

If the state of the initiating test remains undetermined, it will eventually time-out (see gameSeconds in the Parameters section for more info).

The session will not time-out while a unit test is being processed, unless forced to do so by using the FINISH( ) signal.

When a session times-out, the initiating test state will be determined as follows:

• If the numResults parameter was specified when the initiating test was defined, the test will be marked as passed if that exact number of results has been logged, otherwise it will be marked as failed.
• If numResults wasn't defined, the test will be marked as passed.

After timing-out, the session will be terminated and no further units will append the session.

Examples

Let's say we want to monitor what happens to a droid when we tell it to move to our HQ:

• Record any attacks
• Fail the test if it gets destroyed
• Pass the test if it arrives at the HQ within 30 seconds

Our code would look something like this:

// Get a droid (assumes we have one) and the HQ (assumes we have one)
// and store in an object for easy reference elsewhere
var mission = {
	droid: enumDroids(me)[0],
	dest: enumStruct(me, HQ)[0]
};
 
// Start a 30 game sec asynch session, expecting 1 result...
Test(
	"Droid test", // name of test session
	Test.ASYNCH( 30, 1 ), // 30 secs timeout, 1 result expected
	function(mission) { // initiating unit test
		// Let's assume the droid can get to our HQ...
		orderDroid(
			mission.droid, // let's hope it's still alive lol
			DORDER_MOVE,
			mission.dest.x,
			mission.dest.y
		);
		// If that throws an error, test will fail = ending asynch session
	},
	mission // settings to pass in as first param of unit test
);
 
// Now the test is defined, but not yet run - remember tests are queued,
// so we better add some append tests to the events...
 
// When droid reaches HQ, it will become idle
function eventDroidIdle(droid) {
	if (droid.id == mission.droid.id) {
		Test(
			"WIN!", // doesn't really matter what we call it
			Test.APPEND("Droid test"), // case sensitive!
			function() {
				// This one result makes end-of-unit condition
				// checks pass the initiating test and
				// terminate the session. Any subsequent
				// Test.APPEND() invocations will be ignored
				ok( true, "The droid got to our HQ!" );
			}
		);
	}
}
 
// We need to log attacks...
function eventAttacked(victim, attacker) {
	if (victim.type == DROID && victim.id == mission.droid.id) {
		Test(
			"Attacked!",
			Test.APPEND("Droid test"),
			function(attacker) {
				// Comments don't count towards numResults
				comment( "Attacked by a "+attacker.name );
			},
			attacker // settings to pass in to test
		);
	}
}
 
// And what if we get killed?
function eventDestroyed(victim) {
	if (victim.type == DROID && victim.id == mission.droid.id) {
		Test(
			"EPIC FAIL!",
			Test.APPEND("Droid test"),
			function() {
				ABORT( "Mission failed!" ); // abort signal = immediate fail
			}
		);
	}
}