QUnit

Common errors

• ReferenceError: QUnit is not defined

  cause The QUnit library has not been loaded or imported correctly into the JavaScript environment where tests are being run.
  fix Ensure `qunit` is installed (`npm install qunit`). In Node.js, verify that `import QUnit from 'qunit';` (for ESM, v3+) or `require('qunit');` (for CJS) is at the top of your test runner or test files. In a browser, confirm that the `<script src="qunit.js"></script>` tag is correctly placed before your test scripts in the HTML.

• Assertion Failed: Expected N assertions, but M were run

  cause This error occurs when the number of `assert` method calls executed within a test (`M`) does not match the count explicitly specified by `assert.expect(N)`.
  fix It is often best to remove `assert.expect()` entirely as it can be brittle and is often unnecessary with modern test practices. If retained, meticulously adjust the `N` value passed to `assert.expect()` to precisely reflect the actual number of `assert` method calls that will execute in the test, keeping in mind the change in behavior for `assert.step()` in v3.

• TypeError: Cannot read properties of undefined (reading 'test')

  cause This error indicates that you are attempting to call methods like `QUnit.test()` or `QUnit.module()` on an `undefined` `QUnit` object, which typically means `QUnit` itself was not properly imported or made globally available.
  fix This problem shares the same root cause as 'ReferenceError: QUnit is not defined'. Double-check your QUnit import statements (ESM `import` for v3+ Node.js, or CJS `require` for older Node/CJS contexts) or verify script tag inclusion for browser-based testing.

Warnings

• breaking QUnit v3.0 introduces native ES module (ESM) support in Node.js. Projects currently using CommonJS `require()` statements for QUnit will need to adapt to `import` statements or ensure their Node.js environment is configured to handle CommonJS modules explicitly.
  Fix: For Node.js projects, update imports to `import QUnit from 'qunit';` and ensure `"type": "module"` is present in your `package.json` file. Alternatively, use `.cjs` file extensions for files that must remain CommonJS.
• breaking With QUnit v3.0, module context is now passed to `before` and `after` hooks. This changes how inheritance between parent and child modules behaves and addresses previous state leakage issues.
  Fix: Review existing `before` and `after` hook implementations, especially in nested module structures, to ensure their behavior aligns with the new context inheritance model. Adjust any logic that might have relied on the previous behavior or unintentional state sharing.
• deprecated The counting behavior of `assert.expect()` when combined with `assert.verifySteps()` is changing. In QUnit v3, `assert.expect()` will no longer implicitly count `assert.step()` calls towards the expected assertion total.
  Fix: For tests that use both `assert.expect()` and `assert.verifySteps()`, you will need to adjust the value passed to `assert.expect()` to exclude the number of `assert.step()` calls. Monitor QUnit v3 documentation for the final specification on this change.
• gotcha Asynchronous tests must explicitly signal their completion using either `assert.async()` with `done()` callbacks or by returning a Promise from the test function. Failure to do so will cause the test to finish prematurely, often resulting in false positives.
  Fix: For callback-based asynchronous operations, obtain a `done` callback using `const done = assert.async();` at the start of the test and invoke `done();` once all asynchronous operations have completed. For Promise-based asynchronous operations, simply return the Promise from the test function.

Install

• npm install qunit npm
• yarn add qunit yarn
• pnpm add qunit pnpm

Imports

• QUnit.module
  wrong:

  const QUnit = require('qunit');
  QUnit.module('My Module', function() { /* ... */ });

  correct:

  import QUnit from 'qunit';
  QUnit.module('My Module', function() { /* ... */ });

  Since QUnit v3.0, native ES module (ESM) imports are the preferred way to use QUnit in Node.js. For browser environments, QUnit is typically available globally after loading the script via `<script>` tag.
• QUnit.test
  wrong:

  const QUnit = require('qunit');
  QUnit.test('My Test', function(assert) { /* ... */ });

  correct:

  import QUnit from 'qunit';
  QUnit.test('My Test', function(assert) { /* ... */ });

  Used to define individual test cases within a module. The `assert` object, containing all assertion methods, is passed as the first argument to the test callback function.
• assert
  wrong:

  import { assert } from 'qunit';

  correct:

  QUnit.test('My Test', function(assert) {
    assert.equal(1, 1, 'Description');
  });

  The `assert` object is provided as an argument to test and hook callbacks (e.g., `beforeEach`, `afterEach`). It is not imported directly from the `qunit` package.

Quickstart

Demonstrates defining a QUnit module, utilizing `beforeEach` and `afterEach` hooks, writing both synchronous and asynchronous test cases, and employing various QUnit assertion methods. This example is set up to run using native ES modules in a Node.js environment.

import QUnit from 'qunit';

QUnit.module('Calculator operations', function(hooks) {
  let sum;

  hooks.beforeEach(function(assert) {
    sum = 0;
    assert.step('beforeEach hook ran');
  });

  hooks.afterEach(function(assert) {
    assert.step('afterEach hook ran');
  });

  QUnit.test('should correctly add two numbers', function(assert) {
    sum = 5 + 3;
    assert.strictEqual(sum, 8, '5 + 3 should be 8');
    assert.ok(sum > 0, 'Sum should be positive');
    assert.verifySteps(['beforeEach hook ran']); // Verify beforeEach ran before assertions
  });

  QUnit.test('should handle asynchronous addition', function(assert) {
    const done = assert.async();
    setTimeout(() => {
      sum = 10 + 20;
      assert.strictEqual(sum, 30, '10 + 20 should be 30 after async wait');
      done();
    }, 50);
    assert.verifySteps(['beforeEach hook ran']);
  });

  QUnit.test('should handle zero gracefully', function(assert) {
    sum = 0 + 0;
    assert.strictEqual(sum, 0, '0 + 0 should be 0');
  });
});

// To run this example:
// 1. Install QUnit: `npm install qunit`
// 2. Save the code above as `test.js` in your project.
// 3. Add `"type": "module"` to your `package.json` to enable ESM in Node.js.
// 4. Run your tests from the terminal: `npx qunit test.js`