QUnit.config.autostart

version added: 1.0.0.

Description

Control when the test run may start, e.g. after asynchronously loading test files with RequireJS, AMD, ES6 dynamic imports, or other means.

In the browser, QUnit by default waits for all <script> elements to finish loading (by means of the window load event). When using the QUnit CLI, it waits until the specified files are imported.

Set this property to false to instruct QUnit to wait longer, allowing you to load test files asynchronously. Remember to call QUnit.start() once you’re ready for tests to begin running.

Error: Unexpected test after runEnd

If you define new tests after QUnit has finished its run, you may encounter this error:

Error: Unexpected test after runEnd.

If you load test files asynchronously, make sure to disable autostart and call QUnit.start() accordingly (examples).

If you encounter this error unrelated to autostart, you might be dynamically registering a QUnit.test from inside a hook or event callback towards the end of the test run, such as hooks.after() or QUnit.done(). It is recommended to define such tests via QUnit.begin() instead. (#1663)

To report global errors from a plugin or other integration layer, consider calling QUnit.onUncaughtException() instead.

Examples

ESM Dynamic imports

This example uses the import() operator to dynamically load ECMAScript module (ESM) files.

<script src="../lib/qunit.js"></script>
<script type="module" src="tests.js"></script>

// tests.js
QUnit.config.autostart = false;

Promise.all([
  import('./foo.js'),
  import('./bar.js')
]).then(function () {
  QUnit.start();
});

Loading with RequireJS

This example uses RequireJS to load your test files through the require() function (as defined in the AMD specification).

It is recommended to load QUnit itself before RequireJS. See also RequireJS wiki.

<!DOCTYPE html>
<meta charset="utf-8">
<title>QUnit</title>
<link rel="stylesheet" href="./lib/qunit.css">
<body>
  <div id="qunit"></div>
  <script src="../lib/qunit.js"></script>
  <script src="../lib/requirejs/require.js"></script>
  <script src="tests.js"></script>
</body>

// tests.js
QUnit.config.autostart = false;

require(
  [
    'tests/testModule1',
    'tests/testModule2'
  ],
  function () {
    QUnit.start();
  }
);

Migration: UMD-defined QUnit plugin

QUnit 3.0 and later no exports the QUnit API via AMD.

If you define a QUnit plugin through a UMD factory, it is recommended to remove the UMD wrapper and use the QUnit global directly. So long as projects load qunit.js before RequireJS (per the above) this maintains backwards compatibility, because the QUnit global is unconditionally available in browser environments in both QUnit 2 and QUnit 3.

Before:

(function (factory) {
  if (typeof define === 'function' && define.amd) {
    require(['qunit'], factory);
  } else {
    factory(QUnit);
  }
}(function (QUnit) {
  QUnit.on('runEnd', function () {
    console.log('QUnit complete', runEnd.status);
  });
}));

After:

(function () {
  QUnit.on('runEnd', function (runEnd) {
    console.log('QUnit complete', runEnd.status);
  });
}());

NOTE: QUnit 2.x had edge case where if you (or your users) load qunit.js with RequireJS, and you run this outside a browser (e.g. in Node.js), then the QUnit API would be exclusively defined via AMD and the QUnit global remained undefined. This is fixed in QUnit 3.0.

If you need to maintain compatibility with this QUnit 2 edge case, you can check for the global first. This way your plugin won’t require an undefined qunit module with QUnit 3:

(function (factory) {
  if (typeof define === 'function' && define.amd && !globalThis.QUnit) {
    require(['qunit'], factory);
  } else {
    factory(QUnit);
  }
}(function (QUnit) {
  QUnit.on('runEnd', function () {
    console.log('QUnit complete', runEnd.status);
  });
}));