@c9up/helix 0.1.8 → 0.1.9

package/dist/runtime/run.js

@@ -7,8 +7,11 @@
  * tree, non-`only` paths are downgraded to `skip` before execution.
  */
 import { AssertionError } from "./assertion-error.js";
-import { drainTestOutcomeHooks, getAssertionState, registerTestCleanup, withTestContext, } from "./test-context.js";
-function compileTagFilter(tags) {
+import { buildTestContext } from "./context.js";
+import { emitter, } from "./emitter.js";
+import { interpolateDatasetTitle } from "./suite.js";
+import { drainTestOutcomeHooks, getAssertionState, registerTestCleanup, setFrameContext, setFrameOutcome, setFrameTest, withTestContext, } from "./test-context.js";
+function compileTagFilter(tags, matchAll) {
     if (!tags || tags.length === 0)
         return undefined;
     const required = [];
@@ -17,14 +20,16 @@ function compileTagFilter(tags) {
         const t = raw.trim();
         if (!t)
             continue;
-        if (t.startsWith("!"))
+        // `~` is the Japa exclusion prefix; `!` is accepted too (helix legacy) so a
+        // stray `!` never silently becomes an impossible required tag.
+        if (t.startsWith("~") || t.startsWith("!"))
             excluded.push(t.slice(1));
         else
             required.push(t);
     }
     if (required.length === 0 && excluded.length === 0)
         return undefined;
-    return { required, excluded };
+    return { required, excluded, matchAll };
 }
 function compileGrep(grep) {
     if (!grep)
@@ -39,29 +44,68 @@ function compileGrep(grep) {
 }
 function tagMatches(node, filter) {
     const have = new Set(node.tags ?? []);
-    for (const r of filter.required)
-        if (!have.has(r))
-            return false;
+    // Exclusions always win.
     for (const e of filter.excluded)
         if (have.has(e))
             return false;
-    return true;
+    if (filter.required.length === 0)
+        return true;
+    // OR by default (any required tag), AND under `--match-all` (every one).
+    return filter.matchAll
+        ? filter.required.every((r) => have.has(r))
+        : filter.required.some((r) => have.has(r));
+}
+/** Nearest enclosing `test.group(...)` title, for the Japa `--groups` filter. */
+function enclosingGroupTitle(node) {
+    for (let s = node.parent; s !== undefined; s = s.parent) {
+        if (s.isGroup)
+            return s.name;
+    }
+    return undefined;
 }
+/** Whether the test's enclosing group is one of the `--groups` titles. */
+function isInGroups(node, groups) {
+    const title = enclosingGroupTitle(node);
+    return title !== undefined && groups.has(title);
+}
+/**
+ * The value actually thrown, carried alongside its serialized form.
+ *
+ * A result crosses the worker→CLI IPC boundary, so it can only hold plain data.
+ * The EMITTER, though, runs in the worker — where the thrown `Error` still
+ * exists, and where a Japa reporter or plugin expects `errors[].error` to be an
+ * `Error` instance. A symbol key is invisible to `JSON.stringify` and to
+ * `Object.keys`, so the original rides along without ever reaching the frame.
+ */
+const THROWN = Symbol("helix.thrown");
+/** The value a {@link SerializedError} was built from, when it is still around. */
+export function thrownValue(error) {
+    return Reflect.get(error, THROWN);
+}
+function withThrown(serialized, thrown) {
+    Object.defineProperty(serialized, THROWN, {
+        value: thrown,
+        enumerable: false,
+    });
+    return serialized;
+}
+/** The reason Japa attaches to a test skipped because the run bailed. */
+const BAIL_SKIP_REASON = "Skipped due to bail mode";
 function serializeError(err) {
     if (err instanceof AssertionError) {
-        return {
+        return withThrown({
             name: err.name,
             message: err.message,
             stack: err.stack,
             actual: err.actual,
             expected: err.expected,
             operator: err.operator,
-        };
+        }, err);
     }
     if (err instanceof Error) {
-        return { name: err.name, message: err.message, stack: err.stack };
+        return withThrown({ name: err.name, message: err.message, stack: err.stack }, err);
     }
-    return { name: "NonError", message: String(err) };
+    return withThrown({ name: "NonError", message: String(err) }, err);
 }
 function hasOnly(node) {
     if (node.mode === "only")
@@ -107,10 +151,12 @@ function collectHookChain(leaf, type) {
     }
     return chain;
 }
-async function runHooks(hooks, registerCleanups = false) {
+async function runHooks(hooks, registerCleanups = false, subject) {
     for (const h of hooks) {
         try {
-            const ret = await h();
+            // Japa parity: test hooks receive the Test instance, group hooks the
+            // Group instance. Zero-arg hooks simply ignore it.
+            const ret = await h(subject);
             // A `beforeEach` returning a function registers it as a test-scoped
             // cleanup (Vitest/Japa parity). Ignored for `afterEach`.
             if (registerCleanups && typeof ret === "function") {
@@ -144,115 +190,477 @@ function combineErrors(primary, secondary) {
         operator: primary.operator,
     };
 }
-async function withTimeout(p, ms, label) {
-    if (ms <= 0)
-        return await p;
+function makeTimeoutController(ms, label) {
     let timer;
-    const timeout = new Promise((_, reject) => {
+    let rejectTimeout;
+    let current = ms;
+    const arm = () => {
+        if (current <= 0)
+            return;
         timer = setTimeout(() => {
-            reject(new Error(`${label} exceeded ${ms}ms timeout`));
-        }, ms);
-        // Don't keep the event loop alive just for this watchdog.
+            rejectTimeout?.(new Error(`${label} exceeded ${current}ms timeout`));
+        }, current);
         timer.unref?.();
-    });
-    try {
-        return await Promise.race([Promise.resolve(p), timeout]);
+    };
+    return {
+        race(work) {
+            if (current <= 0)
+                return Promise.resolve(work);
+            const timeout = new Promise((_, reject) => {
+                rejectTimeout = reject;
+                arm();
+            });
+            return Promise.race([
+                Promise.resolve(work).then((v) => {
+                    if (timer)
+                        clearTimeout(timer);
+                    return v;
+                }),
+                timeout,
+            ]);
+        },
+        reset(newMs) {
+            if (timer)
+                clearTimeout(timer);
+            if (newMs !== undefined)
+                current = newMs;
+            arm();
+        },
+    };
+}
+/**
+ * Whether a test survives the run's filters (Japa's refiner). `--grep` is a
+ * helix extra applied per resolved title, so it lives at the call sites that
+ * know the interpolated name rather than here.
+ */
+function isFilteredOut(node, ctx) {
+    return ((ctx.tagFilter !== undefined && !tagMatches(node, ctx.tagFilter)) ||
+        (ctx.testTitles !== undefined && !ctx.testTitles.has(node.name)) ||
+        (ctx.groupTitles !== undefined && !isInGroups(node, ctx.groupTitles)) ||
+        (ctx.onlyActive && !pathLeadsToOnly(node)));
+}
+/**
+ * Whether any test under this suite survives the filters — Japa's
+ * `Refiner#isGroupAllowed`: a group announces itself only when it has at least
+ * one runnable test, so a fully filtered-out group is invisible to reporters.
+ */
+function suiteHasRunnableTest(node, ctx) {
+    for (const child of node.children) {
+        if (child.kind === "test") {
+            if (!isFilteredOut(child, ctx))
+                return true;
+        }
+        else if (suiteHasRunnableTest(child, ctx)) {
+            return true;
+        }
     }
-    finally {
-        if (timer)
-            clearTimeout(timer);
+    return false;
+}
+/**
+ * The `meta` bag exposed as `ctx.test.options.meta` and on the test events —
+ * Japa's `{ suite, group, fileName, abort }`.
+ */
+function testMeta(node, ctx) {
+    return {
+        suite: ctx.suite,
+        group: enclosingGroup(node),
+        fileName: ctx.file,
+        // Japa's escape hatch: fail the running test with a given message.
+        abort: (message) => {
+            throw new Error(message);
+        },
+    };
+}
+/** Nearest enclosing `test.group(...)` instance, if any (Japa `meta.group`). */
+function enclosingGroup(node) {
+    for (let s = node.parent; s !== undefined; s = s.parent) {
+        if (s.isGroup)
+            return s.groupInstance;
     }
+    return undefined;
+}
+/**
+ * The `test:start` payload for one concrete test (a plain test, or one dataset
+ * row). `test:end` is this object plus the outcome — exactly how Japa builds
+ * the two nodes.
+ */
+function buildTestStartNode(node, expandedTitle, ctx, dataset, flags) {
+    // Japa's `TestOptions`, field for field. `title`, `tags`, `timeout`, `meta`,
+    // `isPinned` — and, as its `Test` constructor initialises them, `isTodo` and
+    // `retries` — always carry a value. The rest appear only when the matching
+    // modifier was used, so a reporter reading `"isSkipped" in node` sees what
+    // Japa would show it. Pinned down by the golden tests, which compare the raw
+    // key set of both runners' nodes.
+    return {
+        title: { original: node.name, expanded: expandedTitle },
+        tags: node.tags ?? [],
+        timeout: node.timeoutMs ?? ctx.timeoutMs,
+        retries: node.retries ?? inheritedEach(node, "eachRetries") ?? ctx.retries,
+        waitsForDone: node.waitForDone === true ? true : undefined,
+        executor: node.fn ?? node.datasetBody,
+        isTodo: flags.isTodo,
+        isSkipped: flags.isSkipped ? true : undefined,
+        isFailing: node.failing === true ? true : undefined,
+        skipReason: flags.isSkipped ? node.reason : undefined,
+        failReason: node.failing === true ? node.reason : undefined,
+        isPinned: node.pinned === true,
+        meta: testMeta(node, ctx),
+        dataset,
+    };
+}
+/** The `errors` array of a `test:end` / `group:end` node. */
+function toEmittedErrors(error, phase) {
+    if (error === undefined)
+        return [];
+    // Japa types `errors[].error` as `Error`; hand listeners the real one when
+    // this process still has it, and fall back to the serialized shape for a
+    // result that was rebuilt from a frame.
+    const thrown = thrownValue(error);
+    return [{ phase, error: thrown instanceof Error ? thrown : error }];
+}
+/**
+ * Emit the Japa `test:start` / `test:end` pair for a test that never runs a
+ * body — a `todo`, an explicit `.skip()`, or a test whose skip condition threw.
+ * Japa announces those through its `DummyRunner`, back-to-back.
+ *
+ * Tests dropped by a FILTER (`--tags`/`--tests`/`--groups`/`--grep`/`.only`)
+ * are deliberately NOT emitted: Japa's refiner removes them before they can
+ * announce themselves, so a reporter never hears about them. They still show up
+ * as `skip` in {@link FileResult}, which is what the (Vitest-shaped) CLI
+ * reporter consumes.
+ */
+function emitTestResult(node, result, ctx, dataset) {
+    const start = buildTestStartNode(node, result.name, ctx, dataset, {
+        isTodo: result.status === "todo",
+        isSkipped: result.status === "skip",
+    });
+    emitter.emit("test:start", start);
+    emitter.emit("test:end", {
+        ...start,
+        duration: result.durationMs,
+        hasError: result.status === "fail",
+        errors: toEmittedErrors(result.error, result.errorPhase ?? "test"),
+    });
 }
 async function runTest(node, parentFullName, ctx) {
-    const fullName = joinName(parentFullName, node.name);
-    if (node.mode === "todo") {
+    const baseFullName = joinName(parentFullName, node.name);
+    // Filter gates (Japa's refiner). Computed first because a filtered-out test
+    // emits NOTHING — not even the `test:start`/`test:end` pair a `.skip()` or a
+    // `todo` still announces. `grep` is per-name (per row for datasets), so it
+    // stays below.
+    const filteredOut = isFilteredOut(node, ctx);
+    // A dataset test with no body (`test('x').with(rows)` and no `.run(fn)` / no
+    // body in `test`) is a `todo` — same as a bodiless plain test (Japa parity).
+    const datasetTodo = node.datasetFn !== undefined && node.datasetBody === undefined;
+    if (node.mode === "todo" || datasetTodo) {
         const r = {
             name: node.name,
-            fullName,
+            fullName: baseFullName,
             status: "todo",
             durationMs: 0,
         };
         ctx.flatTests.push(r);
-        return r;
+        if (!filteredOut)
+            emitTestResult(node, r, ctx);
+        return [r];
     }
-    const filteredOut = (ctx.grep !== undefined && !ctx.grep.test(fullName)) ||
-        (ctx.tagFilter !== undefined && !tagMatches(node, ctx.tagFilter));
-    if (node.mode === "skip" ||
-        filteredOut ||
-        (ctx.onlyActive && !pathLeadsToOnly(node))) {
-        const r = {
-            name: node.name,
-            fullName,
-            status: "skip",
-            durationMs: 0,
-        };
+    // Deferred skip condition (Japa: a `skip(fn)` callback — possibly async — is
+    // evaluated here at run time, not eagerly at collection). A throwing
+    // condition fails the test rather than silently skipping it.
+    let deferredSkip = false;
+    if (node.skipCondition !== undefined) {
+        try {
+            deferredSkip = Boolean(await node.skipCondition());
+        }
+        catch (err) {
+            const r = {
+                name: node.name,
+                fullName: baseFullName,
+                status: "fail",
+                durationMs: 0,
+                error: serializeError(err),
+                errorPhase: "setup",
+            };
+            ctx.flatTests.push(r);
+            if (!filteredOut)
+                emitTestResult(node, r, ctx);
+            return [r];
+        }
+    }
+    // Node-level gates that apply to the whole test (and every dataset row).
+    // `grep` is applied per-name below (per row for datasets). A bailed run skips
+    // what is left — Japa marks them `skip`, it does not drop them.
+    const nodeSkipped = node.mode === "skip" || deferredSkip || filteredOut || ctx.bailed;
+    // Japa marks a bailed-over test with `skip(true, "Skipped due to bail mode")`,
+    // so the reason travels on the node and reaches `skipReason` on the events.
+    // Mirrored here, on the same node, for the same reason.
+    if (ctx.bailed && node.reason === undefined)
+        node.reason = BAIL_SKIP_REASON;
+    const makeSkip = (name, fullName, emit, dataset) => {
+        const r = { name, fullName, status: "skip", durationMs: 0 };
         ctx.flatTests.push(r);
+        if (emit)
+            emitTestResult(node, r, ctx, dataset);
         return r;
+    };
+    const grepOut = (fullName) => ctx.grep !== undefined && !ctx.grep.test(fullName);
+    // Dataset expansion (Japa `test(name, fn).with(rows)`): resolve the rows at
+    // run time (awaiting an async source), then run one test per row with an
+    // interpolated title. The full resolved dataset is exposed as `ctx.test.dataset`.
+    if (node.datasetFn !== undefined) {
+        let rows;
+        try {
+            rows =
+                typeof node.datasetFn === "function"
+                    ? await node.datasetFn()
+                    : node.datasetFn;
+        }
+        catch (err) {
+            const r = {
+                name: node.name,
+                fullName: baseFullName,
+                status: "fail",
+                durationMs: 0,
+                error: serializeError(err),
+                errorPhase: "setup",
+            };
+            ctx.flatTests.push(r);
+            if (!filteredOut)
+                emitTestResult(node, r, ctx);
+            return [r];
+        }
+        const results = [];
+        for (let i = 0; i < rows.length; i += 1) {
+            const title = interpolateDatasetTitle(node.name, rows[i], i);
+            const fullName = joinName(parentFullName, title);
+            const dataset = {
+                size: rows.length,
+                index: i,
+                row: rows[i],
+            };
+            if (nodeSkipped || grepOut(fullName)) {
+                const emit = !filteredOut && !grepOut(fullName);
+                results.push(makeSkip(title, fullName, emit, dataset));
+                continue;
+            }
+            results.push(await runOneTest(node, title, fullName, ctx, rows, rows[i], dataset));
+        }
+        return results;
+    }
+    // Single (non-dataset) test.
+    if (nodeSkipped || grepOut(baseFullName)) {
+        const emit = !filteredOut && !grepOut(baseFullName);
+        return [makeSkip(node.name, baseFullName, emit)];
     }
+    return [
+        await runOneTest(node, node.name, baseFullName, ctx, undefined, undefined, undefined),
+    ];
+}
+/**
+ * Run one concrete test (a plain test, or one row of a dataset) through its
+ * retry loop and record the result. `title`/`fullName` are already resolved
+ * (interpolated for datasets); `dataset`/`row` are set for a dataset row.
+ */
+async function runOneTest(node, title, fullName, ctx, dataset, row, datasetNode) {
     const before = collectHookChain(node.parent, "beforeEach");
     const after = collectHookChain(node.parent, "afterEach");
-    const perTestTimeout = node.timeoutMs ?? ctx.timeoutMs;
-    const attempts = 1 + Math.max(0, node.retries ?? ctx.retries);
+    // Resolution order: per-test override → nearest group `each.timeout`/`retry`
+    // → run-wide default.
+    const perTestTimeout = node.timeoutMs ?? inheritedEach(node, "eachTimeout") ?? ctx.timeoutMs;
+    const perTestRetries = node.retries ?? inheritedEach(node, "eachRetries") ?? ctx.retries;
+    const attempts = 1 + Math.max(0, perTestRetries);
     const start = Date.now();
+    // Japa announces the test ONCE, before the first attempt; the retry loop
+    // lives inside the start/end pair and only the final attempt is reported.
+    const startNode = buildTestStartNode(node, title, ctx, datasetNode, {
+        isTodo: false,
+        isSkipped: false,
+    });
+    emitter.emit("test:start", startNode);
     // Retry loop: each attempt runs the FULL cycle (beforeEach + body +
     // afterEach) inside its own per-test frame so cleanups / outcome hooks /
     // assertion counters reset between attempts. Passes on the first success.
     let last;
+    // 1-based number of the attempt that produced `last` (Japa counts the first
+    // run as attempt 1), and only reported when the test opted into retries.
+    let attemptNumber = 1;
     for (let attempt = 0; attempt < attempts; attempt += 1) {
-        last = await withTestContext(() => runAttempt(node, fullName, before, after, perTestTimeout, start));
+        attemptNumber = attempt + 1;
+        last = await withTestContext(() => runAttempt(node, title, fullName, before, after, perTestTimeout, perTestRetries, start, dataset, row, testMeta(node, ctx)));
         if (last.status === "pass")
             break;
     }
     ctx.flatTests.push(last);
+    if (ctx.bail && last.status === "fail")
+        ctx.bailed = true;
+    emitter.emit("test:end", {
+        ...startNode,
+        retryAttempt: perTestRetries > 0 ? attemptNumber : undefined,
+        duration: last.durationMs,
+        hasError: last.status === "fail",
+        errors: toEmittedErrors(last.error, last.errorPhase ?? "test"),
+    });
     return last;
 }
+function noop() { }
+/** Narrow an unknown value to a thenable without a cast. */
+function isThenable(v) {
+    return (v !== null &&
+        (typeof v === "object" || typeof v === "function") &&
+        typeof Reflect.get(v, "then") === "function");
+}
+/** Nearest ancestor group's `each.timeout`/`each.retry` default for a test. */
+function inheritedEach(node, key) {
+    for (let suite = node.parent; suite !== undefined; suite = suite.parent) {
+        const value = suite[key];
+        if (value !== undefined)
+            return value;
+    }
+    return undefined;
+}
 /** Run one full attempt of a test inside the active per-test frame. */
-async function runAttempt(node, fullName, before, after, timeoutMs, start) {
-    const beforeErr = await runHooks(before, true);
+async function runAttempt(node, title, fullName, before, after, timeoutMs, retries, start, dataset, row, meta) {
+    // A re-armable body timeout so `ctx.test.resetTimeout()` can push the deadline.
+    const timeoutCtl = makeTimeoutController(timeoutMs, `test "${fullName}"`);
+    // The running test's instance — injected as `ctx.test`, passed to the test
+    // hooks (Japa parity), and threaded into the frame so cleanups receive it.
+    const testInstance = {
+        title,
+        fullName,
+        options: {
+            title,
+            timeout: timeoutMs,
+            retries,
+            tags: node.tags ?? [],
+            isTodo: false,
+            // `test.fails()` — a Japa plugin reads it to know an error was the
+            // point (`@japa/assert` skips its assertion check for such a test).
+            isFailing: node.failing === true,
+            meta,
+        },
+        dataset: dataset ?? node.dataset,
+        isPinned: node.pinned === true,
+        resetTimeout: (ms) => timeoutCtl.reset(ms),
+        cleanup: (fn) => {
+            registerTestCleanup(fn);
+        },
+    };
+    setFrameTest(testInstance);
+    // Build the injected context BEFORE the `beforeEach` chain so hooks can reach
+    // it as `$test.context` (Japa parity) — the SAME context flows to the body.
+    // Built inside the per-test frame so `ctx.cleanup` / getters bind here.
+    const context = buildTestContext(testInstance);
+    // A Japa `Test.executed` hook reads `test.context` — `@japa/assert` validates
+    // its assertion count through it after every test.
+    setFrameContext(context);
+    testInstance.context = context;
+    const beforeErr = await runHooks(before, true, testInstance);
     if (beforeErr) {
-        const afterErrBE = await runHooks(after);
+        const afterErrBE = await runHooks(after, false, testInstance);
         await drainTestOutcomeHooks(true);
         return {
-            name: node.name,
+            name: title,
             fullName,
             status: "fail",
             durationMs: Date.now() - start,
             error: combineErrors(beforeErr, afterErrBE),
+            errorPhase: "setup",
         };
     }
     let testErr;
-    try {
-        const result = node.fn?.();
-        if (result && typeof result.then === "function") {
-            await withTimeout(result, timeoutMs, `test "${fullName}"`);
-        }
-    }
-    catch (err) {
-        testErr = serializeError(err);
-    }
-    // `test.fails()` inverts the body outcome: a throw is success, a clean
-    // run is a failure. Applied before assertion-count checks.
-    if (node.failing) {
-        testErr = testErr
-            ? undefined
-            : {
-                name: "AssertionError",
-                message: `test "${fullName}" was expected to fail (test.fails) but passed`,
-            };
+    // Which phase produced `testErr` — surfaced on `test:end` (Japa parity).
+    let errorPhase;
+    // Per-test setup hooks (`test.setup`) run after the group `each.setup` chain,
+    // just before the body. A failing setup fails the test without running it.
+    const setupErr = await runHooks(node.setups ?? [], true, testInstance);
+    if (setupErr) {
+        testErr = setupErr;
+        errorPhase = "setup";
     }
-    // Assertion-count enforcement (`expect.assertions(n)` / `hasAssertions()`).
-    if (!testErr) {
-        testErr = checkAssertionCount(fullName);
+    else {
+        try {
+            // `done` callback (Japa `waitForDone`): the test completes when the
+            // body calls done()/done(error). Built even when unused (harmless).
+            let doneResolve = noop;
+            let doneReject = noop;
+            const donePromise = new Promise((resolve, reject) => {
+                doneResolve = resolve;
+                doneReject = reject;
+            });
+            let doneCalled = false;
+            const done = (error) => {
+                if (doneCalled)
+                    return;
+                doneCalled = true;
+                if (error !== undefined)
+                    doneReject(error);
+                else
+                    doneResolve();
+            };
+            // A dataset test runs its `datasetBody(ctx, row)`; a plain test its
+            // `fn(ctx, done)`.
+            const result = node.datasetFn !== undefined
+                ? node.datasetBody?.(context, row)
+                : node.fn?.(context, done);
+            if (node.waitForDone) {
+                // Complete on done(); a body rejection still fails fast, but a body
+                // that merely RESOLVES does not complete the test (it must call done).
+                const body = isThenable(result) ? result : Promise.resolve();
+                const bodyRejectsOnly = body.then(() => new Promise(noop), (err) => {
+                    throw err;
+                });
+                await timeoutCtl.race(Promise.race([donePromise, bodyRejectsOnly]));
+            }
+            else if (isThenable(result)) {
+                await timeoutCtl.race(result);
+            }
+        }
+        catch (err) {
+            testErr = serializeError(err);
+            errorPhase = "test";
+        }
+        // `test.fails()` inverts the body outcome: a throw is success, a clean
+        // run is a failure. Applied before assertion-count checks. Only when the
+        // body actually ran (a setup error is a hard failure, not an expected one).
+        if (node.failing) {
+            testErr = testErr
+                ? undefined
+                : {
+                    name: "AssertionError",
+                    message: `test "${fullName}" was expected to fail (test.fails) but passed`,
+                };
+            errorPhase = testErr === undefined ? undefined : "test";
+        }
+        // Assertion-count enforcement (`expect.assertions(n)` / `hasAssertions()`).
+        if (!testErr) {
+            testErr = checkAssertionCount(fullName);
+            if (testErr !== undefined)
+                errorPhase = "test";
+        }
     }
-    const afterErr = await runHooks(after);
-    const finalErr = combineErrors(testErr, afterErr);
-    await drainTestOutcomeHooks(finalErr !== undefined);
+    // Per-test teardown hooks (`test.teardown`) run before the group `each.teardown`.
+    const teardownErr = await runHooks(node.teardowns ?? [], false, testInstance);
+    const afterErr = await runHooks(after, false, testInstance);
+    const finalErr = combineErrors(combineErrors(testErr, teardownErr), afterErr);
+    // Record the outcome BEFORE the frame's cleanup drain (finally) fires, so
+    // `ctx.cleanup((hasError, test) => …)` sees the right `hasError`.
+    setFrameOutcome(finalErr !== undefined);
+    // A `Test.executed` hook is a verdict, not a teardown: `@japa/assert`
+    // validates `assert.plan(n)` there. Its throw has to reach the result, or a
+    // plugin's whole reason for existing passes green.
+    const executedErr = await drainTestOutcomeHooks(finalErr !== undefined);
+    const outcome = executedErr === undefined
+        ? finalErr
+        : combineErrors(finalErr, serializeError(executedErr));
     return {
-        name: node.name,
+        name: title,
         fullName,
-        status: finalErr ? "fail" : "pass",
+        status: outcome ? "fail" : "pass",
         durationMs: Date.now() - start,
-        error: finalErr,
+        error: outcome,
+        // A failure with no recorded phase came from the teardown chain, or from a
+        // `Test.executed` hook, which runs at the same point.
+        errorPhase: outcome === undefined ? undefined : (errorPhase ?? "teardown"),
     };
 }
 /** Verify `expect.assertions(n)` / `hasAssertions()` for the active frame. */
@@ -290,9 +698,11 @@ function attributeHookFailure(node, parentFullName, err, ctx) {
                 status: child.mode === "todo" ? "todo" : "fail",
                 durationMs: 0,
                 error: child.mode === "todo" ? undefined : err,
+                errorPhase: child.mode === "todo" ? undefined : "setup",
             };
             children.push(r);
             ctx.flatTests.push(r);
+            emitTestResult(child, r, ctx);
         }
         else {
             const innerChildren = attributeHookFailure(child, fullName, err, ctx);
@@ -319,19 +729,67 @@ async function runSuite(node, parentFullName, ctx) {
     if (skipEntire)
         return runSkippedSuite(node, fullName, ctx);
     const hookErrors = [];
+    // The group's instance (Japa parity) passed to group hooks, and cleanups a
+    // `group.setup()` returns — run in the afterAll phase with `(hadError, group)`.
+    // For a `test.group()` this is the SAME object the body received and the call
+    // returned (`self === group`); a plain `describe` suite has no group handle,
+    // so fall back to a bare identity object.
+    const group = node.groupInstance ?? {
+        title: node.name,
+        fullName,
+    };
+    const groupCleanups = [];
+    // A group with no runnable test announces nothing — Japa's refiner drops it
+    // before `Group.exec()` runs, so a reporter never sees it.
+    const groupFiltered = !suiteHasRunnableTest(node, ctx);
+    if (!groupFiltered) {
+        emitter.emit("group:start", {
+            title: node.name,
+            meta: { suite: ctx.suite, fileName: ctx.file },
+        });
+    }
     // beforeAll: when one throws, every descendant test inherits the failure
     // and the children list is replaced with those attributed results.
-    const attributed = await runBeforeAllHooks(node, parentFullName, ctx, hookErrors);
+    const attributed = await runBeforeAllHooks(node, parentFullName, ctx, hookErrors, group, groupCleanups);
     const beforeAllFailed = attributed !== null;
     const children = attributed ?? [];
+    // `--bail-layer=group` confines a bail to the group it happened in, so the
+    // next group starts clean. The wider layers leave the flag set.
+    const bailedOnEntry = ctx.bailed;
     if (!beforeAllFailed) {
         for (const child of node.children) {
-            children.push(child.kind === "test"
-                ? await runTest(child, fullName, ctx)
-                : await runSuite(child, fullName, ctx));
+            if (child.kind === "test") {
+                // A dataset test expands to one result per row (Japa parity).
+                for (const r of await runTest(child, fullName, ctx))
+                    children.push(r);
+            }
+            else {
+                children.push(await runSuite(child, fullName, ctx));
+            }
         }
     }
-    await runAfterAllHooks(node, hookErrors);
+    if (ctx.bailLayer === "group")
+        ctx.bailed = bailedOnEntry;
+    const groupHadError = hookErrors.length > 0 || children.some((c) => c.status === "fail");
+    // Errors recorded so far come from `beforeAll`; anything appended by
+    // `runAfterAllHooks` below belongs to the teardown phase.
+    const setupErrorCount = hookErrors.length;
+    await runAfterAllHooks(node, hookErrors, group, groupCleanups, groupHadError);
+    if (!groupFiltered) {
+        emitter.emit("group:end", {
+            title: node.name,
+            meta: { suite: ctx.suite, fileName: ctx.file },
+            // True when ANYTHING under the group failed — a hook or a test — which
+            // is what Japa's GroupRunner reports.
+            hasError: groupHadError || hookErrors.length > 0,
+            // The group's own `errors` are its hook failures only; a test's failure
+            // travels on that test's `test:end` (Japa parity).
+            errors: hookErrors.map((error, i) => ({
+                phase: i < setupErrorCount ? "setup" : "teardown",
+                error,
+            })),
+        });
+    }
     // Surface afterAll failures as a synthetic test so `totals.fail` reflects
     // them and CI exits nonzero.
     if (!beforeAllFailed && hookErrors.length > 0) {
@@ -357,6 +815,12 @@ async function runSuite(node, parentFullName, ctx) {
 /** Build skip/todo results for an entirely-skipped suite (no hooks run). */
 async function runSkippedSuite(node, fullName, ctx) {
     const children = [];
+    // The group still announces itself — its tests are skipped, not filtered
+    // out — so a reporter can nest them under it.
+    emitter.emit("group:start", {
+        title: node.name,
+        meta: { suite: ctx.suite, fileName: ctx.file },
+    });
     for (const child of node.children) {
         if (child.kind === "test") {
             const r = {
@@ -367,11 +831,18 @@ async function runSkippedSuite(node, fullName, ctx) {
             };
             children.push(r);
             ctx.flatTests.push(r);
+            emitTestResult(child, r, ctx);
         }
         else {
             children.push(await runSuiteSkip(child, fullName, ctx));
         }
     }
+    emitter.emit("group:end", {
+        title: node.name,
+        meta: { suite: ctx.suite, fileName: ctx.file },
+        hasError: false,
+        errors: [],
+    });
     return {
         name: node.name,
         fullName,
@@ -386,12 +857,16 @@ async function runSkippedSuite(node, fullName, ctx) {
  * error to `hookErrors` and return the descendant tests attributed with that
  * failure; return `null` when all hooks pass.
  */
-async function runBeforeAllHooks(node, parentFullName, ctx, hookErrors) {
+async function runBeforeAllHooks(node, parentFullName, ctx, hookErrors, group, groupCleanups) {
     for (const h of node.hooks) {
         if (h.type !== "beforeAll")
             continue;
         try {
-            await h.fn();
+            // Japa parity: group hooks receive the Group instance; a returned
+            // function becomes a group-scoped cleanup (run in the afterAll phase).
+            const ret = await h.fn(group);
+            if (typeof ret === "function")
+                groupCleanups.push(ret);
         }
         catch (err) {
             const serialized = serializeError(err);
@@ -406,12 +881,22 @@ async function runBeforeAllHooks(node, parentFullName, ctx, hookErrors) {
  * Run `afterAll` hooks unconditionally so partial setup from a failed beforeAll
  * can be released. Errors are captured into `hookErrors`, not thrown.
  */
-async function runAfterAllHooks(node, hookErrors) {
+async function runAfterAllHooks(node, hookErrors, group, groupCleanups, hadError) {
+    // Group-scoped cleanups (returned by `group.setup()`) run first, in reverse
+    // insertion order, receiving `(hadError, group)` — Japa lifecycle parity.
+    for (let i = groupCleanups.length - 1; i >= 0; i -= 1) {
+        try {
+            await groupCleanups[i](hadError, group);
+        }
+        catch (err) {
+            hookErrors.push(serializeError(err));
+        }
+    }
     for (const h of node.hooks) {
         if (h.type !== "afterAll")
             continue;
         try {
-            await h.fn();
+            await h.fn(group);
         }
         catch (err) {
             hookErrors.push(serializeError(err));
@@ -431,6 +916,10 @@ function suiteStatus(children, hookErrors) {
 async function runSuiteSkip(node, parentFullName, ctx) {
     const fullName = joinName(parentFullName, node.name);
     const children = [];
+    emitter.emit("group:start", {
+        title: node.name,
+        meta: { suite: ctx.suite, fileName: ctx.file },
+    });
     for (const child of node.children) {
         if (child.kind === "test") {
             const r = {
@@ -441,11 +930,18 @@ async function runSuiteSkip(node, parentFullName, ctx) {
             };
             children.push(r);
             ctx.flatTests.push(r);
+            emitTestResult(child, r, ctx);
         }
         else {
             children.push(await runSuiteSkip(child, fullName, ctx));
         }
     }
+    emitter.emit("group:end", {
+        title: node.name,
+        meta: { suite: ctx.suite, fileName: ctx.file },
+        hasError: false,
+        errors: [],
+    });
     return {
         name: node.name,
         fullName,
@@ -464,9 +960,31 @@ export async function executeRoot(root, file, options = {}) {
         timeoutMs: options.timeoutMs ?? 0,
         retries: options.retries ?? 0,
         grep: compileGrep(options.grep),
-        tagFilter: compileTagFilter(options.tags),
+        tagFilter: compileTagFilter(options.tags, options.matchAll === true),
+        testTitles: options.tests && options.tests.length > 0
+            ? new Set(options.tests)
+            : undefined,
+        groupTitles: options.groups && options.groups.length > 0
+            ? new Set(options.groups)
+            : undefined,
+        file,
+        suite: { name: options.suite ?? "default" },
+        bail: options.bail === true,
+        // Japa spells the runner layer as an empty string on its CLI.
+        bailLayer: options.bailLayer === undefined || options.bailLayer === ""
+            ? "runner"
+            : options.bailLayer,
+        bailed: false,
     };
     const suites = [];
+    // Japa's runner/suite frame. Helix has no named-suite layer (one process per
+    // file), so the FILE is the suite — `suite:start` carries its name.
+    // Japa skips a suite whose every test is filtered out — the suite never
+    // announces itself, though the runner still opens and closes the run.
+    const suiteRunnable = suiteHasRunnableTest(root, ctx);
+    emitter.emit("runner:start", {});
+    if (suiteRunnable)
+        emitter.emit("suite:start", { name: ctx.suite.name });
     // Root-level beforeAll: run once before anything, root-level afterAll:
     // once after everything. Errors attribute to a synthetic test entry so
     // they show up in totals.
@@ -496,17 +1014,14 @@ export async function executeRoot(root, file, options = {}) {
     if (!rootBeforeAllFailed) {
         for (const child of root.children) {
             if (child.kind === "test") {
-                const tr = await runTest(child, "", ctx);
+                // A dataset test expands to one result per row (Japa parity).
+                const trs = await runTest(child, "", ctx);
                 suites.push({
                     name: "",
                     fullName: "",
-                    children: [tr],
-                    status: tr.status === "fail"
-                        ? "fail"
-                        : tr.status === "pass"
-                            ? "pass"
-                            : "skip",
-                    durationMs: tr.durationMs,
+                    children: trs,
+                    status: suiteStatus(trs, []),
+                    durationMs: trs.reduce((sum, t) => sum + t.durationMs, 0),
                     hookErrors: [],
                 });
             }
@@ -538,6 +1053,15 @@ export async function executeRoot(root, file, options = {}) {
     const totals = { pass: 0, fail: 0, skip: 0, todo: 0 };
     for (const t of ctx.flatTests)
         totals[t.status] += 1;
+    const hasError = totals.fail > 0;
+    if (suiteRunnable) {
+        emitter.emit("suite:end", {
+            name: ctx.suite.name,
+            hasError,
+            errors: rootHookErrors.map((error) => ({ phase: "setup", error })),
+        });
+    }
+    emitter.emit("runner:end", { hasError });
     return {
         file,
         suites,