All files / core/blong-gogo/src chain.ts

99.27% Statements 408/411
83.63% Branches 46/55
100% Functions 12/12
99.27% Lines 408/411

Press n or j to go to the next uncovered block, b, p or k for the previous block.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 4121x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 66x 66x 66x 1x 1x 112x 112x 112x 112x 112x 112x 112x 112x 112x 112x 112x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 68x 68x 68x 68x 68x 68x 67x 1x 1x 1x 1x 1x 1x 65x 25x 25x 25x 25x 24x 25x 65x 65x 64x 66x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 68x 1x 1x 1x 1x 1x 1x 1x 1x 64x 64x 64x 64x 64x 64x 64x 64x 64x 1x 1x 64x 64x 64x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 64x 64x 64x 1x 1x 1x   1x 1x 64x 64x 64x 64x 1x 1x 64x 64x 64x 64x 64x 64x 64x 64x 64x 64x 64x 64x 64x 64x 64x 64x 64x 64x 64x 64x 64x 64x 1x 1x 1x 1x 1x 1x 64x 64x 64x 64x 64x 1x 1x 1x 1x 1x 1x 1x 1x 26x 26x 26x 26x 26x 26x 26x 26x 26x 26x 23x 23x 23x 1x 1x 1x 68x 68x 68x 68x 68x 68x 68x 68x 68x 68x 68x 68x 68x 68x 68x 68x 68x 343x 343x 68x 68x 68x 68x 68x 68x 68x 68x 68x 68x 68x 68x 68x 68x 68x 68x 68x 68x 68x 11x 11x 11x 68x 68x 68x 68x 68x 68x 368x 273x 273x 368x 68x     68x 68x 68x 68x 68x 68x 68x 64x 64x 64x 64x 64x 64x 64x 64x 68x 68x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 66x 66x 66x 66x 66x 66x 68x 68x 68x 66x 66x  
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>;
type Steps = (Promise<(Step | Step[]) & {name: string}>[] | Step[]) & {
    name: string;
    autoSnapshot?: boolean;
    mask?: string[];
};
interface ITestContext {
    test: (name: string, fn: (t: unknown) => void | Promise<void>) => unknown;
    /**
     * tap's verdict on the test this context is: `false` once it has seen a failure.
     *
     * A method since tap 21 and a plain property before it, so both are read, and a
     * context that carries neither — a chain run driven by something other than tap —
     * offers no verdict rather than a passing one.
     */
    passing?: boolean | (() => boolean);
    /** Set by tap when this very test hit its timeout. */
    timedOut?: boolean;
}
 
/** 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());
}
 
/**
 * The verdict a group gets when its own steps do not tell the story.
 *
 * `broken` rather than `failed`, which is the status Allure keeps for a test that
 * could not finish: the group did not fail an assertion, it was cut off.
 */
interface IGroupVerdict {
    status: 'broken';
    message: string;
    /** The group's own span: a step that hung has no end time to read one from. */
    start: number;
    stop: number;
}
 
/**
 * What tap says about the group, when its steps say something else.
 *
 * A step that hangs is a step that records nothing, so the executor reports a group
 * whose every recorded step passed — while the test around it failed, and the run's own
 * summary counts that failure. tap sets it on the test this run was handed (`timeout!`
 * for a timeout), and that verdict is the only place it exists: `undefined` for every
 * other group leaves the steps as the sole authority for one that ended the ordinary way.
 */
function verdictOf(t: ITestContext, startedAt: number): IGroupVerdict | undefined {
    const passing = typeof t.passing === 'function' ? t.passing() : t.passing;
    if (passing !== false) return undefined;
    return {
        status: 'broken',
        message: t.timedOut
            ? 'timeout! — the group did not finish within its time budget'
            : 'the group did not pass although no step it recorded failed: a timeout ' +
              'reports that way, because the step it cut off recorded nothing',
        start: startedAt,
        stop: Date.now(),
    };
}
 
/** 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,
    verdict?: IGroupVerdict,
): Promise<void> {
    const steps = stepsOf(executor);
    // A step that failed speaks for the group: the report then points at that step and
    // its error, rather than at a verdict the runner would be adding on top of it.
    const final = steps.some(step => step.status === 'failed') ? undefined : verdict;
    // A group that recorded nothing is not a scenario a reader can read — unless it did
    // not finish, which is exactly the case a report must not leave out: the run before
    // the fix printed `passed` for a group the summary listed as failed.
    if (steps.length === 0 && !final) return;
    const {allureGroupResultWrite} = await import(/* @vite-ignore */ allurePackage());
    await allureGroupResultWrite(
        sessionConfig(options).outputDir,
        {
            name,
            steps,
            ...(final
                ? {
                      status: final.status,
                      statusDetails: {message: final.message},
                      start: final.start,
                      stop: final.stop,
                  }
                : {}),
        },
        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) => {
        // Use new parallel TestExecutor for improved performance
        const executor = new TestExecutor({
            concurrency: 10,
            log,
            autoSnapshot: (steps as Steps).autoSnapshot,
            mask: (steps as Steps).mask,
        });
 
        // Resolve any promises in steps array
        const resolvedSteps: (Step | Step[])[] = [];
        for (const stepPromise of steps) {
            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);
 
        // The group's own start, for a verdict that has to be written without the steps'
        // help: a hung step has no end time to read a span from, and that span is what
        // tells a reader how long the group was in flight before it was cut off.
        const startedAt = Date.now();
 
        // Execute with parallel executor, passing test context for nested output
        try {
            await withProgress(
                log,
                `run ${steps.name}`,
                executor.execute(resolvedSteps, results.$meta || {}, t),
                {
                    getProgress: () => {
                        const progress = executor.getProgress();
                        return {done: progress.completedSteps, total: progress.totalSteps};
                    },
                },
            );
 
            // Copy results from executor context to results object
            const progress = executor.getProgress();
            for (const [name, stepProgress] of progress.steps) {
                if (stepProgress.result !== undefined) {
                    (results as Record<string, unknown>)[name] = stepProgress.result;
                }
            }
        } 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, and its
            // verdict is the steps' unless tap watched the test fail while the steps
            // recorded nothing (see `verdictOf`).
            if (reporting && options.allure) {
                await writeGroupResult(
                    options.allure,
                    steps.name,
                    executor,
                    options.method,
                    verdictOf(t, startedAt),
                ).catch(error => log?.error?.(error));
            }
        }
    };
 
// const runStepsSerial =
//     (
//         steps: Steps,
//         results = {$meta: {}} as Record<string, unknown>,
//     ): ((t: ITestContext) => Promise<void>) =>
//     async (t: ITestContext) => {
//         for (const [index, stepPromise] of steps.entries()) {
//             const step = await stepPromise;
//             if (Array.isArray(step))
//                 t.test(
//                     step.name || `step ${index + 1}`,
//                     runStepsSerial(step, results) as (t: unknown) => void | Promise<void>,
//                 );
//             else if (typeof step === 'function') {
//                 const name = step.name;
//                 if (name) {
//                     await t.test(name, async () => {
//                         const result = await step(assert, results);
//                         if (results) (results as Record<string, unknown>)[name] = result;
//                     });
//                 } else {
//                     await t.test(`step ${index + 1}`, async () => {
//                         await step(assert, results);
//                     });
//                 }
//             }
//         }
//     };
 
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, options) as (t: unknown) => void | Promise<void>,
        );
};