January 17, 2007

Continuous Integration with CruiseControl + FlexUnit + XDoclet2

Last year I blogged about XDoclet2 and FlexUnit and Ant . In this entry I am going to look at setting up CruiseControl for continuous integration. I have setup my CruiseControl server on Linux so I will do my best to make sure these instruction also apply to Windows. I also used Perforce as my source control repository so I have included the extra steps that are required to get CruiseControl working with Perforce. CruiseControl supports many other repositories such as Subversion and CVS. Please refer the the CuriseControl configuration reference for more details.

What software do I need?

You will need to download the following software:

• Download the CruiseControl binary distribution - I downloaded CruiseControl 2.6.
• Download a Java SE Development Kit (JDK) - I downloaded JDK 5.0 Update 10.
• Download FlexAntTasks.
• Download Flash Player 9 for Windows, Macintosh or Linux.
• Download Flex SDK.

If you are using Perforce you will also need the following:

• Download the Apache Ant binary distribution Don’t use the embedded copy of Ant that comes with CruiseControl as it doesn’t contain the Perforce tasks - I downloaded Apache Ant 1.7.0.
• Download the Jakarta ORO binary distribution. Jakarta ORO is required by the Perforce Ant tasks - I downloaded Jakarta ORO 2.0.8.
• Download the Perforce client (p4).

Do I need anything else?

Yes - if you are running this on Linux you will need an X Server installed and you will probably want a virtual frame buffer. These are required by the Flash Player - there is no headless version of the player. If you try and run the Flash Player without these you will probably get the following error:

Can't connect to X11 window server using ':0.0' as the value of the DISPLAY

The virtual frame buffer will allow the Flash Player to run in a virtual window without the need for a display plugged in to your server. I used XFree86, which provides an X Server and a virtual frame buffer (Xvfb).

How do I install the software?

• Extract CruiseControl to a suitable location on your local machine.
• Install your JDK.
• Create a JAVA_HOME environment variable with the path to your JDK installation.
• Add $JAVA_HOME/bin (or %JAVA_HOME%\bin on Windows) to your path.
• Copy FlexAntTasks.jar to <ANT_HOME>\lib, where <ANT_HOME> is the path to your Ant installation. If you are using the version of Ant that comes with CruiseControl you will find it under your CruiseControl instalaltion. The example config at the end of this blog shows how to configure an alternative Ant installation.
• Install Flash Player 9.
• Install Flex SDK.

Note: if you are using Linux the FlexUnit Ant task will use the standalone player, please make sure the Flash Player executable (gflashplayer) is on your PATH.

To verify CruiseControl is working start is using cruisecontrol.sh or cruisecontrol.bat (start CruiseControl from its home directory) and connect to the console through your browser using http://<your_server>:8080. You should see a test project called connectfour. Stop CruiseControl after you have connected sucessfully.

If you are using Perforce:

• Extract Apache Ant to a suitable location on your local machine.
• Extract Jakarta ORO and copy the JAR (e.g. jakarta-oro-2.0.8.jar) to <ANT_HOME>\lib, where <ANT_HOME> is the path to your Ant installation.
• Make sure the Perforce client executable (p4) is on your PATH.

You will also need to create a client workspace for Perforce, which is used by CruiseControl. You can do this using the P4V tool or on the command line using p4, for example you can do the following on Linux to create a client workspace:

• mkdir ~/cruisecontrol
• cd ~/cruisecontrol
• p4 -p <port> -c <client_workspace> -u <user> -P <password> client

The final command puts you in the editor, which you can just quit.

How do I run CruiseControl?

If you are running on Linux and using Xvfb execute the following commands:

• export DISPLAY=:1.0
• /usr/X11R6/bin/Xvfb :1 -screen 0 1280x1024x8 &
• cd <CC_HOME>, where <CC_HOME> is the parth to your CruiseControl installation.
• cruisecontrol.sh &

If you are on Windows:

• Open a command prompt.
• cd <CC_HOME>, where <CC_HOME> is the parth to your CruiseControl installation.
• cruisecontrol.bat

You can then connect to the console using your browser: http://<your_server>:8080

How do I configure a project?

You must configure your projects in <CC_HOME>\config.xml, where <CC_HOME> is the parth to your CruiseControl installation.

I have provided an example of config.xml , which externalises its configuration parameters to config.properties. This example uses my FlexUnitExample project.

Note: use the latest version of FlexUnit for Ant as it no longer requires you to create a FlashPlayerTrust configuration file.

Posted by at 7:34 PM | Comments (3)

FlexUnit for Ant Update#4

You can download a new release of FlexUnit for Ant. This version fixes a bug with the toDir property and also removes the need to create a configuration file under the FlashPlayerTrust folder to allow the SWF to run in the local trusted sandbox. The Ant task will now send a policy file to the Flash Player to allow the data to be sent over the socket - should make life a little easier.

For more details on how to use FlexUnit for Ant please see my earlier blog. There is also documentation on the flexunit Ant task parameters at the end of this blog. You can download FlexUnit from Adobe Labs.

 

Binary distribution

• FlexAntTasks-bin.zip
• FlexUnitOptional-bin.zip

 

Source Distribution

• FlexAntTasks-src.zip
• FlexUnitOptional-src.zip

 

Example Project

• FlexUnitExample.zip

 

Ant Task Parameters

Attribute	Description	Required
swf	The name of SWF containing the tests to execute.	Yes
port	The port to receive the test results on from FlexUnit. The default port is 1024.	No
timeout	The time in milliseconds to wait for results from FlexUnit before stopping the building process. The default is 60 seconds. You need to allow enought time for your tests to run as the socket is opended prior to the test execution.	No
toDir	The output directory for the test resutlts. The default is the working directory.	No
haltonfailure	Stop the build process if a test fails. The default is true.	No
failureproperty	The name of the property to set in the event of a failure. The default is 'flexunit.failed''.	No
verbose	Causes the flexunit tasks to print status messages. The default is false.	No

Posted by at 5:11 PM | Comments (3)

November 11, 2006

FlexUnit for Ant Update#3

You can download a new release of FlexUnit for Ant, which fixes a few bugs people have experienced recently. For more details on how to use FlexUnit for Ant please see my earlier blog. There is also documentation on the flexunit Ant task parameters at the end of this blog. You can download FlexUnit from Adobe Labs.

 

Binary distribution

• FlexAntTasks-bin.zip
• FlexUnitOptional-bin.zip

 

Source Distribution

• FlexAntTasks-src.zip
• FlexUnitOptional-src.zip

 

Example Project

• FlexUnitExample.zip

 

Ant Task Parameters

Attribute	Description	Required
swf	The name of SWF containing the tests to execute.	Yes
port	The port to receive the test results on from FlexUnit. The default port is 1024.	No
timeout	The time in milliseconds to wait for results from FlexUnit before stopping the building process. The default is 60 seconds. You need to allow enought time for your tests to run as the socket is opended prior to the test execution.	No
toDir	The output directory for the test resutlts. The default is the working directory.	No
haltonfailure	Stop the build process if a test fails. The default is true.	No
failureproperty	The name of the property to set in the event of a failure. The default is 'flexunit.failed''.	No
verbose	Causes the flexunit tasks to print status messages. The default is false.	No

Posted by at 10:04 PM | Comments (1)

June 28, 2006

New FlexUnit Ant Task

Many thanks to Tony Hillerson of EUI for his contribution following my last blog on FlexUnit + Ant. Tony has taken the FlexUnit task and added the following properties:

• haltonfailure - stop the build process if a failure occurs in one of the tests..
• failureproperty - the name of a property to set if there is a failure in one of the tests..
• verbose - print information about the test run.

The following example shows how to use these properties:

<target name="test-flex">
   <flexunit 
      swf="bin/AntTestRunner.swf"
      toDir="${flex-reports}"
      haltonfailure="false"
      verbose="true"
      failureproperty="flexunit.failed"	/>
		
   <junitreport todir="${flex-reports}">
      <fileset dir="${flex-reports}">
         <include name="TEST-*.xml"/>
      </fileset>
			
      <report format="frames" todir="${reports}/flex"/>
			
   </junitreport>
		
   <fail 
      message="One or more flexunit tests failed. See test reports for details." 
      if="flexunit.failed" />
</target>

Resources

• Download the source for the flexunit Ant task.
• Download the flexunit JAR.

Posted by at 1:32 PM | Comments (4)

June 1, 2006

FlexUnit + Ant

I have been planning this blog for some time, but was spurred on by a recent blog on Continous Integration in Flex. This blog concentrates on integration between Ant and FlexUnit, I will post a follow-up entry with details on how to setup a CruiseControl server for Continuous Integration.

This blog entry was written against Flex 2.0 Beta 3.

I have seen various postings about integration between FlexUnit with Ant, however most solutions seem to require a Flex server. My motivation here was to create an Ant task that has no dependency on a server. That would allow unit tests to be run in autonomously.

Very early on I decided if I was running the tests from Ant I wanted to re-use the JUnit tasks that already ship with Ant. In particular I wanted to use the JUnitReport task, which merges the XML files generated by the JUnit task to produce an HTML report. Therefore I wanted FlexUnit to print the results in the same XML format as the XML formatter used by the JUnit task.

The question was then how to make the XML test results available to the Ant tasks, my answer was to use XML sockets.

Technical Design

My solution is comprised of a controlling Ant task, flexunit, and a FlexUnit test runner, JUnitTestRunner, which is shown in the diagram below. The flexunit task starts a socket server running inside of a thread and launches the Flash Player, which runs the tests using the JUnitTestRunner. When JUnitTestRunner has finished running the test it formats the results as per the JUnit XML format and sends them to the flexunit task over an XML Socket, the flexunit task then saves them to disk. We can then use the JUnitReport task to create a report or use CruiseControl to create a report.

Requirements

• Download the Ant distribution.
• Download the example project (FlexUnitExample).

Software Installation

• Extract the Ant distribution.
• Add <your_ant_directory>\bin to your path.
• Extract the FlexUnitExample project to your Eclipse/FB workspace (you only need to extract it into your workspace if you want to load the project into Eclipse/FB - select File > Import and follow the Existing Projects into Workspace wizard).
• Edit <your_FlexUnitExample_directory>\build.properties and change the value of the flex.sdk.home property to the location of your Flex2 SDK installation (remember to use forward slashes).
• The SWF containing your tests must run in the local trusted sandbox, copy FlexUnitExample.cfg from <your_FlexUnitExample_directory> to C:\Documents and Settings\<your_username>\Application Data\Macromedia\Flash Player\#Security\FlashPlayerTrust.
• Edit FlexUnitExample.cfg so it has the path to <your_FlexUnitExample_directory>\bin.

Example

To run the build script open a command prompt and change directory to <your_FlexUnitExample_directory>. To run the build script execute the following command: ant.

This will execute the Ant build script, which will run the SWF containing the tests and generate a JUnitReport report. The reports directory under <your_FlexUnitExample_directory> will contain the XML files created by JUnitTestRunner, you can view the report by opening <your_FlexUnitExample_directory>\reports\html\index.html. You should see two tests, one that passed and the other that failed.

Resources

You can download the source code for flexunit and JUnitTestRunner below, they are provided as an Eclipse Java Project and an Eclipse Flex Library project respectively.

• Download the source for the flexunit Ant task (FlexAntTasks).
• Download the source for the JUnitTestRunner (FlexUnitOptional).

You can import these projects into your workspace – extract the files into your workspace and in Eclipse select File > Import and follow the Existing Projects into Workspace wizard.

Posted by at 2:57 PM | Comments (27)