@itmetsam/samurai-framework 0.21.4 → 0.22.0

package/dist/request/http-transport.d.ts

@@ -0,0 +1,31 @@
+import type { HeaderEntry } from "./api-response.js";
+/** One request to send, a single hop: redirects are the caller's business */
+export interface HopRequest {
+    url: URL;
+    method: string;
+    /** Names lower-cased */
+    headers: Record<string, string>;
+    body?: Buffer | undefined;
+    ignoreHTTPSErrors: boolean;
+    /** Milliseconds this hop may take; 0 is no limit */
+    timeout: number;
+    signal: AbortSignal;
+}
+export interface HopResponse {
+    status: number;
+    statusText: string;
+    headers: HeaderEntry[];
+    /** The `Set-Cookie` headers, one entry each */
+    setCookies: string[];
+    /** Decoded: `Content-Encoding` is already undone */
+    body: Buffer;
+}
+/** A request that failed before a response was complete */
+export declare class TransportError extends Error {
+    readonly code?: string | undefined;
+    constructor(message: string, code?: string | undefined);
+}
+/** The url without credentials or query: what an error may say about where the request went */
+export declare function describeURL(url: URL): string;
+/** Sends one request over `http` or `https` and reads the whole response. Errors never include header values. */
+export declare function sendHop(request: HopRequest): Promise<HopResponse>;

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/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 {};