@pikku/cli 0.12.90 → 0.12.91

package/dist/src/functions/commands/scenario-plan.d.ts

@@ -0,0 +1,61 @@
+import type { CoreFeature, CoreWorkflow } from '@pikku/core/workflow';
+/** One scenario run: a scenario name and, for a feature's paired entry, its input. */
+export type ScenarioPlanEntry = {
+    scenarioName: string;
+    data?: unknown;
+    tags: string[];
+    /**
+     * Why this scenario is not part of a default run. It stays in the plan so
+     * the runner reports it as skipped rather than omitting it silently, and it
+     * is cleared when the scenario is named directly with `--flows` — the
+     * explicit ask that overrides the quarantine.
+     */
+    skip?: string;
+};
+/**
+ * A run unit. A feature is one group whose hooks run once around all of its
+ * entries; a scenario belonging to no feature is a group of one with no hooks.
+ */
+export type ScenarioPlanGroup = {
+    featureId?: string;
+    featureName?: string;
+    before?: CoreFeature['before'];
+    after?: CoreFeature['after'];
+    entries: ScenarioPlanEntry[];
+};
+export type ScenarioPlanInput = {
+    /** Scenarios the inspector found, in declaration order. */
+    scenarios: Array<{
+        name: string;
+        tags: string[];
+        skip?: string;
+    }>;
+    features: Map<string, CoreFeature>;
+    registrations: Map<string, CoreWorkflow>;
+    flows?: string[];
+    featureIds?: string[];
+    tags?: string[];
+    /**
+     * Tags that disqualify a scenario. `tags` is match-any with no negation, so
+     * without this a default run cannot express "everything except the
+     * live-model ones" — the shape every suite that holds a cluster back needs.
+     */
+    excludeTags?: string[];
+};
+export type ScenarioPlan = {
+    groups: ScenarioPlanGroup[];
+    /** Feature entries whose scenario is not registered — reported, never skipped silently. */
+    unresolved: Array<{
+        featureId: string;
+        index: number;
+    }>;
+};
+/**
+ * Turn the registered scenarios and features into an ordered list of run units.
+ *
+ * Features come first, in registration order, then the scenarios that belong to
+ * no feature, in declaration order. Selection is a filter over that plan rather
+ * than a different traversal, so `--tags` narrowing a feature to two of its
+ * five scenarios still runs the feature's hooks exactly once around those two.
+ */
+export declare const buildScenarioPlan: ({ scenarios, features, registrations, flows, featureIds, tags, excludeTags, }: ScenarioPlanInput) => ScenarioPlan;

package/dist/src/functions/commands/scenario-plan.js

@@ -0,0 +1,106 @@
+import { resolveFeatureScenarios } from '@pikku/core/workflow';
+/**
+ * Turn the registered scenarios and features into an ordered list of run units.
+ *
+ * Features come first, in registration order, then the scenarios that belong to
+ * no feature, in declaration order. Selection is a filter over that plan rather
+ * than a different traversal, so `--tags` narrowing a feature to two of its
+ * five scenarios still runs the feature's hooks exactly once around those two.
+ */
+export const buildScenarioPlan = ({ scenarios, features, registrations, flows, featureIds, tags, excludeTags, }) => {
+    const { entries, unresolved } = resolveFeatureScenarios(features, registrations);
+    if (flows) {
+        const known = new Set(scenarios.map((s) => s.name));
+        const unknown = flows.filter((name) => !known.has(name));
+        if (unknown.length > 0) {
+            throw new Error(`Unknown scenario(s): ${unknown.join(', ')}. Available: ${scenarios
+                .map((s) => s.name)
+                .join(', ')}`);
+        }
+        // A scenario every one of whose feature entries carries `data` has no input
+        // to run with when it is named directly — the feature is what supplies it,
+        // so the feature is what runs. A scenario referenced bare anywhere, or in no
+        // feature at all, runs standalone exactly as before.
+        for (const name of flows) {
+            const appearances = entries.filter((e) => e.scenarioName === name);
+            if (appearances.length === 0)
+                continue;
+            if (appearances.some((e) => e.data === undefined))
+                continue;
+            const containing = [...new Set(appearances.map((e) => e.featureId))];
+            throw new Error(`Scenario '${name}' is only ever run with data supplied by a feature, so there is nothing to run it with on its own — run the feature instead: --features ${containing.join(',')}`);
+        }
+    }
+    if (featureIds) {
+        const unknown = featureIds.filter((id) => !features.has(id));
+        if (unknown.length > 0) {
+            throw new Error(`Unknown feature(s): ${unknown.join(', ')}. Available: ${[...features.keys()].join(', ') || '(none)'}`);
+        }
+    }
+    const skipReasons = new Map(scenarios
+        .filter((scenario) => scenario.skip)
+        .map((scenario) => [scenario.name, scenario.skip]));
+    const wantedFlows = flows ? new Set(flows) : undefined;
+    const wantedFeatures = featureIds ? new Set(featureIds) : undefined;
+    const wantedTags = tags ? new Set(tags) : undefined;
+    const unwantedTags = excludeTags ? new Set(excludeTags) : undefined;
+    // Naming a scenario with `--flows` is the explicit ask that overrides its
+    // quarantine; narrowing to its feature is not — a feature is a group, and
+    // running the group should not silently drag a quarantined member in.
+    const skipFor = (scenarioName) => wantedFlows?.has(scenarioName) ? undefined : skipReasons.get(scenarioName);
+    const keep = (entry, featureId) => {
+        if (wantedFeatures && !(featureId && wantedFeatures.has(featureId))) {
+            return false;
+        }
+        if (wantedFlows && !wantedFlows.has(entry.scenarioName)) {
+            return false;
+        }
+        if (wantedTags && !entry.tags.some((tag) => wantedTags.has(tag))) {
+            return false;
+        }
+        // Naming a scenario with `--flows` is the explicit ask, the same override
+        // that lifts a quarantine: it outranks an exclusion the caller did not aim
+        // at this scenario in particular.
+        if (unwantedTags &&
+            !wantedFlows?.has(entry.scenarioName) &&
+            entry.tags.some((tag) => unwantedTags.has(tag))) {
+            return false;
+        }
+        return true;
+    };
+    const groups = [];
+    for (const [featureId, feature] of features) {
+        const kept = entries
+            .filter((entry) => entry.featureId === featureId)
+            .map(({ scenarioName, data, tags: entryTags }) => ({
+            scenarioName,
+            data,
+            tags: entryTags,
+            skip: skipFor(scenarioName),
+        }))
+            .filter((entry) => keep(entry, featureId));
+        if (kept.length === 0)
+            continue;
+        groups.push({
+            featureId,
+            featureName: feature.name ?? featureId,
+            before: feature.before,
+            after: feature.after,
+            entries: kept,
+        });
+    }
+    const inAFeature = new Set(entries.map((entry) => entry.scenarioName));
+    for (const scenario of scenarios) {
+        if (inAFeature.has(scenario.name))
+            continue;
+        const entry = {
+            scenarioName: scenario.name,
+            tags: scenario.tags,
+            skip: skipFor(scenario.name),
+        };
+        if (!keep(entry))
+            continue;
+        groups.push({ entries: [entry] });
+    }
+    return { groups, unresolved };
+};

package/dist/src/functions/commands/scenario.d.ts

@@ -2,16 +2,34 @@ export declare const scenarioList: import("#pikku").PikkuFunctionConfig<{}, void
 export declare const scenarioRun: import("#pikku").PikkuFunctionConfig<{
     environment: string;
     flows?: string;
+    features?: string;
     tags?: string;
+    excludeTags?: string;
     coverage?: boolean;
+    browser?: boolean;
+    spawn?: boolean;
+    keepAlive?: boolean;
+    trace?: boolean;
 }, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<{
     environment: string;
     flows?: string;
+    features?: string;
     tags?: string;
+    excludeTags?: string;
     coverage?: boolean;
+    browser?: boolean;
+    spawn?: boolean;
+    keepAlive?: boolean;
+    trace?: boolean;
 }, void, "rpc" | "session", import("#pikku").WiredServices> | import("#pikku").PikkuFunction<{
     environment: string;
     flows?: string;
+    features?: string;
     tags?: string;
+    excludeTags?: string;
     coverage?: boolean;
+    browser?: boolean;
+    spawn?: boolean;
+    keepAlive?: boolean;
+    trace?: boolean;
 }, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;

package/dist/src/functions/commands/scenario.js

@@ -2,8 +2,16 @@ import { resolve, join } from 'node:path';
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { pikkuSessionlessFunc } from '#pikku';
 import { InMemoryWorkflowService, createHttpScenarioActors, } from '@pikku/core/services';
-import { pikkuState } from '@pikku/core/internal';
-import { loadUserBootstrap } from './load-user-project.js';
+import { PikkuScenarioService } from '@pikku/core/scenario';
+import { pikkuState, getAllPackageStates } from '@pikku/core/internal';
+import { resolveFeatureScenarios } from '@pikku/core/workflow';
+import { loadScenarioBootstrap } from './load-user-project.js';
+import { collectScenarioStepProse, scenarioBrowserSteps, scenarioFailureFromSteps, scenarioStepRows, } from './scenario-ladder.js';
+import { formatScenarioReport } from './scenario-formatter.js';
+import { resolveScenarioBrowserProvider, scenarioBrowserLifecycle, } from './scenario-browser.js';
+import { resolveScenarioActors } from '../../utils/resolve-scenario-actors.js';
+import { spawnDevServer } from '../../server/spawn-dev-server.js';
+import { buildScenarioPlan } from './scenario-plan.js';
 const isScenario = (wf) => wf?.scenario === true;
 const listScenarios = (state) => Object.entries(state.workflows?.meta ?? {})
     .filter(([, wf]) => isScenario(wf))
@@ -12,27 +20,71 @@ const listScenarios = (state) => Object.entries(state.workflows?.meta ?? {})
     name: wf.name ?? id,
     description: wf.description ?? wf.summary ?? wf.title ?? null,
     tags: wf.tags ?? [],
+    skip: wf.skip,
 }));
+/**
+ * Features and scenario registrations, merged across the main package and any
+ * addon packages. A feature holds the very config objects the registrations
+ * hold, which is what makes membership resolvable by identity.
+ */
+const collectRegisteredWirings = () => {
+    const features = new Map();
+    const registrations = new Map();
+    for (const [packageName] of getAllPackageStates()) {
+        const scope = packageName === '__main__' ? null : packageName;
+        for (const [id, feature] of pikkuState(scope, 'workflows', 'features')) {
+            features.set(id, feature);
+        }
+        for (const [name, registration] of pikkuState(scope, 'workflows', 'registrations')) {
+            registrations.set(name, registration);
+        }
+    }
+    return { features, registrations };
+};
 export const scenarioList = pikkuSessionlessFunc({
-    func: async ({ logger, getInspectorState }) => {
-        const state = await getInspectorState();
+    func: async ({ logger, config, getInspectorState }) => {
+        const state = await getInspectorState(false, false, false, true);
         const flows = listScenarios(state);
         if (flows.length === 0) {
             logger.info('No scenarios found (pikkuScenario exports).');
             return;
         }
+        await loadScenarioBootstrap(resolve(config.rootDir, config.outDir));
+        const { features, registrations } = collectRegisteredWirings();
+        const { entries, unresolved } = resolveFeatureScenarios(features, registrations);
+        for (const { featureId, index } of unresolved) {
+            logger.error(`Feature '${featureId}' scenario #${index} is not a registered scenario — it will not run.`);
+        }
+        const describe = (name) => flows.find((flow) => flow.name === name)?.description;
+        for (const [featureId, feature] of features) {
+            const featureTags = feature.tags?.length
+                ? `  [${feature.tags.join(', ')}]`
+                : '';
+            logger.info(`${feature.name ?? featureId}${featureTags}`);
+            if (feature.description) {
+                logger.info(`  ${feature.description}`);
+            }
+            for (const entry of entries.filter((e) => e.featureId === featureId)) {
+                const data = entry.data ? ` ${JSON.stringify(entry.data)}` : '';
+                logger.info(`  - ${entry.scenarioName}${data}`);
+            }
+        }
+        const inAFeature = new Set(entries.map((entry) => entry.scenarioName));
         for (const flow of flows) {
+            if (inAFeature.has(flow.name))
+                continue;
             const tags = flow.tags.length ? `  [${flow.tags.join(', ')}]` : '';
             logger.info(`${flow.name}${tags}`);
-            if (flow.description) {
-                logger.info(`  ${flow.description}`);
+            const description = describe(flow.name);
+            if (description) {
+                logger.info(`  ${description}`);
             }
         }
     },
 });
 export const scenarioRun = pikkuSessionlessFunc({
-    func: async ({ logger, config, getInspectorState, variables }, { environment, flows, tags, coverage }) => {
-        const state = await getInspectorState(true);
+    func: async ({ logger, config, getInspectorState, variables }, { environment, flows, features, tags, excludeTags, coverage, browser = true, spawn = false, keepAlive = false, trace = false, }) => {
+        const state = await getInspectorState(true, false, false, true);
         const environments = config.scenarios?.environments ?? {};
         const env = environments[environment];
         if (!env) {
@@ -42,20 +94,62 @@ export const scenarioRun = pikkuSessionlessFunc({
                     ? `Configured environments: ${known.join(', ')}`
                     : `Add scenarios.environments to pikku.config.json, e.g. { "${environment}": { "apiUrl": "https://app.example.com/api" } }`));
         }
-        let selected = listScenarios(state);
-        if (flows) {
-            const names = new Set(flows.split(',').map((f) => f.trim()));
-            const unknown = [...names].filter((n) => !selected.some((f) => f.name === n));
-            if (unknown.length) {
-                throw new Error(`Unknown scenario(s): ${unknown.join(', ')}. Available: ${selected.map((f) => f.name).join(', ')}`);
+        if (spawn) {
+            const { hostname, port } = new URL(env.apiUrl);
+            const resolvedPort = Number(port || 80);
+            logger.info(`Starting a server for '${environment}' on ${env.apiUrl}`);
+            const server = await spawnDevServer({
+                cwd: config.rootDir,
+                port: resolvedPort,
+                hostname,
+                coverage,
+                env: { API_URL: env.apiUrl },
+                onOutput: (text) => process.stdout.write(text),
+            });
+            // Registered rather than wrapped in a try/finally: the run below sets
+            // process.exitCode and can throw, and an exit handler covers both without
+            // the whole command body having to nest inside one block.
+            if (!keepAlive) {
+                process.once('exit', server.stop);
+                process.once('SIGINT', () => {
+                    server.stop();
+                    process.exit(1);
+                });
+                process.once('SIGTERM', () => {
+                    server.stop();
+                    process.exit(1);
+                });
             }
-            selected = selected.filter((f) => names.has(f.name));
+            await server.waitUntilReady();
         }
-        if (tags) {
-            const wanted = tags.split(',').map((t) => t.trim());
-            selected = selected.filter((f) => wanted.some((t) => f.tags.includes(t)));
+        // Features live in runtime state, not inspector meta — their scenario lists
+        // may be built by an ordinary loop — so the project has to be loaded before
+        // anything can be selected.
+        await loadScenarioBootstrap(resolve(config.rootDir, config.outDir));
+        const { features: registeredFeatures, registrations } = collectRegisteredWirings();
+        const split = (value) => value ? value.split(',').map((part) => part.trim()) : undefined;
+        let { groups, unresolved } = buildScenarioPlan({
+            scenarios: listScenarios(state).map(({ name, tags: flowTags, skip }) => ({
+                name,
+                tags: flowTags,
+                skip,
+            })),
+            features: registeredFeatures,
+            registrations,
+            flows: split(flows),
+            featureIds: split(features),
+            tags: split(tags),
+            excludeTags: split(excludeTags),
+        });
+        if (unresolved.length > 0) {
+            for (const { featureId, index } of unresolved) {
+                logger.error(`Feature '${featureId}' scenario #${index} is not a registered scenario. ` +
+                    `A feature references scenarios by imported identifier — a scenario built inline inside a feature is never registered.`);
+            }
+            process.exitCode = 1;
+            return;
         }
-        if (selected.length === 0) {
+        if (groups.length === 0) {
             logger.error('No scenarios matched.');
             process.exitCode = 1;
             return;
@@ -65,15 +159,57 @@ export const scenarioRun = pikkuSessionlessFunc({
             throw new Error('SCENARIO_ACTOR_SECRET is not set — scenario actors cannot sign in. ' +
                 'Export it in the environment running this command (never put it in pikku.config.json).');
         }
+        // Declared actors plus one per persona nobody declared a body for. Resolved
+        // once: the HTTP actors and the Playwright provider below must see the same
+        // registry, and codegen resolved the same way to type `ScenarioActorName`.
+        const scenarioActors = resolveScenarioActors(config.scenarios);
         const actors = createHttpScenarioActors({
             apiUrl: env.apiUrl,
             secret,
-            actors: config.scenarios?.actors ?? {},
+            actors: scenarioActors,
             signInPath: env.signInPath,
             rpcPath: env.rpcPath,
         });
-        await loadUserBootstrap(resolve(config.rootDir, config.outDir));
+        const functionsMeta = state.functions?.meta ?? {};
+        const scenarioNames = new Set(groups.flatMap((group) => group.entries.map((e) => e.scenarioName)));
+        const browserStepsByFlow = new Map([...scenarioNames]
+            .map((name) => [
+            name,
+            scenarioBrowserSteps(state.workflows?.meta?.[name], functionsMeta),
+        ])
+            .filter(([, steps]) => steps.length > 0));
+        // Two reasons a scenario is held back, both reported as SKIP rather than
+        // failed. `--no-browser` is the direct replacement for cucumber's `@console`
+        // tag, so a standard run stays green on a machine with no browser; a `skip`
+        // on the scenario itself is the project quarantining it, and the plan has
+        // already cleared that reason for anything named directly with `--flows`.
+        const skipReasonFor = (entry) => {
+            if (entry.skip)
+                return entry.skip;
+            if (!browser && browserStepsByFlow.has(entry.scenarioName)) {
+                return 'browser steps, --no-browser';
+            }
+            return undefined;
+        };
+        const skipped = [];
+        groups = groups
+            .map((group) => ({
+            ...group,
+            entries: group.entries.filter((entry) => {
+                const reason = skipReasonFor(entry);
+                if (!reason)
+                    return true;
+                skipped.push({ name: entry.scenarioName, reason });
+                return false;
+            }),
+        }))
+            .filter((group) => group.entries.length > 0);
         const workflowService = new InMemoryWorkflowService();
+        const scenarioService = workflowService.setRunExtension((engine) => new PikkuScenarioService(engine));
+        scenarioService.setScenarioEnvironment({
+            apiUrl: env.apiUrl,
+            appUrl: env.appUrl,
+        });
         pikkuState(null, 'package', 'singletonServices', {
             logger,
             workflowService,
@@ -86,7 +222,51 @@ export const scenarioRun = pikkuSessionlessFunc({
                     `'${environment}' (${env.apiUrl}), not local services.`);
             },
         };
+        const needsBrowser = groups.some((group) => group.entries.some((entry) => browserStepsByFlow.has(entry.scenarioName)));
+        const failureDir = join(resolve(config.rootDir, config.outDir), 'scenario-failures');
+        const browserLifecycle = scenarioBrowserLifecycle(needsBrowser
+            ? await (async () => {
+                const provider = await resolveScenarioBrowserProvider({
+                    environment,
+                    apiUrl: env.apiUrl,
+                    appUrl: env.appUrl,
+                    secret,
+                    actors: scenarioActors,
+                    signInPath: env.signInPath,
+                    failureDir,
+                    browserScenarios: [...browserStepsByFlow.keys()],
+                    driver: config.scenarios?.browserDriver,
+                });
+                scenarioService.setScenarioBrowserProvider(provider);
+                return provider;
+            })()
+            : undefined);
         const results = [];
+        /**
+         * The step ladder is read back off the recorded run, so it needs no live
+         * step events — it is the same data the console renders. Joining it to the
+         * declared prose happens here, where the inspector state is; laying it out
+         * is the formatter's job.
+         */
+        const readRunSteps = async (service, runId, flowName) => {
+            const prose = collectScenarioStepProse(state.workflows?.meta?.[flowName], functionsMeta);
+            const steps = (await service.getRunSteps(runId)).map((step) => ({
+                stepName: step.stepName,
+                status: step.status,
+                durationMs: step.succeededAt
+                    ? step.succeededAt.getTime() - step.createdAt.getTime()
+                    : undefined,
+                error: step.error?.message,
+                stack: step.error?.stack,
+                expected: step.error?.expected,
+                input: step.data,
+                stepFunc: step.rpcName,
+            }));
+            return {
+                rows: scenarioStepRows(steps, prose),
+                failure: scenarioFailureFromSteps(steps, prose),
+            };
+        };
         const coverageActor = coverage ? Object.values(actors)[0] : undefined;
         let coverageActive = Boolean(coverageActor);
         if (coverage && !coverageActor) {
@@ -106,8 +286,22 @@ export const scenarioRun = pikkuSessionlessFunc({
                 return null;
             }
         };
-        for (const flow of selected) {
+        /**
+         * A feature hook is not a pikku function and not a run — the feature is a
+         * grouping, not something durable. It gets the same three arguments a
+         * scenario body gets, the CLI's own singletons included, and its result is
+         * discarded.
+         */
+        const singletonServices = pikkuState(null, 'package', 'singletonServices');
+        const runFeatureHook = async (hook) => {
+            await hook(singletonServices, undefined, { actors });
+        };
+        const hookFailures = [];
+        const runEntry = async (label, scenarioName, data) => {
             const startedAt = Date.now();
+            // Before the scenario, not after it: the last scenario's window is left
+            // open for headed debugging, while this one still starts clean.
+            await browserLifecycle.reset();
             if (coverageActive) {
                 const reset = await invokeCoverage('pikkuScenarioResetLiveCoverage');
                 if (reset && reset.enabled === false) {
@@ -119,20 +313,27 @@ export const scenarioRun = pikkuSessionlessFunc({
                 await coverageActor?.invoke('pikkuScenarioResetStubs', null);
             }
             catch { }
+            let runId;
+            let runError;
             try {
-                const { runId } = await workflowService.startWorkflow(flow.name, undefined, { type: 'cli' }, guardRpc, { actors });
+                // The id comes back through the callback rather than the return value
+                // because a failing scenario throws instead of returning — and a failed
+                // run is exactly the one whose steps are worth reading.
+                ;
+                ({ runId } = await workflowService.startWorkflow(scenarioName, data, { type: 'cli' }, guardRpc, { actors, onRunCreated: (id) => (runId = id) }));
                 const run = await workflowService.getRun(runId);
                 if (run?.status === 'completed') {
                     results.push({
-                        name: flow.name,
+                        name: label,
                         status: 'passed',
                         durationMs: Date.now() - startedAt,
                         output: run.output,
                     });
                 }
                 else {
+                    runError = run?.error;
                     results.push({
-                        name: flow.name,
+                        name: label,
                         status: 'failed',
                         durationMs: Date.now() - startedAt,
                         error: run?.error?.message ?? `status: ${run?.status}`,
@@ -140,22 +341,90 @@ export const scenarioRun = pikkuSessionlessFunc({
                 }
             }
             catch (e) {
+                runError = { stack: e?.stack };
                 results.push({
-                    name: flow.name,
+                    name: label,
                     status: 'failed',
                     durationMs: Date.now() - startedAt,
                     error: e?.message ?? String(e),
                 });
             }
+            const result = results[results.length - 1];
+            let stepFailure;
+            if (runId) {
+                const read = await readRunSteps(workflowService, runId, scenarioName);
+                result.steps = read.rows;
+                stepFailure = read.failure;
+            }
+            if (result.status === 'failed') {
+                result.failure = {
+                    // A scenario can also fail outside any step — a hook, or the start
+                    // itself — and then the run's own error is all there is to report.
+                    ...(stepFailure ?? {
+                        message: result.error ?? 'unknown failure',
+                        stack: runError?.stack,
+                        expected: runError?.expected,
+                    }),
+                    browser: await browserLifecycle.captureFailure(label),
+                };
+            }
             if (coverageActive) {
                 const report = await invokeCoverage('pikkuScenarioTakeLiveCoverage');
                 if (report) {
-                    scenarioCoverage[flow.name] = report;
+                    scenarioCoverage[label] = report;
                     const covered = report.functions?.filter((f) => f.status === 'covered' || f.status === 'partial');
-                    logger.info(`  coverage: ${covered?.length ?? 0}/${report.summary?.total ?? 0} functions exercised by '${flow.name}'`);
+                    logger.info(`  coverage: ${covered?.length ?? 0}/${report.summary?.total ?? 0} functions exercised by '${label}'`);
+                }
+            }
+        };
+        for (const group of groups) {
+            const groupName = group.featureName ?? group.featureId;
+            const label = (entry) => {
+                const data = entry.data ? ` ${JSON.stringify(entry.data)}` : '';
+                return groupName
+                    ? `${groupName} › ${entry.scenarioName}${data}`
+                    : entry.scenarioName;
+            };
+            let beforeError;
+            if (group.before) {
+                try {
+                    await runFeatureHook(group.before);
+                }
+                catch (e) {
+                    beforeError = e;
+                }
+            }
+            try {
+                if (beforeError) {
+                    // Setup failed, so nothing in the group ran. Reporting them as failed
+                    // rather than skipped is the honest reading: they did not pass.
+                    for (const entry of group.entries) {
+                        results.push({
+                            name: label(entry),
+                            status: 'failed',
+                            durationMs: 0,
+                            error: `feature '${groupName}' before hook failed: ${beforeError?.message ?? beforeError}`,
+                        });
+                    }
+                }
+                else {
+                    for (const entry of group.entries) {
+                        await runEntry(label(entry), entry.scenarioName, entry.data);
+                    }
+                }
+            }
+            finally {
+                if (group.after) {
+                    try {
+                        await runFeatureHook(group.after);
+                    }
+                    catch (e) {
+                        hookFailures.push(`feature '${groupName}' after hook failed: ${e?.message ?? e}`);
+                    }
                 }
             }
         }
+        await browserLifecycle.close();
         if (coverage && Object.keys(scenarioCoverage).length > 0) {
             const coverageDir = join(resolve(config.rootDir, config.outDir), 'coverage');
             mkdirSync(coverageDir, { recursive: true });
@@ -167,17 +436,15 @@ export const scenarioRun = pikkuSessionlessFunc({
             }, null, 2) + '\n');
             logger.info(`Scenario coverage → ${outFile}`);
         }
-        const failed = results.filter((r) => r.status === 'failed');
-        for (const r of results) {
-            if (r.status === 'passed') {
-                logger.info(`PASS ${r.name} (${r.durationMs}ms)${r.output !== undefined ? ` → ${JSON.stringify(r.output)}` : ''}`);
-            }
-            else {
-                logger.error(`FAIL ${r.name} (${r.durationMs}ms): ${r.error}`);
-            }
+        const report = { environment, results, skipped, hookFailures };
+        for (const { level, text } of formatScenarioReport(report, {
+            trace,
+            projectRoot: config.rootDir,
+        })) {
+            logger[level](text);
         }
-        logger.info(`${results.length - failed.length}/${results.length} scenarios passed against '${environment}'`);
-        if (failed.length > 0) {
+        const failed = results.filter((r) => r.status === 'failed');
+        if (failed.length > 0 || hookFailures.length > 0) {
             process.exitCode = 1;
         }
     },