Docs: Add docs for QUnit.reporters

First introduced in QUnit 2.16.0 with f8948c9.
qunitjs · Jan 19, 2025 · abefa66 · abefa66
1 parent 8b5c627
commit abefa66
Show file tree

Hide file tree

Showing 16 changed files with 278 additions and 104 deletions.
diff --git a/docs/Gemfile b/docs/Gemfile
@@ -2,4 +2,4 @@ source "https://rubygems.org"
 ruby RUBY_VERSION
 
 # To apply changes, run `bundle update`.
-gem "jekyll-theme-amethyst", "2.3.2", group: :jekyll_plugins
+gem "jekyll-theme-amethyst", "2.5.0", group: :jekyll_plugins
diff --git a/docs/_config.yml b/docs/_config.yml
@@ -15,6 +15,9 @@ markdown: kramdown
 kramdown:
   input: GFM
   toc_levels: "1,2"
+  # Disable automatic conversion, messes with headings like "--reporter".
+  typographic_symbols:
+    ndash: '--'
 sass:
   # https://jekyllrb.com/docs/assets/#sassscss
   style: compressed

diff --git a/docs/_data/sidebar_api.yml b/docs/_data/sidebar_api.yml
@@ -15,6 +15,9 @@
 - title: Configuration
   group: config
 
+- title: Reporters
+  group: reporters
+
 - group: extension
 
 - group: deprecated

diff --git a/docs/_includes/search.html b/docs/_includes/search.html
diff --git a/docs/api/callbacks/QUnit.on.md b/docs/api/callbacks/QUnit.on.md
@@ -14,7 +14,7 @@ version_added: "2.2.0"
 
 Register a callback that will be invoked after the specified event is emitted.
 
-This API is the primary interface for QUnit reporters, plugins, and continuous integration support. It is based on the [js-reporters CRI standard](/~https://github.com/js-reporters/js-reporters/blob/v2.1.0/spec/cri-draft.adoc).
+This event emitter is the primary interface for QUnit reporters, plugins, and continuous integration support. It is based on the [js-reporters CRI standard](/~https://github.com/js-reporters/js-reporters/blob/v2.1.0/spec/cri-draft.adoc), and includes a [Reporter API](#reporter-api).
 
 | type | parameter | description
 |--|--|--

diff --git a/docs/api/config/current.md b/docs/api/config/current.md
@@ -26,7 +26,7 @@ This object is not a configuration option, but is exposed under `QUnit.config` f
 | 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).
+| `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).
 
 Other properties may change without notice. When possible, use [QUnit.on](../callbacks/QUnit.on.md) or [event callbacks](../callbacks/index.md) instead.
 

diff --git a/docs/api/config/index.md b/docs/api/config/index.md
@@ -7,6 +7,7 @@ amethyst:
   # Override inherited "pagetype: navigation" to enable Typesense indexing
   pagetype: custom
   robots: index
+  toc: true
 redirect_from:
   - "/QUnit.config/"
   - "/config/"

diff --git a/docs/api/config/reporters.md b/docs/api/config/reporters.md
@@ -24,81 +24,22 @@ Control which reporters to enable or disable.
 
 ## Built-in reporters
 
-### tap
+* [`tap`](../reporters/tap.md)
+* [`console`](../reporters/console.md)
+* [`perf`](../reporters/perf.md)
+* [`html`](../reporters/html.md)
 
-The **tap** reporter is a [TAP compliant](https://testanything.org/) reporter. This is the default in the [QUnit CLI](../../cli.md). This allows you to pair QUnit with many [TAP-based reporters](/~https://github.com/sindresorhus/awesome-tap#reporters), by piping the output. For example:
-
-```sh
-qunit test/ | tap-min
-```
-
-### console
-
-The **console** reporter logs a JSON object for each reporter event from [`QUnit.on`](../callbacks/QUnit.on.md). Use this to explore or debug the Reporter API.
-
-```
-runStart {…}
-testStart {…}
-testEnd {…}
-testStart {…}
-testEnd {…}
-runEnd {…}
-```
-
-### perf
-
-The **perf** reporter emits measures for the duration of each QUnit test and each module via the Web Performance API. This allows you to visualize where time is spent during your test run. This uses the [performance.measure()](https://developer.mozilla.org/en-US/docs/Web/API/Performance/measure) method internally. QUnit enables the perf reporter by default in [Browser](../../browser.md) environments. The measures are included in Firefox Profiler and Chrome DevTools (Safari is pending [WebKit #213870](https://bugs.webkit.org/show_bug.cgi?id=213870)).
-
-```
-QUnit Test Run
-└── QUnit Test Suite: Example
-    ├── QUnit Test: apple
-    ├── QUnit Test: banana
-    └── QUnit Test: citron
-```
-
-<figure>
-  <img alt="QUnit profiling in Chrome DevTools Performance tab" src="/resources/perf-chrome.png">
-  <figcaption>Chrome</figcaption>
-</figure>
-
--------
-
-<figure>
-  <img alt="QUnit performance in Firefox Profiler" src="/resources/perf-firefox.png">
-  <figcaption>Firefox</figcaption>
-</figure>
-
-
-The Web Performance API is also [available in Node.js](https://nodejs.org/docs/latest/api/perf_hooks.html) and the QUnit perf reporter can be enabled in Node.js. You can enable it in the QUnit CLI via `--reporter perf`. Note that the [Node.js inspector](https://nodejs.org/docs/latest/api/debugger.html#v8-inspector-integration-for-nodejs) does not yet send these to Chrome DevTools ([upstream nodejs/node#47813](/~https://github.com/nodejs/node/issues/47813)).
-
-
-### html
-
-The **html** reporter renders a toolbar and visualizes test results. This is the default in [Browser](../../browser.md) environments, and is documented at [HTML Reporter](../../browser.md#markup).
-
-## Examples
-
-By default, the [HTML Reporter](../../browser.md) is automatically enabled in browser environments if a `<div id="qunit">` element exists, and it remains disabled ("headless") if such element doesn't exist. You can override this to disable the HTML Reporter even if the element does exist.
-
-For example, this lets you share the same HTML file for manual testing, debugging, and CI runs; and yet disable the HTML Reporter in CI for improved performance.
+## Example
 
+Enable TAP in the browser via [preconfig](./index.md#preconfiguration):
 ```js
-// Declare as preconfig, before loading qunit.js
-qunit_config_reporters_html = false;
-
-// Set at runtime, after loading qunit.js (but before QUnit.begin)
-QUnit.config.reporters.html = false;
+// Set as global variable before loading qunit.js
+qunit_config_reporters_tap = true;
 ```
 
-Declaratively enable the TAP reporter in a browser environment:
+Or, via [QUnit.config](../config/index.md):
 
 ```js
-// Declare preconfig, before loading qunit.js
-qunit_config_reporters_tap = true;
+// Set from any inline script or JS file after qunit.js
+QUnit.config.reporters.tap = true;
 ```
-
-## See also
-
-* [Preconfig](./index.md#preconfiguration)
-* [QUnit Reporter API](../callbacks/QUnit.on.md#reporter-api)
diff --git a/docs/api/index.md b/docs/api/index.md
@@ -18,4 +18,5 @@ QUnit is a powerful, easy-to-use JavaScript unit test suite. QUnit has no depend
 * [Assertions](./assert/)
 * [Callback events](./callbacks/)
 * [Configuration options](./config/)
+* [Reporters](./reporters/)
 * [Extension interface](./extension/)
diff --git a/docs/api/reporters/console.md b/docs/api/reporters/console.md
@@ -0,0 +1,65 @@
+---
+layout: page-api
+title: QUnit.reporters.console
+excerpt: |
+  The console reporter logs a JSON object from all `QUnit.on()` reporting events.
+
+  ```
+  runStart {…}
+  testStart {…}
+  testEnd {…}
+  testStart {…}
+  testEnd {…}
+  runEnd {…}
+  ```
+groups:
+  - reporters
+version_added: "2.3.0"
+---
+
+The **console** reporter logs a JSON object from all [`QUnit.on`](../callbacks/QUnit.on.md) reporting events.
+
+Use this to explore or debug the [QUnit event emitter](../callbacks/QUnit.on.md).
+
+## Example
+
+```
+runStart {…}
+testStart {…}
+testEnd {…}
+testStart {…}
+testEnd {…}
+runEnd {…}
+```
+
+## Usage
+
+[QUnit CLI](../../cli.md#qunit-cli-options):
+
+```sh
+qunit --reporter console test/
+```
+
+Enable manually in JavaScript code (since QUnit 2.16):
+
+```js
+QUnit.reporters.console.init(QUnit);
+```
+
+Enable declaratively via [QUnit.config](../config/index.md) (since QUnit 3.0):
+
+```js
+// Preconfig:
+// Set as environment variable to Node.js,
+// or as global variable before loading qunit.js
+qunit_config_reporters_console = true;
+
+// Config: Set from any inline script or JS file after qunit.js
+QUnit.config.reporters.console = true;
+```
+
+## Changelog
+
+| UNRELEASED | Enable declaratively via [`QUnit.config.reporters`](../config/reporters.md).
+| [QUnit 2.16.0](/~https://github.com/qunitjs/qunit/releases/tag/2.16.0) | Exposed as `QUnit.reporters.perf` for programmatic usage.
+| [QUnit 2.3.0](/~https://github.com/qunitjs/qunit/releases/tag/2.3.0) | Introduced as part of the QUnit CLI and `--reporter console`.
diff --git a/docs/api/reporters/html.md b/docs/api/reporters/html.md
@@ -0,0 +1,36 @@
+---
+layout: page-api
+title: QUnit.reporters.html
+excerpt: The HTML Reporter provides a toolbar, renders test results, diffs, and more.
+groups:
+  - reporters
+version_added: "1.0.0"
+---
+
+The **html** reporter renders a toolbar that lets you filter which modules or tests run, visualizes test results with diffs, provides "Rerun" links for individual tests, and more. This is enabled by default in [Browser](../../browser.md) environments
+
+The HTML Reporter is documented in detail at [Browser § HTML Reporter](../../browser.md#lead).
+
+## Usage
+
+By default, the [HTML Reporter](../../browser.md#lead) is automatically enabled in browser environments if a `<div id="qunit">` element exists. If such element doesn't exist, it remains disabled ("headless").
+
+You can override this and disable the HTML Reporter even if the element does exist. For example, to share and reuse the same HTML file for CI, debugging, and manual testing; but disable the HTML Reporter in CI for improved performance.
+
+### Example
+
+```js
+// Preconfig: Set as global variable before loading qunit.js
+qunit_config_reporters_html = false;
+```
+
+Or
+```js
+// Config: Set from any inline script or JS file after qunit.js
+QUnit.config.reporters.html = false;
+```
+
+## Changelog
+
+| UNRELEASED | Toggle declaratively via [`QUnit.config.reporters`](../config/reporters.md).
+| [QUnit 1.0.0](/~https://github.com/qunitjs/qunit/releases/tag/1.0.0) | Initial release.
diff --git a/docs/api/reporters/index.md b/docs/api/reporters/index.md
@@ -0,0 +1,12 @@
+---
+layout: group
+group: reporters
+title: QUnit.reporters
+excerpt: Built-in reporters for TAP, HTML, console, and perf.
+amethyst:
+  # Override inherited "pagetype: navigation" to enable Typesense indexing
+  pagetype: custom
+  robots: index
+---
+
+To create your own reporter, refer to the [QUnit.on()](../callbacks/QUnit.on.md) event emitter and its Reporter API.
diff --git a/docs/api/reporters/perf.md b/docs/api/reporters/perf.md
@@ -0,0 +1,60 @@
+---
+layout: page-api
+title: QUnit.reporters.perf
+excerpt: |
+  The perf reporter measures each QUnit test, to then access or visualize in the browser devtools.
+
+  <img alt="QUnit profiling in Chrome DevTools Performance tab" src="/resources/perf-chrome.png">
+groups:
+  - reporters
+version_added: "2.7.0"
+---
+
+The **perf** reporter measures the duration of each QUnit test and each module, which you can then access in the browser dev tools to understand where time is spent during your test run.
+
+This uses the [performance.measure()](https://developer.mozilla.org/en-US/docs/Web/API/Performance/measure) method of the User Timing API, which adds each measure to the Performance Timeline.
+
+## Browser usage
+
+QUnit enables the perf reporter by default in [Browser](../../browser.md) environments. The measures are automatically included in Firefox Profiler and Chrome DevTools (Safari is pending [WebKit #213870](https://bugs.webkit.org/show_bug.cgi?id=213870)).
+
+```
+QUnit Test Run
+└── QUnit Test Suite: Example
+    ├── QUnit Test: apple
+    ├── QUnit Test: banana
+    └── QUnit Test: citron
+```
+
+<figure>
+  <img alt="QUnit profiling in Chrome DevTools Performance tab" src="/resources/perf-chrome.png">
+  <figcaption>Chrome</figcaption>
+</figure>
+
+-------
+
+<figure>
+  <img alt="QUnit performance in Firefox Profiler" src="/resources/perf-firefox.png">
+  <figcaption>Firefox</figcaption>
+</figure>
+
+## Node.js usage
+
+The Web Performance API is also [available in Node.js](https://nodejs.org/docs/latest/api/perf_hooks.html), and the QUnit perf reporter can be enabled in Node.js since QUnit 3.0.
+
+You can enable it in the QUnit CLI via `--reporter perf`, or activate it explicitly from a [setup file](../../cli.md#--require) as:
+
+```js
+QUnit.reporters.perf.init(QUnit);
+```
+
+**Note:** As of 2025, the [Node.js inspector](https://nodejs.org/docs/latest/api/debugger.html#v8-inspector-integration-for-nodejs) does not yet send User Timing measures to Chrome DevTools ([upstream nodejs/node#47813](/~https://github.com/nodejs/node/issues/47813)).
+
+This means that you _can_ retrieve the QUnit measures from [`performance.getEntries()`](https://nodejs.org/docs/latest/api/perf_hooks.html) and export or visualise them with tooling of your own (e.g. from a [runEnd event](../callback/QUnit.on.md##the-runend-event), or via a PerformanceObserver).
+
+But, when connecting Chrome DevTools to a Node.js process, these are not currently visualised. If you currently test frontend code for browsers via jsdom in Node.js, consider [testing in a real browser](../../browser.md) instead.
+
+## Changelog
+
+| UNRELEASED | Exposed separately via `qunit --reporter` on the CLI, via `QUnit.reporters.perf` for progammatic use in Node.js, and declaratively via [`QUnit.config.reporters`](../config/reporters.md).
+| [QUnit 2.7.0](/~https://github.com/qunitjs/qunit/releases/tag/2.7.0) | Introduced as part of the HTML Reporter, always enabled.