@itmetsam/samurai-framework 0.21.5 → 0.22.1

package/dist/request/http-transport.js

@@ -0,0 +1,113 @@
+import http from "node:http";
+import https from "node:https";
+import zlib from "node:zlib";
+/** A request that failed before a response was complete */
+export class TransportError extends Error {
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "TransportError";
+    }
+}
+function decode(body, encoding) {
+    if (body.length === 0)
+        return body;
+    switch (encoding?.trim().toLowerCase()) {
+        case "gzip":
+        case "x-gzip":
+            return zlib.gunzipSync(body);
+        case "br":
+            return zlib.brotliDecompressSync(body);
+        case "deflate":
+            try {
+                return zlib.inflateSync(body);
+            }
+            catch {
+                // Some servers send deflate without the zlib header
+                return zlib.inflateRawSync(body);
+            }
+        default:
+            return body;
+    }
+}
+/** The url without credentials or query: what an error may say about where the request went */
+export function describeURL(url) {
+    return `${url.origin}${url.pathname}`;
+}
+/** Sends one request over `http` or `https` and reads the whole response. Errors never include header values. */
+export function sendHop(request) {
+    const { url, method, headers, body, signal } = request;
+    const where = `${method} ${describeURL(url)}`;
+    return new Promise((resolve, reject) => {
+        if (signal.aborted)
+            return reject(new TransportError(`request aborted (${where})`));
+        const transport = url.protocol === "https:" ? https : http;
+        let settled = false;
+        let timer;
+        const finish = (error, value) => {
+            if (settled)
+                return;
+            settled = true;
+            signal.removeEventListener("abort", onAbort);
+            clearTimeout(timer);
+            if (error)
+                reject(error);
+            else
+                resolve(value);
+        };
+        const req = transport.request(url, {
+            method,
+            headers: {
+                ...headers,
+                ...(body && { "content-length": String(body.length) }),
+            },
+            // No shared pool: nothing stays open after the last request
+            agent: false,
+            ...(url.protocol === "https:" && {
+                rejectUnauthorized: !request.ignoreHTTPSErrors,
+            }),
+        }, (res) => {
+            const chunks = [];
+            res.on("data", (chunk) => chunks.push(chunk));
+            res.on("error", (err) => finish(new TransportError(`${err.message} (${where})`)));
+            res.on("end", () => {
+                try {
+                    const raw = res.rawHeaders;
+                    const entries = [];
+                    for (let i = 0; i + 1 < raw.length; i += 2)
+                        entries.push({
+                            name: raw[i],
+                            value: raw[i + 1],
+                        });
+                    const decoded = method === "HEAD"
+                        ? Buffer.alloc(0)
+                        : decode(Buffer.concat(chunks), res.headers["content-encoding"]);
+                    finish(undefined, {
+                        status: res.statusCode ?? 0,
+                        statusText: res.statusMessage ?? "",
+                        headers: entries,
+                        setCookies: res.headers["set-cookie"] ?? [],
+                        body: decoded,
+                    });
+                }
+                catch (err) {
+                    finish(new TransportError(`the response body could not be decoded: ${err.message} (${where})`));
+                }
+            });
+        });
+        const onAbort = () => {
+            req.destroy();
+            finish(new TransportError(`request aborted (${where})`));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        timer =
+            request.timeout > 0
+                ? setTimeout(() => {
+                    req.destroy();
+                    finish(new TransportError(`timed out after ${request.timeout}ms (${where})`, "ETIMEDOUT"));
+                }, request.timeout)
+                : undefined;
+        req.on("error", (err) => finish(new TransportError(`${err.code ?? err.message} (${where})`, err.code)));
+        req.end(body);
+    });
+}

package/dist/request/redirect.d.ts

@@ -0,0 +1,10 @@
+/** Where a response sends the client next: its `Location` against the URL it came from; `undefined` when it does not redirect */
+export declare function redirectTarget(status: number, location: string | undefined, from: URL): URL | undefined;
+/**
+ * The method and body of the request that follows a redirect. 303 (any method but GET and HEAD) and 301/302 after
+ * a POST turn into a GET without a body; 307 and 308 keep both.
+ */
+export declare function followUp<B>(status: number, method: string, body: B | undefined): {
+    method: string;
+    body: B | undefined;
+};

package/dist/request/redirect.js

@@ -0,0 +1,21 @@
+const REDIRECTS = new Set([301, 302, 303, 307, 308]);
+/** Where a response sends the client next: its `Location` against the URL it came from; `undefined` when it does not redirect */
+export function redirectTarget(status, location, from) {
+    if (!REDIRECTS.has(status) || !location)
+        return undefined;
+    try {
+        return new URL(location, from);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The method and body of the request that follows a redirect. 303 (any method but GET and HEAD) and 301/302 after
+ * a POST turn into a GET without a body; 307 and 308 keep both.
+ */
+export function followUp(status, method, body) {
+    const upgrades = (status === 303 && method !== "GET" && method !== "HEAD") ||
+        ((status === 301 || status === 302) && method === "POST");
+    return upgrades ? { method: "GET", body: undefined } : { method, body };
+}

package/dist/request/request-body.d.ts

@@ -0,0 +1,27 @@
+/** A file in a `multipart` body */
+export interface FilePayload {
+    name: string;
+    /** @default "application/octet-stream" */
+    mimeType?: string;
+    buffer: Buffer;
+}
+type Scalar = string | number | boolean;
+/** The body options of a request: at most one is set */
+export interface BodyOptions {
+    /** Sent as it is (a string, a `Buffer`), or as JSON (anything else) */
+    data?: string | Buffer | object | number | boolean | null;
+    /** Sent as `application/x-www-form-urlencoded` */
+    form?: Record<string, Scalar> | URLSearchParams;
+    /** Sent as `multipart/form-data`: fields and files */
+    multipart?: Record<string, Scalar | FilePayload>;
+}
+export interface EncodedBody {
+    body: Buffer;
+    contentType: string;
+}
+/**
+ * The bytes of a request body and the `Content-Type` that goes with them (a header the caller sets wins over it).
+ * `undefined` when there is no body. Throws `fetch(): ...` when more than one of the options is set.
+ */
+export declare function encodeBody(options: BodyOptions): EncodedBody | undefined;
+export {};

package/dist/request/request-body.js

@@ -0,0 +1,71 @@
+import { randomBytes } from "node:crypto";
+function isFile(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        Buffer.isBuffer(value.buffer));
+}
+function isJson(text) {
+    try {
+        JSON.parse(text);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const quoted = (text) => text.replace(/["\r\n]/g, "_");
+function multipartOf(parts) {
+    const boundary = `----samurai${randomBytes(12).toString("hex")}`;
+    const chunks = [];
+    for (const [name, value] of Object.entries(parts)) {
+        const file = isFile(value);
+        const head = file
+            ? `Content-Disposition: form-data; name="${quoted(name)}"; filename="${quoted(value.name)}"\r\nContent-Type: ${value.mimeType ?? "application/octet-stream"}`
+            : `Content-Disposition: form-data; name="${quoted(name)}"`;
+        chunks.push(Buffer.from(`--${boundary}\r\n${head}\r\n\r\n`), file ? value.buffer : Buffer.from(String(value)), Buffer.from("\r\n"));
+    }
+    chunks.push(Buffer.from(`--${boundary}--\r\n`));
+    return {
+        body: Buffer.concat(chunks),
+        contentType: `multipart/form-data; boundary=${boundary}`,
+    };
+}
+/**
+ * The bytes of a request body and the `Content-Type` that goes with them (a header the caller sets wins over it).
+ * `undefined` when there is no body. Throws `fetch(): ...` when more than one of the options is set.
+ */
+export function encodeBody(options) {
+    const given = ["data", "form", "multipart"].filter((key) => options[key] !== undefined);
+    if (given.length > 1)
+        throw new Error(`fetch(): ${given.join(" and ")} cannot be used together, pick one`);
+    const { data, form, multipart } = options;
+    if (form !== undefined) {
+        const params = form instanceof URLSearchParams
+            ? form
+            : new URLSearchParams(Object.entries(form).map(([key, value]) => [key, String(value)]));
+        return {
+            body: Buffer.from(params.toString()),
+            contentType: "application/x-www-form-urlencoded",
+        };
+    }
+    if (multipart !== undefined)
+        return multipartOf(multipart);
+    if (data === undefined)
+        return undefined;
+    if (typeof data === "string")
+        return {
+            body: Buffer.from(data),
+            contentType: isJson(data)
+                ? "application/json"
+                : "application/octet-stream",
+        };
+    if (Buffer.isBuffer(data) || data instanceof Uint8Array)
+        return {
+            body: Buffer.from(data),
+            contentType: "application/octet-stream",
+        };
+    return {
+        body: Buffer.from(JSON.stringify(data)),
+        contentType: "application/json",
+    };
+}

package/dist/request/request.d.ts

@@ -0,0 +1,16 @@
+import type { StorageState } from "../types/use.js";
+import { APIRequestContext, type RequestContextOptions } from "./api-request-context.js";
+/** Options of `request.newContext()` */
+export interface NewRequestContextOptions extends RequestContextOptions {
+    /** Cookies to start with: a JSON file (relative to the project folder) or the object itself. Local storage is not used. */
+    storageState?: string | StorageState;
+}
+/** A request context with its own cookies: the same API as `page.request`, without a browser */
+export declare function createRequestContext(options?: NewRequestContextOptions): APIRequestContext;
+/**
+ * Creates `APIRequestContext`s that belong to no page: `request.newContext({ baseURL })`. Inside a test, the
+ * `request` fixture is one already.
+ */
+export declare const request: {
+    newContext: (options?: NewRequestContextOptions) => Promise<APIRequestContext>;
+};

package/dist/request/request.js

@@ -0,0 +1,20 @@
+import path from "node:path";
+import { projectDir } from "../config/config.js";
+import { loadStorageState } from "../config/storage-state-file.js";
+import { APIRequestContext, } from "./api-request-context.js";
+import { CookieJar } from "./cookie-jar.js";
+/** A request context with its own cookies: the same API as `page.request`, without a browser */
+export function createRequestContext(options = {}) {
+    const { storageState, ...rest } = options;
+    const state = storageState === undefined
+        ? undefined
+        : loadStorageState(storageState, path.resolve(projectDir()), "newContext()");
+    return new APIRequestContext(rest, new CookieJar(state?.cookies));
+}
+/**
+ * Creates `APIRequestContext`s that belong to no page: `request.newContext({ baseURL })`. Inside a test, the
+ * `request` fixture is one already.
+ */
+export const request = {
+    newContext: (options) => Promise.resolve(createRequestContext(options)),
+};

package/dist/runner/all-hooks.d.ts

@@ -1,5 +1,5 @@
 import type { SupportedBrowser } from "../types/browser.js";
-import type { AllHookFixtures, RegisteredTestCase } from "../types/test.js";
+import type { AllHookFixtures, RegisteredTestCase, Suite } from "../types/test.js";
 import { type HookError } from "./hooks.js";
 export interface AllHooksOptions {
     /** The limit of each beforeAll / afterAll hook, in ms */
@@ -21,6 +21,12 @@ export declare class AllHooks {
     ensure(test: RegisteredTestCase, browser: SupportedBrowser): Promise<void>;
     /** Runs the `afterAll` hooks of every suite entered, last entered first, and returns the errors; a second call has nothing to do */
     closeAll(): Promise<HookError[]>;
+    /**
+     * Runs the `afterAll` hooks of `root` and of the suites inside it that were entered, so the next test that arrives
+     * runs their `beforeAll` hooks again: a serial block that starts over. Returns the errors.
+     */
+    closeWithin(root: Suite): Promise<HookError[]>;
+    private runAfter;
     private enter;
     private runBefore;
 }

package/dist/runner/all-hooks.js

@@ -21,9 +21,25 @@ export class AllHooks {
     }
     /** Runs the `afterAll` hooks of every suite entered, last entered first, and returns the errors; a second call has nothing to do */
     async closeAll() {
-        const errors = [];
         const entered = this.entered.splice(0).reverse();
         this.scopes.clear();
+        return this.runAfter(entered);
+    }
+    /**
+     * Runs the `afterAll` hooks of `root` and of the suites inside it that were entered, so the next test that arrives
+     * runs their `beforeAll` hooks again: a serial block that starts over. Returns the errors.
+     */
+    async closeWithin(root) {
+        const inside = (scope) => suiteChain(scope.suite).includes(root);
+        const closing = this.entered.filter(inside).reverse();
+        for (const scope of closing) {
+            this.entered.splice(this.entered.indexOf(scope), 1);
+            this.scopes.get(scope.suite)?.delete(scope.browser);
+        }
+        return this.runAfter(closing);
+    }
+    async runAfter(entered) {
+        const errors = [];
         for (const { suite, browser, ready } of entered) {
             await ready.catch(() => undefined);
             for (const hook of suite.afterAll ?? []) {

package/dist/runner/fixture-defs.d.ts

@@ -1,7 +1,8 @@
+import { type FixtureMeta } from "./fixture-meta.js";
 /** The function of a fixture: sets the value up, calls `use(value)`, cleans up after `use` returns */
 type FixtureSetup = (args: Record<string, unknown>, use: (value: unknown) => Promise<void>) => Promise<void>;
 /** One definition of a fixture: the value or the setup function, what it depends on, whether every test gets it */
-export interface FixtureDef {
+export interface FixtureDef extends FixtureMeta {
     name: string;
     auto: boolean;
     deps: string[];

package/dist/runner/fixture-defs.js

@@ -1,4 +1,5 @@
 import { requestedBy } from "./fixture-args.js";
+import { checkedOptions, OPTIONS_SUFFIX, } from "./fixture-meta.js";
 /** The fixtures the runner builds for every test: a custom fixture of the same name overrides it */
 export const BUILT_IN_FIXTURES = new Set([
     "page",
@@ -11,46 +12,55 @@ export const BUILT_IN_FIXTURES = new Set([
     "outputs",
     "context",
     "baseURL",
+    "request",
     "testInfo",
     "isMobile",
     "hasTouch",
 ]);
-const OPTION_KEYS = new Set(["auto", "scope"]);
 function isPlainObject(value) {
     if (typeof value !== "object" || value === null)
         return false;
     const proto = Object.getPrototypeOf(value);
     return proto === Object.prototype || proto === null;
 }
-/** `[fixture, options]` is always a pair with options; an array value goes in a function */
-function checkedOptions(name, options) {
-    for (const key of Object.keys(options))
-        if (!OPTION_KEYS.has(key))
-            throw new Error(`extend(): fixture "${name}" has an unknown option "${key}"`);
-    if (options.auto !== undefined && typeof options.auto !== "boolean")
-        throw new Error(`extend(): fixture "${name}": auto must be true or false`);
-    if (options.scope === "worker")
-        throw new Error(`extend(): fixture "${name}" has scope "worker", which is not supported; fixtures live as long as one test ({ scope: "test" })`);
-    if (options.scope !== undefined && options.scope !== "test")
-        throw new Error(`extend(): fixture "${name}": scope must be "test"`);
-    return { auto: options.auto === true };
-}
 function definitionOf(name, raw) {
     const [fixture, options] = Array.isArray(raw) && raw.length === 2 && isPlainObject(raw[1])
         ? [raw[0], checkedOptions(name, raw[1])]
-        : [raw, { auto: false }];
+        : [raw, checkedOptions(name, {})];
+    const { auto, meta } = options;
+    checkOptionFixture(name, fixture, meta);
     if (typeof fixture !== "function")
-        return { name, auto: options.auto, deps: [], value: fixture };
+        return { name, auto, deps: [], value: fixture, ...meta };
     const requested = requestedBy(fixture);
     if (requested.kind === "opaque" || requested.rest)
         throw new Error(`extend(): fixture "${name}" must destructure the fixtures it uses in its first argument, as ({ page }, use) or ({}, use)`);
     return {
         name,
-        auto: options.auto,
+        auto,
         deps: requested.names,
         setup: fixture,
+        ...meta,
     };
 }
+/** `option: true` and `fields` go together with a name ending in `Options` and a plain object as the value */
+function checkOptionFixture(name, fixture, meta) {
+    const suffixed = name.endsWith(OPTIONS_SUFFIX) && name !== OPTIONS_SUFFIX;
+    if (!meta.option) {
+        if (meta.fields)
+            throw new Error(suffixed
+                ? `extend(): fixture "${name}" has fields but option is not true`
+                : `extend(): fixture "${name}" has fields but is not an option fixture; put them on "${name}${OPTIONS_SUFFIX}" (option: true)`);
+        return;
+    }
+    if (!suffixed)
+        throw new Error(`extend(): fixture "${name}" is an option fixture, so its name must end in "${OPTIONS_SUFFIX}"`);
+    if (typeof fixture === "function")
+        throw new Error(`extend(): option fixture "${name}" must be a plain object, not a function`);
+    if (!isPlainObject(fixture))
+        throw new Error(`extend(): option fixture "${name}" must be a plain object`);
+}
+/** The name of the fixture an option fixture belongs to */
+const fixtureOf = (optionName) => optionName.slice(0, -OPTIONS_SUFFIX.length);
 /** Where a dependency of `name` (at definition `level`) comes from: another definition, or the built-in fixture */
 export function dependencyOf(layers, name, level, dep) {
     if (dep === name)
@@ -64,6 +74,25 @@ export function dependencyOf(layers, name, level, dep) {
         return { name: dep, level: defs.length - 1 };
     return BUILT_IN_FIXTURES.has(dep) ? "built-in" : undefined;
 }
+/** The built-in fixtures a worker fixture may use: those that do not belong to one test or one page */
+const WORKER_BUILT_INS = new Set([
+    "browserName",
+    "workerIndex",
+    "env",
+    "secrets",
+    "baseURL",
+]);
+/** A worker fixture outlives every test: it may use the run's values, other worker fixtures and plain values */
+function checkWorkerDependency(layers, def, dep, target) {
+    if (target === "built-in") {
+        if (!WORKER_BUILT_INS.has(dep))
+            throw new Error(`extend(): worker fixture "${def.name}" cannot use "${dep}"; it lives longer than one test (it may use ${[...WORKER_BUILT_INS].join(", ")}, other worker fixtures and values)`);
+        return;
+    }
+    const used = target && layers.get(target.name)?.[target.level];
+    if (used && used.scope !== "worker" && used.setup)
+        throw new Error(`extend(): worker fixture "${def.name}" cannot use the test-scoped fixture "${dep}"`);
+}
 /** Throws for a dependency nobody defines and for a cycle (`a` needs `b` needs `a`) */
 function validate(layers) {
     const done = new Set();
@@ -82,14 +111,19 @@ function validate(layers) {
             const target = dependencyOf(layers, name, level, dep);
             if (target === undefined)
                 throw new Error(`extend(): fixture "${name}" depends on unknown fixture "${dep}"`);
+            if (def.scope === "worker")
+                checkWorkerDependency(layers, def, dep, target);
             if (target !== "built-in")
                 walk(target.name, target.level, [...path, key]);
         }
         done.add(key);
     };
-    for (const [name, defs] of layers)
+    for (const [name, defs] of layers) {
+        if (defs[defs.length - 1]?.option && !layers.has(fixtureOf(name)))
+            throw new Error(`extend(): option fixture "${name}" has no fixture "${fixtureOf(name)}"`);
         for (let level = 0; level < defs.length; level++)
             walk(name, level, []);
+    }
 }
 /** The fixtures after `test.extend(definitions)` on a test that has `base`; throws `extend(): ...` for a definition that cannot work */
 export function extendLayers(base, definitions) {

package/dist/runner/fixture-meta.d.ts

@@ -0,0 +1,20 @@
+import type { FixtureField, FixtureOutput } from "../types/extend.js";
+/** What a fixture's options say besides `auto`: its scope, and the metadata the app's catalog and the report use */
+export interface FixtureMeta {
+    scope: "test" | "worker";
+    label?: string;
+    icon?: string;
+    description?: string;
+    outputs?: FixtureOutput[];
+    timeout?: number;
+    /** The fixture is the options of the fixture named without the `Options` suffix */
+    option: boolean;
+    fields?: FixtureField[];
+}
+/** The suffix that pairs an option fixture with its fixture: `order` reads `orderOptions` */
+export declare const OPTIONS_SUFFIX = "Options";
+/** Checks the options of `[fixture, options]` and returns what the definition keeps; throws `extend(): ...` */
+export declare function checkedOptions(name: string, options: Record<string, unknown>): {
+    auto: boolean;
+    meta: FixtureMeta;
+};

package/dist/runner/fixture-meta.js

@@ -0,0 +1,109 @@
+/** The suffix that pairs an option fixture with its fixture: `order` reads `orderOptions` */
+export const OPTIONS_SUFFIX = "Options";
+const OPTION_KEYS = new Set([
+    "auto",
+    "scope",
+    "label",
+    "icon",
+    "description",
+    "outputs",
+    "timeout",
+    "option",
+    "fields",
+]);
+const FIELD_TYPES = [
+    "text",
+    "code",
+    "expression",
+    "number",
+    "select",
+    "segmented",
+    "switch",
+    "secret",
+    "variable",
+];
+const fail = (name, problem) => {
+    throw new Error(`extend(): fixture "${name}": ${problem}`);
+};
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function checkOutputs(name, outputs) {
+    if (!Array.isArray(outputs))
+        return fail(name, "outputs must be an array");
+    const seen = new Set();
+    for (const output of outputs) {
+        if (!isObject(output) ||
+            typeof output.name !== "string" ||
+            output.name === "")
+            fail(name, "every output needs a name");
+        const { name: key, label, secret } = output;
+        if (seen.has(key))
+            fail(name, `output "${key}" is listed twice`);
+        seen.add(key);
+        if (label !== undefined && typeof label !== "string")
+            fail(name, `output "${key}": label must be a string`);
+        if (secret !== undefined && typeof secret !== "boolean")
+            fail(name, `output "${key}": secret must be true or false`);
+    }
+    return outputs;
+}
+function checkFields(name, fields) {
+    if (!Array.isArray(fields))
+        return fail(name, "fields must be an array");
+    const seen = new Set();
+    for (const field of fields) {
+        if (!isObject(field) || typeof field.path !== "string" || field.path === "")
+            fail(name, "every field needs a path");
+        const { path, type, options } = field;
+        if (!FIELD_TYPES.includes(type))
+            fail(name, `field "${path}" has an unknown type ${JSON.stringify(type)}`);
+        if (seen.has(path))
+            fail(name, `field "${path}" is listed twice`);
+        seen.add(path);
+        if ((type === "select" || type === "segmented") && !Array.isArray(options))
+            fail(name, `field "${path}" needs options`);
+    }
+    return fields;
+}
+/** Checks the options of `[fixture, options]` and returns what the definition keeps; throws `extend(): ...` */
+export function checkedOptions(name, options) {
+    for (const key of Object.keys(options))
+        if (!OPTION_KEYS.has(key))
+            throw new Error(`extend(): fixture "${name}" has an unknown option "${key}"`);
+    if (options.auto !== undefined && typeof options.auto !== "boolean")
+        fail(name, "auto must be true or false");
+    if (options.scope !== undefined &&
+        !["test", "worker"].includes(options.scope))
+        fail(name, 'scope must be "test" or "worker"');
+    if (options.label !== undefined && typeof options.label !== "string")
+        fail(name, "label must be a string");
+    if (options.icon !== undefined &&
+        (typeof options.icon !== "string" || options.icon === ""))
+        fail(name, "icon must be a non-empty string");
+    if (options.description !== undefined &&
+        typeof options.description !== "string")
+        fail(name, "description must be a string");
+    if (options.timeout !== undefined &&
+        !(typeof options.timeout === "number" && options.timeout > 0))
+        fail(name, "timeout must be a number of milliseconds above 0");
+    if (options.option !== undefined && typeof options.option !== "boolean")
+        fail(name, "option must be true or false");
+    const meta = {
+        scope: options.scope === "worker" ? "worker" : "test",
+        option: options.option === true,
+        ...(options.label !== undefined && { label: options.label }),
+        ...(options.icon !== undefined && { icon: options.icon }),
+        ...(options.description !== undefined && {
+            description: options.description,
+        }),
+        ...(options.timeout !== undefined && {
+            timeout: options.timeout,
+        }),
+        ...(options.outputs !== undefined && {
+            outputs: checkOutputs(name, options.outputs),
+        }),
+        ...(options.fields !== undefined && {
+            fields: checkFields(name, options.fields),
+        }),
+    };
+    return { auto: options.auto === true, meta };
+}

package/dist/runner/fixture-options.d.ts

@@ -0,0 +1,8 @@
+import type { TestFixtures } from "../types/test.js";
+import type { FixtureDef } from "./fixture-defs.js";
+/**
+ * The value an option fixture gives: its default with the values from `use` over it, key by key. A field of type
+ * `secret` holds the name of a secret and one of type `variable` the name of a variable; they are replaced by the
+ * secret's or the variable's value here, so the fixture never sees the name.
+ */
+export declare function resolveOptions(def: FixtureDef, fromUse: Readonly<Record<string, unknown>> | undefined, base: Pick<TestFixtures, "env" | "secrets">): Record<string, unknown>;

package/dist/runner/fixture-options.js

@@ -0,0 +1,35 @@
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** The object at `path` (dots go into objects) and the last key, or nothing when the path leads nowhere */
+function parentOf(value, path) {
+    const keys = path.split(".");
+    let parent = value;
+    for (const key of keys.slice(0, -1)) {
+        const next = parent[key];
+        if (!isObject(next))
+            return undefined;
+        parent = next;
+    }
+    return { parent, key: keys[keys.length - 1] };
+}
+/**
+ * The value an option fixture gives: its default with the values from `use` over it, key by key. A field of type
+ * `secret` holds the name of a secret and one of type `variable` the name of a variable; they are replaced by the
+ * secret's or the variable's value here, so the fixture never sees the name.
+ */
+export function resolveOptions(def, fromUse, base) {
+    const merged = structuredClone({
+        ...def.value,
+        ...fromUse,
+    });
+    for (const field of def.fields ?? []) {
+        if (field.type !== "secret" && field.type !== "variable")
+            continue;
+        const place = parentOf(merged, field.path);
+        const name = place?.parent[place.key];
+        if (!place || typeof name !== "string" || name === "")
+            continue;
+        place.parent[place.key] =
+            field.type === "secret" ? base.secrets[name] : base.env[name];
+    }
+    return merged;
+}

package/dist/runner/fixture-outputs.d.ts

@@ -0,0 +1,11 @@
+import type { FixtureDef } from "./fixture-defs.js";
+/** A value as the report lists it */
+type OutputValue = string | number | boolean;
+/**
+ * The declared outputs of a fixture that the report and the app may show: the non-secret keys of its value.
+ * Throws when a declared output is not a string, a number or a boolean (the value must be a flat record).
+ */
+export declare function outputsOf(def: FixtureDef, value: unknown): Record<string, OutputValue> | undefined;
+/** JSON with the keys of every object in order, so equal options give equal text */
+export declare function stableJson(value: unknown): string;
+export {};