API Documentation | All Packages | All Classes | Index | Frames No Frames |
BlockFlexUnit4ClassRunner

Package | org.flexunit.runners
Class | public class BlockFlexUnit4ClassRunner
Inheritance | BlockFlexUnit4ClassRunner ParentRunner Object
Implements | IFilterable
Subclasses | Theories, TheoryBlockRunner

The `BlockFlexUnit4ClassRunner` is the heart of running FlexUnit4 tests. It is responsible for iterating through tests in a given class, determining if they are being implemented correctly, and executing them. The following flow occurs for a provided class:

- Any methods that contain a medadata tag of [BeforeClass] are executed.
- Once the [BeforeClass] methods have finished, each method labeled as [Test] is sequenced with all methods that contain [Before] and [After] metadata tags. Beofre each test, all methods marked as a [Before] method will execute. After this occurs, the actual test method will execute. After the test has finished, regardless of whether it succeeded or failed, all methods marked as an [After] method will run. This procedure will be repeated for all tests in the class.
- Any methods that contain a metdata tag of [AfterClass] are finally executed.

While running tests, the `BlockFlexUnit4ClassRunner` uses two very important concepts: recursive sequences and decoration. The first sequence that is used in the `BlockFlexUnit4ClassRunner` is that of the before class sequence, the tests sequence, and after class sequence. Both the before class and after class sequences consist of the before class and after class methods. The tests sequence consists of a sequence of individual test sequences. Each individual test sequnce contains the before sequence, the test, and the after sequence. The before and after sequences contain the before and after methods. Before any before class, after class, before, after, or test methods are executed, they are decorated in order to add functionality. These decorations are used to wrap the invocation of a method with code that should be executed before or after the method in a synchronous nature. Each decarator is applied to the method if necessary; if it is not needed, the decorator is not applied. The wrapping of the actual test method can be seen in the `#withDecoration()` method. This method determines if the tests needs certain decorators based on the metadata of the test.

See also

org.flexunit.internals.runners.statements.StatementSequencer
org.flexunit.internals.runners.statements.SequencerWithDecoration

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | description : IDescription [read-only] Returns an IDescription of the test class that the runner is running, caching it. | ParentRunner

Protected Properties
Hide Inherited Protected Properties
Show Inherited Protected Properties

| Property | Defined By
--- | --- | ---
|  | children : Array [override] [read-only] Returns an array of all methods that have been annotated with Test. | BlockFlexUnit4ClassRunner
|  | name : String [read-only] Returns a name used to describe this Runner. | ParentRunner
|  | stopRequested : Boolean = false private | ParentRunner
|  | testClass : TestClass [read-only] Returns a TestClass object wrapping the class to be executed. | ParentRunner

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | BlockFlexUnit4ClassRunner(klass:Class) Creates a BlockFlexUnit4ClassRunner to run klass. | BlockFlexUnit4ClassRunner
|  | filter(filter:IFilter):void Applies the provided Filter to the runner. | ParentRunner
|  | pleaseStop():void Ask that the tests run stop before starting the next test. | ParentRunner
|  | run(notifier:IRunNotifier, previousToken:IAsyncTestToken):void Runs the test class and updates the notifier on the status of running the tests. | ParentRunner
|  | sort(sorter:ISorter):void Applies the provided ISorter to the runner. | ParentRunner

Protected Methods
Show Inherited Protected Methods
Show Inherited Protected Methods

| Method | Defined By
--- | --- | ---
|  | childrenInvoker(notifier:IRunNotifier):IAsyncStatement Returns an IAsyncStatement: Call #runChild(Object, IRunNotifier, AsyncTestToken) on each object returned by #children() (subject to any imposed filter and sort). | ParentRunner
|  | classBlock(notifier:IRunNotifier):IAsyncStatement Constructs an IAsyncStatement to run all of the tests in the test class. | ParentRunner
|  | collectInitializationErrors(errors:Array):void [override] It additionally validates whether specific instances of tests are implemented correctly. | BlockFlexUnit4ClassRunner
|  | compare(o1:Object, o2:Object):int This sorting method uses the runner's ISorter to compare two child arguments. | ParentRunner
|  | computeTestMethods():Array Returns the methods that run tests. | BlockFlexUnit4ClassRunner
|  | createTest():Object Returns a new fixture for running a test. | BlockFlexUnit4ClassRunner
|  | describeChild(child:*):IDescription [override] Returns an IDescription for child, which can be assumed to be an element of the list returned by ParentRunner#children(). | BlockFlexUnit4ClassRunner
|  | generateDescription():IDescription Returns an IDescription of the test class that the runner is running. | ParentRunner
|  | methodBlock(method:FrameworkMethod):IAsyncStatement Returns an IStatement that, when executed, either returns normally if method passes, or throws an exception if method fails. | BlockFlexUnit4ClassRunner
|  | methodInvoker(method:FrameworkMethod, test:Object):IAsyncStatement Returns an IAsyncStatement that invokes method on test | BlockFlexUnit4ClassRunner
|  | possiblyExpectingExceptions(method:FrameworkMethod, test:Object, statement:IAsyncStatement):IAsyncStatement Returns an IAsyncStatement: if method's Test annotation has the expecting attribute, return normally only if next throws an exception of the correct type, and throw an exception otherwise. | BlockFlexUnit4ClassRunner
|  | runChild(child:*, notifier:IRunNotifier, childRunnerToken:AsyncTestToken):void [override] Runs the test corresponding to child, which can be assumed to be an element of the list returned by ParentRunner#children(). | BlockFlexUnit4ClassRunner
|  | validateInstanceMethods(errors:Array):void Adds to errors for each method annotated with Test, Before, or After that is not a public, void instance method with no arguments. | BlockFlexUnit4ClassRunner
|  | validatePublicVoidNoArgMethods(metaDataTag:String, isStatic:Boolean, errors:Array):void Adds to errors if any method in this class is annotated with metaDataTag, but: is not public, or takes parameters, or returns something other than void, or is static (given isStatic is false), or is not static (given isStatic is true). | ParentRunner
|  | validateTestMethods(errors:Array):void Adds to errors for each method annotated with Test that is not a public, void instance method with no arguments. | BlockFlexUnit4ClassRunner
|  | withAfterClasses():IAsyncStatement Returns an IAsyncStatement: run all non-overridden AfterClass methods on this class and superclasses before executing the statement; all AfterClass methods are always executed: exceptions thrown by previous steps are combined, if necessary, with exceptions from AfterClass methods into a MultipleFailureException. | ParentRunner
|  | withAfters(method:FrameworkMethod, target:Object, statement:IAsyncStatement):IAsyncStatement Returns an IAsyncStatement: run all non-overridden After methods on this class and superclasses before running next; all After methods are always executed: exceptions thrown by previous steps are combined, if necessary, with exceptions from After methods into a MultipleFailureException. | BlockFlexUnit4ClassRunner
|  | withAfterStatements(method:FrameworkMethod, test:Object, statement:IAsyncStatement):IAsyncStatement | BlockFlexUnit4ClassRunner
|  | withBeforeClasses():IAsyncStatement Returns an IAsyncStatement: run all non-overridden BeforeClass methods on this class and superclasses before executing the statement; if any throws an Exception, stop execution and pass the exception on. | ParentRunner
|  | withBefores(method:FrameworkMethod, target:Object, statement:IAsyncStatement):IAsyncStatement Returns an IAsyncStatement: run all non-overridden Before methods on this class and superclasses before running statement; if any throws an Exception, stop execution and pass the exception on. | BlockFlexUnit4ClassRunner
|  | withDecoration(method:FrameworkMethod, test:Object):IAsyncStatement Returns an IAsyncStatement that invokes method on a decorated test. | BlockFlexUnit4ClassRunner
|  | withPotentialAsync(method:FrameworkMethod, test:Object, statement:IAsyncStatement):IAsyncStatement Returns an IAsyncStatement: if method's Test annotation has the async attribute, throw an exception if next encounters an exception during execution. | BlockFlexUnit4ClassRunner
|  | withPotentialRules(method:FrameworkMethod, test:Object, statement:IAsyncStatement):IAsyncStatement Potentially returns a new IAsyncStatement defined by the user on the testcase via the Rule metadata. | BlockFlexUnit4ClassRunner
|  | withPotentialTimeout(method:FrameworkMethod, test:Object, statement:IAsyncStatement):IAsyncStatement Returns an IAsyncStatement: if method's Test annotation has the timeout attribute, throw an exception if next takes more than the specified number of milliseconds. | BlockFlexUnit4ClassRunner
|  | withStackManagement(method:FrameworkMethod, test:Object, statement:IAsyncStatement):IAsyncStatement Returns an IAsyncStatement that manages the stack and allow execution to break across frames. | BlockFlexUnit4ClassRunner

Property Detail

children | property

`children:Array` [read-only] [override]

Returns an array of all methods that have been annotated with `Test`.

Implementation
`protected function get children():Array`
Constructor Detail

BlockFlexUnit4ClassRunner | () | Constructor

`public function BlockFlexUnit4ClassRunner(klass:Class)`

Creates a BlockFlexUnit4ClassRunner to run `klass`.

Parameters

| `klass:Class` — The class to run.

Method Detail

collectInitializationErrors | () | method

`override protected function collectInitializationErrors(errors:Array):void`

It additionally validates whether specific instances of tests are implemented correctly. Adds to `errors` an error for each problem noted with the test class (available from `#testClass()`). Default implementation adds an error for each method annotated with `BeforeClass` or `AfterClass` that is not `public static void` with no arguments.

Parameters

| `errors:Array` — An `Array` of issues encountered when attempting to setup the runner for the test class.

computeTestMethods | () | method |

`protected function computeTestMethods():Array`

Returns the methods that run tests. Default implementation returns all methods annotated with `Test` on this class and superclasses that are not overridden.

Returns

| `Array`

createTest | () | method |

`protected function createTest():Object`

Returns a new fixture for running a test. Default implementation executes the test class's no-argument constructor (validation should have ensured one exists).

Returns

| `Object`

describeChild | () | method |

`override protected function describeChild(child:*):IDescription`

Returns an `IDescription` for `child`, which can be assumed to be an element of the list returned by `ParentRunner#children()`.

Parameters

| `child:*` — The child to describe.

Returns

| `IDescription` — an `IDescription` of the provided `child`.

methodBlock | () | method |

`protected function methodBlock(method:FrameworkMethod):IAsyncStatement`

Returns an IStatement that, when executed, either returns normally if `method` passes, or throws an exception if `method` fails.

Here is an outline of the default implementation:

- Invoke `method` on `test`, and throw any exceptions thrown by either operation.
- HOWEVER, if `method`'s `Test` annotation has the `expecting` attribute, return normally only if the previous step threw an exception of the correct type, and throw an exception otherwise.
- HOWEVER, if `method`'s `Test` annotation has the `timeout` attribute, throw an exception if the previous step takes more than the specified number of milliseconds.
- ALWAYS run all non-overridden `Before` methods on this class and superclasses before any of the previous steps; if any throws an Exception, stop execution and pass the exception on.
- ALWAYS run all non-overridden `After` methods on this class and superclasses before any of the previous steps; all After methods are always executed: exceptions thrown by previous steps are combined, if necessary, with exceptions from After methods into a `MultipleFailureException`.

This can be overridden in subclasses, either by overriding this method, or the implementations creating each sub-statement.

Parameters

| `method:FrameworkMethod`

Returns

| `IAsyncStatement`

methodInvoker | () | method |

`protected function methodInvoker(method:FrameworkMethod, test:Object):IAsyncStatement`

Returns an `IAsyncStatement` that invokes `method` on `test`

Parameters

| `method:FrameworkMethod`
| `test:Object`

Returns

| `IAsyncStatement`

possiblyExpectingExceptions | () | method |

`protected function possiblyExpectingExceptions(method:FrameworkMethod, test:Object, statement:IAsyncStatement):IAsyncStatement`

Returns an `IAsyncStatement`: if `method`'s `Test` annotation has the `expecting` attribute, return normally only if `next` throws an exception of the correct type, and throw an exception otherwise.

Parameters

| `method:FrameworkMethod`
| `test:Object`
| `statement:IAsyncStatement`

Returns

| `IAsyncStatement`

runChild | () | method |

`override protected function runChild(child:*, notifier:IRunNotifier, childRunnerToken:AsyncTestToken):void`

Runs the test corresponding to `child`, which can be assumed to be an element of the list returned by `ParentRunner#children()`. Subclasses are responsible for making sure that relevant test events are reported through `notifier`.

Parameters

| `child:*` — The child to run.
| `notifier:IRunNotifier` — The `IRunNotifier` to notify on the progress of the `child`.
| `childRunnerToken:AsyncTestToken` — The token used to keep track of the `child`'s execution.

validateInstanceMethods | () | method |

`protected function validateInstanceMethods(errors:Array):void`

Adds to `errors` for each method annotated with `Test`, `Before`, or `After` that is not a public, void instance method with no arguments.

Parameters

| `errors:Array`

validateTestMethods | () | method |

`protected function validateTestMethods(errors:Array):void`

Adds to `errors` for each method annotated with `Test` that is not a public, void instance method with no arguments.

Parameters

| `errors:Array`

withAfters | () | method |

`protected function withAfters(method:FrameworkMethod, target:Object, statement:IAsyncStatement):IAsyncStatement`

Returns an `IAsyncStatement`: run all non-overridden `After` methods on this class and superclasses before running `next`; all After methods are always executed: exceptions thrown by previous steps are combined, if necessary, with exceptions from After methods into a `MultipleFailureException`.

Parameters

| `method:FrameworkMethod`
| `target:Object`
| `statement:IAsyncStatement`

Returns

| `IAsyncStatement`

withAfterStatements | () | method |

`protected function withAfterStatements(method:FrameworkMethod, test:Object, statement:IAsyncStatement):IAsyncStatement`

Parameters

| `method:FrameworkMethod`
| `test:Object`
| `statement:IAsyncStatement`

Returns

| `IAsyncStatement`

withBefores | () | method |

`protected function withBefores(method:FrameworkMethod, target:Object, statement:IAsyncStatement):IAsyncStatement`

Returns an `IAsyncStatement`: run all non-overridden `Before` methods on this class and superclasses before running `statement`; if any throws an Exception, stop execution and pass the exception on.

Parameters

| `method:FrameworkMethod`
| `target:Object`
| `statement:IAsyncStatement`

Returns

| `IAsyncStatement`

withDecoration | () | method |

`protected function withDecoration(method:FrameworkMethod, test:Object):IAsyncStatement`

Returns an `IAsyncStatement` that invokes `method` on a decorated `test`.

Parameters

| `method:FrameworkMethod`
| `test:Object`

Returns

| `IAsyncStatement`

withPotentialAsync | () | method |

`protected function withPotentialAsync(method:FrameworkMethod, test:Object, statement:IAsyncStatement):IAsyncStatement`

Returns an `IAsyncStatement`: if `method`'s `Test` annotation has the `async` attribute, throw an exception if `next` encounters an exception during execution.

Parameters

| `method:FrameworkMethod`
| `test:Object`
| `statement:IAsyncStatement`

Returns

| `IAsyncStatement`

withPotentialRules | () | method |

`protected function withPotentialRules(method:FrameworkMethod, test:Object, statement:IAsyncStatement):IAsyncStatement`

Potentially returns a new `IAsyncStatement` defined by the user on the testcase via the Rule metadata. This needs to be factored to a new class

Parameters

| `method:FrameworkMethod`
| `test:Object`
| `statement:IAsyncStatement`

Returns

| `IAsyncStatement`

withPotentialTimeout | () | method |

`protected function withPotentialTimeout(method:FrameworkMethod, test:Object, statement:IAsyncStatement):IAsyncStatement`

Returns an `IAsyncStatement`: if `method`'s `Test` annotation has the `timeout` attribute, throw an exception if `next` takes more than the specified number of milliseconds.

Parameters

| `method:FrameworkMethod`
| `test:Object`
| `statement:IAsyncStatement`

Returns

| `IAsyncStatement`

withStackManagement | () | method |

`protected function withStackManagement(method:FrameworkMethod, test:Object, statement:IAsyncStatement):IAsyncStatement`

Returns an `IAsyncStatement` that manages the stack and allow execution to break across frames.

Parameters

| `method:FrameworkMethod`
| `test:Object`
| `statement:IAsyncStatement`

Returns

| `IAsyncStatement`

Thu Apr 10 2014, 08:07 AM +10:00