QUnit.on()

version added: 2.2.0.

Description

QUnit.on( eventName, callback )

Register a callback that will be invoked after the specified event is emitted.

This API is the primary interface for QUnit reporters, plugins, and continuous integration support. It is based on the js-reporters CRI standard.

The runStart event

The runStart event indicates the beginning of a test run. It is emitted exactly once, and before any other events.

QUnit.on('runStart', runStart => {
  console.log(`Test plan: ${runStart.testCounts.total}`);
});

The suiteStart event

The suiteStart event indicates the beginning of a module. It is eventually be followed by a corresponding suiteEnd event.

QUnit.on('suiteStart', suiteStart => {
  console.log('suiteStart', suiteStart);
  // name: 'my module'
  // fullName: ['grandparent', 'parent', 'my module']
});

The suiteEnd event

The suiteEnd event indicates the end of a module. It is emitted after its corresponding suiteStart event.

QUnit.on('suiteEnd', suiteEnd => {
  console.log(suiteEnd);
  // …
});

The testStart event

The testStart event indicates the beginning of a test. It is eventually followed by a corresponding testEnd event.

QUnit.on('testStart', testStart => {
  console.log(testStart);
  // name: 'my test'
  // moduleName: 'my module'
  // fullName: ['parent', 'my module', 'my test']

  // name: 'global test'
  // moduleName: null
  // fullName: ['global test']
});

The testEnd event

The testEnd event indicates the end of a test. It is emitted after its corresponding testStart event.

Properties of a testEnd object:

Properties of a FailedAssertion object:

QUnit.on('testEnd', testEnd => {
  if (testEnd.status === 'failed') {
    console.error('Failed! ' + testEnd.fullName.join(' > '));
    testEnd.errors.forEach(assertion => {
      console.error(assertion);
      // message: speedometer
      // actual: 75
      // expected: 88
      // stack: at dmc.test.js:12
    });
  }
});

The runEnd event

The runEnd event indicates the end of a test run. It is emitted exactly once.

The runEnd event has memory (since QUnit 3.0). This means listening for this event is possible, even if the event already fired. For example, if you build an integration system that automates running tests in a browser, and are unable to reliably inject a listener before tests have finished executing. You can attach a late event listeners for the runEnd event. These will be invoked immediately in that case. This removes the need for HTML scraping.

QUnit.on('runEnd', runEnd => {
  console.log(`Passed: ${runEnd.passed}`);
  console.log(`Failed: ${runEnd.failed}`);
  console.log(`Skipped: ${runEnd.skipped}`);
  console.log(`Todo: ${runEnd.todo}`);
  console.log(`Total: ${runEnd.total}`);
});

The error event

Version added: QUnit 2.17.0.

The error event notifies plugins of uncaught global errors during a test run.

See also QUnit.onUncaughtException() which is where you can report your own uncaught errors.

The error event has memory (since QUnit 3.0). This means listening for this event is possible, even if the event already fired. This improves reliability of reporters in browser automations, where it might be difficult to reliably inject a listener between qunit.js and anything else.

QUnit.on('error', error => {
  console.error(error);
});

Reporter API

The QUnit CLI accepts a --reporter option that loads a reporter from a Node module (e.g. npm package). Such module must export an init function, which QUnit will call and pass the QUnit object, which you can then use to call QUnit.on(). This contract is known as the Reporter API.

You can implement your reporter either as simply an exported function, or as a class with a static init method.

Example: Reporter class

class MyReporter {
  static init (QUnit) {
    return new MyReporter(QUnit);
  }

  constructor (QUnit) {
    QUnit.on('error', this.onError.bind(this));
    QUnit.on('testEnd', this.onTestEnd.bind(this));
    QUnit.on('runEnd', this.onRunEnd.bind(this));
  }

  onError (error) {
  }

  onTestEnd (testEnd) {
  }

  onRunEnd (runEnd) {
  }
}

// CommonJS, or ES Module
module.exports = MyReporter;
export default MyReporter;

Example: Reporter function

function init (QUnit) {
  QUnit.on('error', onError);
  QUnit.on('testEnd', onTestEnd);
  QUnit.on('runEnd', onRunEnd);

  function onError (error) {
  }
  function onTestEnd (testEnd) {
  }
  function onRunEnd (runEnd) {
  }
}

// CommonJS, or ES Module
module.exports.init = init;
export { init };