cli.md

layout	page
title	Command-line Interface
excerpt	Test JavaScript code in Node.js with the QUnit CLI.
redirect_from	/node/
amethyst	toc true

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

Getting started with QUnit to test your Node.js projects is quick and easy.
First, install the qunit package from npm:

npm install --save-dev qunit

# Or, if using Yarn:
yarn add --dev qunit

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:

function add (a, b) {
  return a + b;
}

module.exports = add;

Now, let's start writing tests!
Create a file in a test directory, for example test/add.js, and write the following:

const add = require('../add.js');

QUnit.module('add');

QUnit.test('two numbers', (assert) => {
  assert.equal(add(1, 2), 3);
});

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:

{
  "scripts": {
    "test": "qunit"
  }
}

Then run:

npm test

Congrats! You just wrote and executed your first QUnit test!

TAP version 13
ok 1 add > two numbers
1..1
# pass 1
# skip 0
# todo 0
# fail 0

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.

Efficient development

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.

• Use --watch to automatically re-run tests after making changes to your files.
• When building out a larger feature, use --filter or --module to run only a subset of tests.

QUnit CLI options

Usage: qunit [options] [files]

  Files should be a space-separated list of files, directories, or glob expressions.
  Defaults to 'test/**/*.js'.

Options:
  -V, --version          output the version number
  -f, --filter <filter>  run only matching module or test names
  -m, --module <name>    run only the specified module
  -r, --reporter [name]  specify the reporter to use
  --require <module>     specify a module or script to include before running any tests
  --seed <value>         specify a seed to enable randomized ordering of tests.
                         set to "true" to generate a new random seed.
  -w, --watch            watch files for changes and re-run the test suite
  -h, --help             display help for command

--filter

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.

--module

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.

--reporter

Built-in reporters:

• tap
• console
• perf

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:

qunit test/ | tap-min

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) 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.

Example:

qunit --reporter tap
qunit --reporter qunit-reporter-example

--require

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:

qunit --require ./test/setup.js

// test/setup.js
require('../build/my-custom-reporter.js').init(QUnit);

QUnit.config.noglobals = true;
QUnit.config.notrycatch = true;

global.MyApp = require('./index');

See QUnit.config for all available configuration options.

--seed

This option assigns QUnit.config.seed for you.

--watch

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.

Node.js CLI options

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:

NODE_OPTIONS='--enable-source-maps' qunit test/

Code coverage

Generate code coverage reports with nyc:

{
  "scripts": {
    "test": "nyc qunit"
  },
  "devDependencies": {
    "nyc": "*",
    "qunit": "*"
  }
}

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.

Node.js support policy

QUnit follows the Node.js Long-term Support (LTS) schedule and provides support for at least the Current, Active LTS, and Maintenance LTS releases.

npm Package name

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.