Packagecom.gskinner.performance
Classpublic class TestSuite
InheritanceTestSuite Inheritance flash.events.EventDispatcher

Test suites allow you to organize and aggregate related tests. It makes tests more portable, generates better organized output, and gives access to some aggregate information, like total time. You can run or queue an entire suite as one item. If it is queued, each iteration of each test will be run independently with a delay between them. If it is run (ex. PerformanceTest.run(myTestSuite) ), then all of the tests will be run synchronously.

There are three ways to build test suites:

1. Inheritance. Extend TestSuite, add the methods to test in the subclass, and define all of the necessary properties in the constructor. This creates a very portable collection of tests.

2. Composition. Create a new TestSuite instance, and set its properties, including specifying tests to run using methods from other classes. This provides a formal, but slightly more adhoc method of creating suites.

3. Using fromObject. This allows you to generate TestSuites from any object with public methods. See fromObject for details.



Public Properties
 PropertyDefined by
  description : String
Optional description for this test.
TestSuite
  initFunction : Function
This allows you to specify a function to execute prior to executing any of the tests (including the tareTest).
TestSuite
  initTime : int = 0
Indicates the time it took to run the initFunction.
TestSuite
  iterations : uint = 0
Specifies the default number of iterations to use for any test in this suite with iterations=0.
TestSuite
  name : String
Optional name for this test suite.
TestSuite
  tareTest : AbstractTest
This specifies a test to use for taring.
TestSuite
  tareTime : int = 0
See tareTest for a full explanation of tareTime.
TestSuite
  tests : Array
An array of the AbstractTest instances in this suite.
TestSuite
  time : int
[read-only] Returns the aggregate time of all tests, or -1 if any test has not run successfully.
TestSuite
Public Methods
 MethodDefined by
  
TestSuite(tests:Array = null, name:String = null, tareTest:AbstractTest = null, initFunction:Function = null, iterations:uint = 0, description:String = null)
Creates a new instance of TestSuite.
TestSuite
  
complete():void
PerformanceTest calls complete() when all of the tests in the suite have been run.
TestSuite
  
fromObject(o:Object, name:String = null, iterations:uint = 1, testLoops:uint = 1, description:String = null):TestSuite
[static] This provides you with a simple way to quickly generate a TestSuite instance from any object with public methods.
TestSuite
  
toString():String
Returns a string representation of this TestSuite.
TestSuite
  
toXML():XML
Returns XML containing all of the information about this test suite and the tests it contains.
TestSuite
Events
 EventSummaryDefined by
   Dispatched when all of the tests in the suite have completed.TestSuite
Property detail
descriptionproperty
public var description:String

Optional description for this test.

initFunctionproperty 
public var initFunction:Function

This allows you to specify a function to execute prior to executing any of the tests (including the tareTest). This is useful for setting up data structures or conditions that your tests require, but which you do not want included in the timed results.

initTimeproperty 
public var initTime:int = 0

Indicates the time it took to run the initFunction.

iterationsproperty 
public var iterations:uint = 0

Specifies the default number of iterations to use for any test in this suite with iterations=0. If this value is also 0, then the PerformanceTest default of 1 is used.

nameproperty 
public var name:String

Optional name for this test suite. This is used for display purposes, and could also be used to uniquely identify the test suite for analytics systems.

tareTestproperty 
public var tareTest:AbstractTest

This specifies a test to use for taring. This test should establish a baseline time that can be used to isolate the significant time in other tests. For example, if you created a suite of tests that all ran a loop 1000 times to test code in the loop, you could write a tare test that runs an empty loop 1000 times, to isolate the time spent on the loop from the time executing the code within the loop.

Tare tests are treated differently than other tests. They are run until two subsequent runs return substantially similar results, and the average time for those two is recorded as the tareTime for the suite. This time will differ from the time value on the test itself.

The iteration property on the tareTest can be set to specify a maximum number of times to attempt to run the tareTest or left at 0 to use the default of 10. After running, the iteration property indicates how many times the tareTest was run to get consistent results. If consistent results are not obtained, then tareTime is set to -1.

Reporting systems may choose to subtract the tareTime from each test's time to isolate only the significant portion of the result.

tareTimeproperty 
public var tareTime:int = 0

See tareTest for a full explanation of tareTime.

testsproperty 
public var tests:Array

An array of the AbstractTest instances in this suite.

timeproperty 
time:int  [read-only]

Returns the aggregate time of all tests, or -1 if any test has not run successfully.

Implementation
    public function get time():int
Constructor detail
TestSuite()constructor
public function TestSuite(tests:Array = null, name:String = null, tareTest:AbstractTest = null, initFunction:Function = null, iterations:uint = 0, description:String = null)

Creates a new instance of TestSuite. See properties for parameter information.

Parameters
tests:Array (default = null)
 
name:String (default = null)
 
tareTest:AbstractTest (default = null)
 
initFunction:Function (default = null)
 
iterations:uint (default = 0)
 
description:String (default = null)
Method detail
complete()method
public function complete():void

PerformanceTest calls complete() when all of the tests in the suite have been run. This causes the suite to dispatch the COMPLETE event. You would not generally call this method directly.

fromObject()method 
public static function fromObject(o:Object, name:String = null, iterations:uint = 1, testLoops:uint = 1, description:String = null):TestSuite

This provides you with a simple way to quickly generate a TestSuite instance from any object with public methods.

If you pass in a generic Object, it will scan all of its dynamic properties for methods, and add any methods that are not prefixed with an underscore to the suite as new Test instances.

If you pass in a typed object, it will add all of its uninherited public methods that are not prefixed with an underscore.

In both cases, it will scan for the existence of label, description, iterations, loops, and id properties on the object, and apply them to the test suite if they are not specified as parameters. It will also look for an init function to set as initFunction, and a tare function to use for the tareTest.

Parameters
o:Object
 
name:String (default = null)
 
iterations:uint (default = 1)
 
testLoops:uint (default = 1)
 
description:String (default = null)

Returns
TestSuite
toString()method 
public override function toString():String

Returns a string representation of this TestSuite. Very handy for tracing:
trace(myTestSuite);

Returns
String
toXML()method 
public function toXML():XML

Returns XML containing all of the information about this test suite and the tests it contains. This is very useful for building analysis tools, and for saving out results to compare them in the future.

I might document the format some day, but for now it's simple enough to just trace the output of this function to see it.

Returns
XML
Event detail
completeevent 
Event object type: flash.events.Event

Dispatched when all of the tests in the suite have completed.