FlexUnit 4 in 360 seconds

About a year back I remember reading a blog post called JUnit in 60 seconds. At the time I pondered how great it would be to have these features in Flex. Little did I know that today I would be writing this post introducing the Flex world to FlexUnit 4.

So, first a little background. FlexUnit 4 is the name for an upcoming release of FlexUnit. It represents the best features of the FlexUnit project combined with the best features of the Fluint project. It is built on top of a newly created foundation designed to support the latest techniques used in the JUnit testing community, but written for the specific requirements and needs of the Flash Player. Top all that off with an extensibility layer that encourages developers to create new types of test runners and extensions while simplify the process of integrating the results into IDEs and continuous integration environments, and it should give you an idea why I am excited about this release.

If it sounds interesting to you as well, the public alpha of this upcoming release is now available as a turnkey test project you can download from the adobe open source site. I hope you will use it to learn and explore the new features, and to provide feedback about any bugs you find along the way. However, it is an alpha, so locations and names of classes, signatures of methods and even which features are supported are all subject to change before release. It is not be advisable to use this as your production testing system.

Speaking of features, let's jump in. There is a bit more content to go through than the original 60 second tutorial, so, I think you will need 4-6 minutes to get through it all. To keep things consistent, many of these examples are adapted right from the JUnit in 60 seconds site referenced above.

1. 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.
   
   
2. 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)].
   
   
3. 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
   }
   
   
4. 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 );
   }
   
   
5. 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));
   }
   
   
6. 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.
   
   
7. 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
   
   
   
8. 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.
   
   
9. 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 {
   }
   
   
10. 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.
    
    
11. 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")]
    
    
    
12. 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
    
    
13. 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 );
    }

If you made it this far, I hope you download the alpha and start playing with it immediately. If you have significant time to devote to serious testing and debugging of the framework, contact me and I will be happy to invite you to the ongoing private beta program.

Stay tuned for some exciting news and, if you have the opportunity, be sure to make it 360|Flex for my session about the new framework. Plus, you never know, 360 is an exciting place, we may just have more to tell you by that time.

Cheers and enjoy,
Labriola