Runner - Documentation

new Runner(suite, optsopt)

Source:

runner.js, line 186

Initialize a Runner at the Root Suite, which represents a hierarchy of Suites and Tests.

Parameters:

Name Type Attributes Description

suite

Suite

Root suite

opts

Object

Settings object

Properties

Name	Type	Attributes	Description
`cleanReferencesAfterRun`	boolean	<optional>	Whether to clean references to test fns and hooks when a suite is done.
`delay`	boolean	<optional>	Whether to delay execution of root suite until ready.
`dryRun`	boolean	<optional>	Whether to report tests without running them.
`failZero`	boolean	<optional>	Whether to fail test run if zero tests encountered.

Extends

external:EventEmitter

Members

(static, readonly) constants :string

Source:

runner.js, line 94

Properties:

Name	Type	Description
`EVENT_HOOK_BEGIN`	string	Emitted when Hook execution begins
`EVENT_HOOK_END`	string	Emitted when Hook execution ends
`EVENT_RUN_BEGIN`	string	Emitted when Root Suite execution begins (all files have been parsed and hooks/tests are ready for execution)
`EVENT_DELAY_BEGIN`	string	Emitted when Root Suite execution has been delayed via `delay` option
`EVENT_DELAY_END`	string	Emitted when delayed Root Suite execution is triggered by user via `global.run()`
`EVENT_RUN_END`	string	Emitted when Root Suite execution ends
`EVENT_SUITE_BEGIN`	string	Emitted when Suite execution begins
`EVENT_SUITE_END`	string	Emitted when Suite execution ends
`EVENT_TEST_BEGIN`	string	Emitted when Test execution begins
`EVENT_TEST_END`	string	Emitted when Test execution ends
`EVENT_TEST_FAIL`	string	Emitted when Test execution fails. Includes an `err` object of type `Error`.
`EVENT_TEST_PASS`	string	Emitted when Test execution succeeds
`EVENT_TEST_PENDING`	string	Emitted when Test becomes pending
`EVENT_TEST_RETRY`	string	Emitted when Test execution has failed, but will retry
`STATE_IDLE`	string	Initial state of Runner
`STATE_RUNNING`	string	State set to this value when the Runner has started running
`STATE_STOPPED`	string	State set to this value when the Runner has stopped

Runner-related constants. Used by reporters. Each event emits the corresponding object, unless otherwise indicated.

Type:

string

Example

const Mocha = require('mocha');
const Base = Mocha.reporters.Base;
const {
  EVENT_HOOK_BEGIN,
  EVENT_TEST_PASS,
  EVENT_TEST_FAIL,
  EVENT_TEST_END
} = Mocha.Runner.constants

function MyReporter(runner, options) {
  Base.call(this, runner, options);

  runner.on(EVENT_HOOK_BEGIN, function(hook) {
    console.log('hook called: ', hook.title);
  });

  runner.on(EVENT_TEST_PASS, function(test) {
    console.log('pass: %s', test.fullTitle());
  });

  runner.on(EVENT_TEST_FAIL, function(test, err) {
    console.log('fail: %s -- error: %s', test.fullTitle(), err.message);
  });

  runner.on(EVENT_TEST_END, function() {
    console.log('end: %d/%d', runner.stats.passes, runner.stats.tests);
  });
}

module.exports = MyReporter;

_eventListeners :Map:.<EventEmitter:, Map:.<string:, Set:.<EventListener:>>>

Source:

runner.js, line 200

Type:

Map:.<EventEmitter:, Map:.<string:, Set:.<EventListener:>>>

Methods

abort() → {Runner}

Source:

runner.js, line 1196

Cleanly abort execution.

Returns:

Runner instance.

Type: Runner

dispose()

Source:

runner.js, line 319

Removes all event handlers set during a run on this instance.
Remark: this does not clean/dispose the tests or suites themselves.

globals(arr) → {Runner}

Source:

runner.js, line 403

Allow the given arr of globals.

Parameters:

Name	Type	Description
`arr`	Array

Returns:

Runner instance.

Type: Runner

grep(re, invert) → {Runner}

Source:

runner.js, line 341

Run tests with full titles matching re. Updates runner.total
with number of tests matched.

Parameters:

Name	Type	Description
`re`	RegExp
`invert`	boolean

Returns:

Runner instance.

Type: Runner

grepTotal(suite) → {number}

Source:

runner.js, line 358

Returns the number of tests matching the grep search for the
given suite.

Parameters:

Name	Type	Description
`suite`	Suite

Returns:

Type: number

isParallelMode() → {false}

Source:

runner.js, line 1210

Returns true if Mocha is running in parallel mode. For reporters.

Subclasses should return an appropriate value.

Returns:

Type: false

(abstract) linkPartialObjects(valueopt) → {Runner}

Source:

runner.js, line 1171

Toggle partial object linking behavior; used for building object references from
unique ID's. Does nothing in serial mode, because the object references already exist.
Subclasses can implement this (e.g., ParallelBufferedRunner)

Example

// this reporter needs proper object references when run in parallel mode
class MyReporter {
  constructor(runner) {
    runner.linkPartialObjects(true)
      .on(EVENT_SUITE_BEGIN, suite => {
        // this Suite may be the same object...
      })
      .on(EVENT_TEST_BEGIN, test => {
        // ...as the `test.parent` property
      });
  }
}

Parameters:

Name	Type	Attributes	Description
`value`	boolean	<optional>	If `true`, enable partial object linking, otherwise disable

Returns:

Type: Runner

run(fn, optsopt) → {Runner}

Source:

runner.js, line 1078

Run the root suite and invoke fn(failures)
on completion.

Parameters:

Name	Type	Attributes	Description
`fn`	function		Callback when finished
`opts`	RunnerOptions	<optional>	For subclasses

Returns:

Runner instance.

Type: Runner

(abstract) workerReporter(path) → {Runner}

Source:

runner.js, line 1224

Configures an alternate reporter for worker processes to use. Subclasses
using worker processes should implement this.

Parameters:

Name	Type	Description
`path`	string	Absolute path to alternate reporter for worker processes to use

Throws:

When in serial mode

Returns:

Type: Runner