QUnit.config


QUnit.config

Description: Configuration for QUnit

  • QUnit.config

    • altertitle (default: true)
      Type: Boolean

      By default, QUnit updates document.title to add a checkmark or x-mark to indicate if a testsuite passed or failed. This makes it easy to see a suites result even without looking at a tab's content.

      If you're dealing with code that tests document.title changes or have some other problem with this feature, set this option to false to disable it.

    • autostart (default: true)
      Type: Boolean

      By default, QUnit runs tests when load event is triggered on the window. If you're loading tests asynchronously, you can set this property to false, then call QUnit.start() once everything is loaded. See below for an example.

    • collapse (default: true)
      Type: Boolean

      By default, QUnit's HTML reporter collapses consecutive failing tests showing only the details for the first failed test. The other tests can be expanded manually with a single click on the test title. Setting this value to false will expand the details for every failing test.

    • current
      Type: Object

      This object isn't actually a configuration property, but is listed here anyway, as its exported through QUnit.config. This gives you access to some QUnit internals at runtime. See below for an example.

    • filter (default: undefined)
      Type: String

      Allows you to filter which tests are run by matching the module name and test title against the provided string. You can do an inverse filter, matching all tests that don't contain the string, by prefixing a ! to the value.

      You can also match via a regular expression by passing in a string version of the regular expression literal, such as /(this|that)/i.

    • fixture (default: undefined)
      Type: String

      Defines the HTML content to use in the fixture container which is reset at the start of each test.

      By default QUnit will use whatever the starting content of #quint-fixture is as the fixture reset. If you do not want the fixture to be reset in between tests, set the value to null.

    • hidepassed (default: false)
      Type: Boolean

      By default, the HTML Reporter will show all the tests results. Enabling this option will make it show only the failing tests, hiding all that pass. This can also be managed by the HTML interface.

    • maxDepth (default: 5)
      Type: Number

      Specifies the depth up-to which an object will be dumped during a diff. To run without a max depth, use a value of -1.

    • module (default: undefined)
      Type: String

      Specify a single module to run by name (exact case-insensitive match required). By default, QUnit will run all the loaded modules when this property is not specified.

      This property was absent in versions 1.16.0 through 1.22.0.

    • moduleId (default: undefined)
      Type: Array

      This property allows QUnit to run specific modules identified by the hashed version of their module name. You can specify one or multiple modules to run.

    • notrycatch (default: false)
      Type: Boolean

      By default, QUnit will run tests within a `try-catch` block to prevent uncaught exceptions from crashing the entire test suite.

      Enabling this flag will run tests without the `try-catch` to allow exceptions to remain uncaught for easier debugging in certain environments.

    • noglobals (default: false)
      Type: Boolean

      Enabling this flag will cause QUnit to check if any new properties have been added to the global context after each test. New global properties being found will result in test failures to help ensure your tests are not leaking state.

    • seed (default: undefined)
      Type: String

      This property tells QUnit to run tests in a seeded-random order. The value provided will be used as the seed in a pseudo-random number generator to ensure that results are reproducible. The randomization will also respect the `reorder` option if enabled and re-run failed tests first without randomizing them.

      Randomly ordering your tests can help identify non-atomic tests which either depend on a previous test or are leaking state to following tests. This is particularly beneficial in a development CI or post-commit process.

      If seed is specified in the page's url parameters, but no value is specified, then QUnit will generate a random value to use as the seed. You can access the value from this property and use it to repeat the same sequence in another run.

    • storage (default: sessionStorage)
      Type: Object

      Defines the storage object used to record failed tests between runs. The object must implement the Storage interface of the Web Storage API.

      Defaults to the global sessionStorage if defined.

    • reorder (default: true)
      Type: Boolean

      By default, QUnit will run tests first that failed on a previous run. In a large testsuite, this can speed up testing a lot.

      It can also lead to random errors, in case your testsuite has non-atomic tests, where the order is important. You should fix those issues, instead of disabling reordering!

      When a failed test is running first, Rerunning previously failed test is displayed in the summary whereas just Running is displayed otherwise.

    • requireExpects (default: false)
      Type: Boolean

      The expect() method is optional by default, though it can be useful to require each test to specify the number of expected assertions.

      Enabling this option will cause tests to fail, if they don't call expect() at all.

    • testId (default: undefined)
      Type: Array

      This property allows QUnit to run specific tests identified by the hashed version of their module name and test name. You can specify one or multiple tests to run.

    • testTimeout (default: undefined)
      Type: Number

      Specify a global timeout in milliseconds after which all tests will fail with an appropriate message. Useful when async tests aren't finishing, to prevent the testrunner getting stuck. Set to something high, e.g. 30000 (30 seconds) to avoid slow tests to time out by accident.

    • scrolltop (default: true)
      Type: Boolean

      By default, scroll to top of the page when suite is done. Setting this to false will leave the page scroll alone.

    • urlConfig
      Type: Array

      This property controls which form controls to put into the QUnit toolbar element (below the header). By default, the "noglobals" and "notrycatch" checkboxes are there. By extending this array, you can add your own checkboxes and select lists.

      Each element should be an object with an id property (used as the config and query-string key) and a label property (used as text in the UI), and optionally a tooltip property (used as the title attribute to explain what the control does). Each element should also have a value property controlling available options and rendering.

      If value is undefined, the option will render as a checkbox. The corresponding URL parameter will be set to "true" when the checkbox is checked, and otherwise will be absent.

      If value is a string, the option will render as a checkbox. The corresponding URL parameter will be set to the string when the checkbox is checked, and otherwise will be absent.

      If value is an array, the option will render as a select-one with an empty first option, followed by an option for each element of the array, with text and value matching the element. The corresponding URL parameter will be absent when the empty option is selected, and otherwise will be set to the value of the selected array element.

      If value is an object, the option will render as a select-one with an empty first option, followed by an option for each property of the object, with text and value matching the name and value (respectively) of the property. The corresponding URL parameter will be absent when the empty option is selected, and otherwise will be set to the value of the selected object property.

      See also the two examples below.

QUnit has a bunch of internal configuration defaults, some of which are useful to override. Check the description for each option for details.

Examples:

Disable autostart, useful when loading tests asynchronsly, here using requirejs:

1
2
3
4
5
6
7
QUnit.config.autostart = false;
require(
[ "tests/testModule1", "tests/testModule2" ],
function() {
QUnit.start();
}
);

Access QUnit.config.current.testName to pass the current test's name on to another tool

1
2
3
4
5
QUnit.test("some test", function() {
// a few regular assertions
// then a call to another tool
speedTest( QUnit.config.current.testName, codeUnderTest );
});

Add a new checkbox to the toolbar, using the urlConfig property. This assumes there's other code on the page that will check the QUnit.config.min property to react to the selection.

1
2
3
4
5
QUnit.config.urlConfig.push({
id: "min",
label: "Minified source",
tooltip: "Load minified source files instead of the regular unminified ones."
});

Add a dropdown to the toolbar, using the urlConfig property. This assumes there's other code on the page that will check the QUnit.config.jquery property to react to the selection, loading the appropiate jQuery Core version.

1
2
3
4
5
6
QUnit.config.urlConfig.push({
id: "jquery",
label: "jQuery version",
value: [ "1.7.2", "1.8.3", "1.9.1" ],
tooltip: "What jQuery Core version to test against"
});