Useful reference for the most used Metadata tags in FlexUnit

There are a lot of Metadata tags used in FlexUnit, and if you're still new to the framework it can be a bit overwhelming to know what to use and what can be included inside them. Here's a comprehensive list of the commonly used tags with a brief explanation of where they can be used. You should be able to find reference to most of these in the code examples listed in this wiki.

BeforeClass

– Used to specify a static method within a TestCase should run one time, before the constructor and all test cases, this only happens once per TestCase, per case execution, regardless of how many tests are in the test case. It's most commonly a BeforeClass marked method would be used to create tables, or connect to a database that would be used in a group of tests. For more information about BeforeClass see Sequences

• ''Attributes:'' order, description, timeout, async, ui, user defined

AfterClass

– Used to specify a static method within a TestCase should run once, after all of the tests in a given test case are complete. In other words, when all of the tests in a test case are complete, before proceeding to the next testcase, this method executes. Conversely to a BeforeClass method AfterClass should preform cleanup on created tables, disconnect from databases, etc. For more information about AfterClass see Sequences

• ''Attributes:'' order, description, timeout, async, ui, user defined

Before

– Used to specify a method with a TestCase should be run before every [Test] in that class. For more information about Before see Sequences

• ''Attributes:'' order, description, timeout, async, ui, user defined

After

– Used to specify a method with a TestCase should be run after every [Test] in that class. For more information about After see Sequences

• ''Attributes:'' order, description, timeout, async, ui, user defined

Rule

– Used to define an advanced [Before]/[After] setup using an entire class allowing for increased reusability. For more information see Creating Rules

• ''Attributes:'' order

Suite

– specifies that the class tagged is a Test Suite and will contain a list of public variables typed as the Test Cases or additional Test Suites you wish to run. This tag is commonly paired with the [RunWith] tag to know what runner to use on the tests within this class. (Note: The Suite tag by it self actually does nothing, and RunWith specified with the Suite runner is all you need to set to get a class to run as a suite.) For more information about test suites see Test Suite

• ''Attributes:'' order, description, user defined

RunWith("fullyQualifiedName")

– Used to identify a specific runner that should be used for this class. Common uses include specifying a class to use the Suite runner or Theory runner. The class specified must be linked into the project and must implement the IRunner interface. For more information about runners see Runners and Builders

• ''Attributes:'' none, other than the fully qualified class name of the runner.

Ignore

– Can be used to ignore a specific [Test] or [Theory], the test will still be built, but will be skipped over when running all tests in the TestCase. The test marked with this tag is still counted in the total tests count. For more information about Ignore see [Ignore]

• ''Attributes:'' description, user defined

Test

– Is used to specify that a method in a TestCase is a method you want FlexUnit to test. There are additional attributes that can be added to this tag such as (async) which is needed if the test is using asyncronous events or (expects="flash.errors.IOError") which indicates that you expect the Test to throw an exception of the specified type and it should catch it. For more information see user defined metadata.

• ''Attributes:'' expects, order, description, timeout, async, ui, user defined, dataProvider

DataPoint(s)

– Used on a public static variable or public static function to return testing data. These are then used in conjunction with a Theory by running the Theory once for each item in that particular [DataPoint]'s range. If DataPoints is used, then the tag [ArrayElementType] must also be used to define the type of data the array contains. For more information see Theories, Datapoints, and Assumptions

• ''Attributes:'' description, user defined, loader

Parameters

– Parameters allow for a multitude of values to be passed into a constructor of a TestCase. For more information about Parameterized testing seeParameterized Testing

• ''Attributes:'' description, user defined, loader

Theory

– Used to test a full range of expected results with the help of DataPoint objects or functions. The Theory should specify accepted arguments of types matching to your declared DataPoints. FlexUnit will run all the theories for all possible combinations of arguments with the DataPoint objects that match argument types.
More info on Theories see Theories, Datapoints, and Assumptions

• ''Attributes:'' description, user defined

Other tags:

ArrayElementType

– Used to define the associated object type contained with an Array, most specifically used with a static variable, or function, marked as a DataPoint. Keep in mind that this piece of metadata is not unique to FlexUnit 4, however is required by [ to function properly.

Meta Data Attributes:

expects

[Test(description="Ensure failure when two items are not strictly equal", expects="flexunit.framework.AssertionFailedError")]
public function testAssertStrictlyEqualsFails():void {
     Assert.assertStrictlyEquals( 5, "5" );
}

– adding this bit of metadata to your tag indicates to the runner that there is an expectation for an error to be thrown and if the error specified is caught then all is good, otherwise the test is a failure.

h2 order

[Before(order=1)]
public function setUp() : void
{
     panel = new Panel();
}

[Before(order=2, async, ui)]
public function otherSetUp() : void
{
     Async.proceedOnEvent(this, panel, FlexEvent.CREATION_COMPLETE);
         
     UIImpersonator.addChild(panel);
}

– adding this bit of metadata to your tag sets the sort order for this test in relation to all the tests within the test case. Keep in mind that if you override sorting by setting your own sort then you will have to identify what metadata you're going to use to calculate sorting. If you're looking for more information on setting up your own sorting see Sorting.

description

[Test(description="Ensure that the assertNull function correctly works when a value of null is provided")]
public function testAssertNull():void {
    Assert.assertNull( null );
}

– This bit of metadata on your tag is used generally to explain the functionality of your test method.

<b>Note:</b> Do not include '<', '>', '&', or '%'. signs in your descriptions, since metadata is parsed into xml and will as a result cause an error with your test. Instead you will need to replace them with their markup forms (< > & and % respectively).

timeout

[Test(async, ui, timeout="1000")]
public function eventWasNotDispatchedWithoutClick() : void 
{
     Async.failOnEvent(this, panel, "userEnteredText");
         
     panel.userText.text = "some text";
}

– indicates to the runner that this test needs to be run within the milliseconds indicated otherwise it is a failure.

async

[Test(async, ui, timeout="1000")]
public function eventWasNotDispatchedWithoutClick() : void 
{
     Async.failOnEvent(this, panel, "userEnteredText");
         
     panel.userText.text = "some text";
}

– indicates to the runner that this test needs to be monitored for asynchronous activity.

ui

[Before(async, ui)]
public function setUp() : void 
{
     panel = new Panel();
      
     Async.proceedOnEvent(this, panel, FlexEvent.CREATION_COMPLETE);
         
     UIImpersonator.addChild(panel);
}

– indicates to the runner that this test needs to instantiate new objects for the test environment. This attribute is needed if you wish to use the UIImpersonator class in your function.

User Defined Metadata

[Test(ticketNumber=5543242)]

[Theory(author="Bill Smith")]

– this is any other metadata attribute declared within your tag. This can be used to save information about the test, suite, theory, etc. Most often it is used to store author name or bug issue id. Anything can be added as a custom attribute and will simply act as reference with no effect on other attributes or the parent Metadata tag.

loader

– Indicates the loader instance that that is responsible for providing data to the specified variable.

public static var dataRetriever1:ParamDataHelper = new ParamDataHelper( "someFakeDataPath.stuff" );
        
[Parameters(loader="dataRetriever1")]
public static var someData:Array;

dataProvider

For parameterized tests, a data Provider is used to pass in a set of data from either an external or user specified source.

public static function dataTwo():Array {
    return [ [ 5, 10 ], [ 6, 12 ], [ 7, 14 ] ];
}

[Test(dataProvider="dataTwo")]
public function timesTwoTest( value:int, result:int ):void {
    assertEquals( 2*value, result );
}

FlexUnit Developer Documentation

Here you can find information and resources regarding FlexUnit open source development. It contains information for developers, and the FlexUnit community in general.

If you cannot find your answers here, then please ask about it on the Developers forum.

Note that many existing articles use the previous version of the graphical test runner, but the underlying testing code should remain the same.

FlexUnit Tutorials

• Flex Developer Center
• Test Driven Development using Flash Builder 4 beta and FlexUnit

Get source codeh2.

Release and milestone versions of the FlexUnit 4 are available from the http://www.flexunit.org/?page_id=14. These downloads are also available from the Adobe Open Source website. Unless you are planning on developing or building modifications on the framework, these are the suggested locations to use. For instructions using the FlexUnit library ''only'' see Getting Started

Day to day development work facilitated by the Flex, Flash and ActionScript communities continues on the FlexUnit 4 framework over on GitHub. If you simply want to view or work with stable milestone builds, use the download link above.

Web browsing

To browse the FlexUnit 4 project, go to http://www.flexunit.org/?page_id=14^{Image Removed}. This should take you to the source page. At the top of the page you will notice links for branches and tags.

The master branch is the main development branch for FlexUnit 4. Branches are created when projects need to stabilize code for a release.

Tags record the code that shipped as a specific release, or other milestones in a project. The code which was used to build the 4.x release of the FlexUnit has been tagged as tags/4.x. Builds prior are tagged in the tags directory.

This site often uses the word “branch” as shorthand for “trunk, branch, or tag”.

To understand what's where inside each branch, see FlexUnit Organization.

You can access directories and files inside the project by appending them onto the project's URL. For example, to browse the FlexUnit 4 directory of the most recent build of FlexUnit, you can go directly to https://git-wip-us.apache.org/repos/asf?p=flex-flexunit.git;a=tree;h=refs/heads/master;hb=master^{Image Removed}.

Installing git

To get your own working copy of the source code, you'll need to use git. Git is primarily a command line environment, however there are gui versions of of the client as well. A client will also let you see the repository structure, look at the revision history of any file or directory, diff two versions of a file, etc.

Github has detailed instructions on using git with Windows, Linux and Mac. Below are quickstart instructions for getting the latest build. For Windows users these instructions assume you are not already using mysys or another terminal client.

You can get the latest versions as well as installation instructions for git from the following addresses:

:* Windows: http://help.github.com/win-git-installation/^{Image Removed}
:* Mac: http://help.github.com/mac-git-installation/^{Image Removed}
:* Linux: http://help.github.com/linux-git-installation/^{Image Removed}

Checking out codeh2.

When you access the repository with a git client, the FlexUnit project is at the URL https://git-wip-us.apache.org/repos/asf?p=flex-flexunit.git^{Image Removed}

To get the entire source code for the project, do a "checkout" from this URL into a local directory on your machine. Using the command-line client, you would execute:

git clone https://git-wip-us.apache.org/repos/asf/flex-flexunit.gitImage Removed

This will create a local copy of the code. ''Note:'' If you would like to contribute to the project you will need to create a fork of the branch and commit changes to the fork. Once you have made changes, you may "push" them to the branch and the author may incorporate them into the existing project.

Building and testing

If you want to build and test the source code, see How to build and test FlexUnit.

For instructions using Ant, see below:

1. Change directories to the root of the recently checked out source code. This directory should contain all of the FlexUnit project folders prefixed with FlexUnit4.
2. If you haven't already, set the value of an environment variable named FLEX_HOME to the absolute path of the Flex SDK with which you want to build FlexUnit.
3. To quickly get started, execute the Ant build script in this directory use the following command to run the unit tests and produce the flexunit.zip build artifact: <pre>ant -v clean package</pre>
4. You may notice that the flexunit.zip artifact is missing the asdocs for the project as well as any supplemental static code analysis reports. To avoid cross platform issues when building the API, we've established an opt-in policy for reporting. The following arguments can be adding to activate various forms of reporting:
   1. -Dbuild.report=true – Used to generate asdocs
   2. -Dbuild.pmd=true – Used to generate PMD, CPD, and Metrics reports. Must be used with -Dbuild.report=true.
5. There are also other options which are opt-out when using the build:
   1. -Dbuild.skipTests – Skips all tests.
   2. -Dbuild.useFlex=true|false – Determines whether to build the the FlexUnit core with a dependency on Flex or just for use with AS3
   3. -Dbuild.instrument – Attempts to run the build using FlexCover assuming the CoverageViewer AIR application is installed and the environment variable FLEX_COVER_SDK is defined pointing to the absolute path of the custom FlexCover SDK. (currently broken)

Contributing to FlexUnit

If you are interested in contributing to FlexUnit, please see the http://flex.apache.org/community-getinvolved.html^{Image Removed} page.

FlexUnit Project Structure

Find out how individual projects inside the FlexUnit4 repository are used.]

Submitting a patch

...