This guide will assist in upgrading from QUnit 1.x to QUnit 2.x. All breaking changes are listed below, explaining how to upgrade your code to work with QUnit 2.x.

The qunit-migrate project can help you automate the transtions to QUnit 2.x.

Note that almost all the new APIs of QUnit 2.0.0 are already usable in QUnit 1.23.1, allowing you to migrate step by step. The only exception is the new module hooks before and after.

QUnit 2.0.x will include a migration layer that throws descriptive errors for all deprecated methods ("Global 'test()' method is removed, use 'QUnit.test() instead"), to help you migrate to the new APIs. QUnit 2.1+ will remove that layer, causing failures that will be more difficult to debug ("ReferenceError: test is not defined").

QUnit no longer exposes multiple global variables. The only global variable still exposed is QUnit. Use QUnit.module() and QUnit.test() to define your testsuite, and use the assert argument in test callbacks to write assertions.

The global stop() and start() methods are gone, replaced by assert.async(), which returns a callback. Execute this callback when your test is done.

The overload of assert.throws() which expected a block, error string, and assertion message has been removed and will now throw an exception. Use a regular expression instead.

Before:

1

2

3

4

5

QUnit.test( "throws", function( assert ) {

assert.throws( function() {

thrownew Error( "This is an error" );

}, "This is an error", "An error should have been thrown" );

});

After:

1

2

3

4

5

QUnit.test( "throws", function( assert ) {

assert.throws( function() {

thrownew Error( "This is an error" );

}, /^This is an error$/, "An error should have been thrown" );

});

Note that in the two-argument overload assert.throws( block, string ), the string argument has always been interpreted as an assertion message instead of an expected value. You do not need to change any of these assertions. Of course, you should use the assert.throws( block, regexp, message ) form anyway to make your assertions more precise.

For several versions of QUnit before 2.0, custom reporters could be registered by calling the appropiate methods with a callback function. If your code still uses the old approach of overwriting a property on the QUnit object, replace that by calling the method instead.

To implement custom assertions, assign functions to QUnit.assert, inside use this.pushResult(), replacing QUnit.push. This way, the assertion will be directly related to its test context, preventing asynchronous tests leaking assertions to other tests.

This method used to reinitialize the test runner. It should never have been exposed as a public method and is now gone, without replacement. If you've built a setup that requires the use of QUnit.init, contact us (issue tracker, forum, IRC) and we can recommend a replacement.

Originally jsDump was a standalone library imported into QUnit. It has since evolved further within the library. To reflect that, the property was renamed to QUnit.dump.parse. This should only affect custom reporter code, not regular testsuites.