Test Explorer for QUnit
See and run your QUnit tests in the VS Code Testing view. Every QUnit.module
becomes a group (nested modules too), every QUnit.test gets a run button in the editor gutter, and every failing
assertion is shown at the line where it failed, with an expected/actual diff.
The extension runs the QUnit command-line runner (qunit) that is already installed in your project, with the
Node.js on your machine. Nothing is uploaded anywhere, and your QUnit setup is not changed.
Features
- Modules and tests appear without running anything. Files that match the
qunitTestExplorer.files patterns
(by default test/**/*.{js,mjs,cjs}, the same default as the qunit command) and use QUnit are read as you type.
These are recognised:
QUnit.module('name', function (hooks) { ... }), with hooks and nested modules inside;
QUnit.module('name', { beforeEach() {} }, function () { ... });
QUnit.module('name') without a callback: the tests after it belong to it, as in QUnit;
QUnit.test, QUnit.test.only / .skip / .todo / .if, and the older QUnit.only / QUnit.skip / QUnit.todo;
QUnit.test.each('name', data, fn) and its .only.each / .skip.each / .todo.each / .if.each forms;
QUnit.module.only / .skip / .todo / .if;
- local names:
const { test } = QUnit, const { test: it } = QUnit, import { module, test } from 'qunit',
import { QUnit } from 'qunit', const Q = require('qunit').
- Run everything, a file, a module or a single test from the Testing view or the gutter. A module or a single test
really runs on its own: the extension passes QUnit an exact filter, so other tests in the file do not run.
- Per-test results with durations: passed, failed, skipped (
QUnit.test.skip, tests in a skipped module).
A todo test whose assertions fail as expected is shown as skipped; a todo test that now passes is shown as failed
with a hint to remove todo, just as QUnit reports it.
test.each cases appear under their test after the first run (for example doubles [0: 1]), and each case can be
run on its own.
- Failures where they happened.
assert.equal, assert.strictEqual, assert.deepEqual, assert.propEqual and
other comparisons open VS Code's diff view with the expected and actual values (formatted the way QUnit prints them).
assert.ok, assert.notEqual and similar checks show their message and values. The message is placed at the
failing assertion in your test file, read from QUnit's own stack information.
- Crashes and load errors are explained. If a test file cannot be loaded (for example a syntax error), the file is
marked as errored with QUnit's message at the line it points to. If the process stops in the middle of a test
(
process.exit, a fatal error), that test is marked as errored with the exit code and the error output.
- Output. QUnit's normal TAP output is streamed to the test run's output while the tests run.
- Debug a file, a module or a test: the tests run in a Node.js debug session of VS Code's built-in JavaScript
debugger, so you can set breakpoints in your test files. Results are shown when the session ends.
- Names built at runtime (
QUnit.test(\case ${n}`, ...)`) are added to the tree after the first run.
Usage
- Install QUnit in your project (
npm install --save-dev qunit) and put your tests where the qunit command finds
them (test/ by default).
- Open the Testing view (the flask icon). Your test files, modules and tests are listed.
- Click a run button in the view or in the editor gutter. Use the debug button to run under the debugger.
The command QUnit: Refresh QUnit tests reads the test files again.
Settings
| Setting |
Default |
Meaning |
qunitTestExplorer.files |
["test/**/*.{js,mjs,cjs}"] |
Glob patterns (relative to the workspace folder) of test files. |
qunitTestExplorer.exclude |
["**/node_modules/**"] |
Glob patterns of files never to show. |
qunitTestExplorer.nodePath |
node |
Node.js used to start node_modules/qunit/bin/qunit.js. |
qunitTestExplorer.command |
[] |
A different command that starts the QUnit CLI, for example ["npx", "qunit"]. |
qunitTestExplorer.args |
[] |
Extra QUnit CLI arguments, for example ["--require", "./test/setup.js"] or ["--seed", "1"]. |
qunitTestExplorer.env |
{} |
Extra environment variables for test runs. |
QUnit runs in the folder that holds the node_modules with QUnit in it (found by looking upwards from each test file),
so relative paths in args are relative to that folder. Each test file runs in its own qunit process, up to four
files at a time.
How it works
The extension starts qunit --require <small reporter> <your test file>. The reporter is a short script shipped with
the extension. It uses QUnit's public event API (QUnit.on('testStart' / 'testEnd' / 'error' / 'runEnd') and
QUnit.log) to write the results to a temporary file that the extension reads; it does not change what QUnit prints.
To run one module or test it sets QUnit's filter option (the same as qunit --filter) to an exact pattern.
Limitations
- Only QUnit's Node.js command-line runner is supported. Tests that run in a browser (QUnit's HTML runner, Karma,
Testem, Ember CLI, QTap and similar) are not run by this extension.
- Checked with QUnit 2.19 and 3.0. It needs QUnit 2.2 or newer (for
QUnit.on). ES module test files need a Node.js
version that can load them; named imports such as import { test } from 'qunit' need QUnit 3.
- Tests are found by reading the source, not by running it. Tests whose names are built at runtime, or that are created
in loops or helper functions with variable names, appear only after a run.
- A custom
command must start the QUnit CLI and accept its --require option.
- Test files compiled from TypeScript or other languages work only when the QUnit CLI can load them directly
(for example with a
--require loader in args); the default file pattern covers only .js, .mjs and .cjs.
- Coverage is not supported.
About
This is an unofficial extension. It is not affiliated with, endorsed by, or sponsored by the QUnit project or the
OpenJS Foundation. The QUnit name is used only to say which test framework the extension works with.
This extension was built with the help of AI (Anthropic's Claude) and is tested automatically, including in a real
VS Code against a real QUnit install. Please report problems with a small example.
Licensed under the MIT License.
| |