{"id":11619,"library":"qunit","title":"QUnit","description":"QUnit is a widely adopted, powerful, and easy-to-use JavaScript testing framework, providing a clear and efficient API for writing unit and integration tests. Originally developed to test the jQuery library, it has significantly matured into a versatile, standalone solution compatible with modern JavaScript applications across various environments, including Node.js (version 10+) and web browsers. The framework is currently stable at version 2.25.0, with an active release cadence that frequently introduces new features and improvements, often focusing on developer experience and compliance with modern JavaScript ecosystems. A significant upcoming release, 3.0.0-rc1, is already available, introducing native ES module (ESM) distribution, which is automatically utilized by Node.js when using `import` statements, marking a key modernization step for module resolution. QUnit's core philosophy centers on simplicity and clarity, which is evident in its direct assertion style, intuitive modular test organization with `QUnit.module()`, programmatic test filtering capabilities via `QUnit.config.testFilter`, and robust support for both synchronous and complex asynchronous testing patterns. It consistently focuses on clear test reporting and comprehensive TAP compliance, ensuring seamless integration with various Continuous Integration/Continuous Deployment (CI/CD) pipelines and test runners.","status":"active","version":"2.25.0","language":"javascript","source_language":"en","source_url":"git://github.com/qunitjs/qunit","tags":["javascript","testing","unit","assert","assertion","tap","tape","karma","jquery"],"install":[{"cmd":"npm install qunit","lang":"bash","label":"npm"},{"cmd":"yarn add qunit","lang":"bash","label":"yarn"},{"cmd":"pnpm add qunit","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const QUnit = require('qunit');\nQUnit.module('My Module', function() { /* ... */ });","symbol":"QUnit.module","correct":"import QUnit from 'qunit';\nQUnit.module('My Module', function() { /* ... */ });"},{"note":"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.","wrong":"const QUnit = require('qunit');\nQUnit.test('My Test', function(assert) { /* ... */ });","symbol":"QUnit.test","correct":"import QUnit from 'qunit';\nQUnit.test('My Test', function(assert) { /* ... */ });"},{"note":"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.","wrong":"import { assert } from 'qunit';","symbol":"assert","correct":"QUnit.test('My Test', function(assert) {\n  assert.equal(1, 1, 'Description');\n});"}],"quickstart":{"code":"import QUnit from 'qunit';\n\nQUnit.module('Calculator operations', function(hooks) {\n  let sum;\n\n  hooks.beforeEach(function(assert) {\n    sum = 0;\n    assert.step('beforeEach hook ran');\n  });\n\n  hooks.afterEach(function(assert) {\n    assert.step('afterEach hook ran');\n  });\n\n  QUnit.test('should correctly add two numbers', function(assert) {\n    sum = 5 + 3;\n    assert.strictEqual(sum, 8, '5 + 3 should be 8');\n    assert.ok(sum > 0, 'Sum should be positive');\n    assert.verifySteps(['beforeEach hook ran']); // Verify beforeEach ran before assertions\n  });\n\n  QUnit.test('should handle asynchronous addition', function(assert) {\n    const done = assert.async();\n    setTimeout(() => {\n      sum = 10 + 20;\n      assert.strictEqual(sum, 30, '10 + 20 should be 30 after async wait');\n      done();\n    }, 50);\n    assert.verifySteps(['beforeEach hook ran']);\n  });\n\n  QUnit.test('should handle zero gracefully', function(assert) {\n    sum = 0 + 0;\n    assert.strictEqual(sum, 0, '0 + 0 should be 0');\n  });\n});\n\n// To run this example:\n// 1. Install QUnit: `npm install qunit`\n// 2. Save the code above as `test.js` in your project.\n// 3. Add `\"type\": \"module\"` to your `package.json` to enable ESM in Node.js.\n// 4. Run your tests from the terminal: `npx qunit test.js`","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0-rc1"},{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0-rc1"},{"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.","message":"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.","severity":"deprecated","affected_versions":">=2.21.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The QUnit library has not been loaded or imported correctly into the JavaScript environment where tests are being run.","error":"ReferenceError: QUnit is not defined"},{"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.","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)`.","error":"Assertion Failed: Expected N assertions, but M were run"},{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'test')"}],"ecosystem":"npm"}