This is a very technical post, so if you are not interested in Actionscript or Unit Testing, you can stop reading.
Some context
A few weeks ago I gave a talk to the Flash Coders NY group about Unit Testing. The talk was mainly oriented towards the benefits of unit testing, but since I’ve taken the time to set up an automatic test runner for the talk, I also took the time to clean it up, make it work for Actionscript2 and make it as easy to use out of the box as possible.
Hopefully this will lower the frustrations of all those that want to start looking into Actionscript Unit Testing but get turned off by all the broken links, complicated tutorials and puzzles that you need to put together to get it working.
So what is this?
Hopefully, an out of the box automatic test runner for both Actionscript3 and Actionscript2 (I couldn’t find any other for As2). Included are also some small unit tests so you can start playing with it fast (out of the box, right?).
By automatic I understand a test runner that compiles, runs and closes without the need of a user, but only through a script, and prints all it’s output to stdout. All of these are necessary conditions for setting up a continuous build, something that is very desirable (since we are all very lazy).
If you are really lazy
If you are too lazy (or too good ð ) to read all this, just download as_test_runner.zip and try it out. If it doesn’t work, come back and read on. I suspect you’ll come back. ð
System requirements
I’ve worked on this on my MacOS X, I also tested on Linux. It should work on Windows too (but I admit I have not tested yet, I should do it these days).
On your machine, you also need:
a standalone Flash Player 9 in your command path (I’ve put mine under /usr/local/bin on linux). You can download it from here. on MacOSX you have to make sure that the standalone Flash Player is the default app for opening swf files. If from a terminal you type “open SomeExampleSwf.swf” and the flash player opens with that file, it’s great. If not, make that happen. you need javac, ant, mtasc (if you want As2) and the flex sdk (if you want As3). If you are thinking of Unit Testing, you should be able to install those yourself. ð
Steps to run your first unit tests
1. Make sure the system prerequisits are met 1.1. If you plan on running the As2 Unit Tests you need to do an extra step, you need to add your path to the FlashPlayerTrust directory.
On MacOS: Create a directory /Library/Application Support/Macromedia/FlashPlayerTrust
On Linux: Create a directory /etc/adobe/FlashPlayerTrust (or ~/.macromedia/Flash_Player/#Security/FlashPlayerTrust)
On Windows: C:\windows\system32\Macromedia\Flash\FlashPlayerTrust
In that directory, create a “trust.cfg” file and add a path to your favorite directory in that file. This will tell the flash player to trust the swf files in that directory.2. Download as_test_runner.zip and extract it in your favorite directory. 3. Edit build.properties such that the mtasc and flex.sdk paths match your configuration. 4. From the directory where you extracted the archive, in a terminal, type “ant”.
You should be all done. If it doesn’t work, let me know (I swear, it works for me ð ).
[update] You should also take a look at the video here, a project that became ProjectSprouts (don’t let the name turn you off). Worth checking out.[/update]
This should work on Linux, MacOS and Windows. I only tested on MacOS (where I cleaned everything up) and Linux. If you have trouble with the security sandbox (the swf opens, but it throws an error) read more about FlashPlayerTrust. If ‘ant’ has trouble launching the flash player, there is some issue with your standalone flash player and path. If you have trouble compiling your swf’s, there are issues with MTASC and the Flex compiler. Check that they are set up correctly and that you can manually compile stuff with them.
Some final thoughts
This is put together starting from the work done here by a guy named Peter Martin. As all the other tutorials they are made from many pieces and you have to tune everything for it to work, so I wanted a super easy out of the box solution. Credits do go to Peter Martin, I just cleaned his work, made it output to stdout and made it work with As2.
A good resource for related work done by various people is here.
In order to make AsUnit (actionscript2) work, I had to make some very very slight changes to AsUnit (to allow a listener deeper investigation of
the framework). This means you can’t just replace AsUnit code with newer code, it will stop working. The good news is, I got it working for As2 (which nobody else did as far as I can tell, they are all blinded by flexunit ð ).
FlexUnit is out of the box (no changes there).
I’ve left the Eclipse/Flex files in the directory, so ideally you could import this as a project into Eclipse and simply run it with Ant, so that you could make development and testing a breeze.
The runner produces some XML output too, for some software called Cruise Control (I never used it). I had to change the java socket listener to display text output (this was a substantial part of the work, along with the as2 port).
Hey Vivi,
This is a really helpful post.
I would like to mention a couple of things.
While ant is really a dramatic improvement over make, the Rubyists have come out with a build tool that improves on ant called ‘rake’. You can read more about it here:
http://martinfowler.com/articles/rake.html
Some quick highlights:
a) Startup time: The Ruby VM starts up very, very quickly – as opposed to the JVM
b) Flexible: Since it’s really just Ruby code, you can do in Rake whatever you can do in Ruby
c) Extensible: When you do find you need something more complex, you don’t have to fire up a heavy-weight Java IDE, you can just start editing Ruby code in a text editor.
In an effort to avoid even the minimal configuration, and encourage Test-Driven Development and Continuous Integration for ActionScript 2, ActionScript 3 and MXML projects, I have been working on a new open-source effort found here:
http://code.google.com/p/projectsprouts/
And an older version is shown here:
http://www.asserttrue.com/articles/2007/04/04/introducing-asproject
Hope that helps!
Luke Bayes
http://www.asserttrue.com
Hi Luke, thanks for dropping by.
I chose Ant only because it was used by Peter Martin. I am usually using a tool internal to my company, so this was my first use of Ant anyways. ð
I did not know about your project, thanks for the link. Before I go out and test it, does it output the tests to stdout? That was one of the main things I needed when I did the above work.
[update] I watched the video for AsProject, it’s pretty cool indeed and it automates most of the ‘prerequisits’ in my blog post and that’s pretty cool. At the time of the creation of that video your runner did not output stuff to the console, but it’s still pretty impressive, nice work.
N-am folosit, nu cunosc dar pentru AS 2 mai sunt :
http://osflash.org/as2lib
http://osflash.org/astuce
http://osflash.org/asunit
http://osflash.org/flexunit
Hey Vivi,
Thanks for the kind words and mentioning Project Sprouts. AsUnit when combined with rake does have the ability to output test results to the shell that initiated it. This is done by simply passing a third, optional argument to the ‘start’ method in your TestRunner. In our environment, this method signature looks like the following:
start(AllTests, null, TestRunner.SHOW_TRACE);
If you pull the as3 branch out of source control, there is even an XMLTestRunner that outputs the same XML that JUnit spits out so that it can be more tightly integrated with continuous integration tools like Cruise Control. In our current project, we are writing that output to the artifacts directory with Ruby, but it is even easier to just send it to stdout.
Gorilla Logic has just open sourced a record/playback tool for Flex that generates FlexUnit tests.
Check it out at http://flexmonkey.googlecode.com.