Command-line Interface | QUnit

This tutorial gets you up-and-running with QUnit in Node.js.
For browser automations from the command-line, refer to Browser automation instead.
Getting started with QUnit to test your Node.js projects is quick and easy. First, install the qunit package from npm:
Let’s create an example program that we can test! We’ll start with a function that adds two numbers. Create a file add.js with the following contents:
Now, let’s start writing tests! Create a file in a test directory, for example test/add.js, and write the following:
This defines a test suite for the “add” feature, with a single test case that verifies the result of adding two numbers together.
You can now run your first test. It is recommended that you run the qunit command via npm test, which will automatically find the qunit program in your local node_modules folder. That’s where npm downloads the dependencies. In your package.json file, specify it like so:
Congrats! You just wrote and executed your first QUnit test!
Check out the API documentation to learn more. For example, use QUnit.module() to organize test, or make other kinds of comparisons via the assertion methods.
As your project grows, you may reach a point where the complete test suite takes more than a second to run. QUnit provides several ways to maintain a fast feedback cycle on the command-line.
Only run tests that match the given filter. The filter is matched against the module and test name, and may either be substring match (case insensitive), or a regular expression.
Examples: --filter foo, --filter !foo, --filter "/foo/", --filter "!/foo/"
Check QUnit.config.filter for more information.
Only run tests that belong to the specified module. The name is matched case-insensitively, but must otherwise be complete.
Examples: --module foo, --module "Foo"
Check QUnit.config.module for more information.
Check QUnit.config.reporters for more information.
By default, the TAP reporter is used. This allows you to pair QUnit with many TAP-based reporters, by piping the output. For example:
To change the reporting from QUnit itself, use qunit --reporter <name> to set a different reporter, where <name> can be the name of a built-in reporter, or a Node module (e.g. npm package, or local script) that implements the QUnit Reporter API. The reporter will be loaded and initialised automatically.
To load a reporter from a local Node.js script, use --require instead.
These modules or scripts will be required before any tests begin running.
This can be used to install Node.js require hooks, such as for TypeScript (ts-node/register), Babel (@babel/register), or CoffeeScript (coffeescript/register).
It can also be used for your own setup scripts to bootstrap the environment, or tweak QUnit.config. For example:
See QUnit.config for all available configuration options.
This option assigns QUnit.config.seed for you.
Automatically re-run your tests after file changes in the current directory.
In watch mode, QUnit will run your tests once initially, and then keep watch mode open to re-run tests after files changed anywhere in or under the current directory. This includes adding or removing files.
The QUnit CLI uses Node.js. You can pass Node.js CLI options via the NODE_OPTIONS environment variable. For example, to use --enable-source-maps or --inspect, invoke QUnit as follows:
Generate code coverage reports with nyc:
See /demos/nyc/ in the QUnit repo for a minimal example.
For a more elaborate example showcasing a unified test coverage report for tests in both Node.js and a headless browser, see Krinkle/example-node-and-browser-qunit.
QUnit follows the Node.js Long-term Support (LTS) schedule and provides support for at least the Current, Active LTS, and Maintenance LTS releases.
Since QUnit 2.4.1, the official npm package is qunit.
Earlier versions of QUnit were published to npm under the name “qunitjs” instead of “qunit”. To download these earlier versions refer to the qunitjs package.
The 0.x and 1.x versions of the “qunit” package held an alternative CLI, now known as node-qunit.
GitHub Chat Mastodon Bluesky Twitter
Copyright OpenJS Foundation and contributors.Edit this page