Docs: Add "Efficient development" to Browser Runner page

This restores a chapter of the QUnit Cookbook that Jörn originally wrote on the original qunitjs.com website. https://web.archive.org/web/20160303175442/http://qunitjs.com/cookbook/#efficient-development https://github.com/qunitjs/qunitjs.com/blob/v2.10.2/pages/cookbook.html Co-authored-by: Jörn Zaefferer <[email protected]>
qunitjs · Jun 28, 2024 · 2830156 · 2830156
1 parent 24f003f
commit 2830156
Show file tree

Hide file tree

Showing 6 changed files with 33 additions and 9 deletions.
diff --git a/docs/api/config/module.md b/docs/api/config/module.md
@@ -9,7 +9,7 @@ redirect_from:
 version_added: "1.8.0"
 ---
 
-Select a single test module to run by name.
+Select a single test module to run by name. The module name must be a complete but case-insensitive match.
 
 <table>
 <tr>
@@ -24,7 +24,7 @@ Select a single test module to run by name.
 
 <p class="note" markdown="1">This option can also be set by URL query parameter.</p>
 
-When specified, only a single module will be run if its name is a complete case-insensitive match. If no module name matches, then no tests will be run.
+When specified, only the tests (and nested modules) under the selected module will run. If no module name matches, then no tests will be run.
 
 This option is undefined by default, which means all loaded test modules will be run.
 

diff --git a/docs/api/config/reorder.md b/docs/api/config/reorder.md
@@ -1,7 +1,7 @@
 ---
 layout: page-api
 title: QUnit.config.reorder
-excerpt: Allow re-running of previously failed tests out of order.
+excerpt: Prioritize re-running previously failed tests.
 groups:
   - config
 redirect_from:
@@ -22,8 +22,8 @@ Allow re-running of previously failed tests out of order, before all other tests
 </tr>
 </table>
 
-By default, QUnit will first re-run any tests that failed on a previous run. For large test suites, this can speed up your feedback cycle by a lot.
+By default, QUnit will prioritize re-running tests that failed on a previous run. For large test suites, this can speed up your feedback cycle by a lot.
 
 Note that this feature may lead to unexpected failures if you have non-atomic tests that rely on a very specific execution order. You should consider improving such tests, but this option allows you to disable the reordering behaviour.
 
-When a previously failed test is running first, the HTML Reporter displays "_Rerunning previously failed test_" in the summary whereas just "_Running_" is displayed otherwise.
+This feature is limited to [browser environments](../../browser.md) by default, as it utilizes the `sessionStorage` API. Set [QUnit.config.storage](./storage.md) to enable this feature in Node.js or in other environments.
diff --git a/docs/api/config/storage.md b/docs/api/config/storage.md
@@ -4,6 +4,7 @@ title: QUnit.config.storage
 excerpt: The Storage object to use for remembering failed tests between runs.
 groups:
   - config
+  - extension
 redirect_from:
   - "/config/storage/"
 version_added: "2.1.0"
@@ -18,10 +19,10 @@ The Storage object to use for remembering failed tests between runs.
 </tr>
 <tr>
   <th>default</th>
-  <td markdown="span">`globalThis.sessionStorage`</td>
+  <td markdown="span">`globalThis.sessionStorage` or `undefined`</td>
 </tr>
 </table>
 
-This is mainly for use by the HTML Reporter, where `sessionStorage` will be used if supported by the browser.
+This is used to power the [reorder feature](../config.md). In [browser environments](../../browser.md) this will use `sessionStorage` if supported by the browser.
 
-While Node.js and other non-browser environments are not known to offer something like this by default, one can attach any preferred form of persistence by assigning an object that implements the [`Storage` interface methods](https://html.spec.whatwg.org/multipage/webstorage.html#the-storage-interface) of the Web Storage API.
+In Node.js and other non-browser environments, there is no storage object available for this purpose by default. You can attach your own preferred form of persistence between test runs, by assigning an object to `QUnit.config.storage` that implements `getItem`, `setItem` and `removeItem` methods, similar to the [Web Storage API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API).
diff --git a/docs/api/extension/QUnit.dump.parse.md b/docs/api/extension/QUnit.dump.parse.md
@@ -33,7 +33,7 @@ If you need more or less output, change the value of `QUnit.dump.maxDepth`, repr
 
 The following is an example from [grunt-contrib-qunit][], which sends results from QUnit (running in Headless Chrome) to a CLI tool.
 
-[grunt-contrib-qunit]: https://github.com/gruntjs/grunt-contrib-qunit/blob/188a29af7817e1798fdd95f1ab7d3069231e4859/chrome/bridge.js#L42-L60
+[grunt-contrib-qunit]: https://github.com/gruntjs/grunt-contrib-qunit/blob/v10.0.0/chrome/bridge.js#L111-L124
 
 ```js
 QUnit.log(function (obj) {

diff --git a/docs/browser.md b/docs/browser.md
@@ -68,6 +68,14 @@ This helps keep your tests them atomic!
 
 Find examples and learn more at [`QUnit.config.fixture`](./api/config/fixture.md).
 
+## Efficient development
+
+As your project grows, you may reach a point where the complete test suite takes more than a second or two to run. QUnit provides several automatic and optional ways to maintain a good feedback cycle.
+
+QUnit's [reorder feature](./api/config/reorder.md) automatically remembers failing tests, and prioritizes those when you reload the page, running them before all other tests. Together with "Hide passed tests" in the [toolbar](#html-reporter), this let's you stay focussed by running and showing only what matters most.
+
+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.
+
 ## Integrations
 
 ### Linting

diff --git a/docs/cli.md b/docs/cli.md
@@ -85,6 +85,21 @@ See [QUnit.config](./api/config/index.md) for all available configuration option
 
 This option assigns [`QUnit.config.seed`](./api/config/seed.md) for you.
 
+### `--watch`
+
+Automatically re-run your tests after file changes in the current directory.
+
+In watch mode, QUnit will run your tests once initially, and then keep watch mode open to re-run tests after files changed anywhere in or under the current directory. This includes adding or removing files.
+
+## Efficient development
+
+_For browser automations from the command-line, refer to [Browser automation](./browser.md#integrations) instead._
+
+As your project grows, you may reach a point where the complete test suite takes more than a second to run. QUnit provides several ways to maintain a fast feedback cycle on the command-line.
+
+* Use [`--watch`](./cli.md) to automatically re-run your tests continously after files in the current directory have changed.
+* When building out a larger feature, use `--filter` or `--module` to decide which tests to run.
+
 ## Node.js CLI options
 
 The QUnit CLI uses Node.js. You can pass [Node.js CLI](https://nodejs.org/api/cli.html) options via the [`NODE_OPTIONS`](https://nodejs.org/api/cli.html#cli_node_options_options) environment variable. For example, to use `--enable-source-maps` or `--inspect`, invoke QUnit as follows: