Docs: Document Theme API and HTML API of HTML Reporter

Fixes #1751.

docs/_sass/custom.scss

@@ -6,6 +6,32 @@ h3 a {
     color: inherit;
 }
 
+.table-style-api th:first-child {
+  min-width: 20em;
+}
+
+@media (max-width: 768px) {
+  .table-style-api tr,
+  .table-style-api th,
+  .table-style-api td {
+    display: block;
+  }
+  .table-style-api tr {
+    display: flex;
+    flex-flow: row wrap;
+    border: 1px solid $color-off-white;
+  }
+  .table-style-api th:first-child,
+  .table-style-api td:first-child {
+    order: 1;
+    flex-grow: 1;
+  }
+  .table-style-api th,
+  .table-style-api td {
+    border: 0;
+  }
+}
+
 /* Plugins */
 #plugins {
     list-style: none;

docs/api/callbacks/QUnit.testDone.md

@@ -32,6 +32,11 @@ Passed to the callback:
 | `runtime` (number) | The execution time in milliseconds of the test, including beforeEach and afterEach calls |
 | `skipped` (boolean) | Indicates whether or not the current test was skipped |
 | `todo` (boolean) | Indicates whether or not the current test was a todo |
+| `testId` (string) | Internal ID of the current test |
+
+## Changelog
+
+| [QUnit 1.16](https://github.com/qunitjs/qunit/releases/tag/1.16.0) | Added `details.testId` property.
 
 ## Examples
 

docs/api/callbacks/QUnit.testStart.md

@@ -26,9 +26,14 @@ Passed to the callback:
 |-----------|-------------|
 | `name` (string) | Name of the next test to run |
 | `module` (string) | Name of the current module |
-| `testId` (string) | Id of the next test to run |
+| `testId` (string) | Internal ID of the next test |
 | `previousFailure` (boolean) | Whether the next test failed on a previous run |
 
+## Changelog
+
+| [QUnit 1.16](https://github.com/qunitjs/qunit/releases/tag/1.16.0) | Added `details.testId` property.
+
+
 ## Examples
 
 Register a callback that logs the module and test name:

docs/api/config/current.md

@@ -19,20 +19,32 @@ Internal object representing the currently running test.
 </tr>
 </table>
 
-This property is not actually a configuration option, but is exposed under `QUnit.config` for use by plugins and other integrations. This offers access to QUnit's internal `Test` object at runtime.
+This object is not a configuration option, but is exposed under `QUnit.config` for use by plugins and other integrations. This offers access to QUnit's internal `Test` object at runtime.
+
+## Properties
+
+| name | description |
+|------|-------------|
+| `testName` (string) | Name of the currently-running test, as passed to [QUnit.test](../QUnit/test.md).
+| `testId` (string) | Internal ID, used by [QUnit.config.testId](./testId.md) to power "Rerun" links and the HTML API in the [HTML Reporter](../../browser.md#html-reporter).
+
+Other properties may change without notice. When possible, use [QUnit.on](../callbacks/QUnit.on.md) or [event callbacks](../callbacks/index.md) instead.
+
+## Changelog
+
+| [QUnit 1.16](https://github.com/qunitjs/qunit/releases/tag/1.16.0) | Added `testId` property.
 
-Internals may change without notice. When possible, use [QUnit.on](../callbacks/QUnit.on.md) or [other callbacks](../callbacks/index.md) instead.
 
 ## Example
 
 Access `QUnit.config.current.testName` to observe the currently running test's name.
 
 ```js
 function whatsUp () {
-  console.log(QUnit.config.current.testName);
+  console.log(QUnit.config.current.testName); // "example"
 }
 
-QUnit.test('example', assert => {
+QUnit.test('example', function (assert) {
   whatsUp();
 
   assert.true(true);

docs/api/config/urlConfig.md

@@ -65,7 +65,7 @@ value = {
 
 ### Add toolbar checkbox
 
-Add a new checkbox to the toolbar. You can then use the `QUnit.config.min` property in your code to implement a behaviour based on it.
+Add a new checkbox to the toolbar. You can then use the `QUnit.urlParams.min` property in your code to implement a behaviour based on it.
 
 ```js
 QUnit.config.urlConfig.push({

docs/browser.md

@@ -76,6 +76,21 @@ QUnit's [reorder feature](./api/config/reorder.md) automatically remembers faili
 
 When building out a larger feature, you can use the [module selector](#module-selector) to re-run only the tests (and nested modules) under one or more selected module names.
 
+## Browser support
+
+QUnit currently supports the following browsers:
+
+* Internet Explorer: 9+
+* Edge: 15+ (both legacy MSEdge and Chromium-based)
+* Firefox: 45+
+* Safari: 9+
+* Opera: 36+
+* Chrome: 58+
+* Android: 4.3+
+* iOS: 7+ (Mobile Safari)
+
+For older browsers, such as Internet Explorer 6-8, Opera 12+, or Safari 5+, please use QUnit 1.x, which you can download from the [release archives](https://releases.jquery.com/qunit/).
+
 ## Integrations
 
 ### Linting
@@ -133,11 +148,13 @@ The header of the report displays:
 
 [No try-catch](./api/config/notrycatch.md) instructs QUnit to run your tests without a try-catch block. In this mode, if your test throws an error it will interrupt QUnit, which may ease debugging.
 
+You can extend the toolbar via [QUnit.config.urlConfig](./api/config/urlConfig.md).
+
 ### Filter
 
 Enter a search phrase to re-run only tests that match the phrase. It performs a case-insensitive substring match by default, on both the module name and test name. You can use regular expressions, and/or invert the match to exclude tests instead.
 
-Read [filter](./api/config/filter.md) for examples.
+Find examples and learn more at [QUnit.config.filter](./api/config/filter.md).
 
 ### Module selector
 
@@ -149,21 +166,75 @@ When selecting a parent module, which contains [nested modules](./api/QUnit/modu
 
 ### Test results
 
-Each result is displayed in a numbered list. After the name of the test, in parentheses, are the number of failed, passed, and total assertions. Click the entry to show the results of each assertion, with details about expected and actual results (for failed asssertions).
+Each result is displayed in a numbered list.
 
-The "Rerun" link at the end will run that test on its own.
+> **MyApp: example** (3) _Rerun_
 
-## Browser support
+After the name of the module and test, in parentheses, is the total number of assertions.
 
-QUnit currently supports the following browsers:
+The "Rerun" link at the end will run that test on its own, skipping all other tests.
 
-* Internet Explorer: 9+
-* Edge: 15+ (both legacy MSEdge and Chromium-based)
-* Firefox: 45+
-* Safari: 9+
-* Opera: 36+
-* Chrome: 58+
-* Android: 4.3+
-* iOS: 7+ (Mobile Safari)
+Click anywhere on result to expand the entry, which reveals the message of each assertion.
 
-For older browsers, such as Internet Explorer 6-8, Opera 12+, or Safari 5+, please use QUnit 1.x, which you can download from the [release archives](https://releases.jquery.com/qunit/).
+For failed assertions, the parenthical reports the failed, passed, and total number of assertions. The expanded view also displays the expected and actual asserted value, with a diff to highlight the difference between the two values.
+
+<iframe loading="lazy" title="Example failure" src="/resources/example-fail.html" style="height: 500px;"></iframe>
+
+### Theme API
+
+The HTML Reporter populates the `<div id="qunit">` element with the following structure:
+
+```html
+<div id="qunit">
+  <h1 id="qunit-header">…</h1>
+  <h2 id="qunit-banner"></h2>
+  <div id="qunit-testrunner-toolbar">…</div>
+  <h2 id="qunit-userAgent">¬</h2>
+  <p id="qunit-testresult">…</p>
+  <ol id="qunit-tests"></ol>
+</div>
+```
+
+You can style these to create your own theme, or add custom styles to the default theme.
+
+Examples: [Theme plugins](./plugins.md)
+
+The following selectors are considered stable and supported:
+
+| Selector | Description
+|--|--
+| `#qunit-header`<br><br>`#qunit-header a` | Displays the page title, with an anchor link that will reload the page and re-run all tests.
+| `#qunit-banner`<br><br>`#qunit-banner.qunit-pass`<br><br>`#qunit-banner.qunit-fail` | Indicates the test run status. It carries no class while tests are in progress. Once completed, the `qunit-pass` or `qunit-fail` indicated the completed status as reported by the [runEnd event](./api/callbacks/QUnit.on.md#the-runend-event).
+| `#qunit-testrunner-toolbar` | The toolbar.
+| `#qunit-modulefilter` | Module selector.
+| `#qunit-modulefilter-dropdown` | Module selector, dropdown menu.
+| `#qunit-modulefilter-actions`<br><br>`#qunit-modulefilter-actions button` | Module selector, top area of dropdown menu with "Reset" and "Apply" buttons.
+| `#qunit-modulefilter .clickable`<br><br>`#qunit-modulefilter .clickable.checked` | Module selector, options in the dropdown menu.
+{:class="table-style-api"}
+
+### HTML API
+
+#### Test output `id="qunit-test-output-TESTID"`
+
+You may rely on an element with the following ID existing during test execution. This includes during [module hooks](./api/QUnit/module.md#hooks), [global hooks](./api/QUnit/hooks.md), and during the test itself and its assertions.
+
+Seeking an element by this ID during an event, or during a different test, may work at your own risk. This is because the HTML Reporter may not have created the element yet, or may have removed it from the DOM (e.g. when [hidepassed](./api/config/hidepassed.md) is enabled).
+
+Demos:
+* [ColorFactory test page](https://krinkle.github.io/node-colorfactory/test/) ([Source code](https://github.com/Krinkle/node-colorfactory/blob/cd79287c09eb0e7118eb4a45811786c65d0640b7/test/testinit.js#L25-L43))
+* [Fabric.js test page](http://fabricjs.com/test/visual/?coverage) ([Source code](https://github.com/fabricjs/fabric.js/blob/v6.0.0-rc5/test/lib/visualCallbackQunit.js#L41))
+
+
+```js
+QUnit.hooks.afterEach(function () {
+  var target = '#qunit-test-output-' + QUnit.config.current.testId;
+});
+
+QUnit.assert.myplugin = function (actual, expected) {
+  var target = '#qunit-test-output-' + QUnit.config.current.testId;
+};
+```
+
+#### Toolbar HTML
+
+It is recommended to extend the toolbar declaratively via [QUnit.config.urlConfig](./api/config/urlConfig.md). Modifying the toolbar elements directly may work at your own risk.

docs/intro.md

@@ -35,7 +35,8 @@ These are the official release channels for QUnit releases:
 
 * Download:
 
-  QUnit has no runtime dependencies for browser use. You can save the [`qunit-2.21.0.js`](https://code.jquery.com/qunit/qunit-2.21.0.js) and [`qunit-2.21.0.css`](https://code.jquery.com/qunit/qunit-2.21.0.css) files directly from the [jQuery CDN](https://code.jquery.com/qunit/).
+  You can save the [`qunit-2.21.0.js`](https://code.jquery.com/qunit/qunit-2.21.0.js) and [`qunit-2.21.0.css`](https://code.jquery.com/qunit/qunit-2.21.0.css) files directly from the jQuery CDN.
+  For older versions, browse the [release archives](https://releases.jquery.com/qunit/).
 
   Or download them via the terminal, and save them in your Git repository.
 
@@ -63,9 +64,9 @@ These are the official release channels for QUnit releases:
 
 * Bower:
 
-  QUnit 1.x and QUnit 2.x releases were published to [Bower](https://bower.io/), and remain available there.
+  QUnit 1.x and QUnit 2.x releases were published to [Bower](https://bower.io/), and remain available there  under the `qunit` package.
 
-  For QUnit 3.0 and later, either download and check-in the JS and CSS file directly (e.g. using the curl command above), or install the `qunit` package from npm as a dev dependency.
+  For QUnit 3.0 and later, either download and commit the JS and CSS file directly in your project (e.g. using the curl command above), or install the `qunit` package from npm as a dev dependency.
 
 ---
 

docs/resources/example-fail.html

@@ -0,0 +1,19 @@
+<!DOCTYPE html>
+<html lang="en">
+<meta charset="utf-8">
+<title>QUnit</title>
+<link rel="stylesheet" href="https://code.jquery.com/qunit/qunit-2.21.0.css">
+<body>
+  <div id="qunit"></div>
+  <div id="qunit-fixture"></div>
+  <script src="https://code.jquery.com/qunit/qunit-2.21.0.js"></script>
+  <script>
+  QUnit.test('example', function (assert) {
+    assert.true(true, 'foo');
+    assert.equal('this is actual', 'this is expected', 'bar');
+    assert.true(true, 'baz');
+  });
+  </script>
+</body>
+</html>
+<!-- This is the demo on the home page. -->