New Event Testing Framework in FlexUnit
Part of the new FlexUnit release is a new TestCase subclass called EventfulTestCase. It provides convenience methods for testing objects that emit events. This new class can streamline your testing code and help catch unexpected events. Below is some sample code that demonstrates this new framework.
To use the new event testing framework subclass EventfulTestCase instead of TestCase.
package com.neophi.test { import flexunit.framework.EventfulTestCase; public class EventTest extends EventfulTestCase { // Test code here } }
In a particular test method once you have the object that you want to test for assertions against, you call a new helper function called listenForEvent(). It takes three arguments:
- source: the object that is to be listened on for the dispatched event
- type: the type of event that the source object might dispatch
- expected: whether the event is expected to be dispatched or now; defaults to EVENT_EXPECTED, the other choice is EVENT_UNEXPECTED (both defined in EventfulTestCase)
After your code has exercised the source to emit events, you make a call to assertEvents() with an optional message to make sure the events happened as planned. A quick example of a positive test for an event would look like this:
public function testEventExpectedPass():void { var eventEmittingObject:EventDispatcher = new EventDispatcher(); listenForEvent(eventEmittingObject, Event.COMPLETE, EVENT_EXPECTED); eventEmittingObject.dispatchEvent(new Event(Event.COMPLETE)); assertEvents("Expecting complete event"); }
After the event source is setup, we notify the testing framework what event we are expecting, emit the event, and then assert that is happened. In a more typical example the dispatchEvent() call would be part of the code under test. Also you aren't limited to listening for just a single event at a time. This example is just demonstrating the test framework API. When setting up an expected event via listenForEvent() the third argument defaults to EVENT_EXPECTED.
If an expected event doesn't get dispatched, the test harness will report an error as this next test demonstrates.
public function testEventExpectedFail():void { var eventEmittingObject:EventDispatcher = new EventDispatcher(); listenForEvent(eventEmittingObject, Event.COMPLETE, EVENT_EXPECTED); assertEvents("Expecting complete event"); }
Testing for unexpected events works the same way but the fail and pass conditions are reversed.
public function testEventUnexpectedPass():void { var eventEmittingObject:EventDispatcher = new EventDispatcher(); listenForEvent(eventEmittingObject, Event.COMPLETE, EVENT_UNEXPECTED); assertEvents("Not expecting complete event"); }
In this case the COMPLETE event is unexpected so by not firing the event the assertion passes, which is what we want. Just to flesh out the example, if an event is unexpected but does fire the assertEvents() call will fail as in this example:
public function testEventUnexpectedFail():void { var eventEmittingObject:EventDispatcher = new EventDispatcher(); listenForEvent(eventEmittingObject, Event.COMPLETE, EVENT_UNEXPECTED); eventEmittingObject.dispatchEvent(new Event(Event.COMPLETE)); assertEvents("Not expecting complete event"); }
In this case because an unexpected event fired it is an error.
Besides listenForEvent() and assertEvents(), two properties are exposed for examining the events that are listened for: lastDispatchedExpectedEvent holds the last event captured by listenForEvent() and dispatchedExpectedEvents holds all of the events captured. This last example shows the ability to listen for multiple events in different states, how events not registered with the listener are ignore, and uses these two convenience properties.
public function testMultipleEventsPass():void { var eventEmittingObject:EventDispatcher = new EventDispatcher(); listenForEvent(eventEmittingObject, Event.INIT, EVENT_EXPECTED); listenForEvent(eventEmittingObject, Event.COMPLETE, EVENT_EXPECTED); listenForEvent(eventEmittingObject, ErrorEvent.ERROR, EVENT_UNEXPECTED); eventEmittingObject.dispatchEvent(new Event(Event.INIT)); eventEmittingObject.dispatchEvent(new Event(Event.CHANGE)); eventEmittingObject.dispatchEvent(new Event(Event.COMPLETE)); assertEvents("Multiple events"); assertEquals(Event.COMPLETE, lastDispatchedExpectedEvent.type); assertEquals(2, dispatchedExpectedEvents.length); }
Some closing notes:
- The order that the events are added by listenForEvent() doesn't matter. The asserts just check that events were or were not fired.
- The event assertion framework will work with asynchronous events. You'll just want to wait to call assertEvents() in the final handler for your test.
- The number of times that an event is dispatched doesn't matter.
- assertEvents() can be called multiple times.
