QUnit.config

Order

Configurations are read in the following order:

  1. Default values
  2. Flat preconfig
  3. Object preconfig
  4. Runner options (URL parameters in the HTML Reporter, or CLI options in the QUnit CLI)
  5. Set QUnit.config from your own inline or bootstrap script.

Set configuration

You can configure the test run via the QUnit.config object. In the HTML Runner, you can set the configuration from any script after qunit.js:

<!DOCTYPE html>
<head>
  <meta charset="utf-8">
  <title>QUnit</title>
  <link rel="stylesheet" href="/lib/qunit/qunit.css">
</head>
<body>
  <div id="qunit"></div>
  <script src="/lib/qunit/qunit.js"></script>
  <script>
  QUnit.config.reorder = false;
  </script>
  <script src="/src/app.js"></script>
  <script src="/test/bootstrap.js"></script>
  <script src="/test/app.test.js"></script>
</body>

If you have custom plugins or want to re-use your configuration across multiple HTML test suites, you can also configure your project from an external /test/bootstrap.js script. Make sure to place this script before your other test files.

When using the QUnit CLI, you can setup your project and configure QUnit via --require.

qunit --require ./test/bootstrap.js

// test/bootstrap.js
QUnit.config.noglobals = true;
QUnit.config.notrycatch = true;

const MyApp = require('../');
MyApp.setAccount('TestUser');

Preconfiguration

Preconfiguration allows you to define QUnit configuration via global variables or environment variables, before QUnit itself is loaded.

This is the recommended approach for general purpose test runners and integrations, as it provides a reliable way to override the default configuration. This can be especially useful if the end-user may control the loading of QUnit, possibly asynchronously, or through custom means, where it would be difficult to inject your overrides at the “right” time (after QUnit loads, but before any user code).

Preconfig allows integrations to declare configuration without needing to embed, wrap, adapt, modify, or otherwise control the loading of QUnit itself. This in turn allows integrations to easily support use of standalone HTML test suites, that developers can also run and debug in the browser directly, without depending on or needing to install and set up any specific integration system.

Flat preconfig

Version added: QUnit 2.21.0.

Flat preconfig allows multiple integrations to seemlessly collaborate, without the risk of projects accidentally unsetting an override (as is the case with Object preconfig).

In the browser context (HTML Runner), global variables that start with qunit_config_ may override the default value of a configuration option. The following inline script (before loading QUnit), is equivalent to setting QUnit.config.hidepassed = true; QUnit.config.seed = 'd84af39036'; QUnit.config.testTimeout = 1000;

<script>
qunit_config_hidepassed = true;
qunit_config_seed = 'd84af39036';
qunit_config_testtimeout = 1000;
</script>

For the QUnit CLI and other Node.js runners, the same can also be done via environment variables. Environment variables must be set in the shell before running the qunit or node command. The variable names are case-sensitive and must be in lowercase. You may set boolean configuration variables using the string true or false.

export qunit_config_noglobals=true
export qunit_config_filter=foo
export qunit_config_testtimeout=1000

qunit test.js

Or:

qunit_config_filter=foo qunit_config_testtimeout=1000 qunit test.js

The environment variables can also make it easy to pass a parameter to QUnit from a child or nested command. For example, if you have several npm run shortcuts in package.json, like so:

{
  "scripts": {
    "test-something": "qunit_config_filter=something npm run test",
    "test": "npm run lint && qunit",
    "lint": "eslint --cache .",
    "lint-fix": "eslint --cache --fix ."
  }
}

Configuration options that are read-only, internal/undocumented, or that require an object value (such as QUnit.config.storage) cannot be set via environment variables. Options that require an array of strings will be converted to an array holding the given string.

Object preconfig

Version added: 2.1.0.

You can create a QUnit global variable with a config property, before QUnit itself is loaded. Any properties on this QUnit.config placeholder object will be carried over and applied to the real QUnit.config object once it exists. Any additional properties on the placeholder are ignored.

// Isomorphic global
// For modern browsers, SpiderMonkey, and Node.js (including strict mode).
globalThis.QUnit = {
  config: {
    autostart: false,
    maxDepth: 12
  }
};

// Browser global
// Supported in all browsers (including old browsers, and strict mode).
window.QUnit = { /* config: .. */ };

// Implicit global
// Supported everywhere, including old browsers. (But not ES strict mode.)
QUnit = { /* config: .. */ };

Changelog

QUnit 2.21.0 Added flat preconfig.
QUnit 2.18.1 Added object preconfig support for Node.js, SpiderMonkey, and other environments.
Previously, it was limited to the browser environment.
QUnit 2.1.0 Introduce object preconfig feature.

QUnit.config.altertitle

Insert a success or failure symbol in the document title.

QUnit.config.autostart

Control when the test run may start.

QUnit.config.collapse

Collapse the details of failing tests after the first one (HTML Reporter).

QUnit.config.current

Internal object representing the currently running test.

QUnit.config.failOnZeroTests

Fail the test run if no tests were run.

QUnit.config.filter

Select tests to run based on a substring or pattern match.

QUnit.config.fixture

Clean HTML playground before each test.

QUnit.config.hidepassed

Hide results of passed tests (HTML Reporter).

QUnit.config.maxDepth

The depth up-to which an object will be serialized during a diff (HTML Reporter).

QUnit.config.module

Select a single test module to run.

QUnit.config.moduleId

Select one or more modules to run, by their internal ID (HTML Reporter).

QUnit.config.modules

List of defined test modules.

QUnit.config.noglobals

Check the global object after each test and report new properties as failures.

QUnit.config.notrycatch

Disable handling of uncaught exceptions during tests.

QUnit.config.reorder

Prioritize re-running previously failed tests.

QUnit.config.requireExpects

Fail tests that don't specify how many assertions they expect.

QUnit.config.scrolltop

Scroll to the top of the page after the test run.

QUnit.config.seed

Enable randomized ordering of tests.

QUnit.config.storage

The Storage object to use for remembering failed tests between runs.

QUnit.config.testId

Select one or more tests to run, by their internal ID (HTML Reporter).

QUnit.config.testTimeout

Default timeout for async tests.

QUnit.config.urlConfig

Register additional input fields in the toolbar (HTML Reporter).