qunitx 1.2.19 → 1.3.1

package/README.md

@@ -2,90 +2,117 @@
 
 # QUnitX
 
+**One test file. Node.js, Deno, and the browser. No config.**
+
 [![CI](https://github.com/izelnakri/qunitx/actions/workflows/ci.yml/badge.svg)](https://github.com/izelnakri/qunitx/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/izelnakri/qunitx/branch/main/graph/badge.svg)](https://codecov.io/gh/izelnakri/qunitx)
 [![npm](https://img.shields.io/npm/v/qunitx)](https://www.npmjs.com/package/qunitx)
+[![JSR](https://jsr.io/badges/@izelnakri/qunitx)](https://jsr.io/@izelnakri/qunitx)
+[![JSR score](https://jsr.io/badges/@izelnakri/qunitx/score)](https://jsr.io/@izelnakri/qunitx)
 [![npm downloads](https://img.shields.io/npm/dm/qunitx)](https://www.npmjs.com/package/qunitx)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
-[![Ask me anything](https://img.shields.io/badge/ask%20me-anything-1abc9c.svg)](https://github.com/izelnakri/qunitx/issues)
 [![Sponsor](https://img.shields.io/badge/sponsor-%E2%99%A5-pink)](https://github.com/sponsors/izelnakri)
 
-</div>
+![QUnitX demo](https://raw.githubusercontent.com/izelnakri/qunitx/main/docs/demo.gif)
 
-**The oldest, most battle-tested JavaScript test API — now universal.**
+<sub>Left: `node --test` and `deno test` on the same file, including watch mode going red → green.<br>
+Right: the same file in real Chrome, with QUnit's filterable, shareable UI.</sub>
 
-Run the **same test file** in Node.js, Deno, and the browser without changes, their usual way.
-Zero dependencies. No config needed for Node. TypeScript works out of the box.
+</div>
 
 ---
 
-## Why QUnit?
+Write a test once. Run it under Node's built-in runner, Deno's built-in runner, and a
+real browser — the **same file**, unchanged, each runtime its usual way.
 
-QUnit was created in 2008 by the jQuery team. While newer frameworks come and go,
-QUnit has quietly accumulated 16+ years of real-world edge-case handling that younger
-tools are still catching up to. Its assertion API is the most mature in the JavaScript
-ecosystem:
-
-- **`assert.deepEqual`** — handles circular references, prototype chains, Sets, Maps,
-  typed arrays, Dates, RegExps, and getters correctly
-- **`assert.throws` / `assert.rejects`** — match errors by constructor, regex, or custom validator
-- **`assert.step` / `assert.verifySteps`** — declarative execution-order verification;
-  catches missing async callbacks that other frameworks silently swallow
-- **`assert.expect(n)`** — fails the test if exactly _n_ assertions didn't run;
-  invaluable for async code where missing assertions would otherwise pass silently
-- **`assert.timeout(ms)`** — hard deadline per test; the test fails with a descriptive
-  message if it doesn't complete in time (all three runtimes)
-- **Hooks** — `before`, `beforeEach`, `afterEach`, `after` with correct FIFO/LIFO ordering,
-  properly scoped across nested modules
-- **Shareable browser URLs** — the QUnit browser UI filters tests via query params, so you can
-  share `https://yourapp.test/?moduleId=abc123` with a colleague and they see exactly the same view
-
-QUnitX wraps this API to work with **Node.js's built-in `node:test` runner** and
-**Deno's native test runner** — no Jest, Vitest, or other framework needed.
-
-QUnit includes the fastest assertion and test runtime in JS world. I've previously contributed to some [speed optimizations](https://qunitjs.com/blog/2022/02/15/qunit-2-18-0/) to QUnit, we benchmark every possible thing to make it the fastest test
-runtime, faster than node.js and deno default assertions in most cases. Therefore I consider myself very objective
-when I say QUnit(X) is the best JS/TS testing tool out there.
+```ts
+import { module, test } from 'qunitx';
 
----
+module('Math', () => {
+  test('addition', (assert) => {
+    assert.equal(2 + 2, 4);
+  });
+});
+```
 
-## Demo
+```sh
+node --test math-test.ts     # Node's runner
+deno test math-test.ts       # Deno's runner
+qunitx math-test.ts          # real browser, TAP in your terminal
+```
 
-> Left window: `node --test` and `deno test` running the same file.
-> Right window: QUnit browser UI with filterable, shareable test results.
+No `jest.config.js`. No `vitest.config.ts`. No setup files, no transform pipeline, no
+globals to inject. TypeScript runs as-is. **Zero runtime dependencies.**
 
-<!-- Demo GIF: see docs/demo.tape (VHS script) for terminal portion.
-     For the combined terminal + browser recording, see "Recording the demo" below. -->
-![QUnitX demo](https://raw.githubusercontent.com/izelnakri/qunitx/main/docs/demo.gif)
+---
 
-Live browser UI example (click to see filterable QUnit test suite):
+## Why QUnit?
 
+QUnit was created in 2008 by the jQuery team. Newer frameworks come and go; QUnit has
+quietly accumulated 16+ years of real-world edge-case handling that younger tools are
+still catching up to. Its assertion API is the most mature in the JavaScript ecosystem:
+
+- **`assert.deepEqual`** handles circular references, prototype chains, Sets, Maps,
+  typed arrays, Dates, RegExps and getters correctly — the cases that quietly return
+  the wrong answer elsewhere.
+- **`assert.throws` / `assert.rejects`** match errors by constructor, regex, error
+  instance, or a custom validator.
+- **`assert.step` / `verifySteps`** turn execution order into a declarative assertion,
+  and catch missing async callbacks that other frameworks silently swallow.
+- **`assert.expect(n)`** fails the test when exactly _n_ assertions did not run —
+  invaluable for async code, where a missing assertion otherwise looks like a pass.
+- **`assert.timeout(ms)`** is a hard per-test deadline, on all three runtimes.
+- **Hooks** — `before`, `beforeEach`, `afterEach`, `after` with correct FIFO/LIFO
+  ordering, properly scoped across nested modules.
+- **Shareable browser URLs** — the QUnit UI keeps filter state in the query string, so
+  `?moduleId=abc123` reproduces exactly what you were looking at for a colleague.
+
+It is also fast. I've contributed [speed optimisations to QUnit itself](https://qunitjs.com/blog/2022/02/15/qunit-2-18-0/),
+and we benchmark every part of this wrapper — in most cases the assertions beat Node's
+and Deno's built-in ones. So I am not especially objective when I say QUnit(X) is the
+best testing tool in JS/TS. But I have the benchmarks.
+
+QUnitX wraps that API over **`node:test`** and **Deno's native runner**. No Jest, no
+Vitest, no second framework underneath.
+
+**Live example** — a real suite in the browser UI, filtered and linkable:
 [objectmodel.js.org/test/?moduleId=6e15ed5f](https://objectmodel.js.org/test/?moduleId=6e15ed5f&moduleId=950ec9c5)
 
 ---
 
-## Installation
+## Install
 
 ```sh
 npm install qunitx --save-dev
 ```
 
-Requires **Node.js >= 22** (LTS) or **Deno >= 2**.
+Deno users can install from JSR instead — same library, published from CI with
+[provenance](https://jsr.io/@izelnakri/qunitx):
 
-No config file needed. No `jest.config.js`, no `vitest.config.ts`, no setup files — just import and run.
-TypeScript is supported natively: pass `.ts` files directly to `node --test` or `deno test`.
+```sh
+deno add jsr:@izelnakri/qunitx
+```
+
+Requires **Node.js >= 22** (LTS) or **Deno >= 2**. For a Deno project with no
+`package.json`, an import map is enough:
+
+```sh
+echo '{"imports": {"qunitx": "npm:qunitx"}}' > deno.json
+```
 
 ---
 
 ## Quick start
 
+One file, every runtime:
+
 ```ts
-// math-test.ts  (works in Node, Deno, and browser unchanged)
+// math-test.ts
 import { module, test } from 'qunitx';
 
 module('Math utilities', (hooks) => {
-  hooks.before((assert) => {
-    assert.step('setup complete');
+  hooks.beforeEach(function () {
+    this.numbers = [1, 2, 3];
   });
 
   test('addition', (assert) => {
@@ -93,14 +120,17 @@ module('Math utilities', (hooks) => {
     assert.notEqual(2 + 2, 5);
   });
 
-  test('deepEqual', (assert) => {
-    assert.deepEqual({ a: 1, b: [2, 3] }, { a: 1, b: [2, 3] });
+  test('deepEqual understands Sets and Maps', (assert) => {
+    assert.deepEqual(
+      { tags: new Set(['js']), scores: new Map([['a', 1]]) },
+      { tags: new Set(['js']), scores: new Map([['a', 1]]) },
+    );
   });
 
   module('Async', () => {
-    test('resolves correctly', async (assert) => {
-      const result = await Promise.resolve(42);
-      assert.strictEqual(result, 42);
+    test('resolves', async (assert) => {
+      const user = await Promise.resolve({ id: 1, name: 'Alice' });
+      assert.propContains(user, { name: 'Alice' });
     });
   });
 });
@@ -109,55 +139,34 @@ module('Math utilities', (hooks) => {
 ### Node.js
 
 ```sh
-# No extra dependencies — uses the Node built-in test runner
-node --test math-test.ts
-
-# Watch mode (re-runs on save)
-node --test --watch math-test.ts
-
-# Glob pattern
-node --test --watch 'test/**/*.ts'
-
-# Code coverage
-npx c8 node --test math-test.ts
+node --test math-test.ts              # built-in runner, no extra deps
+node --test --watch math-test.ts      # rerun on save
+node --test --watch 'test/**/*.ts'    # globs
+npx c8 node --test math-test.ts       # coverage
 ```
 
 ### Deno
 
 ```sh
-# Install qunitx once (same command as Node)
-npm install qunitx --save-dev
-
-# Run
 deno test math-test.ts
-
-# With explicit permissions
 deno test --allow-read --allow-env math-test.ts
-```
-
-For Deno-only projects without a `package.json`, use an import map instead:
-
-```sh
-echo '{"imports": {"qunitx": "npm:qunitx"}}' > deno.json
-deno test math-test.ts
+deno test --coverage=cov math-test.ts
 ```
 
 ### Browser
 
-Use [qunitx-cli](https://github.com/izelnakri/qunitx-cli) to get browser test output
-in your terminal / CI, or to open the live QUnit UI during development:
+[qunitx-cli](https://github.com/izelnakri/qunitx-cli) bundles your test file, runs it in
+a real browser, and streams TAP back to your terminal:
 
 ```sh
 npm install -g qunitx-cli
 
-# Headless (CI-friendly — outputs TAP to stdout)
-qunitx math-test.ts
-
-# Open QUnit browser UI alongside terminal output
-qunitx math-test.ts --debug
+qunitx math-test.ts             # headless — TAP on stdout, CI-friendly
+qunitx math-test.ts --debug     # opens the live QUnit UI too
 ```
 
 The browser UI lets you:
+
 - Filter by module or test name (filter state is preserved in the URL)
 - Share a link that reproduces the exact filtered view with a colleague
 - Re-run individual tests by clicking them
@@ -170,206 +179,387 @@ The browser UI lets you:
 
 ---
 
-## Migrating from QUnit
+## Assertions
+
+Every assertion takes an optional trailing `message` used in the failure output. This is
+the complete list.
+
+### Truthiness
+
+| | |
+|---|---|
+| `assert.ok(value)` | passes if `value` is truthy |
+| `assert.notOk(value)` | passes if `value` is falsy |
+| `assert.true(value)` | passes only for exactly `true` |
+| `assert.false(value)` | passes only for exactly `false` |
 
-One import line is all that changes:
+### Equality
+
+| | |
+|---|---|
+| `assert.equal(actual, expected)` | loose `==`, after QUnit's coercion rules |
+| `assert.notEqual(actual, expected)` | loose `!=` |
+| `assert.strictEqual(actual, expected)` | strict `===` — the one you usually want |
+| `assert.notStrictEqual(actual, expected)` | strict `!==` |
+| `assert.deepEqual(actual, expected)` | deep structural equality: nested objects, arrays, `Set`, `Map`, typed arrays, `Date`, `RegExp`, circular references |
+| `assert.notDeepEqual(actual, expected)` | inverse of `deepEqual` |
+| `assert.propEqual(actual, expected)` | compares **own enumerable properties only** — ignores prototype and class identity, so a class instance can equal a plain object |
+| `assert.notPropEqual(actual, expected)` | inverse of `propEqual` |
+| `assert.propContains(actual, expected)` | **partial** match: every property in `expected` must match, extras in `actual` are ignored |
+| `assert.notPropContains(actual, expected)` | inverse of `propContains` |
+
+`propContains` is the one to reach for when asserting on an API response you only partly
+care about:
 
 ```js
-// Before:
-import { module, test } from 'qunit';
+test('api response', async (assert) => {
+  const user = await fetchUser(1);
+  // passes regardless of createdAt, updatedAt, avatarUrl, …
+  assert.propContains(user, { id: 1, role: 'admin' });
+});
+```
 
-// After:
-import { module, test } from 'qunitx';
+### Errors
+
+| | |
+|---|---|
+| `assert.throws(fn, expected?)` | `fn` must throw |
+| `await assert.rejects(promise, expected?)` | `promise` must reject |
+
+`expected` matches by constructor, by `RegExp` against the message, against another
+`Error` instance (same constructor, name and message), or by a custom validator:
+
+```js
+test('error matching', (assert) => {
+  assert.throws(() => JSON.parse('{'), SyntaxError);              // constructor
+  assert.throws(() => parse(''), /unexpected end/i);              // message regex
+  assert.throws(() => parse(''), new SyntaxError('unexpected'));  // Error instance
+  assert.throws(() => run(), (err) => err.code === 'EAGAIN');     // validator
+});
+
+test('async errors', async (assert) => {
+  await assert.rejects(fetchMissing(), TypeError);
+});
 ```
 
----
+> Passing an `async` function to `assert.throws` is a mistake that silently passes in
+> most frameworks — it returns a rejected promise rather than throwing. QUnitX detects
+> it and tells you to use `assert.rejects`.
 
-## QUnit compatibility
+### Execution order
 
-qunitx follows the same test-environment model as QUnit:
+| | |
+|---|---|
+| `assert.step(label)` | records a step |
+| `assert.verifySteps(labels)` | asserts the recorded steps equal `labels` in order, then clears them |
 
-- **Fresh context per test** — each test gets its own `this` object. Writes in one test never bleed into a sibling.
-- **Prototype-chain inheritance** — a parent module's `before()` hook sets properties on the module context. Each test inherits those properties, so reads work naturally (`this.x`) while writes stay local to the test.
-- **`before()` assertions** — attributed to the first test in the module (matching QUnit's attribution model).
-- **`after()` assertions** — attributed to the last test in the module.
-- **Hook ordering** — `before`/`beforeEach` run FIFO; `afterEach`/`after` run LIFO, exactly as in QUnit.
+```js
+test('callbacks fire in order', (assert) => {
+  emitter.on('start', () => assert.step('start'));
+  emitter.on('done', () => assert.step('done'));
 
-> **Known difference:** In QUnit's browser runner, `before()` hook assertions are attributed to the first test in the *entire subtree* (including nested modules). In the Node/Deno adapters, they are attributed to the first *direct* test of the module. In the common case where direct tests appear before nested modules, the behavior is identical.
+  emitter.run();
 
-### `context` — arrow-function-friendly shared state
+  assert.verifySteps(['start', 'done']);
+});
+```
 
-QUnit exposes the shared test context as `this` inside hooks and test bodies. This works with regular functions but not with arrow functions, since arrow functions capture `this` lexically from the surrounding scope.
+### Async control
 
-QUnitX adds `context` to the meta second argument of every hook and test callback. It points to the same shared object as `this`, so you can use whichever style you prefer:
+| | |
+|---|---|
+| `assert.expect(n)` | the test fails unless exactly `n` assertions ran |
+| `assert.timeout(ms)` | hard deadline for this test; calling again resets it |
+| `assert.async()` | returns a `done` callback; the test waits until every `done` is called |
 
 ```js
-// QUnit style — regular functions, uses `this`
-module('Suite', function (hooks) {
-  hooks.before(function () { this.db = createDb(); });
-  hooks.afterEach(function (assert) { this.db.reset(); });
+test('callback-style async', (assert) => {
+  const done = assert.async();
+  assert.expect(1);
 
-  test('query', function (assert) {
-    assert.ok(this.db.query('SELECT 1'));
+  fs.readFile('data.json', (err, buf) => {
+    assert.ok(buf.length > 0);
+    done();
   });
 });
 
-// QUnitX style — arrow functions, uses `context`
-module('Suite', (hooks, { context }) => {
-  context.shared = 'module-level value';
+test('deadline', async (assert) => {
+  assert.timeout(500);
+  assert.ok(await fetchSomething());
+});
+```
 
-  hooks.before((assert, { context }) => { context.db = createDb(); });
-  hooks.afterEach((assert, { context }) => { context.db.reset(); });
+`assert.expect()` is what turns "the callback never fired" from a silent pass into a
+failure. For `async`/`await` tests just use an `async` callback — `assert.async()` is for
+callback APIs.
 
-  test('query', (assert, { context }) => {
-    assert.ok(context.db.query('SELECT 1'));
+### Custom assertions
+
+`assert.pushResult` is the building block every other assertion is made of. The plain
+version is a function that takes `assert`:
+
+```js
+function assertIsEven(assert, value) {
+  assert.pushResult({
+    result: value % 2 === 0,
+    actual: value,
+    expected: 'an even number',
+    message: `${value} is even`,
   });
+}
+
+test('even numbers', (assert) => {
+  assertIsEven(assert, 4);
 });
 ```
 
-Context inheritance follows QUnit's prototype-chain model regardless of which style you use: `before()` writes are visible to all tests in the module; each test's own writes stay local to that test.
+Better: put it **on `assert` itself**, so it reads like every built-in assertion and
+needs no import at the call site. The assertion class is exported from `qunitx/assert`,
+and adding to its prototype once — in a setup file, or at the top of your test helper —
+makes it available in every test:
+
+```js
+// test-helpers.js
+import Assert from 'qunitx/assert';
+
+Assert.prototype.isEven = function (value, message) {
+  this.pushResult({
+    result: value % 2 === 0,
+    actual: value,
+    expected: 'an even number',
+    message: message ?? `${value} is even`,
+  });
+};
+```
+
+```js
+import './test-helpers.js';
+
+test('even numbers', (assert) => {
+  assert.isEven(4);                      // passes
+  assert.isEven(3, 'three is even');     // fails, with your message
+});
+```
+
+In TypeScript, declare the extended shape and assign through it:
+
+```ts
+import BaseAssert from 'qunitx/assert';
+
+export interface Assert extends BaseAssert {
+  isEven(value: number, message?: string): void;
+}
+
+(BaseAssert.prototype as Assert).isEven = function (value, message) {
+  this.pushResult({
+    result: value % 2 === 0,
+    actual: value,
+    expected: 'an even number',
+    message: message ?? `${value} is even`,
+  });
+};
+```
+
+> `qunitx/assert` default-exports the class, so `declare module 'qunitx/assert'` cannot
+> merge an interface into it — TypeScript can only augment *named* exports. Hence the
+> explicit `extends` above. Test callbacks still receive the base type, so annotate the
+> parameter (`(assert: Assert) => …`) where you call a custom assertion.
+
+`qunitx/assert` touches no runner API, so it resolves the same way in Node, Deno and the
+browser — a helper written against it is as portable as the tests that use it.
 
 ---
 
-## Skip and todo
+## Modules and hooks
 
-Mark individual tests or entire modules as skipped or pending:
+`module()` groups tests and can nest. Hooks are declared on the `hooks` argument:
 
 ```js
-import { module, test } from 'qunitx';
-
-module('Suite', () => {
-  // Skip a single test — body never runs
-  test.skip('not yet implemented', (assert) => {
-    assert.ok(false); // never executes
+module('Database', (hooks) => {
+  hooks.before(async function () { this.db = await connect(); });     // once, first
+  hooks.beforeEach(function () { this.tx = this.db.begin(); });       // before each test
+  hooks.afterEach(function () { this.tx.rollback(); });               // after each test
+  hooks.after(async function () { await this.db.close(); });          // once, last
+
+  test('insert', function (assert) {
+    assert.ok(this.tx.insert({ id: 1 }));
   });
 
-  // todo — body runs but failures do not fail the suite
-  test.todo('multiplication', (assert) => {
-    assert.equal(2 * 3, 6);
+  module('Nested', () => {
+    // parent hooks still apply, outermost first
+    test('inherits the transaction', function (assert) {
+      assert.ok(this.tx);
+    });
   });
+});
+```
 
-  // todo with no body — registers the test as pending
-  test.todo('division');
+`before` / `beforeEach` run FIFO (outermost first); `afterEach` / `after` run LIFO
+(innermost first) — exactly as in QUnit.
 
-  // Skip via runtime options (useful for conditional or cross-runtime skipping)
-  test('flaky on CI', { skip: true }, (assert) => { assert.ok(true); });
-  test('not ready', { todo: 'needs implementation' }, (assert) => { assert.ok(false); });
-});
+### `describe` / `it` — BDD aliases
 
-// Skip or todo an entire module
-module.skip('Legacy API', () => {
-  test('old behaviour', (assert) => { assert.ok(false); }); // never runs
-});
+If you prefer BDD naming, `describe` and `it` are exported as aliases of `module` and
+`test`. They are the *same function objects*, so everything that works on one works on
+the other — options, `.skip`, `.todo`, nesting, and mixing the two styles in one file:
+
+```js
+import { describe, it } from 'qunitx';
+
+describe('Math utilities', (hooks) => {
+  hooks.beforeEach(function () {
+    this.numbers = [1, 2, 3];
+  });
 
-module.todo('Future features', () => {
-  test('planned', (assert) => { assert.ok(false); }); // never runs
+  it('adds', (assert) => {
+    assert.equal(2 + 2, 4);
+  });
+
+  it.skip('not yet implemented', (assert) => { /* never runs */ });
+  it('flaky on CI', { skip: true }, (assert) => {});
+
+  describe('Nested', () => {
+    it('inherits parent hooks', function (assert) {
+      assert.deepEqual(this.numbers, [1, 2, 3]);
+    });
+  });
 });
 ```
 
-Top-level `skip` and `todo` aliases are also exported for QUnit-style usage:
+### `context` — for arrow functions
+
+QUnit exposes shared state as `this`, which arrow functions cannot see. QUnitX passes the
+same object as `context` in the second argument of every hook and test, so both styles
+work:
 
 ```js
-import { module, test, skip, todo } from 'qunitx';
+// QUnit style — regular functions, `this`
+module('Suite', function (hooks) {
+  hooks.before(function () { this.db = createDb(); });
+  test('query', function (assert) { assert.ok(this.db.query('SELECT 1')); });
+});
 
-module('Suite', () => {
-  skip('skipped test', (assert) => { assert.ok(false); });
-  todo('pending test', (assert) => { assert.ok(false); });
+// QUnitX style — arrow functions, `context`
+module('Suite', (hooks, { context }) => {
+  hooks.before((assert, { context }) => { context.db = createDb(); });
+  test('query', (assert, { context }) => { assert.ok(context.db.query('SELECT 1')); });
 });
 ```
 
-> **Node vs. Deno behaviour:** Node's `test.todo` runs the body but does not count failures
-> against the suite. Deno has no native todo concept and maps both `skip` and `todo` to
-> "ignored" — the body does not run.
+Either way the state follows QUnit's prototype-chain model: each test gets a fresh object
+inheriting from the module's, so `before()` writes are visible everywhere and a test's own
+writes never leak into its siblings.
 
 ---
 
-## Timeouts
+## Skip and todo
 
 ```js
-test('slow async operation', async (assert) => {
-  assert.timeout(500); // fail after 500 ms if not complete
+test.skip('not yet implemented', (assert) => { /* never runs */ });
+test.todo('known broken', (assert) => { /* runs; failures do not fail the suite */ });
+test.todo('not even started');                       // no body — registers as pending
 
-  const result = await fetchSomething();
-  assert.ok(result);
-});
+test('flaky on CI', { skip: true }, (assert) => {}); // conditional, via options
+test('waiting on API', { todo: 'needs endpoint' }, (assert) => {});
 
-test('adjustable deadline', async (assert) => {
-  assert.timeout(100);
-  assert.timeout(500); // calling again resets the deadline
-  await doWork();
-  assert.ok(true);
-});
+module.skip('Legacy API', () => { /* whole module skipped */ });
+module.todo('Future features', () => { /* whole module pending */ });
+```
+
+`skip` and `todo` are also exported top-level for QUnit-style usage:
+
+```js
+import { module, test, skip, todo } from 'qunitx';
 ```
 
-`assert.timeout(ms)` sets a hard deadline for the current test. If the test does not complete
-within `ms` milliseconds the runner aborts it with a descriptive error message.
+The BDD aliases carry the same helpers — `describe.skip`, `describe.todo`, `it.skip`,
+and `it.todo` are the exact same functions.
 
-`assert.timeout()` works across all three runtimes. In Node.js and Deno it is handled by
-qunitx's internal deadline mechanism; in the browser it delegates to QUnit's native
-`assert.timeout()` (available since QUnit 2.16).
+> **Runtime difference:** Node's `todo` runs the body and ignores its failures. Deno has
+> no todo concept and maps both `skip` and `todo` to "ignored" — the body does not run.
 
 ---
 
-## Concurrency
+## Runtime options
 
-Tests run **sequentially by default** — matching QUnit's browser behavior where tests run one at a time. You can enable concurrency by passing options to the underlying Node / Deno runner:
+The optional second argument to `module()` and `test()` is passed straight through to the
+underlying runner, so anything `node:test` or Deno BDD accepts works:
 
 ```js
-import { module, test } from 'qunitx';
-
-// Enable parallel execution for this module (Node/Deno only)
-module('Parallel suite', { concurrency: true }, (hooks) => {
-  test('first', (assert) => { assert.ok(true); });
-  test('second', (assert) => { assert.ok(true); });
-});
+// Tests run sequentially by default, matching QUnit's browser behaviour.
+module('Parallel suite', { concurrency: true }, () => { /* … */ });
 
-// Deno-specific: permissions, sanitizeExit, etc.
-module('Deno file access', { permissions: { read: true }, sanitizeExit: false }, (hooks) => {
+// Deno-specific options
+module('File access', { permissions: { read: true }, sanitizeExit: false }, () => {
   test('reads a file', async (assert) => {
-    const text = await Deno.readTextFile('./README.md');
-    assert.ok(text.length > 0);
+    assert.ok((await Deno.readTextFile('./README.md')).length > 0);
   });
 });
 ```
 
+Options a runtime does not recognise are ignored, which is what keeps one file portable
+across all three.
+
 ---
 
-## How it works
+## Migrating from QUnit
 
-| Runtime | Adapter |
-|---------|---------|
-| Node.js | Wraps `node:test` `describe` / `it` with QUnit lifecycle |
-| Deno | Wraps Deno BDD helpers with the same QUnit lifecycle |
-| Browser | Thin re-export of QUnit's native browser API |
+One line:
+
+```diff
+- import { module, test } from 'qunit';
++ import { module, test } from 'qunitx';
+```
 
-The browser path is literally QUnit itself, so you get full QUnit compatibility:
-plugins, custom reporters, the event API (`QUnit.on`, `QUnit.done`, etc.), and the
-familiar browser UI with zero extra layers.
+Coming from a BDD runner instead? Import `describe` / `it` — they are aliases of
+`module` / `test`, see [`describe` / `it`](#describe--it--bdd-aliases).
 
 ---
 
-## Code coverage
+## QUnit compatibility
 
-qunitx loads as a regular dependency rather than wrapping the runtime process, so
-Node.js and Deno's built-in v8 coverage instruments it naturally — no special configuration needed.
+qunitx follows the same test-environment model as QUnit:
 
-```sh
-# Node (any c8-compatible reporter)
-npx c8 node --test test/
+- **Fresh context per test** — each test gets its own `this` object. Writes in one test never bleed into a sibling.
+- **Prototype-chain inheritance** — a parent module's `before()` hook sets properties on the module context. Each test inherits those properties, so reads work naturally (`this.x`) while writes stay local to the test.
+- **`before()` assertions** — attributed to the first test in the module (matching QUnit's attribution model).
+- **`after()` assertions** — attributed to the last test in the module.
+- **Hook ordering** — `before`/`beforeEach` run FIFO; `afterEach`/`after` run LIFO, exactly as in QUnit.
+
+> **Known difference:** In QUnit's browser runner, `before()` hook assertions are attributed to the first test in the *entire subtree* (including nested modules). In the Node/Deno adapters, they are attributed to the first *direct* test of the module. In the common case where direct tests appear before nested modules, the behavior is identical.
 
-# View HTML report
+---
+
+## How it works
+
+| Runtime | Adapter |
+|---|---|
+| Node.js | wraps `node:test`'s `describe` / `it` with the QUnit lifecycle |
+| Deno | wraps Deno's BDD helpers with the same lifecycle |
+| Browser | a thin re-export of QUnit itself |
+
+Because the browser path *is* QUnit, you get the whole thing there: plugins, custom
+reporters, the event API (`QUnit.on`, `QUnit.done`, …) and the familiar UI, with no extra
+layer in between.
+
+QUnitX loads as an ordinary dependency instead of wrapping the runtime process, so v8
+coverage instruments it with no special configuration:
+
+```sh
+npx c8 node --test test/                                    # Node
 npx c8 --reporter=html node --test test/ && open coverage/index.html
+deno test --coverage=cov test/ && deno coverage cov         # Deno
 ```
 
-Browser-mode coverage is limited because qunitx-cli bundles test files with esbuild.
-Native ES import maps support in Puppeteer/Chrome would eliminate the bundling step
-and unlock v8 instrumentation for browser coverage.
+Browser coverage is the one gap — qunitx-cli bundles test files with esbuild, which
+loses the mapping. Native import-map support in headless Chrome would remove the bundling
+step and with it the limitation.
 
 ---
 
 ## Links
 
-- [QUnit API reference](https://api.qunitjs.com)
-- [qunitx-cli](https://github.com/izelnakri/qunitx-cli) — browser runner, CI reporter, and all HTML/runner configuration options
-- [Node.js test runner docs](https://nodejs.org/api/test.html)
-- [Deno testing docs](https://docs.deno.com/runtime/fundamentals/testing/)
+- [QUnit API reference](https://api.qunitjs.com) — every assertion, in depth
+- [qunitx-cli](https://github.com/izelnakri/qunitx-cli) — the browser runner and all of its options
+- [`@izelnakri/qunitx` on JSR](https://jsr.io/@izelnakri/qunitx) · [`qunitx` on npm](https://www.npmjs.com/package/qunitx)
+- [Node.js test runner](https://nodejs.org/api/test.html) · [Deno testing](https://docs.deno.com/runtime/fundamentals/testing/)