Docs: New guide for Browser Runner and HTML Reporter

This restores the first half of the Cookbook that Jörn originally wrote on the original qunitjs.com website. We removed this during the redesign in 2020, but we hadn't found a new place for everything. qunitjs/qunitjs.com#151 https://github.com/qunitjs/qunitjs.com/blob/v2.10.2/pages/cookbook.html * Update config doc pages to reflect whether something is part of Browser Runner (active in any browser environment), or the HTML Reporter. These have been separated now per #1118, as QUnit.reporters.html, and deals purely with what happens inside the optional `div[id=qunit]` element. * Move browser-related content from intro.md to the new browser.md. We should probably do the same for Node.js/CLI as well, and focus this only on env-agnostic getting started. This would be easier if the example use export/import ESM instead of having to assume either module.exports (Node.js) or globals (browser). Co-authored-by: Jörn Zaefferer <[email protected]> Fixes #1748. Fixes #1747.
qunitjs · Jun 28, 2024 · 1b43add · 1b43add
1 parent 29b3975
commit 1b43add
Show file tree

Hide file tree

Showing 25 changed files with 646 additions and 132 deletions.
diff --git a/.eslintrc.json b/.eslintrc.json
@@ -191,6 +191,22 @@
         "sourceType": "module"
       }
     },
+    {
+      "files": [
+        "docs/resources/**/*.html",
+        "docs/resources/**/*.js"
+      ],
+      "parserOptions": {
+        "ecmaVersion": 2018
+      },
+      "env": {
+        "es2017": true,
+        "browser": true
+      },
+      "globals": {
+        "QUnit": "readonly"
+      }
+    },
     {
       "files": ["**/*.md"],
       "processor": "markdown/markdown"

diff --git a/README.md b/README.md
@@ -18,8 +18,8 @@ project and has since evolved to test any client-side or server-side JavaScript
 
 * [API documentation](https://qunitjs.com/api/)
 * [Guides how-to](https://qunitjs.com/guides/)
-* [Browser support](https://qunitjs.com/intro/#browser-support)
-* [Integrations](https://qunitjs.com/intro/#integrations)
+* [Browser support](https://qunitjs.com/browser/#browser-support)
+* [Browser automation](https://qunitjs.com/browser/#integrations)
 
 ## Support
 

diff --git a/docs/_data/sitenav.yml b/docs/_data/sitenav.yml
@@ -3,8 +3,12 @@
   sub:
     - name: Getting Started
       href: /intro/
+    - name: Browser Runner
+      href: /browser/
     - name: Command-line Interface
       href: /cli/
+    - name: Download
+      href: /intro/#download
     - name: Plugins
       href: /plugins/
     - name: QUnit 2.0 Upgrade Guide
@@ -17,7 +21,7 @@
     - name: Who's using QUnit?
       href: /projects/
     - name: Browser Support
-      href: /intro/#browser-support
+      href: /browser/#browser-support
     - name: About QUnit
       href: /about/
     - name: Brand Guidelines

diff --git a/docs/api/callbacks/QUnit.on.md b/docs/api/callbacks/QUnit.on.md
@@ -4,6 +4,7 @@ title: QUnit.on()
 excerpt: Register an event listener callback.
 groups:
   - callbacks
+  - extension
 redirect_from:
   - "/callbacks/QUnit.on/"
 version_added: "2.2.0"

diff --git a/docs/api/config/altertitle.md b/docs/api/config/altertitle.md
@@ -1,15 +1,15 @@
 ---
 layout: page-api
 title: QUnit.config.altertitle
-excerpt: Insert a success or failure symbol in the document title (HTML Reporter).
+excerpt: Insert a success or failure symbol in the document title.
 groups:
   - config
 redirect_from:
   - "/config/altertitle/"
 version_added: "1.0.0"
 ---
 
-In the HTML Reporter, whether to insert a success or failure symbol in the document title.
+In browser environments, whether to insert a success or failure symbol in the document title.
 
 <table>
 <tr>

diff --git a/docs/api/config/collapse.md b/docs/api/config/collapse.md
@@ -22,6 +22,6 @@ In the HTML Reporter, collapse the details of failing tests after the first one.
 </tr>
 </table>
 
-By default, QUnit's HTML Reporter collapses consecutive failing tests showing only the details for the first failed test. The other tests can be expanded manually with a single click on the test title.
+By default, the [HTML Reporter](../../browser.md) collapses consecutive failing tests showing only the details for the first failed test. The other tests can be expanded manually with a single click on the test title.
 
 Set this option to `false` to expand the details for all failing tests.
diff --git a/docs/api/config/filter.md b/docs/api/config/filter.md
@@ -24,7 +24,7 @@ Select tests to run based on a substring or pattern match.
 
 <p class="note" markdown="1">
 
-This option is available as [CLI option](../../cli.md), as control in the [HTML Reporter](../../intro.md#in-the-browser), and supported as URL query parameter.
+This option is available as [CLI option](../../cli.md), as control in the [HTML Reporter](../../browser.md), and supported as URL query parameter.
 
 </p>
 
@@ -78,3 +78,12 @@ The below matches `foo`, `foo > sub`, and `foo.sub`, but skips `bar`, `bar.foo`,
 ```js
 QUnit.config.filter = '/^foo/';
 ```
+
+### URL parameter
+
+```
+?filter=foo
+?filter=!foo
+?filter=/foo/
+?filter=!/foo/
+```
diff --git a/docs/api/config/fixture.md b/docs/api/config/fixture.md
@@ -1,15 +1,15 @@
 ---
 layout: page-api
 title: QUnit.config.fixture
-excerpt: HTML content to render in the fixture container at the start of each test (HTML Reporter).
+excerpt: HTML content to render before each test.
 groups:
   - config
 redirect_from:
   - "/config/fixture/"
 version_added: "1.0.0"
 ---
 
-In the HTML Reporter, this HTML content will be rendered in the fixture container at the start of each test.
+In browser environments, this HTML will be rendered in the `#qunit-fixture` element before each test.
 
 <table>
 <tr>
@@ -22,6 +22,164 @@ In the HTML Reporter, this HTML content will be rendered in the fixture containe
 </tr>
 </table>
 
-By default QUnit will observe the initial content of the `#qunit-fixture` element, and use that as the fixture content for all tests. Use this option to configure the fixture content through JavaScript instead.
+QUnit automatically resets the contents of `<div id="qunit-fixture">`. This gives every test a fresh start, and automatically cleans up any additions or other changes from your tests. As long as you append or insert your elements inside the fixture, you will never have to manually clean up after your tests to keep them atomic.
+
+By starting with an empty fixture in your test HTML file, you effectively give each test a clean start, as QUnit will automatically remove anything that was added there before the next test begins.
+
+If many of your tests require the same markup, you can also set it inside the fixture ahead of time. This reduces duplication between tests. QUnit guruantees that each test will start with a fresh copy of the original fixture, undoing any changes that happened during any previous tests.
+
+You can define a custom fixture in one of two ways:
+
+* In HTML: By writing it as HTML inside the `<div id="qunit-fixture">` element.
+* In JavaScript: Set `QUnit.config.fixture` to a string from an [inline or bootstrap script](./index.md).
+
+By default, if `QUnit.config.fixture` is not set, QUnit will look for the `#qunit-fixture` element when the test run begins, and assign its contents to `QUnit.config.fixture`. The initially observed content is then restored before each test.
 
 To disable QUnit's fixture resetting behaviour, set the option to `null`.
+
+## Example
+
+### Automatic teardown
+
+Starting with an empty fixture. Any additions are automatically removed.
+
+```html
+<body>
+  <div id="qunit"></div>
+  <div id="qunit-fixture"></div>
+
+  <script src="test/example.js"></script>
+</body>
+```
+```js
+// test/example.js
+
+QUnit.test('example [first]', function (assert) {
+  const fixture = document.querySelector('#qunit-fixture');
+
+  const resultA = document.querySelectorAll('#first');
+  assert.strictEqual(resultA.length, 0, 'initial');
+
+  const div = document.createElement('div');
+  div.id = 'first';
+  fixture.append(div);
+
+  const resultB = document.querySelectorAll('#first');
+  assert.strictEqual(resultB.length, 1, 'after append');
+});
+
+QUnit.test('example [second]', function (assert) {
+  const fixture = document.querySelector('#qunit-fixture');
+
+  // The previous elements were automatically detached.
+  const result = document.querySelectorAll('#first');
+  assert.strictEqual(result.length, 0, 'initial is back to zero');
+});
+```
+
+
+### qunit-fixture HTML
+
+```html
+<body>
+  <div id="qunit"></div>
+  <div id="qunit-fixture">
+    <p>
+      <span class="marty"><strong>Marty McFly</strong>: Listen, you got a back door to this place?</span><br>
+      <span class="bar"><strong>Bartender</strong>: Yeah, it's in the <em>back</em>.</span>
+    </p>
+  </div>
+</body>
+```
+
+```js
+function findText (element, tagName) {
+  let ret = '';
+  for (const emNode of element.querySelectorAll(tagName)) {
+    ret += emNode.textContent + ' ';
+  }
+  return ret.trim() || null;
+}
+
+QUnit.test('findText [strong]', function (assert) {
+  const fixture = document.querySelector('#qunit-fixture');
+
+  assert.strictEqual(
+    findText(fixture, 'strong'),
+    'Marty McFly Bartender',
+    'initial'
+  );
+
+  fixture.querySelector('.bar').remove();
+
+  assert.strictEqual(
+    findText(fixture, 'strong'),
+    'Marty McFly',
+    'removed bar'
+  );
+});
+
+QUnit.test('findText [code]', function (assert) {
+  const fixture = document.querySelector('#qunit-fixture');
+  fixture.innerHTML = '<p>You can <code>add</code> two <em>numbers</em>.</p>';
+
+  assert.strictEqual(
+    findText(fixture, 'code'),
+    'add'
+  );
+
+  assert.strictEqual(
+    findText(fixture, 'strong'),
+    null
+  );
+});
+
+// The first test removed <span class=bar> and its <em> child.
+// The second test replaced the fixture entirely.
+// The fixture is clean and restored before each test starts.
+QUnit.test('findText [em]', function (assert) {
+  const fixture = document.querySelector('#qunit-fixture');
+
+  assert.strictEqual(
+    findText(fixture, 'em'),
+    'back',
+    'initial content was restored'
+  );
+});
+```
+
+### dynamic qunit-fixture
+
+```html
+<body>
+  <div id="qunit"></div>
+  <div id="qunit-fixture"></div>
+
+  <script src="test/bootstrap.js"></script>
+  <script src="test/example.js"></script>
+</body>
+```
+```js
+// test/bootstrap.js
+
+QUnit.config.fixture = '<p>Hi <strong>there</strong>, stranger!</p>';
+
+// test/example.js
+
+QUnit.test('example [first]', function (assert) {
+  const fixture = document.querySelector('#qunit-fixture');
+
+  assert.strictEqual(fixture.textContent, 'Hi there, stranger!');
+
+  fixture.querySelector('strong').remove();
+
+  assert.strictEqual(fixture.textContent, 'Hi , stranger!');
+});
+
+QUnit.test('example [second]', function (assert) {
+  const fixture = document.querySelector('#qunit-fixture');
+
+  // The fixture starts fresh on each test!
+  assert.strictEqual(fixture.textContent, 'Hi there, stranger!');
+});
+```
diff --git a/docs/api/config/hidepassed.md b/docs/api/config/hidepassed.md
@@ -22,6 +22,14 @@ In the HTML Reporter, hide results of passed tests.
 </tr>
 </table>
 
-<p class="note" markdown="1">This option can also be controlled via the [HTML Reporter](../../intro.md#in-the-browser).</p>
+<p class="note" markdown="1">
 
-By default, the HTML Reporter will list (in collapsed form) the names of all passed tests. Enable this option, to only list failing tests.
+This option can also be controlled via the [HTML Reporter](../../browser.md).
+
+</p>
+
+By default, the HTML Reporter will list both passing and failing tests. Passing tests are by default collapsed to display only their name. Enable `hidepassed` to hide passing tests completely, and show only failing tests in the list.
+
+## See also
+
+* [QUnit.config.collapse](./collapse.md)
diff --git a/docs/api/config/moduleId.md b/docs/api/config/moduleId.md
@@ -9,7 +9,7 @@ redirect_from:
 version_added: "1.23.0"
 ---
 
-In the HTML Reporter, select one or more modules to run by their internal ID.
+Used by the HTML Reporter, this selects one or more modules by their internal ID to run exclusively.
 
 <table>
 <tr>
@@ -22,7 +22,11 @@ In the HTML Reporter, select one or more modules to run by their internal ID.
 </tr>
 </table>
 
-<p class="note" markdown="1">This option can be controlled via the [HTML Reporter](../../intro.md#in-the-browser) interface.</p>
+<p class="note" markdown="1">
+
+This option can be controlled via the [HTML Reporter](../../browser.md) interface.
+
+</p>
 
 Specify modules by their internally hashed identifier for a given module. You can specify one or multiple modules to run. This option powers the multi-select dropdown menu in the HTML Reporter.
 

diff --git a/docs/api/config/noglobals.md b/docs/api/config/noglobals.md
@@ -24,4 +24,10 @@ Check the global object after each test and report new properties as failures.
 
 Enable this option to let QUnit keep track of which global variables and properties exist on the global object (e.g. `window` in browsers). When new global properties are found, they will result in test failures to you make sure your application and your tests are not leaking any state.
 
-<p class="note" markdown="1">This option can also be controlled via the [HTML Reporter](../../intro.md#in-the-browser).</p>
+This helps you make sure the code under test doesn't accidentally leak or declare any global variables.
+
+<p class="note" markdown="1">
+
+This option can also be controlled via the [HTML Reporter](../../browser.md).
+
+</p>
diff --git a/docs/api/config/notrycatch.md b/docs/api/config/notrycatch.md
@@ -22,8 +22,13 @@ Disable handling of uncaught exceptions during tests.
 </tr>
 </table>
 
-<p class="note" markdown="1">This option can also be controlled via the [HTML Reporter](../../intro.md#in-the-browser) interface, and is supported as URL query parameter.</p>
+<p class="note" markdown="1">
 
-By default, QUnit handles uncaught exceptions during test execution and reports them as test failures. This lets other tests continue running and allows reporters to summarise results.
+This option can also be controlled via the [HTML Reporter](../../browser.md) interface, and is supported as URL query parameter.
+
+</p>
+
+By default, QUnit handles uncaught errors during test execution and reports them as test failures. This allows reporters to reliably summarise results.
+
+Enabling this flag will disable this error handling, allowing your error to become a "native" uncaught exception and thus interrupt QUnit. This can sometimes ease debugging through a browser's developer tools, such as when dealing with breakpoints, or source maps.
 
-Enabling this flag will disable this error handling, allowing you to more easily debug uncaught exceptions through developer tools.
diff --git a/docs/api/config/scrolltop.md b/docs/api/config/scrolltop.md
@@ -1,15 +1,15 @@
 ---
 layout: page-api
 title: QUnit.config.scrolltop
-excerpt: Scroll to the top of the page after the test run (HTML Reporter).
+excerpt: Scroll to the top of the page after the test run.
 groups:
   - config
 redirect_from:
   - "/config/scrolltop/"
 version_added: "1.14.0"
 ---
 
-In the HTML Reporter, ensure the browser is scrolled to the top of the page when the tests are done.
+In browser environments, scrop to the top of the page after the tests are done.
 
 <table>
 <tr>