@itmetsam/samurai-framework 0.1.0 → 0.2.0

package/dist/browser/pdf.d.ts

@@ -0,0 +1,72 @@
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+/** Paper sizes in centimetres, as the browser wants them */
+declare const PAPER: {
+    readonly Letter: {
+        readonly width: 21.59;
+        readonly height: 27.94;
+    };
+    readonly Legal: {
+        readonly width: 21.59;
+        readonly height: 35.56;
+    };
+    readonly Tabloid: {
+        readonly width: 27.94;
+        readonly height: 43.18;
+    };
+    readonly Ledger: {
+        readonly width: 43.18;
+        readonly height: 27.94;
+    };
+    readonly A0: {
+        readonly width: 84.1;
+        readonly height: 118.9;
+    };
+    readonly A1: {
+        readonly width: 59.4;
+        readonly height: 84.1;
+    };
+    readonly A2: {
+        readonly width: 42;
+        readonly height: 59.4;
+    };
+    readonly A3: {
+        readonly width: 29.7;
+        readonly height: 42;
+    };
+    readonly A4: {
+        readonly width: 21;
+        readonly height: 29.7;
+    };
+    readonly A5: {
+        readonly width: 14.8;
+        readonly height: 21;
+    };
+    readonly A6: {
+        readonly width: 10.5;
+        readonly height: 14.8;
+    };
+};
+export type PaperFormat = keyof typeof PAPER;
+export interface PdfOptions {
+    /** Also write the PDF here (folders are created) */
+    path?: string;
+    landscape?: boolean;
+    /** 0.1 to 2 */
+    scale?: number;
+    /** Pages to print, e.g. `["1-3", 5]` */
+    pageRanges?: (string | number)[];
+    /** Page margins in centimetres */
+    margin?: {
+        top?: number;
+        bottom?: number;
+        left?: number;
+        right?: number;
+    };
+    /** Print background colours and images */
+    printBackground?: boolean;
+    /** Paper size. Without one the browser's default is used */
+    format?: PaperFormat;
+}
+/** Renders the page as a PDF and returns it (also written to `options.path`) */
+export declare function printPdf(connector: BiDiConnector, context: string, options?: PdfOptions): Promise<Buffer>;
+export {};

package/dist/browser/pdf.js

@@ -0,0 +1,37 @@
+import { writeOutput } from "./screenshot.js";
+/** Paper sizes in centimetres, as the browser wants them */
+const PAPER = {
+    Letter: { width: 21.59, height: 27.94 },
+    Legal: { width: 21.59, height: 35.56 },
+    Tabloid: { width: 27.94, height: 43.18 },
+    Ledger: { width: 43.18, height: 27.94 },
+    A0: { width: 84.1, height: 118.9 },
+    A1: { width: 59.4, height: 84.1 },
+    A2: { width: 42, height: 59.4 },
+    A3: { width: 29.7, height: 42 },
+    A4: { width: 21, height: 29.7 },
+    A5: { width: 14.8, height: 21 },
+    A6: { width: 10.5, height: 14.8 },
+};
+/** Renders the page as a PDF and returns it (also written to `options.path`) */
+export async function printPdf(connector, context, options = {}) {
+    const { scale, format } = options;
+    if (scale !== undefined && !(scale >= 0.1 && scale <= 2)) {
+        throw new RangeError("pdf(): scale must be between 0.1 and 2");
+    }
+    if (format !== undefined && !(format in PAPER)) {
+        throw new RangeError(`pdf(): unknown paper format "${format}"; use one of ${Object.keys(PAPER).join(", ")}`);
+    }
+    const { data } = await connector.send("browsingContext.print", {
+        context,
+        ...(options.landscape && { orientation: "landscape" }),
+        ...(scale !== undefined && { scale }),
+        ...(options.pageRanges && { pageRanges: options.pageRanges }),
+        ...(options.margin && { margin: options.margin }),
+        ...(options.printBackground && { background: true }),
+        ...(format && { page: { ...PAPER[format] } }),
+    });
+    const pdf = Buffer.from(data, "base64");
+    await writeOutput(options.path, pdf);
+    return pdf;
+}

package/dist/browser/screenshot.d.ts

@@ -0,0 +1,29 @@
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+export interface ScreenshotOptions {
+    /** Also write the image here (folders are created) */
+    path?: string;
+    /** The whole document instead of the viewport */
+    fullPage?: boolean;
+    /** Only this part: in viewport coordinates, or document coordinates with `fullPage` */
+    clip?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** @default "png" */
+    type?: "png" | "jpeg";
+    /** 0 to 100, jpeg only */
+    quality?: number;
+}
+/** The options a single element's screenshot takes: the image format and where to write it */
+export type ElementScreenshotOptions = Pick<ScreenshotOptions, "path" | "type" | "quality">;
+/**
+ * Captures the page (or, with `element`, that element) and returns the image. Writes it to `options.path` too.
+ * The browser answers Base64.
+ */
+export declare function takeScreenshot(connector: BiDiConnector, context: string, options?: ScreenshotOptions, element?: {
+    sharedId: string;
+}): Promise<Buffer>;
+/** Writes `data` to `file`, creating the folders; nothing happens without a path */
+export declare function writeOutput(file: string | undefined, data: Buffer): Promise<void>;

package/dist/browser/screenshot.js

@@ -0,0 +1,42 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+const MIME = { png: "image/png", jpeg: "image/jpeg" };
+/** The `format` of a capture command; validates the type/quality combination */
+function imageFormat({ type, quality }) {
+    if (quality !== undefined) {
+        if (type !== "jpeg")
+            throw new RangeError("screenshot(): quality only applies to jpeg");
+        if (!Number.isFinite(quality) || quality < 0 || quality > 100) {
+            throw new RangeError("screenshot(): quality must be between 0 and 100");
+        }
+    }
+    if (type === undefined)
+        return undefined;
+    return { type: MIME[type], ...(quality !== undefined && { quality: quality / 100 }) };
+}
+/**
+ * Captures the page (or, with `element`, that element) and returns the image. Writes it to `options.path` too.
+ * The browser answers Base64.
+ */
+export async function takeScreenshot(connector, context, options = {}, element) {
+    const format = imageFormat(options);
+    const clip = element
+        ? { type: "element", element: { sharedId: element.sharedId } }
+        : options.clip && { type: "box", ...options.clip };
+    const { data } = await connector.send("browsingContext.captureScreenshot", {
+        context,
+        ...(options.fullPage && { origin: "document" }),
+        ...(format && { format }),
+        ...(clip && { clip }),
+    });
+    const image = Buffer.from(data, "base64");
+    await writeOutput(options.path, image);
+    return image;
+}
+/** Writes `data` to `file`, creating the folders; nothing happens without a path */
+export async function writeOutput(file, data) {
+    if (!file)
+        return;
+    await mkdir(path.dirname(file), { recursive: true });
+    await writeFile(file, data);
+}

package/dist/cli/args.d.ts

@@ -0,0 +1,35 @@
+import type { ProjectOptions } from "../runner/run.js";
+/** The values a command line can override for one run */
+type RunOverrides = Pick<ProjectOptions, "environment" | "timeout" | "expectTimeout">;
+/** Flags and positional arguments of a command line; an unknown flag is an error */
+export declare function parseCommandLine(argv: string[]): {
+    values: {
+        env?: string | undefined;
+        timeout?: string | undefined;
+        "expect-timeout"?: string | undefined;
+        headless?: boolean | undefined;
+        port?: string | undefined;
+        grep?: string | undefined;
+        file?: string[] | undefined;
+        json?: boolean | undefined;
+        test?: string | undefined;
+        at?: string | undefined;
+        new?: string | undefined;
+        url?: string | undefined;
+        help?: boolean | undefined;
+        version?: boolean | undefined;
+    };
+    positionals: string[];
+};
+/** How the command line says tests are selected and the browser starts */
+export interface RunnerFlags {
+    headless?: boolean;
+    port?: number;
+    grep?: string;
+    files?: string[];
+}
+/** Reads `--headless`, `--port <n>`, `--grep <text>` and `--file <spec>` (repeatable) from `argv` */
+export declare function parseRunnerFlags(argv: string[]): RunnerFlags;
+/** Reads `--env`, `--timeout` and `--expect-timeout` from `argv`; the environment falls back to SAMURAI_ENV */
+export declare function parseRunOverrides(argv: string[], env?: Partial<NodeJS.ProcessEnv>): RunOverrides;
+export {};

package/dist/cli/args.js

@@ -0,0 +1,69 @@
+import { parseArgs } from "node:util";
+const FLAGS = {
+    env: { type: "string" },
+    timeout: { type: "string" },
+    "expect-timeout": { type: "string" },
+    headless: { type: "boolean" },
+    port: { type: "string" },
+    grep: { type: "string" },
+    file: { type: "string", multiple: true },
+    json: { type: "boolean" },
+    test: { type: "string" },
+    at: { type: "string" },
+    new: { type: "string" },
+    url: { type: "string" },
+    help: { type: "boolean", short: "h" },
+    version: { type: "boolean", short: "v" },
+};
+/** Flags and positional arguments of a command line; an unknown flag is an error */
+export function parseCommandLine(argv) {
+    return parseArgs({
+        args: argv,
+        options: FLAGS,
+        strict: true,
+        allowPositionals: true,
+    });
+}
+function parseFlags(argv) {
+    return parseCommandLine(argv).values;
+}
+/** Reads `--headless`, `--port <n>`, `--grep <text>` and `--file <spec>` (repeatable) from `argv` */
+export function parseRunnerFlags(argv) {
+    const values = parseFlags(argv);
+    const flags = {};
+    if (values.headless)
+        flags.headless = true;
+    if (values.port !== undefined) {
+        const port = Number(values.port);
+        if (!Number.isInteger(port) || port < 1 || port > 65535) {
+            throw new Error(`--port must be a port number between 1 and 65535, got "${values.port}"`);
+        }
+        flags.port = port;
+    }
+    if (values.grep !== undefined)
+        flags.grep = values.grep;
+    if (values.file?.length)
+        flags.files = values.file;
+    return flags;
+}
+/** Reads `--env`, `--timeout` and `--expect-timeout` from `argv`; the environment falls back to SAMURAI_ENV */
+export function parseRunOverrides(argv, env = {}) {
+    const values = parseFlags(argv);
+    const overrides = {};
+    const environment = values.env ?? env.SAMURAI_ENV;
+    if (environment)
+        overrides.environment = environment;
+    if (values.timeout !== undefined)
+        overrides.timeout = milliseconds("--timeout", values.timeout);
+    if (values["expect-timeout"] !== undefined) {
+        overrides.expectTimeout = milliseconds("--expect-timeout", values["expect-timeout"]);
+    }
+    return overrides;
+}
+function milliseconds(flag, raw) {
+    const value = Number(raw);
+    if (raw.trim() === "" || !Number.isInteger(value) || value < 0) {
+        throw new Error(`${flag} must be a whole number of milliseconds, got "${raw}"`);
+    }
+    return value;
+}

package/dist/cli/cli.cli-test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/cli.cli-test.js

@@ -0,0 +1,170 @@
+import assert from "node:assert/strict";
+import { existsSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { describe, it } from "node:test";
+import { ConsoleReporter } from "./console-reporter.js";
+import { initProject, scaffold } from "./init.js";
+import { main, USAGE } from "./main.js";
+function io() {
+    const out = [];
+    const err = [];
+    const target = {
+        out: (t) => out.push(t),
+        err: (t) => err.push(t),
+        color: false,
+        env: {},
+    };
+    return { target, out: () => out.join(""), err: () => err.join("") };
+}
+describe("main", () => {
+    it("prints the usage for --help, -h and help", async () => {
+        for (const argv of [["--help"], ["-h"], ["help"], ["run", "--help"]]) {
+            const { target, out } = io();
+            assert.equal(await main(argv, target), 0);
+            assert.equal(out(), USAGE);
+        }
+    });
+    it("prints the version", async () => {
+        const { target, out } = io();
+        assert.equal(await main(["--version"], target), 0);
+        assert.match(out(), /^\d+\.\d+\.\d+/);
+    });
+    it("exits 2 for an unknown command, with the usage", async () => {
+        const { target, err } = io();
+        assert.equal(await main(["bogus"], target), 2);
+        assert.match(err(), /Unknown command "bogus"/);
+        assert.match(err(), /Usage:/);
+    });
+    it("exits 2 for an unknown flag or a bad value, with a message", async () => {
+        const flag = io();
+        assert.equal(await main(["run", "--nope"], flag.target), 2);
+        assert.match(flag.err(), /nope/);
+        const port = io();
+        assert.equal(await main(["run", "--port", "abc"], port.target), 2);
+        assert.match(port.err(), /--port/);
+    });
+    it("exits 2 when the project has no config", async () => {
+        const dir = mkdtempSync(path.join(tmpdir(), "samurai-cli-"));
+        const previous = process.cwd();
+        process.chdir(dir);
+        try {
+            const { target, err } = io();
+            assert.equal(await main(["list"], target), 2);
+            assert.ok(err().length > 0);
+        }
+        finally {
+            process.chdir(previous);
+        }
+    });
+    it("record needs a spec and a sensible --at", async () => {
+        const none = io();
+        assert.equal(await main(["record"], none.target), 2);
+        assert.match(none.err(), /Which spec/);
+        const bad = io();
+        assert.equal(await main(["record", "a.spec.ts", "--at", "x"], bad.target), 2);
+        assert.match(bad.err(), /--at/);
+    });
+    it("record refuses a spec that does not exist unless --new is given", async () => {
+        const dir = mkdtempSync(path.join(tmpdir(), "samurai-cli-"));
+        writeFileSync(path.join(dir, "samurai.config.ts"), "export default {};");
+        const previous = process.cwd();
+        process.chdir(dir);
+        try {
+            const { target, err } = io();
+            assert.equal(await main(["record", "tests/none.spec.ts"], target), 2);
+            assert.match(err(), /does not exist/);
+        }
+        finally {
+            process.chdir(previous);
+        }
+    });
+    it("init scaffolds a project and never overwrites", async () => {
+        const dir = mkdtempSync(path.join(tmpdir(), "samurai-init-"));
+        writeFileSync(path.join(dir, "package.json"), '{"name":"mine"}');
+        const { target, out } = io();
+        assert.equal(await main(["init", dir], target), 0);
+        assert.match(out(), /kept\s+package\.json/);
+        assert.match(out(), /created samurai\.config\.ts/);
+        assert.equal(readFileSync(path.join(dir, "package.json"), "utf8"), '{"name":"mine"}');
+        for (const file of [
+            "samurai.config.ts",
+            "tests/example.spec.ts",
+            ".env.example",
+            ".gitignore",
+        ]) {
+            assert.ok(existsSync(path.join(dir, file)), file);
+        }
+    });
+});
+describe("scaffold", () => {
+    it("is an ES module project with a test script", () => {
+        const manifest = JSON.parse(scaffold("shop")["package.json"]);
+        assert.equal(manifest.type, "module");
+        assert.equal(manifest.scripts.test, "samurai run");
+        assert.equal(manifest.name, "shop");
+    });
+    it("names the package after the folder, safely", () => {
+        const dir = mkdtempSync(path.join(tmpdir(), "My Shop!-"));
+        initProject(dir);
+        const manifest = JSON.parse(readFileSync(path.join(dir, "package.json"), "utf8"));
+        assert.match(manifest.name, /^[a-z0-9-]+$/);
+    });
+});
+describe("ConsoleReporter", () => {
+    const summary = {
+        status: "failed",
+        duration: 2300,
+        startTime: 0,
+        environment: "staging",
+        tests: [
+            {
+                name: "a",
+                file: "/x/a.spec.ts",
+                startTime: 0,
+                status: "success",
+                duration: 1000,
+            },
+            {
+                name: "b > c",
+                file: "/x/a.spec.ts",
+                startTime: 0,
+                status: "failed",
+                duration: 1300,
+                type: "error",
+                message: "boom\nsecond line",
+            },
+        ],
+    };
+    it("prints a line per test, the failures in full and a count", () => {
+        let text = "";
+        const reporter = new ConsoleReporter({
+            write: (t) => (text += t),
+            color: false,
+        });
+        reporter.handle({ type: "run-start", environment: "staging", total: 2 });
+        reporter.handle({ type: "test-start", name: "a", file: "/x/a.spec.ts" });
+        for (const result of summary.tests)
+            reporter.handle({
+                type: "test-end",
+                name: "name" in result ? result.name : "",
+                file: "/x/a.spec.ts",
+                result,
+            });
+        reporter.handle({ type: "run-end", summary });
+        assert.match(text, /Running 2 tests against staging/);
+        assert.match(text, /✔ a \(1\.0s\)/);
+        assert.match(text, /✖ b > c \(1\.3s\)/);
+        assert.match(text, /\n {4}boom\n {4}second line\n/);
+        assert.match(text, /1 failed, 1 passed \(2\.3s\)/);
+        assert.ok(!text.includes("\u001b"), "no colour codes when colour is off");
+    });
+    it("colours when asked to", () => {
+        let text = "";
+        new ConsoleReporter({ write: (t) => (text += t), color: true }).handle({
+            type: "run-end",
+            summary,
+        });
+        assert.ok(text.includes("\u001b[31m"));
+    });
+});

package/dist/cli/console-reporter.d.ts

@@ -0,0 +1,15 @@
+import type { RunEvent } from "../runner/run.js";
+export interface ConsoleReporterOptions {
+    write: (text: string) => void;
+    /** Colour with ANSI codes */
+    color: boolean;
+}
+/** Prints a run for a person: one line per test as it ends, then every failure in full and a count */
+export declare class ConsoleReporter {
+    private readonly write;
+    private readonly paint;
+    constructor({ write, color }: ConsoleReporterOptions);
+    handle(event: RunEvent): void;
+    private line;
+    private summary;
+}

package/dist/cli/console-reporter.js

@@ -0,0 +1,52 @@
+const seconds = (ms) => `${(ms / 1000).toFixed(1)}s`;
+/** Prints a run for a person: one line per test as it ends, then every failure in full and a count */
+export class ConsoleReporter {
+    constructor({ write, color }) {
+        this.write = write;
+        this.paint = (code, text) => color ? `\u001b[${code}m${text}\u001b[0m` : text;
+    }
+    handle(event) {
+        switch (event.type) {
+            case "run-start":
+                this.write(`Running ${event.total} ${event.total === 1 ? "test" : "tests"} against ${event.environment}\n`);
+                return;
+            case "test-end":
+                this.write(`  ${this.line(event.name, event.result)}\n`);
+                return;
+            case "run-end":
+                this.summary(event.summary);
+                return;
+            case "test-start":
+                return;
+        }
+    }
+    line(name, result) {
+        const took = "duration" in result
+            ? ` ${this.paint(90, `(${seconds(result.duration)})`)}`
+            : "";
+        return result.status === "success"
+            ? `${this.paint(32, "✔")} ${name}${took}`
+            : `${this.paint(31, "✖")} ${name}${took}`;
+    }
+    summary(summary) {
+        const failed = summary.tests.filter((test) => test.status !== "success");
+        for (const test of failed) {
+            if (!("name" in test))
+                continue;
+            const message = "message" in test ? test.message : "did not finish";
+            this.write(`\n${this.paint(31, `${test.name}`)}\n`);
+            this.write(`${message
+                .split("\n")
+                .map((line) => `    ${line}`)
+                .join("\n")}\n`);
+            if ("file" in test)
+                this.write(`    ${this.paint(90, test.file)}\n`);
+        }
+        const passed = summary.tests.length - failed.length;
+        const parts = [
+            failed.length > 0 && this.paint(31, `${failed.length} failed`),
+            this.paint(32, `${passed} passed`),
+        ].filter(Boolean);
+        this.write(`\n${parts.join(", ")} ${this.paint(90, `(${seconds(summary.duration)})`)}\n`);
+    }
+}

package/dist/cli/init.d.ts

@@ -0,0 +1,7 @@
+/** The files `samurai init` writes, by path relative to the project folder */
+export declare function scaffold(name: string): Record<string, string>;
+/** Writes the scaffold into `dir`, never overwriting a file. Returns what was written and what was left alone */
+export declare function initProject(dir: string): {
+    written: string[];
+    skipped: string[];
+};

package/dist/cli/init.js

@@ -0,0 +1,61 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+const PACKAGE = "@itmetsam/samurai-framework";
+/** The files `samurai init` writes, by path relative to the project folder */
+export function scaffold(name) {
+    return {
+        "package.json": JSON.stringify({
+            name,
+            version: "0.1.0",
+            private: true,
+            type: "module",
+            scripts: { test: "samurai run" },
+            dependencies: { [PACKAGE]: "^0.1.0" },
+            devDependencies: { tsx: "^4.21.0" },
+        }, null, 2) + "\n",
+        "samurai.config.ts": `import { defineConfig } from "${PACKAGE}";
+
+export default defineConfig({
+  srcDir: "./tests",
+  browser: "firefox",
+  timeout: 30000,
+  environments: {
+    local: { baseURL: "http://localhost:3000" },
+  },
+  defaultEnvironment: "local",
+});
+`,
+        "tests/example.spec.ts": `import { expect, test } from "${PACKAGE}";
+
+test("example.com has its heading", async ({ page }) => {
+  await page.goto("https://example.com");
+  await expect(page.getByRole("heading", { name: "Example Domain" })).toBeVisible();
+});
+`,
+        ".env.example": `# Copy to .env.<environment>, e.g. .env.local. Never commit real values.
+# Tests read these as secrets.TEST_PASSWORD; real environment variables win over this file.
+SAMURAI_SECRET_TEST_PASSWORD=
+`,
+        ".gitignore": "node_modules\nresult\nlogs\nbrowsers\n.env\n.env.*\n!.env.example\n",
+    };
+}
+/** Writes the scaffold into `dir`, never overwriting a file. Returns what was written and what was left alone */
+export function initProject(dir) {
+    const root = path.resolve(dir);
+    const written = [];
+    const skipped = [];
+    for (const [file, content] of Object.entries(scaffold(path
+        .basename(root)
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-") || "samurai-tests"))) {
+        const target = path.join(root, file);
+        if (existsSync(target)) {
+            skipped.push(file);
+            continue;
+        }
+        mkdirSync(path.dirname(target), { recursive: true });
+        writeFileSync(target, content);
+        written.push(file);
+    }
+    return { written, skipped };
+}

package/dist/cli/main.d.ts

@@ -0,0 +1,12 @@
+export declare const USAGE = "samurai: browser tests over WebDriver BiDi\n\nUsage:\n  samurai run [options]       Run the tests (the default command)\n  samurai list [options]      List the tests without running them\n  samurai record <spec>       Open a browser and record what you do into a spec file\n  samurai init [folder]       Scaffold a project: config, an example test, .env.example\n\nOptions for run and list:\n  --env <name>                Environment to run against (or SAMURAI_ENV)\n  --file <spec>               Only this spec file; repeatable\n  --grep <text>               Only tests whose full name contains the text\n  --json                      Machine-readable output: JSON lines for run, one array for list\n\nOptions for run:\n  --timeout <ms>              Time one test may take\n  --expect-timeout <ms>       Time actions and assertions retry\n  --headless                  Run the browser without a window\n  --port <n>                  Browser debugging port (default 9223)\n\nOptions for record (also --env, --port, --json):\n  --new <title>               Add a test with this title (creates the spec file if needed)\n  --test <name|index>         Record into this test; not needed when the file has one\n  --at <n>                    Insert from step n (default: after the last step)\n  --url <url>                 Page to start on (default: the environment's baseURL)\n  Stop with Ctrl+C or by closing the browser window.\n\n  -h, --help                  Show this help\n  -v, --version               Show the version\n\nExit code: 0 when every test passed, 1 when a test failed, 2 for a usage or configuration error.\nRun it in the project folder, the one holding samurai.config.ts.\n";
+export interface Io {
+    out: (text: string) => void;
+    err: (text: string) => void;
+    /** Whether output goes to a terminal that shows colours */
+    color: boolean;
+    env: Partial<NodeJS.ProcessEnv>;
+    /** Aborts a recording (Ctrl+C) */
+    signal?: AbortSignal;
+}
+/** The command line as `samurai` runs it. Returns the exit code */
+export declare function main(argv: string[], io: Io): Promise<number>;