@feasibleone/blong-gogo 1.35.0 → 1.37.0

package/src/browserEagerImports.test.ts

@@ -0,0 +1,62 @@
+import {readFileSync, readdirSync} from 'node:fs';
+import {dirname, join} from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {test} from 'tap';
+
+// ---------------------------------------------------------------------------
+// Node-only modules must not be imported for a value.
+//
+// A browser build stubs what it cannot resolve and carries on, so an eager import of a
+// node-only module survives CI and only shows up in a teardown-free dev server: vite
+// links the module graph before any code runs and refuses a *named* import from its
+// browser-external stub, which takes the whole page down ("The requested module
+// '/@id/__vite-browser-external:node:events' does not provide an export named
+// 'EventEmitter'"). The browser entry reaches `Watch.ts` through a dynamic import the
+// loader executes at startup, so a static import inside it is as eager as one made by
+// the entry itself — this scans the sources rather than a bundle because a dynamic edge
+// hides the module from a bundler's static view.
+// ---------------------------------------------------------------------------
+
+const srcDir = dirname(fileURLToPath(import.meta.url));
+
+interface INodeOnlyModule {
+    /** Import specifier as written in the sources. */
+    specifier: string;
+    /** What makes it unusable in a browser. */
+    reason: string;
+}
+
+const NODE_ONLY: INodeOnlyModule[] = [
+    {
+        specifier: './chain.ts',
+        reason: 'it needs node:assert, node:test and the event emitter its executor extends',
+    },
+];
+
+/** `import x from '...'`, `export {x} from '...'` and side-effect imports, but not `import type`. */
+const eagerImport = (specifier: string) =>
+    new RegExp(
+        `^\\s*(?:import|export)\\s+(?!type\\s)[^;]*?from\\s*['"]${specifier}['"]|^\\s*import\\s*['"]${specifier}['"]`,
+        'gm',
+    );
+
+test('a node-only module is never imported for a value', async t => {
+    const files = readdirSync(srcDir).filter(
+        name => name.endsWith('.ts') && !name.endsWith('.test.ts'),
+    );
+    t.ok(files.length > 0, 'the sources were found');
+
+    for (const {specifier, reason} of NODE_ONLY) {
+        const pattern = eagerImport(specifier);
+        const offenders = files.flatMap(name =>
+            [...readFileSync(join(srcDir, name), 'utf8').matchAll(pattern)].map(
+                match => `${name}: ${match[0].trim()}`,
+            ),
+        );
+        t.same(
+            offenders,
+            [],
+            `${specifier} is imported eagerly (${reason}); import it dynamically, or for its types only:\n      ${offenders.join('\n      ')}`,
+        );
+    }
+});

package/src/chain.allure.test.ts

@@ -0,0 +1,216 @@
+/**
+ * What the chain runner does with Allure reporting when it cannot have it.
+ *
+ * Allure 3's format is a directory of files, so the integration needs a filesystem.
+ * A browser platform has none, and the lazy import of `blong-allure` there can only
+ * fail — which the runner used to discover once per group, leaving a run with no
+ * results and no explanation of why. These tests pin the two halves of the fix: the
+ * platform decides *before* the attempt, and the reason is reported once for the run
+ * rather than once per group.
+ *
+ * Each test imports the module fresh: the session, the run's options and the reason
+ * it cannot report are module-level state, and a test that inherited them from the
+ * one before it would be asserting the previous test's outcome.
+ */
+
+import {existsSync} from 'node:fs';
+import {mkdtemp, readdir, readFile, rm} from 'node:fs/promises';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+import {test} from 'tap';
+
+/** A test context that runs what it is given, the way the runner's own does. */
+interface IContext {
+    test: (name: string, fn: (t: IContext) => unknown) => Promise<unknown>;
+}
+
+function contextAt(): IContext {
+    return {
+        test: async (_name: string, fn: (t: IContext) => unknown) => fn(contextAt()),
+    };
+}
+
+/** A group's steps, named the way the runner names them from the wire name. */
+function group(name: string, steps: Array<() => unknown>): Array<() => unknown> {
+    const wrapped = [...steps];
+    Object.defineProperty(wrapped, 'name', {value: name});
+    return wrapped;
+}
+
+/** The log the runner is handed, recording what a run would have shown a reader. */
+function recordingLog(): {
+    warnings: string[];
+    errors: unknown[];
+    log: {warn: (text: unknown) => void; error: (error: unknown) => void};
+} {
+    const warnings: string[] = [];
+    const errors: unknown[] = [];
+    return {
+        warnings,
+        errors,
+        log: {
+            warn: (text: unknown) => void warnings.push(String(text)),
+            error: (error: unknown) => void errors.push(error),
+        },
+    };
+}
+
+test('a browser run is told why it produces no report, once for the run', async t => {
+    const dir = await mkdtemp(join(tmpdir(), 'blong-chain-allure-'));
+    t.teardown(() => rm(dir, {recursive: true, force: true}));
+    const outputDir = join(dir, 'allure-results');
+    const {warnings, errors, log} = recordingLog();
+    const ran: string[] = [];
+    const {default: chainFactory} = await t.mockImport<typeof import('./chain.ts')>(
+        './chain.ts',
+        {},
+    );
+
+    const chain = await chainFactory(contextAt() as never, log, {
+        method: 'test.order.checkpoint',
+        allure: {enabled: true, outputDir},
+        platform: 'browser',
+    });
+    const run = chain as unknown as (steps: unknown) => Promise<unknown>;
+    await run(
+        group('order checkpoint', [
+            async function loadsOrder() {
+                ran.push('loadsOrder');
+                return 'loaded';
+            },
+        ]),
+    );
+    // A second group, whose own attempt would be a second opportunity to say the
+    // same thing: the answer belongs to the run, so it is said once.
+    await run(
+        group('payment settle', [
+            async function sendsPayment() {
+                ran.push('sendsPayment');
+                return 'sent';
+            },
+        ]),
+    );
+
+    t.same(
+        ran,
+        ['loadsOrder', 'sendsPayment'],
+        'the groups ran: a withheld report is not a withheld test',
+    );
+    t.equal(warnings.length, 1, 'the reader is told once, not once per group');
+    t.match(warnings[0] ?? '', /browser platform cannot write its files/, 'and told the reason');
+    t.match(warnings[0] ?? '', /Allure reporting is enabled/, 'as a configuration mistake');
+    t.same(errors, [], 'nothing failed: the tests are judged on their tests');
+    t.notOk(existsSync(outputDir), 'and no results directory was created');
+
+    // The end of the run closes nothing, because nothing opened: no session means no
+    // import, which on this platform is the one thing that cannot work.
+    await (await import('./chain.ts')).endAllureSession();
+});
+
+test('a server run opens the session and writes the group result', async t => {
+    const dir = await mkdtemp(join(tmpdir(), 'blong-chain-allure-'));
+    t.teardown(() => rm(dir, {recursive: true, force: true}));
+    const outputDir = join(dir, 'allure-results');
+    const {warnings, errors, log} = recordingLog();
+    const {default: chainFactory, endAllureSession} = await t.mockImport<
+        typeof import('./chain.ts')
+    >('./chain.ts', {});
+
+    const chain = await chainFactory(contextAt() as never, log, {
+        method: 'test.order.checkpoint',
+        allure: {enabled: true, outputDir},
+        platform: 'server',
+    });
+    await (chain as unknown as (steps: unknown) => Promise<unknown>)(
+        group('order checkpoint', [
+            async function loadsOrder() {
+                return 'loaded';
+            },
+        ]),
+    );
+
+    t.same(warnings, [], 'a server platform reports nothing and says nothing');
+    t.same(errors, []);
+    const written = await readdir(outputDir);
+    t.ok(
+        written.includes('environment.properties'),
+        'the session laid out its directory, as it does for a real run',
+    );
+    const resultFile = written.find(name => name.endsWith('-result.json'));
+    t.ok(resultFile, 'and the group left a result');
+    const result = JSON.parse(await readFile(join(outputDir, resultFile as string), 'utf8')) as {
+        name?: string;
+        labels?: Array<{name: string; value: string}>;
+    };
+    t.equal(result.name, 'order checkpoint', 'named as the group was run');
+    t.ok(
+        result.labels?.some(label => label.name === 'parentSuite' && label.value === 'test'),
+        'labelled from the group wire name',
+    );
+
+    // The end writes to stdout, which a tap run parses: its line is captured here
+    // rather than left in the middle of the suite's output.
+    const lines: string[] = [];
+    const original = console.log;
+    console.log = (...args: unknown[]) => void lines.push(args.join(' '));
+    try {
+        await endAllureSession();
+    } finally {
+        console.log = original;
+    }
+    t.match(
+        lines.join(''),
+        /Allure results written to/,
+        'the run ends by saying where the results are',
+    );
+
+    // Nothing is left to close: the second end is a no-op rather than a second report.
+    await endAllureSession();
+});
+
+test('a failure to start is reported once, and leaves nothing to close', async t => {
+    const dir = await mkdtemp(join(tmpdir(), 'blong-chain-allure-'));
+    t.teardown(() => rm(dir, {recursive: true, force: true}));
+    const {warnings, errors, log} = recordingLog();
+    let started = 0;
+    let ended = 0;
+    const {default: chainFactory, endAllureSession} = await t.mockImport<
+        typeof import('./chain.ts')
+    >('./chain.ts', {
+        // A server platform that cannot import the integration at all — a package
+        // missing on the runner, say. The runner cannot prevent this one; it can only
+        // say it once and carry on.
+        '@feasibleone/blong-allure': {
+            allureSessionStart: async () => {
+                started += 1;
+                throw new Error('blong-allure is not installed');
+            },
+            allureSessionEnd: async () => {
+                ended += 1;
+            },
+            allureGroupResultWrite: async () => undefined,
+        },
+    });
+
+    const chain = await chainFactory(contextAt() as never, log, {
+        method: 'test.order.checkpoint',
+        allure: {enabled: true, outputDir: join(dir, 'allure-results')},
+        platform: 'server',
+    });
+    const run = chain as unknown as (steps: unknown) => Promise<unknown>;
+    const step = async function loadsOrder() {
+        return 'loaded';
+    };
+    await run(group('order checkpoint', [step]));
+    await run(group('payment settle', [step]));
+
+    t.equal(started, 1, 'one attempt, however many groups ask for a report');
+    t.equal(errors.length, 1, 'and one report of it, not one per group');
+    t.match(String(errors[0]), /blong-allure is not installed/, 'naming what went wrong');
+    t.same(warnings, [], 'an unexpected failure is not a platform refusal');
+
+    // A session that never opened is nothing to close: the end is a no-op, so a run
+    // that could not write results does not also try to generate a report from them.
+    await endAllureSession();
+    t.equal(ended, 0, 'the end of the run closes nothing');
+});

package/src/chain.ts

@@ -1,5 +1,6 @@
-import {TestExecutor, type ITestLogger} from '@feasibleone/blong-chain';
+import {TestExecutor, type IStepProgress, type ITestLogger} from '@feasibleone/blong-chain';
 import {withProgress} from '@feasibleone/blong-lib';
+import type {IPlatformApi} from '@feasibleone/blong/types';
 import assert from 'node:assert';
 
 type Step = (a: typeof assert, results: object) => object | Promise<object>;
@@ -12,10 +13,227 @@ interface ITestContext {
     test: (name: string, fn: (t: unknown) => void | Promise<void>) => unknown;
 }
 
+/** Allure reporting options, as the framework config supplies them. */
+export interface IAllureRunOptions {
+    /** Write results at all. Off by default, on for a captured (CI) run. */
+    enabled?: boolean;
+    /** Results directory (default `allure-results`). */
+    outputDir?: string;
+    /** Trend history file (default `.allure/history.jsonl`). */
+    historyPath?: string;
+    /** Generate the HTML report when the session ends. */
+    generateOnEnd?: boolean;
+    /** Pattern with `{traceId}`, used to link a result to its log trace. */
+    logUrl?: string;
+}
+
+export interface IChainOptions {
+    /** The group's wire name, e.g. `test.order.checkpoint` — what Allure labels come from. */
+    method?: string;
+    allure?: IAllureRunOptions;
+    /**
+     * The platform this run belongs to, as `IPlatformApi` names it.
+     *
+     * Allure 3's format is a directory of files, so producing one needs a
+     * filesystem — and the browser platform has none. The platform is therefore what
+     * decides whether the attempt is made at all (see `canWriteReport`). A caller
+     * that names no platform is read as the server, which is what a direct chain run
+     * in Node is: refusing to report there would be worse than trying.
+     */
+    platform?: IPlatformApi['platform'];
+}
+
+/**
+ * `@feasibleone/blong-allure`, assembled rather than written out.
+ *
+ * A specifier written as a literal is *resolved* by the bundler even when the import
+ * is dynamic, so the whole integration was landing in every browser build: its modules
+ * import `node:fs`, `node:fs/promises`, `node:crypto`, `node:url` and
+ * `node:child_process`, none of which a browser can provide, and
+ * `browserBundle.test.ts` failed on exactly that list. Building the string at runtime
+ * leaves the specifier opaque to the bundler, which is the same trick `load.ts` uses
+ * (`extension` there) to keep the server half of the platform map out of a browser
+ * build — and it costs nothing on the server, where Node resolves the specifier when
+ * it is imported.
+ *
+ * The import is never *made* on a browser either: `canWriteReport` refuses the
+ * platform before it, because a browser has nowhere to write a report.
+ */
+const allurePackage = (): string => ['@feasibleone', 'blong-allure'].join('/');
+
+/**
+ * The one Allure session of this process, started by the first group that runs.
+ *
+ * A session clears its results directory, so it cannot be per group: the first
+ * group would wipe the results of the ones before it. It is started lazily
+ * instead, and ended by {@link endAllureSession} once every group has finished.
+ */
+let session: Promise<void> | undefined;
+
+/** The options the running session was started with, for its end. */
+let sessionOptions: IAllureRunOptions | undefined;
+
+/**
+ * Why this process will produce no Allure report, once that is known.
+ *
+ * Held for the run rather than per group, because the answer is the run's: a
+ * second group that says the same thing again adds noise to a run that has already
+ * explained why the report it asked for will not exist. `session` is never set
+ * while this is, so a blocked run also does not try to close a session later.
+ */
+let blocked: string | undefined;
+
+/**
+ * Whether this platform can write Allure's files at all.
+ *
+ * The browser platform is the one that cannot: it has no `node:fs`, so the lazy
+ * import of `blong-allure` there can only fail — and a failure caught per group is
+ * a failure reported per group over a run whose tests were fine. Its tests report
+ * through their own producer (Allure's Playwright integration), so the results this
+ * guard withholds are ones that were never going to exist on that platform.
+ *
+ * The allowed kinds are listed rather than the refused one, so a platform added
+ * later has to be considered here instead of inheriting a report nobody can write.
+ */
+function canWriteReport(platform: IChainOptions['platform']): boolean {
+    return platform === undefined || platform === 'server';
+}
+
+/** The results directory and history file, defaulted the way Allure documents them. */
+function sessionConfig(options: IAllureRunOptions): {
+    outputDir: string;
+    historyPath: string;
+    logUrl?: string;
+} {
+    return {
+        outputDir: options.outputDir ?? 'allure-results',
+        historyPath: options.historyPath ?? '.allure/history.jsonl',
+        logUrl: options.logUrl,
+    };
+}
+
+/**
+ * Start the Allure session if this run wants one, once.
+ *
+ * `blong-allure` is imported here rather than at the top of the file, for the
+ * reason the log implementation is chosen lazily: a run that does not report to
+ * Allure should not load it.
+ *
+ * The platform is checked *before* the attempt, and the reason it cannot report is
+ * said out loud — as a configuration mistake rather than an error in a test, so the
+ * absence of a report is explained rather than discovered.
+ *
+ * An unexpected failure (a package that cannot be imported on a platform that
+ * should be able to write results) is reported on the same terms, and the session
+ * is dropped rather than left rejected: there is nothing for the end of the run to
+ * close, and a later group must not await a promise that has already failed.
+ *
+ * This never throws. A report that cannot be written is not a test that failed —
+ * the run is judged on its tests — and a caller that had to guard the call would be
+ * one place too many for that decision to live.
+ */
+async function ensureSession(
+    options: IAllureRunOptions | undefined,
+    platform: IChainOptions['platform'],
+    log?: ITestLogger,
+): Promise<boolean> {
+    if (options?.enabled !== true || blocked !== undefined) return false;
+    if (!canWriteReport(platform)) {
+        blocked =
+            `Allure reporting is enabled for this run but the ${platform} platform cannot write its ` +
+            'files, so a report will not be produced';
+        log?.warn?.(blocked);
+        return false;
+    }
+    if (session === undefined) {
+        sessionOptions = options;
+        session = (async () => {
+            const {allureSessionStart} = await import(/* @vite-ignore */ allurePackage());
+            await allureSessionStart(sessionConfig(options));
+        })();
+    }
+    try {
+        await session;
+        return true;
+    } catch (error) {
+        // The first group to lose the session reports it; a group that was awaiting
+        // the same start loses it too and stays quiet, because the reason is the
+        // run's rather than its own.
+        session = undefined;
+        sessionOptions = undefined;
+        if (blocked === undefined) {
+            blocked = `Allure reporting failed: ${String(error)}`;
+            log?.error?.(error);
+        }
+        return false;
+    }
+}
+
+/**
+ * The Allure context for a group's wire name.
+ *
+ * `test.order.checkpoint` reads as realm `test`, collection `order`, group
+ * `checkpoint`. A name that does not split stays the realm, so a suite with its
+ * own naming still gets a label rather than a result filed under nothing.
+ */
+function contextOf(method: string | undefined, options: IAllureRunOptions) {
+    const [realm, collection, ...rest] = (method ?? '').split('.').filter(Boolean);
+    return {
+        realm,
+        collection,
+        group: rest.length > 0 ? rest.join('.') : undefined,
+        logUrl: options.logUrl,
+    };
+}
+
+/** The steps an executor recorded, in the order they completed. */
+function stepsOf(executor: TestExecutor): IStepProgress[] {
+    return Array.from(executor.getProgress().steps.values());
+}
+
+/** Write one group result, standing in for a step list its executor may not have. */
+async function writeGroupResult(
+    options: IAllureRunOptions,
+    name: string,
+    executor: TestExecutor,
+    method?: string,
+): Promise<void> {
+    const steps = stepsOf(executor);
+    if (steps.length === 0) return;
+    const {allureGroupResultWrite} = await import(/* @vite-ignore */ allurePackage());
+    await allureGroupResultWrite(
+        sessionConfig(options).outputDir,
+        {name, steps},
+        contextOf(method, options),
+    );
+}
+
+/**
+ * End the Allure session, if one was started, and optionally generate its report.
+ *
+ * Called by the runner once every group has finished, because the results
+ * directory belongs to the run rather than to any one group.
+ */
+export async function endAllureSession(): Promise<void> {
+    if (session === undefined) return;
+    const options = sessionOptions ?? {};
+    const closing = session;
+    session = undefined;
+    sessionOptions = undefined;
+    // Waiting on the start first: the end must not run the CLI over a results
+    // directory while the thing that lays it out is still opening it. A start that
+    // failed has already cleared `session` (see `ensureSession`), so this awaits one
+    // that opened, or that is opening.
+    await closing;
+    const {allureSessionEnd} = await import(/* @vite-ignore */ allurePackage());
+    await allureSessionEnd({...sessionConfig(options), generateOnEnd: options.generateOnEnd});
+}
+
 const runSteps =
     (
         steps: Steps,
         log?: ITestLogger,
+        options: IChainOptions = {},
         results = {$meta: {}},
     ): ((t: ITestContext) => Promise<void>) =>
     async (t: ITestContext) => {
@@ -33,6 +251,11 @@ const runSteps =
             resolvedSteps.push(await stepPromise);
         }
 
+        // Reporting is a run-level concern, and this call never throws: a report that
+        // cannot be written says so once and the run carries on being judged on its
+        // tests (see `ensureSession`).
+        const reporting = await ensureSession(options.allure, options.platform, log);
+
         // Execute with parallel executor, passing test context for nested output
         try {
             await withProgress(
@@ -57,6 +280,15 @@ const runSteps =
         } catch (error) {
             // Preserve error with context
             throw error;
+        } finally {
+            // The group is the test case: one result per group, written whether the
+            // group passed or not — a scenario that failed is the one a reader opens
+            // the report for. The group's own name is what it was run as.
+            if (reporting && options.allure) {
+                await writeGroupResult(options.allure, steps.name, executor, options.method).catch(
+                    error => log?.error?.(error),
+                );
+            }
         }
     };
 
@@ -92,8 +324,12 @@ const runSteps =
 export default async (
     test: ITestContext,
     log?: ITestLogger,
+    options: IChainOptions = {},
 ): Promise<(steps: Steps) => unknown> => {
     const context = test || (await import('node:test')).default;
     return steps =>
-        context.test(steps.name, runSteps(steps, log) as (t: unknown) => void | Promise<void>);
+        context.test(
+            steps.name,
+            runSteps(steps, log, options) as (t: unknown) => void | Promise<void>,
+        );
 };