This method is __deprecated__. Remove call, or replace by a single call to [`QUnit.start()`](./start.md).
+ +## Changelog + +| UNRELEASED | Deprecated. Use [`QUnit.start()`](./start.md) instead. +| [QUnit 2.1.1](https://github.com/qunitjs/qunit/releases/tag/2.1.1) | `QUnit.start()` no longer requires calling `QUnit.load()` first. + +## Migration examples + +If you still call `QUnit.load()` with QUnit 2.2 or later, the call is usually redundant and safe to remove (including before you upgrade to QUnit 3). + +## Calling both `QUnit.load()` and `QUnit.start()` + +If your project started with QUnit 1.x, and you use `QUnit.config.autostart = false`, then you might be calling both of these methods. [`QUnit.start()`](./start.md) previously required calling `QUnit.load()`. + +This has not been needed since [QUnit 2.1.1](https://github.com/qunitjs/qunit/releases/tag/2.1.1), and the call to `QUnit.load()` is safe to remove. + +## Calling only `QUnit.load()` + +Prior to QUnit 2.21, the built-in HTML Reporter called `QUnit.load()` from the window.onload event, which in turn gracefully calls `QUnit.start()` if it has not been called already. + +If your test runner works in a similar way, call [`QUnit.start()`](./start.md) instead of `QUnit.load()`. This will solve the deprecation warning and prepares you for QUnit 3. + +## Calling neither + +Calling neither requires no changes. Refer to [`QUnit.start()`](./start.md) if you're curious how this is automatically called for you. diff --git a/docs/QUnit/start.md b/docs/QUnit/start.md index 1fa7e8956..9007cc754 100644 --- a/docs/QUnit/start.md +++ b/docs/QUnit/start.md @@ -12,8 +12,16 @@ version_added: "1.0.0" `QUnit.start()` -Start the test runner manually, when [`QUnit.config.autostart`](../config/autostart.md) is `false`. For example, if you load test files with AMD, RequireJS, or ESM dynamic imports. +Call this method to start the test runner. This indicates that all relevant source code has been loaded and all tests have been defined. -Note: See [`QUnit.config.autostart`](../config/autostart.md) for detailed examples of how to use this. +In most environments this is **automatically called** and you do not need to call it. This includes use in web browsers and via the QUnit CLI. -**Warning**: Prior to QUnit 1.16, this method was used for resuming an async `QUnit.start` function, as complement to `QUnit.stop()`. To resume asynchronous tests, use [`assert.async()`](../assert/async.md) instead.
+If you build a custom test runner (such in SpiderMonkey or Node.js), or if you disable `QUnit.config.autostart` and load test files asynchronously (with AMD, RequireJS, or ESM dynamic imports), then you need to call this once after your test files have been loaded. See [`QUnit.config.autostart`](../config/autostart.md) for detailed examples of how to use this. + +Prior to QUnit 1.16, this method was used for resuming an async `QUnit.test()` function, as complement to `QUnit.stop()`. To resume asynchronous tests, use [`assert.async()`](../assert/async.md) instead.
+ +## Changelog + +| [QUnit 2.1.1](https://github.com/qunitjs/qunit/releases/tag/2.1.1) | `QUnit.start()` no longer requires calling [`QUnit.load()`](./load.md) first. +| [QUnit 2.0](https://github.com/qunitjs/qunit/releases/tag/2.0.0) | Support for calling `start()` to resume an async test was removed. ([Migration guide](https://qunitjs.com/upgrade-guide-2.x/#introducing-assertasync)) +| [QUnit 1.16](https://github.com/qunitjs/qunit/releases/tag/1.16.0) | Use of `start()` to resume an async test was deprecated in favour of [`assert.async()`](../assert/async.md). diff --git a/docs/assert/async.md b/docs/assert/async.md index 77a3ad2a1..79dd0def2 100644 --- a/docs/assert/async.md +++ b/docs/assert/async.md @@ -22,7 +22,7 @@ Instruct QUnit to wait for an asynchronous operation. `assert.async()` returns a callback function and pauses test processing until the callback function is called. The callback will throw an `Error` if it is invoked more often than the required call count. -This replaces functionality previously provided by `QUnit.stop()` and [`QUnit.start()`](../QUnit/start.md). +This replaces functionality that QUnit 1.x provided via `QUnit.stop()` and [`QUnit.start()`](../QUnit/start.md). ## Examples diff --git a/src/core.js b/src/core.js index 12e7a72a9..522628e76 100644 --- a/src/core.js +++ b/src/core.js @@ -83,15 +83,21 @@ extend(QUnit, { 'QUnit.config.autostart was true'); } + // Until we remove QUnit.load() in QUnit 3, we keep `pageLoaded`. + // It no longer serves any purpose other than to support old test runners + // that still call only QUnit.load(), or that call both it and QUnit.start(). if (!config.pageLoaded) { - // The page isn't completely loaded yet, so we set autostart and then - // load if we're in Node or wait for the browser's load event. + // If the test runner used `autostart = false` and is calling QUnit.start() + // to tell is their resources are ready, but the browser isn't ready yet, + // then enable autostart now, and we'll let the tests really start after + // the browser's "load" event handler calls autostart(). config.autostart = true; - // Starts from Node even if .load was not previously called. We still return - // early otherwise we'll wind up "beginning" twice. + // If we're in Node or another non-browser environment, we start now as there + // won't be any "load" event. We return early either way since autostart + // is responsible for calling scheduleBegin (avoid "beginning" twice). if (!document) { - QUnit.load(); + QUnit.autostart(); } return; @@ -115,9 +121,20 @@ extend(QUnit, { }, load: function () { + Logger.warn('QUnit.load is deprecated and will be removed in QUnit 3.0.' + + ' Refer to