MochaRunner

About

This class is a subclass of MochaSuite that initiates a test run.

NOTE

MochaRunner will work with a compiled project, but requires access to the host project source files in order to run tests.

API

constructor()

constructor(cs : Object { ; options : Object })

Creates a new MochaRunner instance and runs the specified tests. cs should be the class store of the host project.

The options object, if passed, may contain the following properties:

Property	Description	Default
.include	A pattern specifying the test classes to include	"test"
.exclude	A pattern specifying the test classes to exclude	""
.grep	A pattern specifying the test functions to include/exclude	""
.invert	If true, `.grep` excludes	false
.reporter	The reporter delegate class	`cs.js.MochaHtmlReporter`
.reporterOptions	Options for the reporter delegate class	`{}`
.bdd	The assertion class	`cs.js.ChaiBdd`
.showProgress	If true, a progress dialog is displayed	true

Selecting classes

The .include and .exclude properties are used to select the test classes to run.

By default, all classes in the test Explorer folder are run. To specify a different set of folders, pass a comma-delimited list of folder names in the .include property. White space around the comma is ignored.

For example, to select all classes in the test and test2 folders, use:

$options:=New object("include"; "test, test2")
cs.js.MochaRunner.new(cs; $options)

You can select only specific classes within a folder by adding a glob, separated from the folder name by /.

You can filter out specific classes that were selected by .include by passing a comma-delimited list of globs in the .exclude property. White space around the comma is ignored.

Globs

If a glob begins and ends with "/" and has at least one character in between, the portion between "/" is used as a regular expression patternopen in new window and regex matching is performed. Remember that regex matching is case-sensitive by default.

Otherwise regular case-insensitive string matching using = is performed. The string may contain 4D wildcards (@) to do partial matching.

For example, let’s say you have the following class structure in the Home view of the Explorer:

test
  FooTest
  FoobarTest
  BazTest
test2
  BarTest
  QuuxTest

To include only the classes in the test folder that begin with "Foo", you could do this:

$options:=New object("include"; "test/Foo@, test2")
cs.js.MochaRunner.new(cs; $options)

To include only classes in the test folder that begin with "Foo" or "Baz", you could use a regular expression:

$options:=New object("include"; "test/^(Foo|Bar)/", test2")
cs.js.MochaRunner.new(cs; $options)

To include all classes in either folder except those which begin with "Foo" or "Bar", you could do this:

$options:=New object()
$options.include:="test, test2"
$options.exclude:="foo@, bar@"  // case-insensitive partial matching
cs.js.MochaRunner.new(cs; $options)

Alternatively, you could use a single regular expression to do the same thing:

$options:=New object()
$options.include:="test, test2"
$options.exclude:="/^(Foo|Bar)/"  // case-sensitive matching
cs.js.MochaRunner.new(cs; $options)

On the other hand, if your convention is to prefix test classes with "Test", like this:

test
  TestFoo
  TestBaz
test2
  TestBar
  TestQuux

To exclude all classes in either folder which end with "foo" or "bar", you could do either of the following:

$options:=New object()
$options.include:="test, test2"
$options.exclude:="@foo, @bar"  // case-insensitive partial matching
cs.js.MochaRunner.new(cs; $options)

// OR

$options.include:="test, test2"
$options.exclude:="/(Foo|Bar)$/"  // case-sensitive matching
cs.js.MochaRunner.new(cs; $options)

Selecting test functions

After the test classes have been selected, the .grep option, if non-empty, is used to specify a pattern to match against the test function names. The .invert option, if true, inverts the match.

Because all test function names must begin with the prefix "test", and what follows is usually the name of a function that is being tested, for the purposes of matching, the "test" prefix is stripped off and the following letter is lowercased. For example, if you have a test function named "testFoo", the pattern "foo" will match it.

The .grep option follows the same format as the .exclude option: it should be a comma-delimited list of strings which may be "/"-enclosed regular expression patterns or plain strings with optional wildcards. As with the .exclude option, white space around the comma is ignored.

For example, to run all test functions whose names begin with "testFoo" or "testBar", you could do either of the following:

// case-insensitive partial matching, "test" prefix is stripped off
$options:=New object("grep"; "foo@, bar@")
cs.js.MochaRunner.new(cs; $options)

// OR

// case-sensitive matching, "test" prefix is stripped off
$options:=New object("grep"; "/^(foo|bar)/")
cs.js.MochaRunner.new(cs; $options)

If instead you want to exclude all test functions whose names begin with "testFoo" or "testBar", you would do the same as above, but also set $options.invert:=True.

TIP

On a more granular level, you can also use MochaSuite.only()/MochaTest.only() and MochaSuite.skip()/MochaTest.skip() to select or exclude specific suites/tests.

Reporter options

The default reporter for the Mocha runner is cs.js.MochaHtmlReporter. It generates an interactive HTML report which is displayed in a dialog window when the tests are complete.

If you want to use a different reporter, you can specify its class in the .reporter property.

NOTE

.reporter must be a class, not an instance of a class.

The .reporter class should conform to the MochaReporterDelegate interface, and is responsible for outputting test results in some fashion. If the .reporter class constructor takes options, you can pass them in the .reporterOptions property.

Assertion library options

.bdd defines the class that is instantiated by .expect(), which in turn defines the set of assertions and syntax you can use in your tests. The default is cs.js.ChaiBdd.

Test run execution

When you instantiate MochaRunner, the test run begins. Execution proceeds as follows:

Using the criteria you specified (or the defaults) in the .include and .exclude properties, the test classes are selected. If the selection is empty, an alert is displayed and the test run is aborted. Otherwise, if the .showProgress option is true, a progress dialog is displayed after 300 ms.
For each selected test class, its source file is parsed to find all test functions. If the .grep option in non-empty, the test functions are then filtered using the .grep and .invert options.
For each selected test class, the runner instantiates a suite with the name of the class (minus any leading underscore and "Test" prefix or suffix) and instantiates the test class with that suite. The parent of that suite is the runner itself. If the test class instance has a .name property, that is used for the suite’s .title instead of the stripped class name.
After instantiating the test class, the runner calls each of the selected test functions, passing the test class’ suite as the parameter. The test function (provided by you) calls .describe() and .specify() or .should() to define the test suite and the tests that will be run in subsequent steps.
Starting with the root suite (which is the runner itself), the runner executes:
Any before all hooks. This happens only once.
For each test that is not excluded either explicitly by .skip() or implicitly by .only(), the runner executes:
1. Any before each hooks
2. The test (and reports the result)
3. Any after each hooks
If the current suite has a child suite, repeat steps 6 and 7 for each child suite that is not excluded either explicitly by .skip() or implicitly by .only(); each child suite inherits any before each and after each hooks defined in its parent.
Any after all hooks are executed. This happens only once.
If a progress dialog was visible, it is closed, and the .report() function of the registered reporter delegate class is called.

See .on() for a full list of the events that are emitted during the test run.

.afterAll()

.afterAll(func : Callable {; …funcN : Callable })

Sets the list of functions to call after all tests have been executed. The functions are called in the order they are passed to this function.

Within each function, This refers to the current test suite.

.beforeAll()

.beforeAll(func : Callable {; …funcN : Callable })

Sets the list of functions to call before all tests have been executed. The functions are called in the order they are passed to this function.

Within each function, This refers to the current test suite.

.on()

.on(event : Text; func : Callable)

Registers func to run when event occurs. This is primarily used by reporter delegates to listen to runner events and build the report.

At various points during a test run, the runner will emit the following events:

Event	Description
start	Execution of a test run started
end	Execution of a test run complete
suite	Test suite execution started
suite end	All tests (and sub-suites) have finished
test	Test execution started
test end	Test completed
hook	Hook is about to be executed
hook end	Hook has been executed
pass	Test passed
fail	Test failed

If event is not one of the above events, this function does nothing.

# MochaRunner

# About

# API

# constructor()

# Selecting classes

# Globs

# Selecting test functions

# Reporter options

# Assertion library options

# Test run execution

# .afterAll()

# .beforeAll()

# .on()