If your tests pass without warnings on QUnit 2.24, you can upgrade to QUnit 3 without changes.
The QUnit 3.0 release only removes deprecated methods, and promotes warnings to errors. If your tests pass on QUnit 2.24 or later without warnings, then you should be able to upgrade to QUnit 3 without changes.
As is our tradition, no significant features are introduced in major releases. The new features that you may informally associate with “QUnit 3” have been gradually in the QUnit 2.x series. Learn about new features introduced since QUnit 2.0 in The Road to QUnit 3.
Changes
- New features
- New theme
- Deprecation warnings
- Remove QUnit.load
- Remove QUnit.onError and QUnit.onUnhandledRejection
- Remove support for legacy markup
- Remove support for Node.js 10-16
- Remove support for PhantomJS
- Remove Bower distribution
- Remove AMD export
New features
Check out The Road to QUnit 3 to learn more about features introduced between QUnit 2.1 and QUnit 2.24, such as:
assert.step()provides a complete and strict way to verify asynchronous or event-driven code.assert.timeout()to control the allowed duration of an async test.assert.rejects()to cleanly wait for and match an expected error from any async function or rejected Promise.assert.true()andassert.false()shortcuts.assert.propContains()to partially compare an object while ignoring other properties.assert.closeTo()to expect a number within a certain range or tolerance.QUnit.test.each()to generate test cases via a data provider.QUnit.test.if()to automatically skip a test when a condition is false.QUnit.reporters.perfto find and analyze slow tests in your browser DevTools.
New theme
The default theme in QUnit 3 is faster, more accessible, and includes better error reporting.
Read First look at the QUnit 3 theme and Instant render with QUnit 3 on the QUnit Blog.
Deprecation warnings
Hook on wrong module
This warning was introduced in QUnit 2.15 (#1576) and has been promoted to an error:
Warning: The beforeEach hook was called inside the wrong module.
Async module scope
This warning was introduced in QUnit 2.16 (#1600) and has been promoted to an error:
Warning: Returning a promise from a module callback is not supported.
Error: QUnit.module() callback must not be async. For async module setup, use hooks.
Unexpected test after runEnd
This warning was introduced in QUnit 2.17 (#1377) and has been promoted to an error:
Warning: Unexpected test after runEnd.
Default test timeout
If a test takes longer than 3 seconds and you have no timeout set, the following deprecation warning is logged (since QUnit 2.21, #1483):
Warning: Test {name} took longer than 3000ms, but no timeout was set.
QUnit 3 enables a default test timeout of 3 seconds. Check config.testTimeout for how to address this warning before upgrading to QUnit 3.
Change assert.expect() counting
QUnit 3 excludes assert.step() calls from the assertion count. QUnit 2.21 added this warning:
Warning: Counting each assert.step() for assert.expect() is changing in QUnit 3.0.
Omit assert.expect() from tests that use assert.step(), or enable QUnit.config.countStepsAsOne.
Review assert.expect() and decide if you still need to count assertions. See also The value and benefit of assert.expect() on the Ember Discuss forum, which resulted in a recommendation and ESLint rule to discourages assertion counting, especially because assert.verifySteps() already counts the steps. If you prefer to keep counting assertions, check Migration: countStepsAsOne.
Remove QUnit.load()
The QUnit.load() method was used by some test runners and CI plugins to customize loading of scripts.
This is deprecated in favor of the simpler QUnit.start(). Refer to QUnit.load() for a migration guide.
Remove QUnit.onError() and QUnit.onUnhandledRejection()
The undocumented QUnit.onError() and QUnit.onUnhandledRejection() callbacks could be used by an integration plugin or custom test runner. These are deprecated in favor of QUnit.onUncaughtException() since QUnit 2.17.
Remove support for legacy markup
Prior to QUnit 1.2, test pages used the following markup:
<body>
<h1 id="qunit-header">Tests</h1>
<h2 id="qunit-banner"></h2>
<div id="qunit-testrunner-toolbar"></div>
<h2 id="qunit-userAgent"></h2>
<ol id="qunit-tests"></ol>
</body>
Since QUnit 1.3, released in 2012, this markup is automatically created and inserted into a <div id="qunit"> element on the page.
<body>
<div id="qunit"></div>
</body>
QUnit 1.x and 2.x supported manual creation of this markup for backwards compatibility. This has now been removed. Use <div id="qunit"> instead. Learn about HTML test file markup on the Browser Runner page.
Remove support for Node.js 10-16
Support for Node.js 10-16 was removed. The QUnit CLI now requires Node.js 18 or later.
Remove support for PhantomJS
QUnit no longer supports running tests in the PhantomJS browser. This was deprecated in QUnit 2.13.
Other browser support remains unchanged. View the support table for browsers and other runtimes at Getting Started § Compatibility.
Remove Bower distribution
Future QUnit releases are no longer published to the Bower registry. QUnit 1.x and 2.x packages remain available via the Bower CLI.
Refer to Download or Getting started.
Remove AMD export
The qunit.js distribution no longer exports the QUnit API via AMD.
This change only affects the loading of the qunit.js file. You can continue to load your application source code and QUnit test files via AMD or RequireJS. See Example: Loading with RequireJS.