How to use FlexUnit with FlexBuilder 2

First things first, you'll want to download FlexUnit. Because I'll be demonstrating using the flexunit.swc file, you'll want to grab the .zip archive containing the docs, source, and swc. Download and extract the flexunit.zip file to your harddrive. I'm using C:\Development\Flex as the extract location, which creates a directory C:\Development\Flex\flexunit containing the files.

After FlexUnit is downloaded / extracted, you'll need to create a Flex project to compile the test runner. FlexUnit comes with beautiful test runner GUI, but because the test runner is written with MXML it needs to be run through a Flex project. If you're attempting to test an ActionScript 3-only project, you'll want to create a Flex project alongside of it to run the tests.

Open up FlexBuilder 2.0 Beta and create a new Flex project by selecting File -> New -> Flex Project.

• Select "No" when asked about Flex Enterprise Services and press the "Next" button.
• Give the project a name, I'm using "ExampleTestRunner" and creating the project in "C:\Development\Flex\ExampleTestRunner" with "ExampleTestRunner.mxml" as the main application file. Click the "Next" button.
• Select the "Libraries" tab and press the "Add SWC" button.
• Browse for the "flexunit.swc" file that was extracted from the original flexunit.zip. The location for me is "C:\Development\Flex\flexunit\bin\flexunit.swc". Press "OK".
• Click the "Finish" button.

Adding the .swc to the build path of the project allows you to use the FlexUnit code. If you're not creating a project from scratch, you can add the flexunit.swc to the build path by right-clicking on the project name and selecting "Properties." Select "Flex Build Path", click the "Libraries" tab, and follow the rest of the steps outlined above.

Now that the project is set up correctly to reference the FlexUnit code, the first thing you'll want to do is create the code for the test runner. For this example, I'm going to focus on creating a TemperatureConverter class to convert from celsuis to fahrenheit and vice versa. The code for the test runner looks like this:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.macromedia.com/2005/mxml" xmlns="*"
				xmlns:flexunit="flexunit.flexui.*"
				creationComplete="onCreationComplete()">
	
	<mx:Script>
		<![CDATA[
			import flexunit.framework.TestSuite;
			
			// After everything is built, configure the test
			// runner to use the appropriate test suite and
			// kick off the unit tests
			private function onCreationComplete()
			{
				testRunner.test = createSuite();
				testRunner.startTest();
			}
			
			// Creates the test suite to run
			private function createSuite():TestSuite {
				var ts:TestSuite = new TestSuite();
				
				// TODO: Add more tests here to test more classes
				// by calling addTest as often as necessary
				ts.addTest( TemperatureConverterTest.suite() );
				
				return ts;
			}
			
		]]>
	</mx:Script>

	<!-- flexunit provides a very handy default test runner GUI -->
	<flexunit:TestRunnerBase id="testRunner" width="100%" height="100%" />
</mx:Application>>

There are some important things to note in the above code block. First, note the "flexunit" namespace declared in the <mx:Application> tag. This allows you to easily create the test runner. Also, once the application has been created, the "testRunner" has the test property set before starting the tests. Finally, the createSuite() method creates a test suite, and adds all of the tests to it.

You'll notice that the test suite we're using is going to be called "TemperatureConverterTest". Since the test runner is set up at this point, the next step is to create the test suite. Create a new ActionScript file named "TemperatureConverterTest.as" and use the following code:

package {

	import flexunit.framework.TestCase;
	import flexunit.framework.TestSuite;
	
	public class TemperatureConverterTest extends TestCase {
		
	    public function TemperatureConverterTest( methodName:String ) {
			super( methodName );
        }
	
		public static function suite():TestSuite {
			var ts:TestSuite = new TestSuite();
			
			ts.addTest( new TemperatureConverterTest( "testToFahrenheit" ) );
			ts.addTest( new TemperatureConverterTest( "testToCelsius" ) );
			return ts;
		}
		
		/**
		 * Ensures the celsius to fahrenheit conversion works as expected.
		 */
		public function testToFahrenheit():void {
			// Test boiling point
			var celsius:Number = 100;
			var fahrenheit:Number = TemperatureConverter.toFahrenheit( celsius );
			assertTrue( "Expecting 212 fahrenheit", fahrenheit == 212 );
			
			// Test freezing point
			var celsius:Number = 0;
			var fahrenheit:Number = TemperatureConverter.toFahrenheit( celsius );
			assertTrue( "Expecting 32 fahrenheit", fahrenheit == 32 );
		}
		
		/**
		 * Ensures the fahrenheit to celsius conversion works as expected.
		 */
		public function testToCelsius():void {
			// Test boiling point
			var fahrenheit:Number = 212;
			var celsius:Number = TemperatureConverter.toCelsius( fahrenheit );
			assertTrue( "Expecting 100 celsius", celsius == 100 );
			
			// Test freezing point
			fahrenheit = 32;
			celsius = TemperatureConverter.toCelsius( fahrenheit );
			assertTrue( "Expecting 0 celsius", celsius == 0 );
		}
		
	}
}

Notice the use of assertTrue() - this is the key to assuring the values are as expected. There is a conditional passed as the second parameter. You're asserting that the conditional should result in the value of true with the assertTrue() method. If the value doesn't result in true, the assertion is going to fail, and the test runner will let you know about it.

Along with assertTrue(), you can also use assertFalse(), assertNull(), etc. The full list is available in the assert documentation

Since the tests are now written, the next step is to create the TemperatureConverter class so the project will compile. The first thing to do is create stub methods that return generic values just so you can get the project to compile. The stubbed TemperatureConverter class looks like this (place this code in TemperatureConverter.as):

package {
	
	public class TemperatureConverter {
		
		public static function toFahrenheit( celsius:Number ):Number {
			return 0;
		}
		
		public static function toCelsius( fahrenheit:Number ):Number {
			return 0;
		}
	}
}

Believe it or not, these failures are a good thing. You know there are problems with your code and the test runner tells you precisely what tests failed. Now that the project compiles, it's time to go back and finish writing the TemperatureConverter, replacing the stub methods with real calculations:

package {
	
	public class TemperatureConverter {
		
		public static function toFahrenheit( celsius:Number ):Number {
			return ( 9 / 5 ) * celsius + 32;
		}
		
		public static function toCelsius( fahrenheit:Number ):Number {
			return ( 5 / 9 ) * ( fahrenheit - 32 );
		}
	}
}

After modifying the TemperatureConverter class and running the tests again, you can see that the tests pass this time:

You can be reasonably sure that your code does in fact do what you want it to now because the tests created for it all pass without error. The next step would be creating even more tests, trying to test anything and everything. Before adding new classes to the project, you'll want to create the tests for the classes first. It's ok for the tests to fail initially because it gives you targetted goals to work towards during development.

This entry demonstrated how to get started with test driven design using ActionScript 3 and Flex 2. Hopefully you'll take this information and start applying it towards your own development practices. Good luck!