@itmetsam/samurai-framework 0.21.4 → 0.21.5

package/dist/config/config.js

@@ -2,6 +2,7 @@ import path from "path";
 import logger from "../logger/index.js";
 import { pathToFileURL } from "url";
 import { validateBrowserConfig } from "./browsers.js";
+import { validateUseConfig } from "./use-options.js";
 import { validateForbidOnlyConfig } from "./forbid-only.js";
 import { validateRetriesConfig } from "./retries.js";
 import { validateWorkersConfig } from "./workers.js";
@@ -30,6 +31,7 @@ export function validateConfig(config) {
     validateWorkersConfig(config);
     validateForbidOnlyConfig(config);
     validateRetriesConfig(config);
+    validateUseConfig(config);
 }
 /** The whole `samurai.config.ts` of the project (the working directory unless a project is active) */
 export async function loadRawConfig() {

package/dist/config/use-options.d.ts

@@ -0,0 +1,16 @@
+import type { SamuraiTestConfig } from "../types/config.js";
+import type { UseOptions } from "../types/use.js";
+/**
+ * Checks the options of `test.use()` or of the config's `use` and returns them. The config's `use` also holds
+ * options that are not these (`viewport`, `headless`, ...), so it passes `allowOthers`; `test.use()` refuses
+ * a key it does not know. Throws `use(): what is wrong`.
+ */
+export declare function validateUseOptions(options: unknown, allowOthers?: boolean): UseOptions;
+/** Checks a storage state object, whether it came from the options or from a file */
+export declare function checkStorageStateObject(state: Record<string, unknown>): void;
+/** The options after `layers` are applied in order: a later layer wins, key by key */
+export declare function mergeUse(layers: readonly UseOptions[]): UseOptions;
+/** Checks the new options of a config's `use` */
+export declare function validateUseConfig(config: SamuraiTestConfig): void;
+/** The options of `test.use()` that a config's `use` holds, without the rest (`viewport`, `headless`, ...) */
+export declare function useOptionsOf(configUse: object | undefined): UseOptions;

package/dist/config/use-options.js

@@ -0,0 +1,128 @@
+const NAMES = [
+    "locale",
+    "timezoneId",
+    "userAgent",
+    "javaScriptEnabled",
+    "acceptInsecureCerts",
+    "hasTouch",
+    "isMobile",
+    "storageState",
+    "extraHTTPHeaders",
+    "colorScheme",
+];
+const BOOLEANS = [
+    "javaScriptEnabled",
+    "acceptInsecureCerts",
+    "hasTouch",
+    "isMobile",
+];
+const COLOR_SCHEMES = ["light", "dark", "no-preference"];
+const HEADER_NAME = /^[\w!#$%&'*+.^`|~-]+$/;
+const fail = (problem) => {
+    throw new TypeError(`use(): ${problem}`);
+};
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * Checks the options of `test.use()` or of the config's `use` and returns them. The config's `use` also holds
+ * options that are not these (`viewport`, `headless`, ...), so it passes `allowOthers`; `test.use()` refuses
+ * a key it does not know. Throws `use(): what is wrong`.
+ */
+export function validateUseOptions(options, allowOthers = false) {
+    if (!isObject(options))
+        return fail("the options must be an object");
+    for (const key of Object.keys(options))
+        if (!allowOthers && !NAMES.includes(key))
+            fail(`unknown option "${key}"`);
+    const use = options;
+    for (const name of BOOLEANS)
+        if (use[name] !== undefined && typeof use[name] !== "boolean")
+            fail(`${name} must be true or false, got ${JSON.stringify(use[name])}`);
+    checkLocale(use.locale);
+    checkTimezone(use.timezoneId);
+    if (use.userAgent !== undefined && !nonEmpty(use.userAgent))
+        fail("userAgent must be a non-empty string");
+    if (use.colorScheme !== undefined && !COLOR_SCHEMES.includes(use.colorScheme))
+        fail(`colorScheme must be "light", "dark" or "no-preference", got ${JSON.stringify(use.colorScheme)}`);
+    checkHeaders(use.extraHTTPHeaders);
+    checkStorageState(use.storageState);
+    return use;
+}
+const nonEmpty = (value) => typeof value === "string" && value !== "";
+function checkLocale(locale) {
+    if (locale === undefined)
+        return;
+    try {
+        if (!nonEmpty(locale) || Intl.getCanonicalLocales(locale).length !== 1)
+            throw new RangeError();
+    }
+    catch {
+        fail(`invalid locale ${JSON.stringify(locale)}`);
+    }
+}
+function checkTimezone(timezone) {
+    if (timezone === undefined)
+        return;
+    try {
+        if (!nonEmpty(timezone))
+            throw new RangeError();
+        new Intl.DateTimeFormat(undefined, { timeZone: timezone });
+    }
+    catch {
+        fail(`unknown timezoneId ${JSON.stringify(timezone)}`);
+    }
+}
+function checkHeaders(headers) {
+    if (headers === undefined)
+        return;
+    if (!isObject(headers))
+        fail("extraHTTPHeaders must be an object of header names and values");
+    for (const [name, value] of Object.entries(headers))
+        if (!HEADER_NAME.test(name))
+            fail(`extraHTTPHeaders has an invalid header name "${name}"`);
+        else if (typeof value !== "string")
+            fail(`extraHTTPHeaders "${name}" must be a string`);
+}
+function checkStorageState(state) {
+    if (state === undefined)
+        return;
+    if (typeof state === "string") {
+        if (state === "")
+            fail("storageState must not be an empty path");
+        return;
+    }
+    if (!isObject(state))
+        return fail("storageState must be a file path or an object");
+    checkStorageStateObject(state);
+}
+/** Checks a storage state object, whether it came from the options or from a file */
+export function checkStorageStateObject(state) {
+    for (const key of ["cookies", "origins"])
+        if (state[key] !== undefined && !Array.isArray(state[key]))
+            fail(`storageState.${key} must be an array`);
+    for (const cookie of (state.cookies ?? [])) {
+        if (!isObject(cookie) ||
+            !nonEmpty(cookie.name) ||
+            typeof cookie.value !== "string" ||
+            !nonEmpty(cookie.domain))
+            fail("every storageState cookie needs a name, a value and a domain");
+    }
+    for (const origin of (state.origins ?? [])) {
+        if (!isObject(origin) ||
+            !nonEmpty(origin.origin) ||
+            !Array.isArray(origin.localStorage ?? []))
+            fail("every storageState origin needs an origin and a localStorage list");
+    }
+}
+/** The options after `layers` are applied in order: a later layer wins, key by key */
+export function mergeUse(layers) {
+    return Object.assign({}, ...layers);
+}
+/** Checks the new options of a config's `use` */
+export function validateUseConfig(config) {
+    if (config.use !== undefined)
+        validateUseOptions(config.use, true);
+}
+/** The options of `test.use()` that a config's `use` holds, without the rest (`viewport`, `headless`, ...) */
+export function useOptionsOf(configUse) {
+    return Object.fromEntries(Object.entries(configUse ?? {}).filter(([key]) => NAMES.includes(key)));
+}

package/dist/logger/warn-once.d.ts

@@ -0,0 +1,4 @@
+/** Logs a warning the first time `key` is seen in this process; later calls with the same key do nothing */
+export declare function warnOnce(key: string, message: string): void;
+/** Forgets what was warned about (tests) */
+export declare function resetWarnOnce(): void;

package/dist/logger/warn-once.js

@@ -0,0 +1,13 @@
+import logger from "./index.js";
+const warned = new Set();
+/** Logs a warning the first time `key` is seen in this process; later calls with the same key do nothing */
+export function warnOnce(key, message) {
+    if (warned.has(key))
+        return;
+    warned.add(key);
+    logger.warn(message);
+}
+/** Forgets what was warned about (tests) */
+export function resetWarnOnce() {
+    warned.clear();
+}

package/dist/runner/attachments.d.ts

@@ -0,0 +1,16 @@
+/** What `testInfo.attach` takes besides the name */
+export interface AttachInput {
+    body?: string | Buffer;
+    path?: string;
+    contentType?: string;
+}
+/**
+ * Writes one attachment into `dir` and returns what to list: a body is saved under the cleaned name, a path is
+ * copied under it keeping its extension. `used` holds the file names taken so far; a repeat gets -2, -3, ...
+ * String bodies are masked like the rest of a report.
+ */
+export declare function saveAttachment(dir: string, used: Set<string>, name: string, input: AttachInput): Promise<{
+    name: string;
+    contentType: string;
+    path: string;
+}>;

package/dist/runner/attachments.js

@@ -0,0 +1,60 @@
+import { copyFile, mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { cleanName } from "../browser/evidence.js";
+import { maskText } from "../config/mask.js";
+/** The file types an attachment is known by; the rest is `application/octet-stream` */
+const TYPES = {
+    ".txt": "text/plain",
+    ".log": "text/plain",
+    ".html": "text/html",
+    ".json": "application/json",
+    ".csv": "text/csv",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webm": "video/webm",
+    ".pdf": "application/pdf",
+    ".zip": "application/zip",
+};
+const OCTET = "application/octet-stream";
+/** The extension (with its dot) that stands for `contentType`, else `fallback` */
+function extensionOf(contentType, fallback) {
+    const found = Object.entries(TYPES).find(([, type]) => type === contentType);
+    return found ? found[0] : fallback;
+}
+/**
+ * Writes one attachment into `dir` and returns what to list: a body is saved under the cleaned name, a path is
+ * copied under it keeping its extension. `used` holds the file names taken so far; a repeat gets -2, -3, ...
+ * String bodies are masked like the rest of a report.
+ */
+export async function saveAttachment(dir, used, name, input) {
+    if (name === "")
+        throw new Error("attach(): name must not be empty");
+    const { body, path: from } = input;
+    if (body === undefined && from === undefined)
+        throw new Error("attach(): give either body or path");
+    if (body !== undefined && from !== undefined)
+        throw new Error("attach(): give either body or path, not both");
+    const fileExt = from !== undefined ? path.extname(from).toLowerCase() : "";
+    const contentType = input.contentType ??
+        (from !== undefined
+            ? (TYPES[fileExt] ?? OCTET)
+            : typeof body === "string"
+                ? "text/plain"
+                : OCTET);
+    const ext = fileExt !== ""
+        ? fileExt
+        : extensionOf(contentType, typeof body === "string" ? ".txt" : ".bin");
+    const base = cleanName(name);
+    let unique = base;
+    for (let n = 2; used.has(unique); n++)
+        unique = `${base}-${n}`;
+    used.add(unique);
+    const file = path.join(dir, `${unique}${ext}`);
+    await mkdir(dir, { recursive: true });
+    if (from !== undefined)
+        await copyFile(from, file);
+    else
+        await writeFile(file, typeof body === "string" ? maskText(body) : body);
+    return { name, contentType, path: file };
+}

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

@@ -0,0 +1,15 @@
+/** What a function asks for in the destructuring of its first parameter */
+export type Requested = {
+    kind: "names";
+    names: string[];
+    rest: boolean;
+}
+/** No destructuring pattern: the function takes the fixtures object whole, or none */
+ | {
+    kind: "opaque";
+};
+/**
+ * The fixture names a function destructures from its first parameter (`async ({ page, user }) => ...`), read
+ * from its source. A `...rest` entry asks for everything.
+ */
+export declare function requestedBy(fn: (...args: never[]) => unknown): Requested;

package/dist/runner/fixture-args.js

@@ -0,0 +1,95 @@
+const OPAQUE = { kind: "opaque" };
+/** Where the `}` or `)` that closes the bracket at `from` is, skipping strings; -1 when there is none */
+function closing(text, from) {
+    let depth = 0;
+    for (let i = from; i < text.length; i++) {
+        const c = text[i];
+        if (c === '"' || c === "'" || c === "`") {
+            i = endOfString(text, i);
+            if (i < 0)
+                return -1;
+        }
+        else if (c === "{" || c === "(" || c === "[")
+            depth++;
+        else if (c === "}" || c === ")" || c === "]") {
+            depth--;
+            if (depth === 0)
+                return i;
+        }
+    }
+    return -1;
+}
+function endOfString(text, from) {
+    const quote = text[from];
+    for (let i = from + 1; i < text.length; i++) {
+        if (text[i] === "\\")
+            i++;
+        else if (text[i] === quote)
+            return i;
+    }
+    return -1;
+}
+/** Splits at the commas that sit outside brackets and strings */
+function topLevelParts(text) {
+    const parts = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        if (c === '"' || c === "'" || c === "`") {
+            const end = endOfString(text, i);
+            if (end < 0)
+                break;
+            i = end;
+        }
+        else if (c === "{" || c === "(" || c === "[")
+            depth++;
+        else if (c === "}" || c === ")" || c === "]")
+            depth--;
+        else if (c === "," && depth === 0) {
+            parts.push(text.slice(start, i));
+            start = i + 1;
+        }
+    }
+    parts.push(text.slice(start));
+    return parts.map((part) => part.trim()).filter((part) => part !== "");
+}
+/** The property a destructuring entry reads: `a`, `a: b`, `a = 1`, `"a-b": c`; undefined for a computed key */
+function keyOf(entry) {
+    const quoted = /^(["'])(.*?)\1/.exec(entry);
+    if (quoted)
+        return quoted[2];
+    return /^[\w$]+/.exec(entry)?.[0];
+}
+/**
+ * The fixture names a function destructures from its first parameter (`async ({ page, user }) => ...`), read
+ * from its source. A `...rest` entry asks for everything.
+ */
+export function requestedBy(fn) {
+    const text = Function.prototype.toString.call(fn);
+    if (/^(async\s+)?[\w$]+\s*=>/.test(text))
+        return OPAQUE;
+    const open = text.indexOf("(");
+    if (open < 0)
+        return OPAQUE;
+    let at = open + 1;
+    while (/\s/.test(text[at] ?? ""))
+        at++;
+    if (text[at] === ")")
+        return { kind: "names", names: [], rest: false };
+    if (text[at] !== "{")
+        return OPAQUE;
+    const end = closing(text, at);
+    if (end < 0)
+        return OPAQUE;
+    const names = [];
+    let rest = false;
+    for (const entry of topLevelParts(text.slice(at + 1, end))) {
+        const key = entry.startsWith("...") ? undefined : keyOf(entry);
+        if (key === undefined)
+            rest = true;
+        else
+            names.push(key);
+    }
+    return { kind: "names", names, rest };
+}

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

@@ -0,0 +1,22 @@
+/** 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 {
+    name: string;
+    auto: boolean;
+    deps: string[];
+    setup?: FixtureSetup;
+    value?: unknown;
+}
+/** Every custom fixture by name; the last definition of a name wins, the ones before it are what it may depend on by its own name */
+export type FixtureLayers = ReadonlyMap<string, readonly FixtureDef[]>;
+/** The fixtures the runner builds for every test: a custom fixture of the same name overrides it */
+export declare const BUILT_IN_FIXTURES: ReadonlySet<string>;
+/** Where a dependency of `name` (at definition `level`) comes from: another definition, or the built-in fixture */
+export declare function dependencyOf(layers: FixtureLayers, name: string, level: number, dep: string): {
+    name: string;
+    level: number;
+} | "built-in" | undefined;
+/** The fixtures after `test.extend(definitions)` on a test that has `base`; throws `extend(): ...` for a definition that cannot work */
+export declare function extendLayers(base: FixtureLayers | undefined, definitions: unknown): FixtureLayers;
+export {};

package/dist/runner/fixture-defs.js

@@ -0,0 +1,103 @@
+import { requestedBy } from "./fixture-args.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",
+    "browser",
+    "browserName",
+    "workerIndex",
+    "env",
+    "secrets",
+    "inputs",
+    "outputs",
+    "context",
+    "baseURL",
+    "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 }];
+    if (typeof fixture !== "function")
+        return { name, auto: options.auto, deps: [], value: fixture };
+    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,
+        deps: requested.names,
+        setup: fixture,
+    };
+}
+/** 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)
+        return level > 0
+            ? { name, level: level - 1 }
+            : BUILT_IN_FIXTURES.has(dep)
+                ? "built-in"
+                : undefined;
+    const defs = layers.get(dep);
+    if (defs)
+        return { name: dep, level: defs.length - 1 };
+    return BUILT_IN_FIXTURES.has(dep) ? "built-in" : undefined;
+}
+/** Throws for a dependency nobody defines and for a cycle (`a` needs `b` needs `a`) */
+function validate(layers) {
+    const done = new Set();
+    const walk = (name, level, path) => {
+        const key = `${name}#${level}`;
+        if (done.has(key))
+            return;
+        if (path.includes(key)) {
+            const loop = [...path.slice(path.indexOf(key)), key];
+            throw new Error(`extend(): fixtures depend on each other in a circle: ${loop.map((k) => k.split("#")[0]).join(" -> ")}`);
+        }
+        const def = layers.get(name)?.[level];
+        if (!def)
+            return;
+        for (const dep of def.deps) {
+            const target = dependencyOf(layers, name, level, dep);
+            if (target === undefined)
+                throw new Error(`extend(): fixture "${name}" depends on unknown fixture "${dep}"`);
+            if (target !== "built-in")
+                walk(target.name, target.level, [...path, key]);
+        }
+        done.add(key);
+    };
+    for (const [name, defs] of layers)
+        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) {
+    if (!isPlainObject(definitions))
+        throw new Error("extend(): needs an object of fixtures");
+    const layers = new Map(base);
+    for (const [name, raw] of Object.entries(definitions))
+        layers.set(name, [...(layers.get(name) ?? []), definitionOf(name, raw)]);
+    validate(layers);
+    return layers;
+}

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

@@ -0,0 +1,33 @@
+import type { TestFixtures } from "../types/test.js";
+import { type FixtureLayers } from "./fixture-defs.js";
+/** A custom fixture whose setup threw or never called `use` */
+export declare class FixtureSetupError extends Error {
+    constructor(name: string, cause: unknown);
+}
+/**
+ * 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 declare class FixtureScope {
+    private readonly layers;
+    private readonly base;
+    /** The built-in fixtures, with each custom fixture added (replacing a built-in of that name) once it is set up */
+    readonly fixtures: TestFixtures;
+    private readonly values;
+    private readonly pending;
+    private readonly started;
+    private closed;
+    constructor(layers: FixtureLayers, base: TestFixtures);
+    /** Sets up the fixtures marked `auto` */
+    prepareAuto(): Promise<void>;
+    /** Sets up the custom fixtures `fn` destructures from its first parameter */
+    prepare(fn: (...args: never[]) => unknown): Promise<void>;
+    /**
+     * 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.
+     */
+    teardown(limitMs: number): Promise<Error | undefined>;
+    private ensure;
+    private setUp;
+}