Test Runner IV

Requirements

• Export TestRunner as named and default. Keep test(name, callback), skip(name), and async run() from Test Runner. Add describe(name, declare), which invokes a synchronous declaration callback with this runner. Registration methods return this for chaining. Names must be nonempty strings after trimming; preserve their original text, and allow duplicates.
• Suites may nest. Each test result name consists of its suite names followed by its test name, joined with > and one space on each side. Root test names remain unchanged. Suites themselves do not create results. Restore the parent registration scope after describe finishes.
• Invalid names/callbacks throw TypeError. If a suite declaration throws, remove all tests registered by that describe call and restore the parent scope; rethrow the same error. A declaration returning a thenable throws TypeError and rolls back. Async suite declarations are unsupported; do not schedule later registrations from them.
• run returns Promise<{ total, passed, failed, skipped, results }>. Results have name and status: passed, failed, or skipped. Only failed results have an own error property containing the exact thrown/rejected value, including undefined. Skipped tests invoke no callbacks.
• Execute active tests serially in registration order, awaiting returned values/thenables. One failure does not stop later tests. Snapshot registrations at run start; later registrations affect future runs only. Each run executes the full snapshot again and returns fresh objects.
• Reject overlapping run calls on the same runner with Error without disturbing the active run. Independent runners may run concurrently. Release the running flag even after failures. No test library, timeouts, parallel test scheduling, retries, durations, or assertion implementation is required.
• Add beforeEach(callback) and afterEach(callback), returning this. Register hooks on the current suite, including the root. Callbacks may be synchronous or return thenables, and invalid hook callbacks throw TypeError. Hooks run only for active tests in their own suite or descendant suites.
• For each active test, await beforeEach hooks from root to innermost suite, preserving registration order within each suite. Then invoke the test. Await afterEach hooks from innermost suite to root, again in registration order within each suite. Skip registrations run neither tests nor hooks.
• If setup fails, stop remaining setup hooks and skip the test body, but still attempt every inherited cleanup hook, including hooks from suites whose setup did not run. Cleanup errors never stop later cleanup hooks. A test has one result; keep the first setup/body/cleanup failure reason exactly, even undefined. Cleanup-only failure makes the test failed.
• Snapshot each test’s applicable hook lists at run start. Hooks registered after a test but before run apply to it. Hooks or tests registered while running affect future runs only. Failed suite declarations discard their own hooks and tests. No beforeAll/afterAll hooks or retries are required.
• Add describeAsync(name, declare): Promise<this>. Await the declaration callback before restoring its parent scope. The callback may register tests/hooks before and after awaits and may await nested describeAsync calls. Synchronous describe remains supported with its existing restrictions.
• Await every describeAsync call before registering sibling/root entries or starting another declaration. Overlapping sibling declarations and fire-and-forget nested declarations are outside scope. Suite declaration callbacks only register content; they do not execute test callbacks.
• If an async declaration rejects, roll back every test registered by that declaration, including nested registrations; restore its parent scope and reject with the exact reason. Failed declaration hooks are discarded along with their suite.
• run rejects with Error while any declaration scope is active, leaving registrations untouched. describeAsync rejects during an active run without invoking its callback. A rejected run/declaration must not disturb a later valid run. Keep serial awaiting, snapshots, inherited hook order, cleanup on failures, and exact error values from Test Runner III.

Examples

Input: await runner.describeAsync("loaded", async suite => { await Promise.resolve(); suite.beforeEach(async()=>{ await prepare(); }); suite.test("works", async()=>{ await check(); }); }); await runner.run();
Output: Runs the prepared async test inside loaded > works.

Input: await runner.describeAsync("outer", async suite => { await suite.describeAsync("inner", async child => { child.test("value", ()=>42); }); });
Output: Registers outer > inner > value.