Core: Deprecate QUnit.load() and document migration path

Based on #1502.
Closes #1084.

Co-authored-by: Steve <[email protected]>

build/prep-release.js

@@ -19,6 +19,10 @@ function versionAddedString (version) {
   return `version_added: "${version}"`;
 }
 
+function versionDeprecatedString (version) {
+  return `version_deprecated: "${version}"`;
+}
+
 function formatChangelogColumn (version) {
   return `| [QUnit ${version}](https://github.com/qunitjs/qunit/releases/tag/${version}) |`;
 }
@@ -30,6 +34,7 @@ const Repo = {
     }
     {
       const UNRELEASED_ADDED = versionAddedString('unreleased');
+      const UNRELEASED_DEP = versionDeprecatedString('unreleased');
       const UNRELEASED_CHANGELOG = '| UNRELEASED |';
 
       // Silence error from grep, which exits non-zero if no results.
@@ -42,6 +47,7 @@ const Repo = {
         fs.writeFileSync(filePath,
           doc
             .replace(UNRELEASED_ADDED, versionAddedString(version))
+            .replace(UNRELEASED_DEP, versionDeprecatedString(version))
             .replace(UNRELEASED_CHANGELOG, formatChangelogColumn(version))
         );
       });

docs/QUnit/load.md

@@ -0,0 +1,46 @@
+---
+layout: page-api
+title: QUnit.load()
+excerpt: Inform the test runner that code has finished loading.
+groups:
+  - deprecated
+redirect_from:
+  - "/start/"
+version_added: "1.0.0"
+version_deprecated: "unreleased"
+---
+
+`QUnit.load()`
+
+Inform the test runner that your source code and tests have finished loading.
+
+This method was used in conjunction with the [`QUnit.config.autostart`](../config/autostart.md) option in a web browser, to indicate when your custom way of loading scripts is complete.
+
+As of [QUnit 2.1.1](https://github.com/qunitjs/qunit/releases/tag/2.1.1), calls to `QUnit.load()` are no longer needed. Existing calls are usually ignored and safe to remove.
+
+<p class="note note--warning" markdown="1">This method is __deprecated__. Remove call, or replace by a single call to [`QUnit.start()`](./start.md).</p>
+
+## 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 guide
+
+If you still call `QUnit.load()` with QUnit 2.2 or later, the call is usually redundant and safe to remove.
+
+### If you call 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. In the QUnit 1.x era, [`QUnit.start()`](./start.md) required that you also call `QUnit.load()` first.
+
+This is no longer 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.
+
+### If you call `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.
+
+### Karma runner
+
+If you encounter this warning in Karma output, upgrade to [karma-qunit](https://github.com/karma-runner/karma-qunit) 4.2.0 or later, which [fixes](https://github.com/karma-runner/karma-qunit/pull/184) this warning.

docs/QUnit/start.md

@@ -12,8 +12,18 @@ 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 testing via the HTML Runner and the QUnit CLI.
 
-<p class="note note--warning" markdown="1">**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.</p>
+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 `QUnit.start()`.
+
+<p class="note note--warning" markdown="1">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.</p>
+
+## 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).

docs/assert/async.md

@@ -22,7 +22,9 @@ 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).
+## See also
+
+* [Migration guide](https://qunitjs.com/upgrade-guide-2.x/#introducing-assertasync) from QUnit 1.x `stop()` and `start()`.
 
 ## Examples
 

src/core.js

@@ -85,15 +85,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;
@@ -117,9 +123,20 @@ extend(QUnit, {
   },
 
   load: function () {
+    Logger.warn('QUnit.load is deprecated and will be removed in QUnit 3.0.' +
+      ' Refer to <https://api.qunitjs.com/QUnit/load/>.');
+
+    QUnit.autostart();
+  },
+
+  /**
+   * @internal
+   */
+  autostart: function () {
     config.pageLoaded = true;
 
     // Initialize the configuration options
+    // TODO: Move this to config.js in QUnit 3.
     extend(config, {
       started: 0,
       updateRate: 1000,

src/html-reporter/html.js

@@ -1079,9 +1079,9 @@ const stats = {
   }
 
   if (!usingPhantom && document.readyState === 'complete') {
-    QUnit.load();
+    QUnit.autostart();
   } else {
-    addEvent(window, 'load', QUnit.load);
+    addEvent(window, 'load', QUnit.autostart);
   }
 
   // Wrap window.onerror. We will call the original window.onerror to see if