Causes a test to keep running until it either passes, fails or times-out... |
Test("Basic syntax", Test.ASYNCH( [gameSeconds[, numResults]] ), function() { // Test will keep running until it times-out, passes or fails... }); |
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 |
Value | Type | Notes | API Version |
---|---|---|---|
<mode> | Object | The mode object is associated with the unit test defined in the same Test() invocation. | 1.0 |
<error> | Error | If you specify gameSeconds and/or numResults, and the specified value is invalid (eg. not a number or negative, etc) an error will be thrown and the test will not be run. | 1.0 |
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:
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.
The following conditions will cause the initiating test to fail immediately if triggered at any point during the session:
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.
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:
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:
After timing-out, the session will be terminated and no further units will append the session.
Let's say we want to monitor what happens to a droid when we tell it to move to our HQ:
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 } ); } } |