FlexUnit4 async test - asyncHandler's usage isn't clear

There is the doc page about FlexUnit4's async approach: http://docs.flexunit.org/index.php?title=Writing_an_AsyncTest

Here is the concept that's confusing for me:

// timer is a Timer instance set to tick once with a delay of TIMER_TIME.

[Test(async)]
public function testAsync() : void {
      var asyncHandler:Function = Async.asyncHandler( this, handleTimerComplete, ASYNC_TIME, null, handleTimeout );
      timer.addEventListener(TimerEvent.TIMER_COMPLETE, asyncHandler, false, 0, true );
      timer.start();    
}

handleTimerComplete is called when the timer object is completed (after TIMER_TIME). It only happens when TIMER_TIME < ASYNC_TIME. handleTimeout called if asyncHandler i开发者_运维知识库s completed (after ASYNC_TIME). It happens if ASYNC_TIME < TIMER_TIME.

It's really doesn't make sense to me. I'd expect to call a test function periodically with a time limit, and as soon as the test succeed the periodical call should complete successfully. On the other hand I'm not sure where to put the actions (what I want to test) and where to put the tests (asserts).

Is there a more detailed documentation or an example that clarify the approach?

Thanks!

im just starting to use asyncHandlers and ive been going by the approach that if your handleTimerComplete function fires then in that function you could add your assert pass, in the timeout you assert fail.

for me its http events so in my "pass" handler i can also use assert to check for correct status code etc.

One thing i am trying to figure out is if you can re-use the same async handler, e.g. link it up as a listener for 3 or 4 different type of events, so far i think no, it seems that the second time its called you get an error that the handler function pointer is now null. need to do some more investigation though

An assertion basically does this:

function assertEquals( value:*, ...rest) : void {
    for each( var item:* in rest ) 
        if( item != value ) throw new Error("fail");
}

This (pseudo code) assertion checks whether the parameters that were passed in have the expected value, and throws an Error, if they don't. So there really is no restriction to where you can put assertions - they're just plain old methods that will throw an error, if some conditions aren't met.

The unit testing framework runs each test method within a try/catch block, and any unexpected Errors thrown by assertions cause the test to fail. That's how other tests can still keep running, and how you get your log messages and results, even if something went horribly wrong.

The problem is: If you have to make asynchronous assertions, i.e. check variable values at a later point in time, the test framework's behavior becomes much more complicated. Somehow, all method calls that occur between the end of the primary test method, and the actual end of the test, must also be monitored, the objects that were instantiated in setUp() must continue to exist, and all errors must still be caught - otherwise, the entire test runner would crash, and you'd get a whole lot of "null object reference" errors.

The framework, however, can't know when the current test is finished, unless there is some way to signal completeness - and for this reason, you must use at least one asyncHandler (or failOnEvent/proceedOnEvent, if you only need to verify if an event was dispatched/not dispatched at all) to handle an event that marks the end of the test, i.e. in your case, TimerEvent.TIMER_COMPLETE - or fail, if that event is never encountered. In either case, the next test can now be run.

I believe it is fine to use several asyncHandlers in the same test, but I'm not sure an asyncHandler will work correctly if called several times in a loop - that somehow contradicts the timeout functionality.

To keep things nicely readable, and to mark for yourself where you expect the test to end, I recommend using only one asyncHandler per test - and place all other assertions into "regular" event handler methods.

btw if you're interested in how the rest of FlexUnit works, you can find the full source code at GitHub.