QUnit Test Runner for Node.js

Common errors

• Error: Cannot find module 'qunit'

  cause Attempting to install or `require` the `qunit` package when `node-qunit` is intended. `node-qunit` was previously named `qunit` before v1.0.0.
  fix `npm install node-qunit` and then `require("node-qunit")` in your code.

• ReferenceError: module is not defined

  cause Using `module()` directly in a QUnit test file. The global `module` keyword conflicts with Node.js's native `module` object.
  fix Use `QUnit.module()` instead, as `QUnit` is exposed globally by the test runner for defining test modules.

• SyntaxError: Named export 'testrunner' not found

  cause Attempting to import `node-qunit` using ES Module syntax (`import { testrunner } from 'node-qunit'`). The package is CommonJS-only.
  fix Change the import statement to CommonJS: `const testrunner = require("node-qunit");`.

• RangeError: Maximum call stack size exceeded

  cause A synchronous test, or an asynchronous test failing to complete its assertions within the configured `maxBlockDuration` (default 2000ms), causing the child process to be killed.
  fix Review the test for infinite loops, blocking operations, or long-running async tasks. If the test genuinely needs more time, increase `testrunner.options.maxBlockDuration` or the specific run's `maxBlockDuration`.

Warnings

• breaking Prior to version 1.0.0, this package was published under the name `qunit`. Users upgrading from older versions must change their package dependency from `qunit` to `node-qunit`.
  Fix: Update `package.json` to `"node-qunit": "^2.0.0"` and run `npm install`.
• breaking The `node-qunit` package name was previously used by a different, deprecated project that is now published under the name `qnit`. This can cause confusion if installing based on historical context.
  Fix: Ensure you are installing `node-qunit` for the QUnit test runner, and not `qnit` (the old project). Review your `package.json` dependencies carefully.
• gotcha When writing QUnit test files for `node-qunit`, the global `module` function is reserved by Node.js. You must use `QUnit.module()` instead to define test modules.
  Fix: Replace `module('My tests', ...)` with `QUnit.module('My tests', ...)` in your test files.
• gotcha This package is CommonJS-only and does not support ES Modules (`import`/`export`) syntax for its own API. Attempting to import `node-qunit` using ESM will result in an error.
  Fix: Use `const testrunner = require("node-qunit");` for importing the package.
• breaking This package is considered abandoned, with its last publish seven years ago (version 2.0.2). It is unlikely to receive further updates, bug fixes, or security patches. Usage in new projects is strongly discouraged.
  Fix: Consider migrating to actively maintained testing frameworks like Jest, Mocha, or the official QUnit CLI (which runs QUnit tests in Node.js via headless browsers like Puppeteer or Playwright).

Install

• npm install node-qunit npm
• yarn add node-qunit yarn
• pnpm add node-qunit pnpm

Imports

• testrunner
  wrong:

  import { testrunner } from 'node-qunit';

  correct:

  const testrunner = require("node-qunit");

  This package is CommonJS-only. Its last update was 7 years ago, pre-dating widespread Node.js ESM support.
• QUnit.module
  wrong:

  module('My tests', function() { /* ... */ });

  correct:

  QUnit.module('My tests', function() { /* ... */ });

  `QUnit` is exposed as a global object within the test files executed by `node-qunit`. The `module` keyword is reserved in Node.js, so `QUnit.module` must be used instead.
• QUnit.test

  QUnit.test('My test case', function(assert) { /* ... */ });

  `QUnit.test` is also exposed globally to test files, following the standard QUnit API for defining test cases.

Quickstart

Demonstrates how to programmatically run QUnit tests in Node.js, including setting up a simple code file and its corresponding test file using the `node-qunit` test runner API. This example creates temporary files to illustrate the `code` and `tests` configuration.

const testrunner = require("node-qunit");
const path = require("path");
const fs = require("fs");

// Define a simple code file to be tested
const codeFilePath = path.join(__dirname, "my-code.js");
fs.writeFileSync(codeFilePath, `
module.exports = {
  add: (a, b) => a + b,
  subtract: (a, b) => a - b
};
`);

// Define a simple test file using QUnit API
const testFilePath = path.join(__dirname, "my-tests.js");
fs.writeFileSync(testFilePath, `
QUnit.module('Calculator', function(hooks) {
  hooks.beforeEach(function(assert) {
    // Setup code if needed
  });

  QUnit.test('add function', function(assert) {
    const calculator = require('./my-code.js'); // Relative path needed for child process
    assert.equal(calculator.add(1, 2), 3, '1 + 2 should be 3');
  });

  QUnit.test('subtract function', function(assert) {
    const calculator = require('./my-code.js');
    assert.equal(calculator.subtract(5, 2), 3, '5 - 2 should be 3');
  });
});
`);

// Configure and run the tests
testrunner.run({
    code: codeFilePath,
    tests: testFilePath,
    log: {
        summary: true,
        errors: true,
        coverage: false // Assuming no istanbul setup for quickstart
    }
}, function(err, report) {
    if (err) {
        console.error("Test runner encountered an error:", err);
        process.exit(1);
    }
    console.log("Test Report:", JSON.stringify(report, null, 2));
    // Cleanup generated files
    fs.unlinkSync(codeFilePath);
    fs.unlinkSync(testFilePath);
    process.exit(report.globalSummary.failed > 0 ? 1 : 0);
});