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=2)|Before(order=2)]
public function runBeforeEveryTest():void {
        // I run Second before every test
    }
 [Before(order=1)|Before(order=1)]
public function alsoRunBeforeEveryTest():void {
        // I run First before every test
    }
 [After(order=1)|After(order=1)]
public function runAfterEveryTest():void {
        // I run First after every test
    }

 [After(order=2)|After(order=2)]
public function runAfterEveryTestAlso():void {
        // I run second after every test
    }

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")|Test(expects="flash.errors.IOError")]
public function doIOError():void {
        //a test which causes an IOError
    }

 [Test(expects="TypeError")|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")|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 provided 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")|Before(async,timeout="250")]
public function setMeUp():void {
}

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

 [Test(async,timeout="500")|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.

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 given 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")|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 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")|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")|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")|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.