Major New Features of FlexUnit 4

Test Metadata

Test cases are now marked with a piece of metadata named [Test]. Your tests no longer need any special name (prefixed with test, etc.) Also, the need for specific Test and Suite classes disappears. Your classes no longer need to inherit from any framework class. Here are a couple of sample tests.

[Test]
public function addition():void { 
   Assert.assertEquals(12, simpleMath.add(7, 5)); 
}

[Test] 
public function subtraction():void { 
   Assert.assertEquals(9, simpleMath.subtract(12, 3)); 
}

Because your test classes no longer inherit from a class in the FlexUnit framework, you will notice that the assert functions you used in the past (assertEquals, assertTrue) are now referenced as static functions of the Assert class; more on the new ways of asserting later in this post.

Before and After

Sometimes you need to setup your test environment (or fixture) for your tests. In the example above, you need to ensure your simpleMath reference exists before the tests are run. In previous versions of FlexUnit and Fluint you could override a setup() or teardown() method to accomplish this goal. FlexUnit 4 introduces Before and After metadata which accomplishes a similar goal. Any methods marked with Before will be run before each test method. Any methods marked with After will be run after each test method. This also means you can have multiple methods that run before or after the test.

[Before]
public function runBeforeEveryTest():void { 
   simpleMath = new SimpleMath(); 
} 

[Before]
public function alsoRunBeforeEveryTest():void { 
   simpleMath1 = new SimpleMath(); 
} 

[After] 
public function runAfterEveryTest():void { 
   simpleMath = null; 
   simpleMath1 = null; 
}

If you do choose to use multiple before or after, you can control the order that these methods execute using an order parameter. So, for example [Before(order=1)], [Before(order=2)].

BeforeClass and AfterClass

Methods marked with Before and After will run before and after each test method respectively. BeforeClass and AfterClass allow you to define static methods that will run once before and after the entire test class. Like Before and After, you can define multiple methods for BeforeClass and AfterClass and can control the order.

[BeforeClass]
public static function runBeforeClass():void { 
   // run for one time before all test cases 
} 

[AfterClass] 
public static function runAfterClass():void { 
   // run for one time after all test cases 
}

Exception Handling

Test metadata can also have an expects parameter. The expects parameter allows you to indicate that a given test is expected to throw an exception. If the test throws the named exception it is considered a success, if it does not, it is considered a failure. This prevents us from having to write tests wrapped in a try block with an empty catch.

[Test(expects="flash.errors.IOError")] 
public function doIOError():void { 
   //a test which causes an IOError }Or 
[Test(expects="TypeError")] 
public function divisionWithException():void { 
   simpleMath.divide( 11, 0 );
}

Ignore

Ignore metadata can be added before any test case you want to ignore. You can also add a string which indicates why you are ignoring the test. Unlike commenting out a test, these tests will still appear in the output reminding you to fix and/or complete these methods.

[Ignore("Not Ready to Run")] 
[Test] 
public function multiplication():void { 
   Assert.assertEquals(15, simpleMath.multiply(3, 5)); 
}

Async

In previous versions of FlexUnit it was difficult to have multiple asynchronous events and to test code that was event driven but not always asynchronous. Fluint provides enhanced asynchronous support including asynchronous setup and teardown, but every test carried the overhead of the asynchronous code to facilitate this feature. FlexUnit 4 allows the developer to specify which tests need asynchronous support using the async parameter. When provided, the async parameter enables the full asynchronous support provided by Fluint for that particular test. When the async parameter is specified you may also specify an optional timeout for the method.

[Before(async,timeout="250")] 
public function setMeUp():void { 
}

[After(async,timeout="250")] 
public function allDone():void { 
}

[Test(async,timeout="500")] 
public function doSomethingAsynchronous():void { 
   //Async.proceedOnEvent( testCase, target, eventName ); 
   //Async.failOnEvent( testCase, target, eventName ); 
   //Async.handleEvent( testCase, target, eventName, eventHandler ); 
   //Async.asyncHandler( testCase, eventHandler ); 
   //Async.asyncResponder( testCase, responder ); 
}

In addition to the async parameter, there are several new Async methods, each of which can also take individual timeouts, handlers and passThroughData.

Hamcrest

Earlier I alluded to new assertions. Thanks to the hamcrest-as3 project we now have the power of Hamcrest assertions. Hamcrest is based on the idea of matchers which match conditions for your assertions. For example:

[Test]
public function testGreaterThan():void { 
   assertThat( 11, greaterThan(3) );
}

[Test]
public function isItInHere():void { 
   var someArray:Array = [ 'a', 'b', 'c', 'd', 'e', 'f' ];
   assertThat( someArray, hasItems("b", "c") );
}

For more information on hamcrest:
*Hamcrest AS3
*Hamcrest
*Hamcrest Tutorial for Java
*Hamcrest Tutorial for PHP

Suites

FlexUnit 4 has a concept of test suites just like FlexUnit and Fluint. Test suites are just a collection of classes that represent tests or even other suites. A suite is defined by the [Suite] metadata. However, in FlexUnit 4, you also need to provide one additional piece of metadata called [RunWith] which instructs the test runner to execute the tests defined below using a specific class. The [RunWith] metadata forms the basis of the extensibility layer which will be discussed shortly.

[Suite]
[RunWith("org.flexunit.runners.Suite")]   
public class FlexUnitIn360 {
   public var t1:BasicMathTest;
   public var t2:MyTheory;
}

The test cases and any nested test suites, are simply defined as public variables. There is no need to instantiate them or mark them in any other way. FlexUnit's test suite code understands how to recursively parse this class and find the tests.

User Defined Metadata Parameters

It's often extremely useful to include additional pieces of information which are relevant to your development process when defining tests. So, for example, you might want to provide a detailed description of what a test is supposed to prove. This description could then be displayed if the test fails. Or perhaps you would like to note that a test relates to a give issue number in your bug tracking system. These custom parameters are stored by the framework when encountered during the test and can be used in reporting the success or failure later.

[Test(description="This one makes sure something works",issueID="12345")]
public function checkSomething():void {
}

Theories, Datapoints and Assumptions

This is probably the largest single new feature as it introduces a whole new way of testing. A developer can create theories, which are 'insights' into the way a given test should behave or over a large, potentially infinite set of values. In other words these are tests that take parameters. The parameters are defined in properties, arrays or can be retrieved from functions or other external sources. A complete description of this feature can and will take a lot of documentation, however, if you are up for reading a bit of theory, this document will introduce the ideas . Here is a quick sample of using these new techniques:

[DataPoints]
[ArrayElementType("String")]
public static var stringValues:Array = ["one","two","three","four","five"];

[DataPoint]
public static var values1:int = 2;
[DataPoint]
public static var values2:int = 4;

[DataPoints]
[ArrayElementType("int")]
public static function provideData():Array {
   return [-10, 0, 2, 4, 8, 16 ];
}

[Theory]
public function testDivideMultiply( value1:int, value2:int ):void {
   assumeThat( value2, greaterThan( 0 ) );
   
   var div:Number = simpleMath.divide( value1, value2 );
   var mul:Number = simpleMath.multiply( div, value2 );
   
   Assert.assertEquals( mul, value1 );
}      

[Theory]
public function testStringIntCombo( value:int, stringValue:String ):void {         
   //call some method and do something 
}

In this case, there are datapoints defined by static properties as well as method calls. The framework introspects the datapoints and uses this data combined along with any type specified in the ArrayElementType metadata. This information is used in combination with the theory method signatures to call each theory for each possible combination of parameters.

RunWith

FlexUnit 4 is nothing more than a set of runners combined to run a complete set of tests. A runner is a class that implements a specific interface and understands how to find, execute and report back information about any tests in a given class. Each time a new class is encountered, FlexUnit 4 works through a list of possible runners and attempts to identify the correct one to execute the tests contained in the class.

The RunWith metadata allows you to override the default choice made by the framework and specify a different class to act as the runner. This feature allows developers to write entirely new types of runners, with support for new features, which can work directly with the existing framework and report their results back through the same interface.
In the case of the suite, you are instructing the framework to run this class in a specialized runner that simply finds the correct runner for all of the classes it contains.

[RunWith("org.flexunit.runners.Suite")]

Adapters

Using the flexibility of the multiple runners discussed above, the new FlexUnit 4 framework has legacy runners built in for both FlexUnit 1 and Fluint tests. This means that FlexUnit 4 is completely backwards compatible; all existing FlexUnit and Fluint tests can be run, and even mixed into suites with FlexUnit 4 tests without any code changes.

Further, supplemental runners are in development for FUnit and several other testing projects

User Interface Facade

Lastly FlexUnit 4 provides a UIComponent testing facade which allows you to add or remove components from the display list. This allows you to accurately test component methods in a real runtime state. This feature creates a foundation for other projects to extend into areas of integration and functional testing without the need for extensive rewrites or modifications.

[Before(async,ui)]
public function setUp():void {
   //Create a textInput, add it to the testEnvironment. Wait until it is created, then run tests on it 
   textInput = new TextInput();
   Async.proceedOnEvent( this, textInput, FlexEvent.CREATION_COMPLETE, 200 );
   UIImpersonator.addChild( textInput );
}

Additional documentation on these and other features will become available as the project progresses.