tape-six 1.7.2 → 1.7.3

package/README.md

@@ -4,7 +4,7 @@
 [npm-url]: https://npmjs.org/package/tape-six
 
 `tape-six` is a [TAP](https://en.wikipedia.org/wiki/Test_Anything_Protocol)-based library for unit tests.
-It is written in the modern JavaScript for the modern JavaScript and works in [Node](https://nodejs.org/), [Deno](https://deno.land/), [Bun](https://bun.sh/) and browsers.
+It is written in the modern JavaScript for the modern JavaScript and works in [Node](https://nodejs.org/), [Deno](https://deno.land/), [Bun](https://bun.sh/) and browsers. **Zero runtime dependencies.**
 
 It runs ES modules (`import`-based code) natively and supports CommonJS modules transparently using the built-in [ESM](https://nodejs.org/api/esm.html).
 
@@ -37,7 +37,7 @@ with existing unit test libraries:
 - The [DX](https://en.wikipedia.org/wiki/User_experience#Developer_experience) in browsers are usually abysmal.
   - Both console-based debugging and a UI to navigate results are properly supported.
   - Integration with browser automation tools is supported for automated testing.
-    - Examples for such tools are [Playwright](https://playwright.dev/) and [Puppeteer](https://pptr.dev/) are provided.
+    - Examples for [Playwright](https://playwright.dev/) and [Puppeteer](https://pptr.dev/) are provided.
 
 ## How it looks
 
@@ -137,6 +137,8 @@ import test from 'tape-six';
 // const {default: test} = require('tape-six');
 ```
 
+To help port tests from other frameworks, `test()` is aliased as `suite()`, `describe()` and `it()`. When called inside a test body, `test()` and its aliases automatically delegate to the current tester's `t.test()` method. The same applies to `test.skip()`, `test.todo()`, and `test.asPromise()`. Using `t.test()` directly is still preferred because it makes the delegation explicit.
+
 This function registers a test suite. Available options:
 
 - `async test(name, options, testFn)` — registers a test suite to be executed asynchronously.
@@ -162,11 +164,15 @@ The arguments mentioned above are:
   - `name` — the optional name of the test suite. If not provided, it will be set to the name of the test function or `'(anonymous)'`.
     - Can be overridden by the `name` argument.
   - `timeout` — the optional timeout in milliseconds. It is used for asynchronous tests.
-    - If the timeout is exceeded, the test suite will be marked as failed.
-    - **Important:** JavaScript does not provide a generic way to cancel asynchronous operations.
-      When the timeout is exceeded, `tape6` will stop waiting for the test to finish,
-      but it will continue running in the background.
+    - If the timeout is exceeded, `tape6` will use the tester's `signal` to indicate cancellation and stop waiting for the test to finish.
     - The default: no timeout.
+  - Hooks:
+    - `beforeAll` — a function to be executed before all tests in the suite.
+    - `afterAll` — a function to be executed after all tests in the suite.
+    - `beforeEach` — a function to be executed before each test in the suite.
+    - `afterEach` — a function to be executed after each test in the suite.
+    - `before` — an alias for `beforeAll`.
+    - `after` — an alias for `afterAll`.
   - `testFn` — the optional test function to be executed (see below).
     - Can be overridden by the `testFn` argument.
   - `testPromiseFn` — the optional callback-based test function to be executed.
@@ -307,8 +313,11 @@ The following methods are available (all `msg` arguments are optional):
   - `skip(name, options, testFn)` — skips a test suite asynchronously. See `test.skip()` above.
   - `todo(name, options, testFn)` — runs a provisional test suite asynchronously. See `test.todo()` above.
   - `asPromise(name, options, testPromiseFn)` — runs a test suite asynchronously. See `test.asPromise()` above.
+  - Note: top-level `test()` and its aliases auto-delegate to `t.test()` when called inside a test body. Using `t.test()` directly is preferred.
+- Properties:
+  - `signal` — an [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that fires when the test is aborted (e.g. on timeout or bail-out). Use it to cancel pending async operations.
 - Miscellaneous:
-  - `any` — returns the `any` object. It can be used in deep equivalency asserts to match any value.
+  - `any` — a symbol that can be used in deep equivalency asserts to match any value.
     See [deep6's any](https://github.com/uhop/deep6/wiki/any) for details.
     - `_` — an alias of `any`.
   - `plan(n)` — sets the number of tests in the test suite. Rarely used.
@@ -339,7 +348,7 @@ test('Sample test', async t => {
 
 ### Before/after hooks
 
-`tape-six` supports scope-based before/after hooks: `beforeAll`, `afterAll`, `beforeEach`, `afterEach`, which can be used to set-up and tear-down a proper environment for tests. Read all about it in [before and after hooks](https://github.com/uhop/tape-six/wiki/Before-and-after-hooks).
+`tape-six` supports scope-based before/after hooks: `beforeAll`, `afterAll`, `beforeEach`, `afterEach` (with `before`/`after` as aliases for `beforeAll`/`afterAll`), which can be used to set-up and tear-down a proper environment for tests. Like `test()` and its aliases, the top-level hook functions auto-delegate to the current tester when called inside a test body. Using `t.beforeAll()`, etc. is preferred. Read all about it in [before and after hooks](https://github.com/uhop/tape-six/wiki/Before-and-after-hooks).
 
 ### Running tests
 
@@ -411,6 +420,7 @@ Test output can be controlled by flags. See [Supported flags](https://github.com
 
 The most recent releases:
 
+- 1.7.3 _Bug fixes in reporters, runners, and assertions. Documentation corrections and improvements._
 - 1.7.2 _Minor internal refactoring and fixes._
 - 1.7.1 _Added AI support, added timeout to start test runners, fixed some bugs in the sequential test runner._
 - 1.7.0 _New features: after/before hooks for tests, aliases for `suite()`, `describe()`, `it()`, `tape6-seq` — an in-process sequential test runner. Improvements: stricter monochrome detection, refactoring, bugfixes, updated dev dependencies and the documentation._

package/TESTING.md

@@ -0,0 +1,756 @@
+# Testing with tape-six
+
+> This guide is for AI agents and developers working on projects that use `tape-six` for testing.
+> It covers how to write tests, run them, and configure test discovery.
+
+`tape-six` supports ES modules and CommonJS. TypeScript is supported natively — no transpilation needed (Node 22+, Deno, Bun all run `.ts` files directly).
+
+## Install
+
+```bash
+npm i -D tape-six
+```
+
+## Quick start
+
+Create a test file (e.g., `tests/test-example.js`):
+
+```js
+import test from 'tape-six';
+
+test('arithmetic', t => {
+  t.equal(2 + 2, 4, 'addition');
+  t.ok(10 > 5, 'comparison');
+  t.deepEqual({a: 1}, {a: 1}, 'deep equality');
+});
+```
+
+Run it directly:
+
+```bash
+node tests/test-example.js
+```
+
+Run all configured tests:
+
+```bash
+npx tape6 --flags FO
+```
+
+## Writing tests
+
+### Importing
+
+ES modules (`.js`, `.mjs`, `.ts`, `.mts`):
+
+```js
+import test from 'tape-six';
+// or named imports:
+import {test, describe, it, beforeAll, afterAll, beforeEach, afterEach} from 'tape-six';
+```
+
+CommonJS (`.cjs`, `.cts`):
+
+```js
+const {test} = require('tape-six');
+```
+
+### Registering tests
+
+`test(name, options, testFn)` — all arguments are optional, recognized by type.
+
+```js
+test('name', t => {
+  t.pass('unconditional pass');
+});
+
+test('async test', async t => {
+  const result = await fetchData();
+  t.equal(result.status, 200, 'status OK');
+});
+```
+
+Aliases: `suite()`, `describe()`, `it()` — all identical to `test()`.
+
+When called inside a test body, top-level functions (`test`, `it`, `describe`, and all hooks) automatically delegate to the current tester. Using `t.test()`, `t.before()`, etc. is still preferred because it makes the delegation explicit. The top-level form is convenient when porting tests from frameworks like Mocha or Jest:
+
+```js
+import {describe, it, before, beforeEach} from 'tape-six';
+
+describe('module', () => {
+  before(() => {
+    /* setup — same as t.before() */
+  });
+  beforeEach(() => {
+    /* per-test setup */
+  });
+
+  it('works', t => {
+    t.ok(true);
+  });
+
+  it('also works', t => {
+    t.equal(1 + 1, 2);
+  });
+});
+```
+
+### Skip and TODO
+
+```js
+test.skip('not ready', t => {
+  t.fail();
+}); // skipped entirely
+test.todo('in progress', t => {
+  t.equal(1, 2);
+}); // runs, failures not counted
+```
+
+### Assertions
+
+All `msg` arguments are optional. If omitted, a generic message is used.
+
+| Method                               | Checks                          | Common aliases                   |
+| ------------------------------------ | ------------------------------- | -------------------------------- |
+| `t.pass(msg)`                        | Unconditional pass              |                                  |
+| `t.fail(msg)`                        | Unconditional fail              |                                  |
+| `t.ok(val, msg)`                     | `val` is truthy                 | `true`, `assert`                 |
+| `t.notOk(val, msg)`                  | `val` is falsy                  | `false`, `notok`                 |
+| `t.error(err, msg)`                  | `err` is falsy                  | `ifError`, `ifErr`               |
+| `t.equal(a, b, msg)`                 | `a === b`                       | `is`, `strictEqual`, `isEqual`   |
+| `t.notEqual(a, b, msg)`              | `a !== b`                       | `not`, `notStrictEqual`, `isNot` |
+| `t.deepEqual(a, b, msg)`             | Deep strict equality            | `same`, `isEquivalent`           |
+| `t.notDeepEqual(a, b, msg)`          | Not deeply equal                | `notSame`, `notEquivalent`       |
+| `t.looseEqual(a, b, msg)`            | `a == b`                        |                                  |
+| `t.notLooseEqual(a, b, msg)`         | `a != b`                        |                                  |
+| `t.deepLooseEqual(a, b, msg)`        | Deep loose equality             |                                  |
+| `t.notDeepLooseEqual(a, b, msg)`     | Not deeply loosely equal        |                                  |
+| `t.throws(fn, msg)`                  | `fn()` throws                   |                                  |
+| `t.doesNotThrow(fn, msg)`            | `fn()` does not throw           |                                  |
+| `t.matchString(str, re, msg)`        | `str` matches `re`              |                                  |
+| `t.doesNotMatchString(str, re, msg)` | `str` doesn't match `re`        |                                  |
+| `t.match(a, b, msg)`                 | Structural pattern match        |                                  |
+| `t.doesNotMatch(a, b, msg)`          | No structural match             |                                  |
+| `t.rejects(promise, msg)`            | Promise rejects (**await it**)  | `doesNotResolve`                 |
+| `t.resolves(promise, msg)`           | Promise resolves (**await it**) | `doesNotReject`                  |
+
+### Async assertions
+
+`rejects` and `resolves` are async — always `await` them:
+
+```js
+test('async asserts', async t => {
+  await t.rejects(Promise.reject(new Error('fail')), 'should reject');
+  await t.resolves(Promise.resolve(42), 'should resolve');
+});
+```
+
+### Nested (embedded) tests
+
+Tests can be nested. The preferred way is `t.test()` because it makes the delegation explicit. Top-level `test()`/`it()` are equivalent inside a test body — they auto-delegate to the current tester:
+
+```js
+import {test, it} from 'tape-six';
+
+test('suite', async t => {
+  // these two forms are equivalent:
+  await t.test('using t.test', t => {
+    t.pass();
+  });
+
+  await it('using top-level it()', t => {
+    t.ok(true);
+  });
+});
+```
+
+Embedded tests must be `await`ed to preserve execution order.
+
+### Hooks (setup/teardown)
+
+Hooks are scoped — they only affect tests at their registration level.
+
+`before` is an alias for `beforeAll`, `after` is an alias for `afterAll`. These aliases work everywhere: as named exports, on `test.before`/`test.after`, on `t.before`/`t.after`, and in options objects.
+
+**Top-level hooks** (affect all top-level tests in the file):
+
+```js
+import {test, beforeAll, afterAll, beforeEach, afterEach} from 'tape-six';
+// or with aliases:
+import {test, before, after, beforeEach, afterEach} from 'tape-six';
+
+beforeAll(() => {
+  /* once before first test */
+});
+afterAll(() => {
+  /* once after last test */
+});
+beforeEach(() => {
+  /* before each test */
+});
+afterEach(() => {
+  /* after each test */
+});
+```
+
+**Nested hooks** (affect embedded tests within a suite):
+
+The preferred way is `t.before()`/`t.after()` because it makes the scope explicit. Top-level `before()`/`after()` are equivalent inside a test body — they auto-delegate to the current tester:
+
+```js
+import {test, before, after, beforeEach} from 'tape-six';
+
+test('database tests', async t => {
+  let db;
+  // these use top-level functions — they auto-delegate to t:
+  before(async () => {
+    db = await connect();
+  });
+  after(async () => {
+    await db.close();
+  });
+  beforeEach(() => {
+    /* reset state */
+  });
+
+  // equivalent using t. methods:
+  // t.before(async () => { db = await connect(); });
+  // t.after(async () => { await db.close(); });
+  // t.beforeEach(() => { /* reset state */ });
+
+  await t.test('insert', async t => {
+    const result = await db.insert({name: 'Alice'});
+    t.ok(result.id, 'got an id');
+  });
+
+  await t.test('query', async t => {
+    const rows = await db.query('SELECT * FROM users');
+    t.ok(rows.length > 0, 'has rows');
+  });
+});
+```
+
+**Hooks via options** (reusable across tests):
+
+```js
+const dbOpts = {
+  beforeEach: () => resetFixtures(),
+  afterEach: () => cleanupDb()
+};
+
+test('suite A', dbOpts, async t => {
+  /* ... */
+});
+test('suite B', dbOpts, async t => {
+  /* ... */
+});
+```
+
+## Migrating from other test frameworks
+
+`tape-six` supports `describe`/`it` and `before`/`after` aliases. When called inside a test body, all top-level functions automatically delegate to the current tester. This means migration from Mocha, Jest, or `node:test` is nearly mechanical — change the import and swap assertions.
+
+### Mocha / Jest → tape-six
+
+```js
+// Mocha / Jest
+describe('module', () => {
+  before(() => {
+    /* setup */
+  });
+  after(() => {
+    /* teardown */
+  });
+  beforeEach(() => {
+    /* per-test setup */
+  });
+
+  it('works', () => {
+    expect(1).toBe(1);
+  });
+});
+```
+
+```js
+// tape-six — just change the import and swap assertions
+import {describe, it, before, after, beforeEach} from 'tape-six';
+
+describe('module', () => {
+  before(() => {
+    /* setup */
+  });
+  after(() => {
+    /* teardown */
+  });
+  beforeEach(() => {
+    /* per-test setup */
+  });
+
+  it('works', t => {
+    t.equal(1, 1);
+  });
+});
+```
+
+Key differences from Mocha/Jest:
+
+- **Assertions** use `t.equal`, `t.deepEqual`, etc. instead of `expect`.
+- The test function receives a `t` argument for assertions.
+- No magic globals — everything is imported explicitly.
+- `it()` inside `describe()` is auto-delegated, no need to use `t.test()`.
+- `before()`/`after()` inside `describe()` are auto-delegated, no need to use `t.before()`/`t.after()`.
+
+### Chai → tape-six
+
+Chai is commonly used with Mocha and other test frameworks. Its `expect`/`should`/`assert` styles all throw `AssertionError`, which `tape-six` catches automatically. You can use Chai assertions directly inside `tape-six` tests, or replace them with `t.*` equivalents:
+
+```js
+// Chai expect style
+import {expect} from 'chai';
+
+describe('module', () => {
+  it('works', () => {
+    expect(1 + 1).to.equal(2);
+    expect([1, 2]).to.deep.equal([1, 2]);
+    expect(true).to.be.ok;
+    expect(() => badFn()).to.throw();
+  });
+});
+```
+
+```js
+// tape-six — Chai assertions work as-is, or replace with t.*
+import {describe, it} from 'tape-six';
+
+describe('module', () => {
+  it('works', t => {
+    t.equal(1 + 1, 2);
+    t.deepEqual([1, 2], [1, 2]);
+    t.ok(true);
+    t.throws(() => badFn());
+  });
+});
+```
+
+You can also keep Chai alongside `tape-six` — failures are reported correctly either way:
+
+```js
+import {describe, it} from 'tape-six';
+import {expect} from 'chai';
+
+describe('mixed assertions', () => {
+  it('uses both', t => {
+    expect(1).to.be.lessThan(2); // Chai — caught automatically
+    t.equal(1 + 1, 2); // tape-six native
+  });
+});
+```
+
+### node:test → tape-six
+
+```js
+// node:test
+import {describe, it, before, after} from 'node:test';
+import assert from 'node:assert/strict';
+
+describe('module', () => {
+  before(() => {
+    /* setup */
+  });
+  it('works', () => {
+    assert.equal(1, 1);
+  });
+});
+```
+
+```js
+// tape-six — change import, optionally swap assert for t.*
+import {describe, it, before} from 'tape-six';
+
+describe('module', () => {
+  before(() => {
+    /* setup */
+  });
+  it('works', t => {
+    t.equal(1, 1);
+  });
+});
+```
+
+Note: you can also keep using `node:assert` inside tape-six tests — `AssertionError` is caught automatically (see [3rd-party assertion libraries](#3rd-party-assertion-libraries)).
+
+### Quick reference
+
+| Mocha / Jest / node:test            | tape-six equivalent                               |
+| ----------------------------------- | ------------------------------------------------- |
+| `describe(name, fn)`                | `describe(name, fn)` — same                       |
+| `it(name, fn)`                      | `it(name, t => { ... })` — same, but receives `t` |
+| `before(fn)`                        | `before(fn)` — same (alias for `beforeAll`)       |
+| `after(fn)`                         | `after(fn)` — same (alias for `afterAll`)         |
+| `beforeEach(fn)`                    | `beforeEach(fn)` — same                           |
+| `afterEach(fn)`                     | `afterEach(fn)` — same                            |
+| `expect(a).toBe(b)`                 | `t.equal(a, b)`                                   |
+| `expect(a).toEqual(b)`              | `t.deepEqual(a, b)`                               |
+| `expect(a).toBeTruthy()`            | `t.ok(a)`                                         |
+| `expect(fn).toThrow()`              | `t.throws(fn)`                                    |
+| `assert.equal(a, b)`                | `t.equal(a, b)` or keep `assert.equal`            |
+| `assert.deepEqual(a, b)`            | `t.deepEqual(a, b)` or keep `assert.deepEqual`    |
+| `expect(a).to.equal(b)` (Chai)      | `t.equal(a, b)` or keep `expect`                  |
+| `expect(a).to.deep.equal(b)` (Chai) | `t.deepEqual(a, b)` or keep `expect`              |
+| `expect(a).to.be.ok` (Chai)         | `t.ok(a)` or keep `expect`                        |
+| `expect(fn).to.throw()` (Chai)      | `t.throws(fn)` or keep `expect`                   |
+
+### Wildcard matching with `t.any`
+
+Use `t.any` (or `t._`) in deep equality checks to match any value:
+
+```js
+test('partial match', t => {
+  const result = {id: 123, name: 'Alice', createdAt: new Date()};
+  t.deepEqual(result, {id: 123, name: 'Alice', createdAt: t.any});
+});
+```
+
+### Testing exceptions
+
+```js
+test('errors', async t => {
+  t.throws(() => {
+    throw new Error('boom');
+  }, 'should throw');
+  t.doesNotThrow(() => 42, 'should not throw');
+  await t.rejects(Promise.reject(new Error('fail')), 'should reject');
+  await t.resolves(Promise.resolve(42), 'should resolve');
+});
+```
+
+### 3rd-party assertion libraries
+
+`tape-six` catches `AssertionError` automatically. You can use `chai` or `node:assert`:
+
+```js
+import test from 'tape-six';
+import {expect} from 'chai';
+
+test('with chai', t => {
+  expect(1).to.be.lessThan(2);
+  expect([1, 2]).to.deep.equal([1, 2]);
+});
+```
+
+```js
+import test from 'tape-six';
+import assert from 'node:assert/strict';
+
+test('with node:assert', t => {
+  assert.equal(1 + 1, 2);
+  assert.deepEqual({a: 1}, {a: 1});
+});
+```
+
+## Running tests
+
+### Single file
+
+```bash
+node tests/test-example.js            # Node.js
+bun run tests/test-example.js         # Bun
+deno run -A tests/test-example.js     # Deno
+```
+
+### All configured tests
+
+```bash
+npx tape6 --flags FO                  # parallel (worker threads)
+npx tape6-seq --flags FO              # sequential (in-process, no workers)
+npx tape6 --par 4 --flags FO          # limit to 4 workers
+```
+
+**`tape6` vs `tape6-seq`**: The default `tape6` runner spawns worker threads to run test files in parallel — faster, but each file runs in its own isolated context. `tape6-seq` runs all test files sequentially in a single process — slower, but useful for debugging, for tests that share state, or when worker threads are unavailable.
+
+### Selected test files
+
+```bash
+npx tape6 --flags FO tests/test-foo.js tests/test-bar.js
+npx tape6-seq --flags FO tests/test-foo.js tests/test-bar.js
+```
+
+### Typical package.json scripts
+
+```json
+{
+  "scripts": {
+    "test": "tape6 --flags FO",
+    "test:bun": "tape6-bun --flags FO",
+    "test:deno": "tape6-deno --flags FO",
+    "test:seq": "tape6-seq --flags FO",
+    "test:seq:bun": "bun run `tape6-seq --self` --flags FO",
+    "test:seq:deno": "deno run -A `tape6-seq --self` --flags FO"
+  }
+}
+```
+
+### Flags
+
+Flags control test output. Uppercase = enabled, lowercase = disabled.
+
+| Flag | Meaning                                |
+| ---- | -------------------------------------- |
+| `F`  | **F**ailures only — hide passing tests |
+| `O`  | Fail **o**nce — stop at first failure  |
+| `T`  | Show **t**ime for each test            |
+| `D`  | Show **d**ata of failed tests          |
+| `B`  | Show **b**anner with summary           |
+| `N`  | Show assert **n**umber                 |
+| `M`  | **M**onochrome — no colors             |
+| `C`  | Don't **c**apture console output       |
+| `H`  | **H**ide streams and console output    |
+
+Common combinations: `FO` (failures only + stop at first), `FOT` (+ show time).
+
+### Environment variables
+
+- `TAPE6_FLAGS` — flags string (alternative to `--flags`).
+- `TAPE6_PAR` — number of parallel workers.
+- `TAPE6_TAP` — force TAP output format.
+- `TAPE6_JSONL` — force JSONL output format.
+
+## Configuring test discovery
+
+Add to `package.json`:
+
+```json
+{
+  "tape6": {
+    "tests": ["/tests/test-*.*js"],
+    "importmap": {
+      "imports": {
+        "tape-six": "/node_modules/tape-six/index.js",
+        "tape-six/": "/node_modules/tape-six/src/",
+        "my-package": "/src/index.js",
+        "my-package/": "/src/"
+      }
+    }
+  }
+}
+```
+
+- `tests` — glob patterns for test files (relative to project root with leading `/`). Common for all environments.
+- `cli` — additional patterns for CLI-only environments (Node, Bun, Deno). Typically used for `.cjs` files.
+- `node`, `deno`, `bun`, `browser` — additional patterns specific to a given environment. These are **not overrides** — they are added to `tests` (and `cli` for non-browser).
+- `importmap` — import map for browser testing (standard [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) format).
+
+Example with environment-specific tests:
+
+```json
+{
+  "tape6": {
+    "node": ["/tests/node/test-*.js"],
+    "deno": ["/tests/deno/test-*.js"],
+    "browser": ["/tests/web/test-*.html"],
+    "tests": ["/tests/test-*.*js"],
+    "importmap": {
+      "imports": {
+        "tape-six": "/node_modules/tape-six/index.js",
+        "tape-six/": "/node_modules/tape-six/src/"
+      }
+    }
+  }
+}
+```
+
+In this example, running `tape6` on Node will execute tests matching `/tests/node/test-*.js` + `/tests/test-*.*js`. Running in a browser will execute `/tests/web/test-*.html` + `/tests/test-*.*js`.
+
+## Browser testing
+
+Browser tests use `tape6-server`, a static file server bundled with `tape-six` that provides a web UI for running tests.
+
+### Setup
+
+1. Configure `importmap` in `package.json` so the browser can resolve bare imports:
+
+```json
+{
+  "tape6": {
+    "tests": ["/tests/test-*.*js"],
+    "browser": ["/tests/web/test-*.html"],
+    "importmap": {
+      "imports": {
+        "tape-six": "/node_modules/tape-six/index.js",
+        "tape-six/": "/node_modules/tape-six/src/",
+        "my-package": "/src/index.js",
+        "my-package/": "/src/"
+      }
+    }
+  }
+}
+```
+
+2. Start the server:
+
+```bash
+npx tape6-server --trace
+```
+
+3. Open `http://localhost:3000` in a browser to see the web UI and run all configured tests.
+
+### Running all configured browser tests
+
+Navigate to:
+
+```
+http://localhost:3000/
+```
+
+The web app fetches the configured test list from the server and runs them.
+
+### Running specific test files by name
+
+Use the `?q=` query parameter (supports multiple values):
+
+```
+http://localhost:3000/?q=/tests/test-foo.js&q=/tests/test-bar.js
+```
+
+These are glob patterns resolved by the server, so wildcards work:
+
+```
+http://localhost:3000/?q=/tests/test-sample.*js
+```
+
+### Running a single test file (HTML shim)
+
+Create an HTML file that loads test scripts directly with an inline import map:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>My tests</title>
+    <script type="importmap">
+      {
+        "imports": {
+          "tape-six": "/node_modules/tape-six/index.js",
+          "tape-six/": "/node_modules/tape-six/src/"
+        }
+      }
+    </script>
+    <script type="module" src="../test-sample.js"></script>
+  </head>
+  <body>
+    <h1>My tests</h1>
+    <p>See the console.</p>
+  </body>
+</html>
+```
+
+Navigate to the HTML file directly (e.g., `http://localhost:3000/tests/web/test-simple.html`). Results appear in the browser console. This approach does not use the web UI.
+
+### Flags and parallel execution in the browser
+
+Append query parameters:
+
+```
+http://localhost:3000/?flags=FO&par=3
+```
+
+### Browser automation
+
+Use Puppeteer or Playwright to run browser tests from the command line:
+
+```js
+import puppeteer from 'puppeteer';
+const browser = await puppeteer.launch({headless: true});
+const page = await browser.newPage();
+page.on('console', msg => console.log(msg.text()));
+await page.exposeFunction('__tape6_reportResults', async text => {
+  await browser.close();
+  process.exit(text === 'success' ? 0 : 1);
+});
+await page.goto('http://localhost:3000/?flags=M');
+```
+
+### Browser limitations
+
+- Browsers cannot run TypeScript files directly — only `.js` and `.mjs`.
+- Browsers cannot run CommonJS (`.cjs`) files.
+- Browsers can run HTML shim files in addition to JS files.
+
+## Test file conventions
+
+- **Naming**: `test-*.js`, `test-*.mjs`, `test-*.cjs`, `test-*.ts`, `test-*.mts`, `test-*.cts`.
+- **Location**: typically `tests/` directory.
+- **Self-contained**: each test file should be directly executable with `node`.
+- **One concern per file**: group related tests in a single file, use embedded tests for sub-grouping.
+
+## Patterns for AI agents writing tests
+
+### Testing a new function
+
+```js
+import test from 'tape-six';
+import {myFunction} from 'my-package/my-module.js';
+
+test('myFunction', async t => {
+  await t.test('returns correct result for basic input', t => {
+    t.deepEqual(myFunction(1, 2), {sum: 3, product: 2});
+  });
+
+  await t.test('handles edge cases', t => {
+    t.deepEqual(myFunction(0, 0), {sum: 0, product: 0});
+    t.throws(() => myFunction(null), 'throws on null input');
+  });
+
+  await t.test('async variant', async t => {
+    const result = await myFunction.async(1, 2);
+    t.equal(result.sum, 3);
+  });
+});
+```
+
+### Testing a class
+
+```js
+import test from 'tape-six';
+import {MyClass} from 'my-package/my-class.js';
+
+test('MyClass', async t => {
+  let instance;
+  t.beforeEach(() => {
+    instance = new MyClass();
+  });
+
+  await t.test('constructor', t => {
+    t.ok(instance, 'creates instance');
+    t.equal(instance.size, 0, 'starts empty');
+  });
+
+  await t.test('add', t => {
+    instance.add('item');
+    t.equal(instance.size, 1, 'size increases');
+  });
+
+  await t.test('remove', t => {
+    instance.add('item');
+    instance.remove('item');
+    t.equal(instance.size, 0, 'size decreases');
+  });
+});
+```
+
+### Verifying after writing tests
+
+```bash
+node tests/test-<name>.js    # run your new test file directly
+npm test                      # run full suite to check for regressions
+```
+
+## Links
+
+- Full API reference: https://github.com/uhop/tape-six/wiki/Tester
+- Hooks documentation: https://github.com/uhop/tape-six/wiki/Before-and-after-hooks
+- Configuration: https://github.com/uhop/tape-six/wiki/Set-up-tests
+- Supported flags: https://github.com/uhop/tape-six/wiki/Supported-flags
+- npm: https://www.npmjs.com/package/tape-six

package/index.d.ts

@@ -66,15 +66,15 @@ export declare interface Tester {
   /**
    * A symbol that can be used to match any value.
    */
-  any: Symbol;
+  any: symbol;
 
   /**
    * A symbol that can be used to match any value. An alias of `any`.
    */
-  _: Symbol;
+  _: symbol;
 
   /**
-   * A signal that can be used to abort asynchronous operations. It is triggered when the test is ended.
+   * A signal that can be used to abort asynchronous operations. It is triggered when the test ends.
    */
   signal: AbortSignal;
 
@@ -287,7 +287,7 @@ export declare interface Tester {
   ): Promise<void>;
 
   /**
-   * Runs non-asynchronous callback-based test.
+   * Runs a callback-based test wrapped in a promise.
    * @param name - The name of the test
    * @param fn - The test function
    * @param options - The test options
@@ -299,7 +299,7 @@ export declare interface Tester {
   ): Promise<void>;
 
   /**
-   * Runs non-asynchronous callback-based test.
+   * Runs a callback-based test wrapped in a promise.
    * @param name - The name of the test
    * @param options - The test options
    * @param fn - The test function
@@ -311,7 +311,7 @@ export declare interface Tester {
   ): Promise<void>;
 
   /**
-   * Runs non-asynchronous callback-based test.
+   * Runs a callback-based test wrapped in a promise.
    * @param fn - The test function
    * @param options - The test options
    * @param name - The name of the test
@@ -323,7 +323,7 @@ export declare interface Tester {
   ): Promise<void>;
 
   /**
-   * Runs non-asynchronous callback-based test.
+   * Runs a callback-based test wrapped in a promise.
    * @param fn - The test function
    * @param name - The name of the test
    * @param options - The test options
@@ -335,7 +335,7 @@ export declare interface Tester {
   ): Promise<void>;
 
   /**
-   * Runs non-asynchronous callback-based test.
+   * Runs a callback-based test wrapped in a promise.
    * @param options - The test options
    * @param fn - The test function
    * @param name - The name of the test
@@ -347,7 +347,7 @@ export declare interface Tester {
   ): Promise<void>;
 
   /**
-   * Runs non-asynchronous callback-based test.
+   * Runs a callback-based test wrapped in a promise.
    * @param options - The test options
    * @param name - The name of the test
    * @param fn - The test function
@@ -425,8 +425,8 @@ export declare interface Tester {
   notOk(value: unknown, message?: string): void;
 
   /**
-   * Asserts that `error` is an error and fails the test.
-   * @param error - The error to test
+   * Asserts that `error` is falsy. If the value is truthy (e.g. an Error object), the assertion fails.
+   * @param error - The value to test
    * @param message - Optional message to display if the assertion fails
    */
   error(error: Error | null | unknown, message?: string): void;
@@ -600,22 +600,22 @@ export declare interface Tester {
   notok(value: unknown, message?: string): void;
 
   /**
-   * Asserts that `error` is an error and fails the test. Alias of `error`.
-   * @param error - The error to test
+   * Asserts that `error` is falsy. If the value is truthy (e.g. an Error object), the assertion fails. Alias of `error`.
+   * @param error - The value to test
    * @param message - Optional message to display if the assertion fails
    */
   ifError(error: Error | null | unknown, message?: string): void;
 
   /**
-   * Asserts that `error` is an error and fails the test. Alias of `error`.
-   * @param error - The error to test
+   * Asserts that `error` is falsy. If the value is truthy (e.g. an Error object), the assertion fails. Alias of `error`.
+   * @param error - The value to test
    * @param message - Optional message to display if the assertion fails
    */
   ifErr(error: Error | null | unknown, message?: string): void;
 
   /**
-   * Asserts that `error` is an error and fails the test. Alias of `error`.
-   * @param error - The error to test
+   * Asserts that `error` is falsy. If the value is truthy (e.g. an Error object), the assertion fails. Alias of `error`.
+   * @param error - The value to test
    * @param message - Optional message to display if the assertion fails
    */
   iferror(error: Error | null | unknown, message?: string): void;
@@ -1122,57 +1122,64 @@ export declare interface Test {
 }
 
 /**
- * The main function, which is used to define tests. Many other functions are defined as properties of this function.
+ * The main function used to define tests. When called inside a test body, it delegates to the current tester.
+ * Many other functions are defined as properties of this function.
  */
 export declare const test: Test;
 
 /**
- * An alias for `test`. Used for compatibility with other testing frameworks to define test suites.
+ * An alias for `test`. When called inside a test body, it delegates to the current tester.
  */
 export declare const suite = test;
 
 /**
- * An alias for `test`. Used for compatibility with other testing frameworks to define test suites.
+ * An alias for `test`. When called inside a test body, it delegates to the current tester.
  */
 export declare const describe = test;
 
 /**
- * An alias for `test`. Used for compatibility with other testing frameworks to define tests.
+ * An alias for `test`. When called inside a test body, it delegates to the current tester.
  */
 export declare const it = test;
 
 /**
  * Registers a function that will be called before all 1st-level embedded tests in the current scope.
+ * When called inside a test body, delegates to the current tester.
  * @param fn a hook function
  */
 export declare const beforeAll: typeof test.beforeAll;
 
 /**
  * Registers a function that will be called after all 1st-level embedded tests in the current scope.
+ * When called inside a test body, delegates to the current tester.
  * @param fn a hook function
  */
 export declare const afterAll: typeof test.afterAll;
 
 /**
  * Registers a function that will be called before each 1st-level embedded test in the current scope.
+ * When called inside a test body, delegates to the current tester.
  * @param fn a hook function
  */
 export declare const beforeEach: typeof test.beforeEach;
 
 /**
  * Registers a function that will be called after each 1st-level embedded test in the current scope.
+ * When called inside a test body, delegates to the current tester.
  * @param fn a hook function
  */
 export declare const afterEach: typeof test.afterEach;
 
 /**
  * Registers a function that will be called before all 1st-level embedded tests in the current scope. An alias for `beforeAll()`.
+ * When called inside a test body, delegates to the current tester.
  * @param fn a hook function
  */
 export declare const before: typeof test.before;
 
 /**
  * Registers a function that will be called after all 1st-level embedded tests in the current scope. An alias for `afterAll()`.
+ * When called inside a test body, delegates to the current tester.
  * @param fn a hook function
  */
 export declare const after: typeof test.after;

package/llms-full.txt

@@ -9,6 +9,7 @@
 - Browser testing with built-in web UI and automation support (Puppeteer, Playwright)
 - Before/after hooks: `beforeAll`, `afterAll`, `beforeEach`, `afterEach`
 - `test()` is aliased as `suite()`, `describe()`, and `it()` for easy migration
+- When called inside a test body, top-level functions auto-delegate to the current tester
 - Compatible with `AssertionError`-based libraries like `node:assert` and `chai`
 
 ## Quick start
@@ -128,6 +129,20 @@ test('top', async t => {
 
 Always `await` embedded tests to preserve execution order.
 
+Top-level `test()`/`it()`/`describe()` auto-delegate when called inside a test body, so these are equivalent:
+
+```js
+import {describe, it, before, beforeEach} from 'tape-six';
+
+describe('module', () => {
+  before(() => { /* setup */ });
+  beforeEach(() => { /* per-test setup */ });
+
+  it('works', t => { t.ok(true); });
+  it('also works', t => { t.equal(1, 1); });
+});
+```
+
 ## Tester API
 
 The `Tester` object is passed to test functions. All `msg` arguments are optional.
@@ -163,17 +178,17 @@ The `Tester` object is passed to test functions. All `msg` arguments are optiona
 
 ### Embedded test methods
 
-- `test(name, options, testFn)` — nested test suite (async, await it).
+- `test(name, options, testFn)` — nested test suite (async, await it). Top-level `test()`/`it()` also works.
 - `skip(name, options, testFn)` — skip nested suite.
 - `todo(name, options, testFn)` — TODO nested suite.
 - `asPromise(name, options, testPromiseFn)` — callback-style nested suite.
 
 ### Hooks
 
-- `beforeAll(fn)` / `before(fn)` — run before first nested test.
-- `afterAll(fn)` / `after(fn)` — run after last nested test.
-- `beforeEach(fn)` — run before each nested test.
-- `afterEach(fn)` — run after each nested test.
+- `beforeAll(fn)` / `before(fn)` — run before first nested test. Top-level `beforeAll()`/`before()` also works.
+- `afterAll(fn)` / `after(fn)` — run after last nested test. Top-level `afterAll()`/`after()` also works.
+- `beforeEach(fn)` — run before each nested test. Top-level `beforeEach()` also works.
+- `afterEach(fn)` — run after each nested test. Top-level `afterEach()` also works.
 
 ### Miscellaneous
 
@@ -211,12 +226,16 @@ beforeEach(() => { /* runs before each top-level test */ });
 afterEach(() => { /* runs after each top-level test */ });
 ```
 
-Nested hooks (via tester object):
+Nested hooks (top-level functions auto-delegate to current tester):
 
 ```js
+import {test, beforeEach, afterEach} from 'tape-six';
+
 test('suite', async t => {
-  t.beforeEach(() => { /* before each nested test */ });
-  t.afterEach(() => { /* after each nested test */ });
+  beforeEach(() => { /* before each nested test */ });
+  afterEach(() => { /* after each nested test */ });
+
+  // equivalent: t.beforeEach(), t.afterEach()
 
   await t.test('test 1', t => t.pass());
   await t.test('test 2', t => t.pass());
@@ -323,6 +342,7 @@ Browser: `http://localhost:3000/?flags=FO`
 - `TAPE6_PAR` — number of parallel workers.
 - `TAPE6_TAP` — force TAP reporter (any non-empty value).
 - `TAPE6_JSONL` — force JSONL reporter (any non-empty value).
+- `TAPE6_MIN` — force minimal reporter (any non-empty value).
 - `TAPE6_TEST_FILE_NAME` — set by runners to identify the current test file.
 
 ## Browser testing

package/llms.txt

@@ -33,6 +33,7 @@ Registers a test. All three arguments are optional and can be in any order (reco
 Returns a promise that resolves when the test finishes. Usually no need to await.
 
 Aliases: `suite`, `describe`, `it` — all are the same function.
+When called inside a test body, these (and all hook functions) automatically delegate to the current tester — no need to use `t.test()` or `t.before()` explicitly.
 
 ```js
 import {test, describe, it, suite} from 'tape-six';
@@ -97,7 +98,7 @@ The object passed to test functions. Provides assertions and test control.
 
 #### Embedded tests (all async, should be awaited)
 
-- `await t.test(name, options, testFn)` — nested test.
+- `await t.test(name, options, testFn)` — nested test. Top-level `test()`/`it()` also works (auto-delegates).
 - `await t.skip(name, options, testFn)` — nested skipped test.
 - `await t.todo(name, options, testFn)` — nested TODO test.
 - `await t.asPromise(name, options, testPromiseFn)` — nested callback-style test.
@@ -122,12 +123,14 @@ afterAll(() => { /* runs once after all tests */ });
 beforeEach(() => { /* runs before each test */ });
 afterEach(() => { /* runs after each test */ });
 
-// Or inside a test:
+// Inside a test — top-level functions auto-delegate to current tester:
 test('suite', async t => {
-  t.beforeAll(() => { /* before embedded tests */ });
-  t.afterAll(() => { /* after embedded tests */ });
-  t.beforeEach(() => { /* before each embedded test */ });
-  t.afterEach(() => { /* after each embedded test */ });
+  beforeAll(() => { /* before embedded tests */ });
+  afterAll(() => { /* after embedded tests */ });
+  beforeEach(() => { /* before each embedded test */ });
+  afterEach(() => { /* after each embedded test */ });
+
+  // equivalent: t.beforeAll(), t.afterAll(), t.beforeEach(), t.afterEach()
 
   await t.test('inner', t => { t.pass(); });
 });
@@ -198,9 +201,12 @@ test('partial match', t => {
 ### Using describe/it style
 
 ```js
-import {describe, it} from 'tape-six';
+import {describe, it, before, beforeEach} from 'tape-six';
 
 describe('my module', () => {
+  before(() => { /* setup — auto-delegates to current tester */ });
+  beforeEach(() => { /* per-test setup */ });
+
   it('should work', t => {
     t.ok(true);
   });
@@ -223,6 +229,15 @@ npx tape6-seq              # run sequentially (no worker threads)
 npx tape6-server --trace   # start browser test server
 ```
 
+## Environment variables
+
+- `TAPE6_FLAGS` — flags string.
+- `TAPE6_PAR` — number of parallel workers.
+- `TAPE6_TAP` — force TAP reporter (any non-empty value).
+- `TAPE6_JSONL` — force JSONL reporter (any non-empty value).
+- `TAPE6_MIN` — force minimal reporter (any non-empty value).
+- `TAPE6_TEST_FILE_NAME` — set by runners to identify the current test file.
+
 ## Configuration (package.json)
 
 ```json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tape-six",
-  "version": "1.7.2",
+  "version": "1.7.3",
   "description": "TAP-based unit test library for Node, Deno, Bun, and browsers. ES modules, TypeScript, zero dependencies.",
   "type": "module",
   "main": "index.js",
@@ -61,7 +61,8 @@
     "bun",
     "nodejs",
     "tap-protocol",
-    "cross-runtime"
+    "cross-runtime",
+    "zero-dependency"
   ],
   "author": "Eugene Lazutkin <eugene.lazutkin@gmail.com> (https://www.lazutkin.com/)",
   "funding": "https://github.com/sponsors/uhop",
@@ -78,7 +79,9 @@
     "web-app",
     "src",
     "llms.txt",
-    "llms-full.txt"
+    "llms-full.txt",
+    "TESTING.md",
+    "workflows"
   ],
   "tape6": {
     "tests": [
@@ -101,7 +104,7 @@
   },
   "devDependencies": {
     "@types/chai": "^5.2.3",
-    "@types/node": "^25.3.0",
+    "@types/node": "^25.3.1",
     "chai": "^6.2.2",
     "playwright": "^1.58.2",
     "puppeteer": "^24.37.5",

package/src/Tester.js

@@ -236,7 +236,7 @@ export class Tester {
 
   deepLooseEqual(a, b, msg) {
     this.reporter.report({
-      name: msg || 'should be loosely equal',
+      name: msg || 'should be deeply loosely equal',
       test: this.testNumber,
       marker: new Error(),
       time: this.timer.now(),
@@ -251,7 +251,7 @@ export class Tester {
 
   notDeepLooseEqual(a, b, msg) {
     this.reporter.report({
-      name: msg || 'should not be loosely equal',
+      name: msg || 'should not be deeply loosely equal',
       test: this.testNumber,
       marker: new Error(),
       time: this.timer.now(),

package/src/reporters/MinReporter.js

@@ -1,16 +1,5 @@
 import Reporter from './Reporter.js';
 
-const getEnvVar = name => {
-  if (typeof Deno == 'object' && Deno?.version) {
-    return Deno.env.get(name);
-  } else if (typeof Bun == 'object' && Bun?.version) {
-    return Bun.env[name];
-  } else if (typeof process == 'object' && process?.versions?.node) {
-    return process.env[name];
-  }
-  return undefined;
-};
-
 export class MinReporter extends Reporter {
   constructor({failOnce = false, originalConsole} = {}) {
     super({failOnce});

package/src/reporters/Reporter.js

@@ -76,7 +76,7 @@ export class Reporter {
     console: 'onConsole',
     stdout: 'onStdout',
     stderr: 'onStderr',
-    bailOut: 'onBailOut'
+    'bail-out': 'onBailOut'
   };
 }
 

package/src/runners/deno/worker.js

@@ -1,7 +1,7 @@
 const DEFAULT_START_TIMEOUT = 5_000;
 
 const getTimeout = () => {
-  const timeoutValue = Deno.env.get('TAPE6_WORKER_START TIMEOUT');
+  const timeoutValue = Deno.env.get('TAPE6_WORKER_START_TIMEOUT');
   if (!timeoutValue) return DEFAULT_START_TIMEOUT;
   let timeout = Number(timeoutValue);
   if (isNaN(timeout) || timeout <= 0 || timeout === Infinity) timeout = DEFAULT_START_TIMEOUT;

package/src/runners/seq/BypassReporter.js

@@ -25,8 +25,8 @@ export class BypassReporter {
     return this.reporter.signal;
   }
 
-  get abort() {
-    return this.reporter.abort;
+  abort() {
+    this.reporter.abort();
   }
 
   report(event) {

package/src/test.js

@@ -203,6 +203,7 @@ export const runTests = async tests => {
         });
       } else {
         tester.reporter.report({
+          type: 'assert',
           name: 'UNEXPECTED EXCEPTION: ' + String(error),
           test: testNumber,
           marker: new Error(),

package/workflows/write-tests.md

@@ -0,0 +1,33 @@
+---
+description: Write or update tape-six tests for a module or feature
+---
+
+# Write Tests
+
+Write or update tests using the tape-six testing library.
+
+## Notes
+
+- `tape-six` supports ES modules (`.js`, `.mjs`, `.ts`, `.mts`) and CommonJS (`.cjs`, `.cts`).
+- TypeScript is supported natively — no transpilation needed (Node 22+, Deno, Bun run `.ts` files directly).
+- The default `tape6` runner uses worker threads for parallel execution. `tape6-seq` runs sequentially in-process — useful for debugging or when tests share state.
+
+## Steps
+
+1. Read the testing guide at `node_modules/tape-six/TESTING.md` for API reference and patterns.
+2. Identify the module or feature to test. Read its source code to understand the public API.
+3. Create or update the test file in `tests/test-<name>.js` (or `.ts` for TypeScript projects):
+   - Import `test` from `tape-six` (ESM: `import test from 'tape-six'`; CJS: `const {test} = require('tape-six')`).
+   - Import the module under test using the project's package name.
+   - Write one top-level `test()` per logical group.
+   - Use embedded `await t.test()` for sub-cases.
+   - Use `t.beforeEach`/`t.afterEach` for shared setup/teardown.
+   - Cover: normal operation, edge cases, error conditions.
+   - Use `t.equal` for primitives, `t.deepEqual` for objects/arrays, `t.throws` for errors, `await t.rejects` for async errors.
+   - All `msg` arguments are optional but recommended for clarity.
+     // turbo
+4. Run the new test file directly to verify: `node tests/test-<name>.js`
+   // turbo
+5. Run the full test suite to check for regressions: `npm test`
+   - If debugging, use `npm run test:seq` (runs sequentially, easier to trace issues).
+6. Report results and any failures.