@itmetsam/samurai-framework 0.21.4 → 0.21.5

package/dist/runner/fixture-scope.js

@@ -0,0 +1,156 @@
+import { requestedBy } from "./fixture-args.js";
+import { BUILT_IN_FIXTURES, dependencyOf, } from "./fixture-defs.js";
+/** A custom fixture whose setup threw or never called `use` */
+export class FixtureSetupError extends Error {
+    constructor(name, cause) {
+        super(`fixture "${name}" setup failed: ${messageOf(cause)}`);
+        this.name = "FixtureSetupError";
+        if (cause instanceof Error && cause.stack)
+            this.stack = cause.stack;
+    }
+}
+const messageOf = (err) => err instanceof Error ? err.message : String(err);
+/** Runs `setup` until it calls `use`; resolves with the value and the means to finish it */
+function startSetup(def, args) {
+    return new Promise((resolve, reject) => {
+        let release = () => { };
+        const released = new Promise((r) => (release = r));
+        let used = false;
+        let running;
+        const done = () => running ?? Promise.resolve();
+        const use = async (value) => {
+            if (used)
+                throw new Error("use() was called twice");
+            used = true;
+            resolve({ value, release, done });
+            await released;
+        };
+        running = (async () => def.setup?.(args, use))();
+        running.then(() => {
+            if (!used)
+                reject(new Error("the setup never called use()"));
+        }, (err) => {
+            if (!used)
+                reject(err);
+        });
+        // A failure after use() is read by teardown; this keeps it from being reported as unhandled meanwhile
+        running.catch(() => { });
+    });
+}
+/**
+ * The custom fixtures of one test run. Fixtures are set up when a test or hook asks for them (by destructuring
+ * them), their dependencies first, and torn down in the opposite order. The hooks and the body of a test share
+ * one scope, so they see the same instances.
+ */
+export class FixtureScope {
+    constructor(layers, base) {
+        this.layers = layers;
+        this.base = base;
+        this.values = new Map();
+        this.pending = new Map();
+        this.started = [];
+        this.closed = false;
+        const own = Object.getOwnPropertyDescriptors(base);
+        for (const descriptor of Object.values(own))
+            descriptor.configurable = true;
+        this.fixtures = Object.defineProperties({}, own);
+    }
+    /** Sets up the fixtures marked `auto` */
+    async prepareAuto() {
+        for (const [name, defs] of this.layers)
+            if (defs[defs.length - 1]?.auto)
+                await this.ensure(name, defs.length - 1);
+    }
+    /** Sets up the custom fixtures `fn` destructures from its first parameter */
+    async prepare(fn) {
+        const requested = requestedBy(fn);
+        if (requested.kind === "opaque")
+            return;
+        const names = requested.rest ? [...this.layers.keys()] : requested.names;
+        for (const name of names) {
+            const defs = this.layers.get(name);
+            if (defs)
+                await this.ensure(name, defs.length - 1);
+            else if (!BUILT_IN_FIXTURES.has(name))
+                throw new Error(`extend(): unknown fixture "${name}"`);
+        }
+    }
+    /**
+     * Finishes the fixtures that were set up, last first, each within `limitMs`. Returns the first error (a
+     * fixture's cleanup threw or ran out of time); the others still run.
+     */
+    async teardown(limitMs) {
+        this.closed = true;
+        let first;
+        for (let one = this.started.pop(); one; one = this.started.pop()) {
+            one.release();
+            let timer;
+            try {
+                await Promise.race([
+                    one.done(),
+                    new Promise((_, reject) => {
+                        timer = setTimeout(() => reject(new Error(`timed out after ${limitMs / 1000} seconds`)), limitMs);
+                    }),
+                ]);
+            }
+            catch (err) {
+                first ??= new Error(`fixture "${one.name}" teardown failed: ${messageOf(err)}`);
+                if (err instanceof Error && err.stack)
+                    first.stack = err.stack;
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+        return first;
+    }
+    ensure(name, level) {
+        const key = `${name}#${level}`;
+        let promise = this.pending.get(key);
+        if (!promise) {
+            promise = this.setUp(name, level);
+            this.pending.set(key, promise);
+        }
+        return promise;
+    }
+    async setUp(name, level) {
+        const def = this.layers.get(name)?.[level];
+        if (!def)
+            throw new Error(`extend(): unknown fixture "${name}"`);
+        try {
+            const args = {};
+            for (const dep of def.deps) {
+                const target = dependencyOf(this.layers, name, level, dep);
+                if (target === "built-in" || target === undefined)
+                    args[dep] = this.base[dep];
+                else {
+                    await this.ensure(target.name, target.level);
+                    args[dep] = this.values.get(`${target.name}#${target.level}`);
+                }
+            }
+            let value = def.value;
+            if (def.setup) {
+                const started = await startSetup(def, args);
+                if (this.closed) {
+                    started.release();
+                    throw new Error("the test is already over");
+                }
+                value = started.value;
+                this.started.push({ name, ...started });
+            }
+            this.values.set(`${name}#${level}`, value);
+            if (level === (this.layers.get(name)?.length ?? 0) - 1)
+                Object.defineProperty(this.fixtures, name, {
+                    value,
+                    enumerable: true,
+                    configurable: true,
+                    writable: true,
+                });
+        }
+        catch (err) {
+            throw err instanceof FixtureSetupError
+                ? err
+                : new FixtureSetupError(name, err);
+        }
+    }
+}

package/dist/runner/fixtures.d.ts

@@ -0,0 +1,34 @@
+import type { Browser } from "../browser/browser.js";
+import type Page from "../browser/page.js";
+import type { SupportedBrowser } from "../types/browser.js";
+import type { AllHookFixtures, RegisteredTestCase, TestFixtures, TestInfo } from "../types/test.js";
+import type { RunnerOptions } from "./options.js";
+import type { PreparedRun } from "./prepare-run.js";
+import type { OutputSink } from "../wait/output-sink.js";
+/** What `beforeAll` and `afterAll` hooks get: no page, only what a run knows */
+export declare function allHookFixtures(run: PreparedRun, browserName: SupportedBrowser, workerIndex?: number): AllHookFixtures;
+/** What one run of a test builds its fixtures from */
+export interface FixtureSources {
+    launched: {
+        page: Page;
+        browser: Browser;
+    };
+    browserName: SupportedBrowser;
+    workerIndex: number;
+    run: PreparedRun;
+    test: RegisteredTestCase;
+    options: RunnerOptions;
+    sink: OutputSink;
+    info: TestInfo;
+    /** What the `use` options came to in this browser */
+    device: {
+        isMobile: boolean;
+        hasTouch: boolean;
+    };
+}
+/**
+ * The fixtures a test body and its each-hooks receive. `context`, `baseURL` and `testInfo` are getters: nothing
+ * is looked up until a test reads one (and `page.context()` throws for a page without one, which only a test
+ * that asks for it should see).
+ */
+export declare function buildTestFixtures(from: FixtureSources): TestFixtures;

package/dist/runner/fixtures.js

@@ -0,0 +1,39 @@
+import { createSecretsFixture } from "../config/secrets.js";
+import { createEnvFixture } from "../config/variables.js";
+import { createInputsFixture, createOutputsFixture } from "./test-io.js";
+/** What `beforeAll` and `afterAll` hooks get: no page, only what a run knows */
+export function allHookFixtures(run, browserName, workerIndex = 0) {
+    const { settings, secrets } = run;
+    return {
+        browserName,
+        workerIndex,
+        env: createEnvFixture(settings.environment, settings.variables),
+        secrets: createSecretsFixture(settings.environment, secrets),
+    };
+}
+/**
+ * The fixtures a test body and its each-hooks receive. `context`, `baseURL` and `testInfo` are getters: nothing
+ * is looked up until a test reads one (and `page.context()` throws for a page without one, which only a test
+ * that asks for it should see).
+ */
+export function buildTestFixtures(from) {
+    const { launched, browserName, workerIndex, run, test, options, sink, info, device, } = from;
+    const { settings, secrets } = run;
+    const fixtures = {
+        page: launched.page,
+        browser: launched.browser,
+        browserName,
+        workerIndex,
+        env: createEnvFixture(settings.environment, settings.variables),
+        secrets: createSecretsFixture(settings.environment, secrets),
+        inputs: createInputsFixture(test.inputs, options.inputs),
+        outputs: createOutputsFixture(sink),
+        isMobile: device.isMobile,
+        hasTouch: device.hasTouch,
+    };
+    return Object.defineProperties(fixtures, {
+        context: { enumerable: true, get: () => launched.page.context() },
+        baseURL: { enumerable: true, get: () => settings.baseURL },
+        testInfo: { enumerable: true, get: () => info },
+    });
+}

package/dist/runner/hooks.d.ts

@@ -1,4 +1,5 @@
 import type { Suite, TestFixtures } from "../types/test.js";
+import type { FixtureScope } from "./fixture-scope.js";
 import { type HookKind } from "./suite.js";
 /** A hook threw or ran out of time: the message names the hook (`beforeEach hook failed: <message>`) */
 export declare class HookError extends Error {
@@ -21,4 +22,8 @@ export declare function runHook<F>(kind: HookKind, hook: (fixtures: F) => Promis
  * - What it throws: the `beforeEach` failure, else the body's error, else the first `afterEach` failure. A skip is
  *   overruled by a failing `afterEach`.
  */
-export declare function runWithEachHooks(suite: Suite, fixtures: TestFixtures, signal: AbortSignal, body: () => Promise<void>): Promise<void>;
+export declare function runWithEachHooks(suite: Suite, fixtures: TestFixtures, signal: AbortSignal, body: () => Promise<void>, 
+/** Called once the body (or a `beforeEach` hook) is over, before the `afterEach` hooks, with what it threw */
+onBodyDone?: (error: unknown) => void, 
+/** The custom fixtures: the `auto` ones are set up first, and a hook gets the ones it destructures */
+custom?: FixtureScope): Promise<void>;

package/dist/runner/hooks.js

@@ -46,24 +46,36 @@ export async function runHook(kind, hook, fixtures, limitMs) {
  * - What it throws: the `beforeEach` failure, else the body's error, else the first `afterEach` failure. A skip is
  *   overruled by a failing `afterEach`.
  */
-export async function runWithEachHooks(suite, fixtures, signal, body) {
+export async function runWithEachHooks(suite, fixtures, signal, body, 
+/** Called once the body (or a `beforeEach` hook) is over, before the `afterEach` hooks, with what it threw */
+onBodyDone, 
+/** The custom fixtures: the `auto` ones are set up first, and a hook gets the ones it destructures */
+custom) {
+    const withFixtures = (hook) => custom
+        ? async (given) => {
+            await custom.prepare(hook);
+            return hook(given);
+        }
+        : hook;
     let primary;
     let failed = false;
     try {
+        await custom?.prepareAuto();
         for (const hook of beforeEachOf(suite))
-            await runHook("beforeEach", hook, fixtures);
+            await runHook("beforeEach", withFixtures(hook), fixtures);
         await body();
     }
     catch (error) {
         primary = error;
         failed = true;
     }
+    onBodyDone?.(failed ? primary : undefined);
     let afterError;
     let afterFailed = false;
     if (!signal.aborted) {
         for (const hook of afterEachOf(suite)) {
             try {
-                await runHook("afterEach", hook, fixtures);
+                await runHook("afterEach", withFixtures(hook), fixtures);
             }
             catch (error) {
                 if (!afterFailed)

package/dist/runner/registry.d.ts

@@ -1,41 +1,5 @@
-import type { AllHook, EachHook, RegisteredTestCase, TestCaseBase, TestDetails, TestOptions } from "../types/test.js";
-type Body = TestCaseBase["function"];
-/** `test(title, fn)`, `test.skip(title, fn)`, `test.skip(condition, reason)` and the other forms */
-export interface TestFunction {
-    (title: string, fn: Body): void;
-    (title: string, options: TestOptions, fn: Body): void;
-    /** Registers a test that is not run */
-    skip: SkipFunction;
-    /** Registers a test that is not run because it is known to be broken */
-    fixme: SkipFunction;
-    /** Runs only this test (and the other `only` ones) */
-    only: {
-        (title: string, fn: Body): void;
-        (title: string, options: TestOptions, fn: Body): void;
-    };
-}
-/**
- * With a title and a body it registers a skipped test, `{ reason }` saying why; with a condition it skips the
- * running test when the condition is true
- */
-interface SkipFunction {
-    (title: string, fn: Body): void;
-    (title: string, options: TestOptions, fn: Body): void;
-    (condition: boolean, reason?: string): void;
-}
-/** `describe.skip` and `describe.fixme`: every test inside gets the modifier, and `{ reason }` says why */
-interface DescribeSkipFunction {
-    (title: string, fn: () => void): void;
-    (title: string, details: TestDetails, fn: () => void): void;
-}
-/** `describe(title, fn)` and the same with a modifier on every test inside */
-export interface DescribeFunction {
-    (title: string, fn: () => void): void;
-    skip: DescribeSkipFunction;
-    fixme: DescribeSkipFunction;
-    only(title: string, fn: () => void): void;
-}
-export declare const test: TestFunction;
+import type { AllHook, EachHook, RegisteredTestCase } from "../types/test.js";
+import type { DescribeFunction, TestFunction } from "./test-function.js";
 export declare const describe: DescribeFunction;
 /** Runs before each test of the `describe` block it is written in (of the file, at the top level) */
 export declare function beforeEach(hook: EachHook): void;
@@ -45,7 +9,7 @@ export declare function afterEach(hook: EachHook): void;
 export declare function beforeAll(hook: AllHook): void;
 /** Runs once per worker, when the worker is done, for every `describe` block it ran a `beforeAll` for */
 export declare function afterAll(hook: AllHook): void;
+export declare const test: TestFunction;
 export declare function registeredTests(): readonly RegisteredTestCase[];
 /** Forgets every registered test: a run registers its specs afresh */
 export declare function clearRegistry(): void;
-export {};

package/dist/runner/registry.js

@@ -1,8 +1,12 @@
 import { fileURLToPath } from "node:url";
 import logger from "../logger/index.js";
-import { SkipSignal } from "./skip.js";
+import { extendLayers } from "./fixture-defs.js";
+import { validateUseOptions } from "../config/use-options.js";
+import { currentStepLog, currentTestInfo, infoFor, skipFromCondition, } from "./test-info.js";
+import { runStep } from "./steps.js";
+import { markTests } from "./test-annotations.js";
 import { validateTestIO } from "./test-io.js";
-import { addHook, currentSuite, enterSuite, leaveSuite, modifierOf, resetSuites, } from "./suite.js";
+import { addHook, addUse, currentSuite, enterSuite, leaveSuite, modifierOf, resetSuites, } from "./suite.js";
 const registered = [];
 /** Runs `fn` as the `describe` block `title`, under `modifier` when there is one. `fn` runs immediately and must be synchronous. */
 function openDescribe(file, title, fn, modifier, reason) {
@@ -18,8 +22,8 @@ function openDescribe(file, title, fn, modifier, reason) {
         leaveSuite();
     }
 }
-function add(file, title, fn, modifier, extras = {}) {
-    const { reason, inputs, outputs } = extras;
+function add({ file, line, column }, title, fn, modifier, extras = {}) {
+    const { reason, inputs, outputs, extension, expectedFail } = extras;
     const suite = currentSuite(file);
     const titlePath = [...titlesOf(suite), title];
     const name = titlePath.join(" > ");
@@ -28,10 +32,13 @@ function add(file, title, fn, modifier, extras = {}) {
         titlePath,
         function: fn,
         file,
+        ...(line !== undefined && { line, column }),
         suite,
         ...modifierOf({ modifier, ...(reason !== undefined && { reason }) }, suite),
         ...(inputs && { inputs }),
         ...(outputs && { outputs }),
+        ...(extension && { extension }),
+        ...(expectedFail && { expectedFail }),
     });
     logger.debug("Registered test %s", name);
 }
@@ -58,28 +65,59 @@ function bodyAndOptions(call, title, second, third) {
     };
 }
 /** `test()` and `test.only()`: a reason only makes sense with skip and fixme */
-function registering(call, modifier) {
+function registering(call, modifier, extension) {
     return ((title, second, third) => {
         const { fn, reason, ...io } = bodyAndOptions(call, title, second, third);
         if (reason !== undefined)
             throw new Error(`${call}(): reason only applies to skip and fixme`);
         // Frames: Error, callerFile, this function, the spec
-        add(callerFile(), title, fn, modifier, io);
+        add(callerLocation(), title, fn, modifier, {
+            ...io,
+            ...(extension && { extension }),
+        });
     });
 }
 /** `test.skip` and `test.fixme`: a title and a body register a test with the modifier; a condition skips the running test */
-function skipping(annotation) {
+function skipping(annotation, extension) {
     return ((first, second, third) => {
         if (typeof first === "string") {
             const { fn, ...extras } = bodyAndOptions(`test.${annotation}`, first, second, third);
             // Frames: Error, callerFile, this function, the spec
-            add(callerFile(), first, fn, annotation, extras);
+            add(callerLocation(), first, fn, annotation, {
+                ...extras,
+                ...(extension && { extension }),
+            });
             return;
         }
-        if (first)
-            throw new SkipSignal(annotation, second);
+        skipFromCondition(annotation, first, second);
     });
 }
+/**
+ * `test.fail`: a title and a body register a test that is expected to fail; otherwise the running test (or, in a
+ * `describe` block, every test in it) is marked
+ */
+function failing(extension) {
+    return ((first, second, third) => {
+        if (typeof first !== "string") {
+            // Frames: Error, callerFile, this function, the spec
+            const file = callerFile();
+            return markTests("fail", () => currentSuite(file), first, second);
+        }
+        const { fn, reason, ...io } = bodyAndOptions("test.fail", first, second, third);
+        // Frames: Error, callerFile, this function, the spec
+        add(callerLocation(), first, fn, undefined, {
+            ...io,
+            expectedFail: { ...(reason !== undefined && { description: reason }) },
+            ...(extension && { extension }),
+        });
+    });
+}
+/** `test.slow`: triples the timeout of the running test, or of every test of the `describe` block it is written in */
+const slow = ((condition, reason) => {
+    // Frames: Error, callerFile, this function, the spec
+    const file = callerFile();
+    markTests("slow", () => currentSuite(file), condition, reason);
+});
 /** `describe.skip` and `describe.fixme`, with or without `{ reason }` */
 function describeSkipping(annotation) {
     return ((title, second, third) => {
@@ -87,11 +125,6 @@ function describeSkipping(annotation) {
         openDescribe(callerFile(), title, fn, annotation, reason);
     });
 }
-export const test = Object.assign(registering("test"), {
-    skip: skipping("skip"),
-    fixme: skipping("fixme"),
-    only: registering("test.only", "only"),
-});
 export const describe = Object.assign((title, fn) => openDescribe(callerFile(), title, fn), {
     skip: describeSkipping("skip"),
     fixme: describeSkipping("fixme"),
@@ -113,6 +146,34 @@ export function beforeAll(hook) {
 export function afterAll(hook) {
     addHook(currentSuite(callerFile()), "afterAll", hook);
 }
+/** `test.use(options)`: checked now, applied when each test of the scope runs */
+function use(options) {
+    addUse(currentSuite(callerFile()), validateUseOptions(options));
+}
+/**
+ * A `test` that registers its tests with the custom fixtures `extension`. The aliases are the same functions as
+ * the named exports: they find the spec file from the stack, so they must not be wrapped.
+ */
+function makeTest(extension) {
+    return Object.assign(registering("test", undefined, extension), {
+        skip: skipping("skip", extension),
+        fixme: skipping("fixme", extension),
+        fail: failing(extension),
+        slow,
+        setTimeout: (ms) => infoFor("setTimeout()").setTimeout(ms),
+        step: (title, body, options) => runStep(currentStepLog(), title, body, options),
+        only: registering("test.only", "only", extension),
+        info: currentTestInfo,
+        use,
+        describe,
+        beforeEach,
+        afterEach,
+        beforeAll,
+        afterAll,
+        extend: (fixtures) => makeTest(extendLayers(extension, fixtures)),
+    });
+}
+export const test = makeTest();
 export function registeredTests() {
     return registered;
 }
@@ -121,10 +182,23 @@ export function clearRegistry() {
     registered.length = 0;
     resetSuites();
 }
-/** File of the code that called the entry point: stack lines are Error, callerFile, the entry point, the caller */
-function callerFile() {
+/** The place of the caller: stack lines are Error, callerLocation, the entry point, the caller */
+function callerLocation() {
     const caller = new Error().stack?.split("\n")[3] ?? "";
-    const match = caller.match(/\((.+?):\d+:\d+\)$/) ?? caller.match(/at (.+?):\d+:\d+$/);
+    return parseFrame(caller);
+}
+/** File of the code that called the entry point (the same frames as `callerLocation`) */
+function callerFile() {
+    return parseFrame(new Error().stack?.split("\n")[3] ?? "").file;
+}
+function parseFrame(frame) {
+    const match = frame.match(/\((.+?):(\d+):(\d+)\)$/) ??
+        frame.match(/at (.+?):(\d+):(\d+)$/);
     const location = match?.[1] ?? "";
-    return location.startsWith("file://") ? fileURLToPath(location) : location;
+    const file = location.startsWith("file://")
+        ? fileURLToPath(location)
+        : location;
+    return match
+        ? { file, line: Number(match[2]), column: Number(match[3]) }
+        : { file };
 }

package/dist/runner/reporter.d.ts

@@ -1,4 +1,4 @@
-import type { RegisteredTestCase, TestError, TestLogEntry, TestResult, TestRetries, TestSummary } from "../types/test.js";
+import type { TestAnnotation, TestStepEntry, TestAttachmentEntry, RegisteredTestCase, TestError, TestLogEntry, TestResult, TestRetries, TestSummary } from "../types/test.js";
 import type { SupportedBrowser } from "../types/browser.js";
 /** What a run reports while it happens */
 export type RunEvent = {
@@ -60,6 +60,12 @@ export interface TestEndExtras extends TestRetries {
     inputs?: Record<string, string>;
     /** The test's saved outputs, when it declares any */
     outputs?: Record<string, string>;
+    /** Files the test attached with `testInfo.attach`, relative to the result folder */
+    attachments?: TestAttachmentEntry[];
+    /** The notes the test pushed to `testInfo.annotations` */
+    annotations?: TestAnnotation[];
+    /** The steps the test ran with `test.step` */
+    steps?: TestStepEntry[];
 }
 export default class TestReporter implements TestSink {
     private testResults;

package/dist/runner/reporter.js

@@ -148,6 +148,9 @@ export default class TestReporter {
             ...(extras?.screenshots?.length && { screenshots: extras.screenshots }),
             ...(extras?.inputs && { inputs: extras.inputs }),
             ...(extras?.outputs && { outputs: extras.outputs }),
+            ...(extras?.attachments && { attachments: extras.attachments }),
+            ...(extras?.annotations && { annotations: extras.annotations }),
+            ...(extras?.steps && { steps: extras.steps }),
             ...(extras?.retry && { retry: extras.retry }),
             ...(extras?.flaky && { flaky: true }),
             ...(extras?.previousAttempts?.length && {

package/dist/runner/run-test.d.ts

@@ -1,5 +1,5 @@
 import type { SupportedBrowser } from "../types/browser.js";
-import type { AllHookFixtures, RegisteredTestCase } from "../types/test.js";
+import type { RegisteredTestCase } from "../types/test.js";
 import type { RunnerOptions } from "./options.js";
 import type { AllHooks } from "./all-hooks.js";
 import type { PreparedRun } from "./prepare-run.js";
@@ -17,7 +17,5 @@ export interface WorkerResources {
     /** The `beforeAll` / `afterAll` hooks of this worker: kept across tests, closed when the worker is done */
     allHooks?: AllHooks;
 }
-/** What `beforeAll` and `afterAll` hooks get: no page, only what a run knows */
-export declare function allHookFixtures(run: PreparedRun, browserName: SupportedBrowser, workerIndex?: number): AllHookFixtures;
 /** Runs one test in one browser and reports it: launch, run the body, judge the page's logs, close the browser */
 export declare function runOneTest(test: RegisteredTestCase, browserName: SupportedBrowser, run: PreparedRun, options: RunnerOptions, srcDir: string, reporter: TestSink, resources?: WorkerResources): Promise<void>;