The following instructions are to setup an Ant build using the template project described below. Please note, the build
- Download Apache Ant 1.7.1 or higher from http://ant.apache.org/bindownload.cgi.
- Extract the compressed file (e.g. - zip, tarball, etc) to a location on your computer, preferably without spaces in the path.
- Append the
<install dir>/bindirectory on your computer's
- Create an environment variable named ANT_OPTS with the following values to increase the JVM's heap boundaries and perm gen space to be more friendly to Flex/Flash builds:
-XX:MaxPermSize=128M -Xms128M -Xmx512M
Setup your environment
- Download the Flex SDK @ http://opensource.adobe.com/wiki/display/flexsdk/Download+Flex+3 and extract it to a folder on your computer.
- If you are using Linux and wish to use the ADL support to execute your test suite(s), download the AIR SDK for Linux @ http://www.adobe.com/cfusion/entitlement/index.cfm?e=airsdk and extract the bundle on top of Flex SDK so the FlexUnit Ant task may use it correctly.
- Create an environment variable named
FLEX_HOMEwith the value of the absolute path to the directory in which the Flex SDK was extracted.
- Download the stand alone debugger Flash Player for your platform @ http://www.adobe.com/support/flashplayer/downloads.html and install the player. If running on Linux, be sure to create a symlink to the executable with the name
gflashplayerwhich is in a directory available on
- If not running on Linux, associate the mime-type for SWF files with the stand-alone debugger Flash Player. If done correctly, opening a SWF file directly (e.g. - double-clicking the file) should cause it to open in the stand-alone player.
Use the FlexUnit4SampleCIProject as a template
- Download the latest FlexUnit4 source code bundle @ http://github.com/flexunit/flexunit/zipball/master.
- Extract the FlexUnit4SampleCIProject from the bundle into a location you'd like to use for your project.
- Delete all folders and files under the
<project dir>/src/test/flexlocations as well as the
pom.xmlfile since this is a Maven build file.
- Place any source code under
<project dir>/src/main/flexand your test code under
<project dir>/src/test/flex. Please note, you don't have to use these folder locations, the included build scripts are just setup to work without edits with these paths.
- Sample build scripts are provided within the template as files beginning with the prefix
build. There is a sample for using the stand-alone Flash Player and ADL to execute your test suite(s). These build scripts are just suggestions, there are many different ways to write an Ant build script, these samples are solely intended to present Ant in a simple manner.
- When in doubt on how to organize your project or which build script to use, check out the comments in all of the build files as well as the
README.txtfile which comes with the FlexUnit4SampleCIProject.
Running your build
- Once you've placed the appropriate source and test code in their respective locations, change directory to the location where the project template was extracted.
- Any of the stock Ant build scripts can be executed by running the following command:
ant -v clean packageThis will provide you with verbose details of the build script execution and help you debug any errors you may encounter.
During the setup process, if things don't work out as expected, please don't hesitate to ask us for help on the FlexUnit forums @ http://forums.adobe.com/community/opensource/flexunit/general. We generally respond within a few hours, if not immediately, and are more than happy to help.
Below is a description of the possible configuration options for the FlexUnit4 Ant task:
<flexunit player="flash|air" command="<path to the executable for the Flash Player or ADL>" swf="<path to your SWF file>" toDir="<path where XML reports should be written>" workingDir="<path to which compilation resource may be copied>" haltonfailure="true|false" verbose="true|false" localTrusted="true|false" port="<port number on which to run the XMLSocket>" buffer="<size in bytes of buffer for incoming data from flash movie>" timeout="<timeout for the runner in milliseconds>" failureproperty="<property name to set to 'true' if any tests fail>" headless="true|false" display="<X-Windows display # to use in headless mode"> <source dir="..." /> <testSource dir="..."> <include name="**/*Test.as" /> <include name="**/*Test.mxml" /> </testSource> <library dir="..." /> </flexunit>
Note: a custom built version is available that also allows you to pass compiler constants (like SOMETHING::something=something). Read about it in the discussion section (link at the top of the page).
Below is a more detailed description of each attribute of the task:
- player -- DEFAULT: flash (4.0.0)
- This toggles the ability to execute the test SWF using the Flash Player or ADL. Test SWF's executed using ADL should be built using the amxmlc executable or mxmlc.jar with the parameter "+configname=air".
- If building on Linux, the AIR SDK folders must be extracted on top of the Flex SDK folders for the Ant task to properly function.
- command (4.1.0)
- This is a relative or absolute path to an executable command which should be used to launch the SWF identified by the "swf" property or automatically generated by the built in compilation process.
- The task will attempt to kill the process ID associated with the command when told the test run has completed.
- This property was added to allow the use of using a web browser to execute a test run rather than the stand-alone Flash Player for tests specific to Flash movie running in the context of a web browser.
- This property may also be used to obviate the default mechanism of launching the stand-alone Flash Player on Linux (i.e. - creating an alias named gflashplayer).
- swf (4.0.0)
- This is a relative or absolute path to the SWF file which has been compiled with the CIListener class added as a listener to the FlexUnitCore. See src/test/flex/TestRunner.mxml for an example. Please note that paths containing spaces are not currently supported.
- toDir -- DEFAULT: Project base directory (4.0.0)
- This is a relative or absolute path to the directoy where the task should write the XML test result reports. The report files will be named in the pattern "TEST-*.xml".
- workingDir -- DEFAULT: Project base directory (4.1.0)
- This is a relative or absolute path to the directory where the task should copy the resources created during compilation. Currently, only the "TestRunner.mxml" and "TestRunner.swf" file will be copied into this location.
- haltonfailure -- DEFAULT: false (4.0.0)
- Setting this attribute to true will cause the build to stop when tests within the SWF have failed. All tests within the SWF will execute before the build is halted to maximize the test results returned from a test run.
- verbose -- DEFAULT: false (4.0.0)
- Setting this attribute to true will cause the task to output which tests have failed, errored, and been ignored as well as a summary of test counts per test class.
- localTrusted -- DEFAULT: true (4.0.0)
- Setting this attribute to true will add the path passed into the "swf" attribute to the local FlashPlayer Trust. This trust entry is made in the flexUnit.cfg file on your machine's local trust folder for the Flash Player. If this attribute is set to false, the flexUnit.cfg file will be removed.
- On Linux, make sure that that the user executing the Ant script has a home folder and its HOME environment variable is declared. Currently running the script as the root user is not supported. Fix pending...
- Excluded if using player="air".
- port -- DEFAULT: 1024 (4.0.0)
- Setting this attribute informs the task to listen for test results on the specified port. Using this attribute implies that the port on the CIListener instance registered on the FlexUnitCore is registered with the same port number.
- buffer -- DEFAULT : 262144 (4.0.0)
- Data buffer size (in bytes) for incoming communication from the Flash movie to the task. Useful to increase for large sets of tests with potentially lots of failures/errors. Current set to ~256K which should never typically need to be changed.
- timeout - DEFAULT: 60000 (60s) (4.0.0)
- Setting this attribute will dictate the amount of time the task waits for a connection from the player executing the test runner.
- failureproperty -- DEFAULT: flexunit.failed (4.0.0)
- If a test failure occurs during the test run, the property name set in this attribute will receive a value of true. Per Ant conventions, this property will not exist unless a test in the run has failed or errored.
- headless -- DEFAULT : false (4.0.0)
- Setting this attribute to true allows the task to execute tests headlessly via Xvnc. See below for more details on running headlessly.
- display -- DEFAULT : 99 (4.0.0)
- The base display number used by Xvnc for headless support in the task. See below for more details on running headlessly.
Below is a more detailed description of each element of the task. Please note that currently elements are only used for automatic test SWF compilation and do not relate to the execution of that or any other test SWF. Additionally, the current implementation supports the simplest of compilation scenarios. If to compile the test runner a more detailed list of compiler arguments is required than the supported elements below, this feature may not satisfy your build needs.
- source (4.1.0)
- An element used to locate a directory which contains only source code to be used for compilation. This is done by using the location in the dir attribute of the element. In the future, this element will be used to identify what folders contain source code, potentially for code coverage integration.
- Cardinality - 0 .. n -- (i.e. - zero to multiple numbers of this element are allowed within root element)
- testSource (4.1.0)
- An Ant fileset used to locate a directory which contains only test source code to be used for compilation. The dir attribute of the fileset will be placed on the source path along with any directories specified for "source" elements.
- By default, the following filter patterns are applied to this element
- 1 .. n (if automatic test SWF compilation is being used) -- (i.e. - at least 1 testSource element must be present if the swf attribute is not specified).
- 0 .. n (if automatic test SWF compilation is NOT being used) -- (i.e. - zero to multiple testSource elements may be be provided if the swf attribute is specified).
- library (4.1.0)
- An element used to locate a directory which contains SWC files to be used for compilation. This is done by using the location in the dir attribute of the element.
- By default, the following filter patterns are applied to this element
- Cardinality - 0 .. n -- (i.e. - zero to multiple library elements may be provided)
The Ant task has support to execute a test SWF under a headless environment for Linux platforms with Xvnc support. Currently there is no built in support for executing a test run headlessly on Windows although this is possible; see the Continuous Integration Support page for more details. The current support is a port of the Xvnc Hudson Plugin found at http://wiki.hudson-ci.org/display/HUDSON/Xvnc+Plugin. By marking headless="true", the task will attempt to do the following to supplement the execution of the test SWF:
- Attempt to execute the command "vncserver :<display>", where display is the value of the display attribute which defaults to 99.
- If the display value is in use by X-Windows, then the task will increment the display number up to 3 additional times to attempt to successfully execute the above command.
- Once the vncserver has been started, the player command will be issued with the environment variable "DISPLAY" set to a value of ":<display>". This will cause all windowing output for the duration of the player command, to be transferred to the display on which the vncserver is executing.
- Once the player command has completed, the command "vncserver -kill :<display>" will be issued closing the vncserver on the appropriate display.
Please note that X-Windows, an implementation of vncserver, and their respective dependencies (determined per platform) are required to utilize this support.
See the Continuous Integration Support page for more information on setting up Xvnc.