Skip to content
This repository has been archived by the owner on Apr 1, 2024. It is now read-only.

Latest commit

 

History

History
227 lines (153 loc) · 8.08 KB

intro.md

File metadata and controls

227 lines (153 loc) · 8.08 KB
Raw
layout title amethyst redirect_from
page
Getting Started
toc
true
/guides/
/cookbook/

The following guide will get you up-and-running with QUnit either in Node.js or in the Browser.

QUnit has no dependencies and supports Node.js, SpiderMonkey, and all major browsers.

In Node.js

Getting started with QUnit for Node.js projects is quick and easy. First, install the qunit package using 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. Refer to the QUnit.test() page in our API Documentation for how to organise tests and make other assertions.

You can now run your first test through the QUnit CLI. It is recommended that you run the qunit command via an npm script, which will automatically find the qunit program in your local node_modules folder, which is where npm keeps the dependencies you download. In your package.json file, specify it like so:

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

Then run:

npm test

... and QUnit will run your test!

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

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

Check out the API documentation to learn about QUnit APIs for organising tests and making assertions.

See Command-line interface for help with the qunit command.

Support policy

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

Package name prior to 2.4.1

Prior to QUnit 2.4.1, the npm package was published under the name "qunitjs" instead of "qunit". To install earlier versions of QUnit for Node, check out qunitjs.

The 0.x and 1.x versions of the "qunit" package on npm holds an alternative CLI that is now published as node-qunit.

Linting

The eslint-plugin-qunit package has a variety of rules available for enforcing best testing practices as well as detecting broken tests.

In the Browser

To get started with QUnit in the browser, create a simple HTML file called test.html and include the following markup:

<!DOCTYPE html>
<meta charset="utf-8">
<title>Test Suite</title>
<link rel="stylesheet" href="https://code.jquery.com/qunit/qunit-2.20.1.css">
<body>
  <div id="qunit"></div>
  <div id="qunit-fixture"></div>
  <script src="https://code.jquery.com/qunit/qunit-2.20.1.js"></script>
</body>

That's all the markup you need to start writing tests. Note that this loads the library from the jQuery CDN.

See also Integrations & Downloads for integration you can use to automate browser testing. These usually also manage the HTML file for you.

Let's add the following script, which tests an example add() function for adding two numbers together:

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

  QUnit.module('add', function() {
    QUnit.test('two numbers', function(assert) {
      assert.equal(add(1, 2), 3);
    });
  });
</script>

This code defines a test module for the add() function and verifies the result of adding two numbers.

If you open this up in the browser you'll find a detailed report of the tests that ran and their assertions, as well as various options for filtering and re-running individual tests to help during development. Like so:

<iframe loading="lazy" title="The test code running in the browser" src="/resources/example-index.html" style="height: 300px;"></iframe>

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

Check out the API documentation to learn more about the QUnit APIs for organising tests and making assertions.

Browser support

QUnit currently supports the following browsers:

  • Internet Explorer: 9+
  • Edge: 15+ (both legacy MSEdge and Chromium-based)
  • Firefox: 45+
  • Safari: 9+
  • Opera: 36+
  • Chrome: 58+
  • Android: 4.3+
  • iOS: 7+ (Mobile Safari)

For older browsers, such as Internet Explorer 6-8, Opera 12+, or Safari 5+, please use the 1.x series of QUnit.

Integrations

The following integrations can be used to automate the running of browser tests with QUnit:

Example projects:

  • Krinkle/example-node-and-browser-qunit-ci: Run QUnit tests locally and in CI, on Headless Firefox and Chrome (using Karma), and with Node.js.
    Also demonstrates code coverage, and testing of isomorphic JavaScript projects.

Release channels

These are the officially supported download channels for QUnit releases:

  • Download:

    QUnit has no runtime dependencies for browser use. You can save the qunit-2.20.1.js and qunit-2.20.1.css files directly from the jQuery CDN, which is powered by StackPath.

    Or download them via the terminal:

    curl -o qunit.css 'https://code.jquery.com/qunit/qunit-2.20.1.css'
curl -o qunit.js 'https://code.jquery.com/qunit/qunit-2.20.1.js'

  • npm Registry:

    If your development workflow uses Node.js, you can install the qunit package the npm Registry, using the npm CLI:

    npm install --save-dev qunit

    Or, if using Yarn:

    yarn add --dev qunit

    You can then reference node_modules/qunit/qunit/qunit.css and node_modules/qunit/qunit/qunit.js in your HTML.

    If your project uses a custom npm frontend that locates packages elsewhere, you may need to generate the HTML dynamically and use require.resolve() to locate qunit/qunit/qunit.js and qunit/qunit/qunit.css. Alternatively, use one of the Integrations such as karma-qunit which do all of that for you.

  • Bower:

    Using Bower:

    bower install --save-dev qunit

    Then reference bower_components/qunit/qunit/qunit.css and bower_components/qunit/qunit/qunit.js in your HTML.

Further Reading