Docs: Add ESM dynamic import example and integration test

Make explicit mention of the "Unexpected test after runEnd." warning
to help in discovery through our search function, and general web
search.

Closes #1694.

Author: Krinkle

.eslintrc.json

@@ -138,6 +138,18 @@
         "compat/compat": "off"
       }
     },
+    {
+      "files": ["test/dynamic-import/**"],
+      "env": {
+        "es2017": true
+      },
+      "parserOptions": {
+        "ecmaVersion": 2020
+      },
+      "rules": {
+        "compat/compat": "off"
+      }
+    },
     {
       "files": ["test/node/**"],
       "env": {

Gruntfile.js

@@ -75,6 +75,7 @@ module.exports = function (grunt) {
 
             'test/amd.html',
             'test/autostart.html',
+            'test/dynamic-import.html',
             'test/events-filters.html',
             'test/events-in-test.html',
             'test/headless.html',

docs/QUnit/start.md

@@ -1,7 +1,7 @@
 ---
 layout: page-api
 title: QUnit.start()
-excerpt: Start an async test suite.
+excerpt: Start the test runner.
 groups:
   - main
   - async
@@ -10,21 +10,10 @@ redirect_from:
 version_added: "1.0.0"
 ---
 
-`QUnit.start()` must be used to start a test run that has [`QUnit.config.autostart`](../config/autostart.md) set to `false`.
+`QUnit.start()`
 
-<p class="note note--warning" markdown="1">Warning: This method was previously used to control async tests on text contexts along with `QUnit.stop`. For asynchronous tests, use [`assert.async`](../assert/async.md) instead.</p>
+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.
 
-When your async test has multiple exit points, call `QUnit.start()` for the corresponding number of `QUnit.stop()` increments.
+Note: See [`QUnit.config.autostart`](../config/autostart.md) for detailed examples of how to use this.
 
-## Examples
-
-A test run that does not begin when the page is done loading. This example uses an Asynchronous Module Definition (AMD) loader-style `require` call.
-
-```js
-QUnit.config.autostart = false;
-
-require(
-  ['test/tests1.js', 'test/tests2.js'],
-  QUnit.start
-);
-```
+<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>

docs/config/autostart.md

@@ -1,13 +1,13 @@
 ---
 layout: page-api
 title: QUnit.config.autostart
-excerpt: Start running the tests once all files have been loaded.
+excerpt: Control when the test run may start.
 groups:
   - config
 version_added: "1.0.0"
 ---
 
-Start running the tests once all files have been loaded.
+Control when the test run may start, e.g. after asynchronously loading test files with RequireJS, AMD, ES6 dynamic imports, or other means.
 
 <table>
 <tr>
@@ -20,13 +20,40 @@ Start running the tests once all files have been loaded.
 </tr>
 </table>
 
-By default, QUnit starts running the tests when `load` event is triggered on the `window` (in the browser), or after all specified files have been imported (in the CLI).
+In the browser, QUnit by default waits for all `<script>`  elements to finish loading (by means of the window `load` event). When using the QUnit CLI, it waits until the specified files are imported.
 
-Set this property to `false` if you load your test files asynchronously through custom means (e.g. RequireJS). Remember to call `QUnit.start()` once you're ready for tests to begin running.
+Set this property to `false` to instruct QUnit to wait longer, allowing you to load test files asynchronously. Remember to call [`QUnit.start()`](../QUnit/start.md) once you're ready for tests to begin running.
 
-## Example
+If you asynchronously load test files _without_ disabling autostart, you may encounter this warning:
 
-Disable autostart when loading tests asynchronously, such as when using RequireJS:
+<p class="note note--warning" markdown="1">**warning**: Unexpected test after runEnd.</p>
+
+## Examples
+
+### ESM Dynamic imports
+
+This example uses the [import()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import) operator to dynamically load ECMAScript module (ESM) files.
+
+```html
+<script src="../lib/qunit.js"></script>
+<script type="module" src="tests.js"></script>
+```
+
+```js
+// tests.js
+QUnit.config.autostart = false;
+
+Promise.all([
+  import('./foo.js'),
+  import('./bar.js')
+]).then(function () {
+  QUnit.start();
+});
+```
+
+### Loading with RequireJS
+
+This example uses [RequireJS](https://requirejs.org/) to call a "require" function as defined by the [AMD specification](https://github.com/amdjs/amdjs-api/blob/master/require.md) (Asynchronous Module Definition).
 
 ```js
 QUnit.config.autostart = false;

test/dynamic-import.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <title>QUnit</title>
+  <link rel="stylesheet" href="../qunit/qunit.css">
+</head>
+<body>
+  <div id="qunit"></div>
+  <script src="../qunit/qunit.js"></script>
+  <script type="module" src="dynamic-import/index.js"></script>
+</body>
+</html>

test/dynamic-import/bar.js

@@ -0,0 +1,5 @@
+QUnit.module('bar', function () {
+  QUnit.test('example', function (assert) {
+    assert.true(true);
+  });
+});

test/dynamic-import/foo.js

@@ -0,0 +1,5 @@
+QUnit.module('foo', function () {
+  QUnit.test('example', function (assert) {
+    assert.true(true);
+  });
+});

test/dynamic-import/index.js

@@ -0,0 +1,8 @@
+QUnit.config.autostart = false;
+
+Promise.all([
+  import('./foo.js'),
+  import('./bar.js')
+]).then(function () {
+  QUnit.start();
+});