Test JavaScript
code in a real browser with QUnit.
QUnit releases are standalone and require no runtime dependencies for use in the browser. To get started, all you need is an HTML file that loads two files: qunit.js and qunit.css.
This is typically saved as /test.html or /test/index.html in your project.
The above example loads QUnit from the jQuery CDN. For improved experience during local or offline development, it is recommended to install or download QUnit within your project. Some integrations, like Web Test Runner and Karma, can auto-create the HTML from a list of JS files or glob pattern.
Let’s add the following script, which tests an “add” function that adds two numbers together:
Open your HTML file in a browser to find a detailed report. Live example (open in a new tab):
Congrats! You just executed your first QUnit test!
Don’t worry about DOM changes from one test affecting other tests, because QUnit will automatically reset the markup after each test. As long as you append or insert your elements inside the fixture, you will never have to manually clean up after your tests.
This helps keep your tests them atomic!
Find examples and learn more at QUnit.config.fixture.
As your project grows, you may reach a point where the complete test suite takes more than a second or two to run. QUnit provides several automatic and optional ways to maintain a good feedback cycle.
QUnit’s reorder feature automatically remembers failing tests, and prioritizes those when you reload the page, running them before all other tests. Together with “Hide passed tests” in the toolbar, this let’s you stay focussed by running and showing only what matters most.
When building out a larger feature, you can use the module selector to re-run only the tests (and nested modules) under one or more selected module names.
The browser support table was moved to Compatibility.
The eslint-plugin-qunit package has a variety of rules available for enforcing best testing practices as well as detecting broken tests.
The following integrations can be used to automate the running of browser tests with QUnit:
QUnit requires no HTML markup in order to run tests. The above “Getting started” example is recommended for new projects, but you can customize this as-needed.
To display test results, the only markup necessary is a <div> with id="qunit". Without this, the tests will run headless with the HTML Reporter disabled.
Browser automations that run tests for you from the command-line, might enable other reporters or event listeners instead. For example, they might use a TAP reporter, or QUnit.on() to automatically extract results in a machine-readable way, and use it to set the build status of a continuous integration job (CI).
The header of the report displays:
Hide passed tests is useful when a lot of tests ran and only a few failed. Ticking the checkbox will show only the tests that failed..
Check for globals detects if a test creates or removes global variable is. QUnit keeps a list of properties found on the window object. If properties were added or removed, the test fails.
No try-catch instructs QUnit to run your tests without a try-catch block. In this mode, if your test throws an error it will interrupt QUnit, which may ease debugging with browser devtools.
You can extend the toolbar via QUnit.config.urlConfig.
Each result is displayed in a numbered list.
MyApp: example (3) Rerun
After the name of the module and test, in parentheses, is the total number of assertions.
The “Rerun” link at the end will reload the page and quickly run the test again in isolation, skipping all other tests.
Click on the test name to expand the entry, which reveals the message of each assertion.
For failed assertions:
Enter a search phrase to re-run only tests that match the phrase. It performs a case-insensitive substring match by default, on both the module name and test name. You can use regular expressions, and/or invert the match to exclude tests instead.
Find examples and learn more at QUnit.config.filter.
To quickly re-run one or more modules of tests, select them from the module selector and press “Apply”.
You can use the input field to quickly find a module, even if you have many modules. The input field performs fuzzy matching, so don’t worry about getting it exactly right! For example, typing bor game or abGame will find awesome board games. This is similar to how “Quick Open” works in modern text editors.
When selecting a parent module, which contains nested modules, the nested modules and their tests will also be run.
The HTML Reporter generates the following HTML inside the <div id="qunit"> element:
You can style these to create your own theme, or add custom styles to the default theme.
Examples: Theme plugins
The following selectors are considered stable and supported:
You may rely on an element with the following ID existing during test execution. This includes during module hooks, global hooks, and during the test itself and its assertions.