@asrunjs/asrun 0.0.0-stage → 0.2.0

package/dist/lib/baselines.js

@@ -0,0 +1,108 @@
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadProfiles } from './profiles.js';
+import { listCaseFileIds } from './cases.js';
+import { ROOT, TESTS_DIR } from './paths.js';
+import { parseTargets, readCaseText } from './targets.js';
+export const snapshotsDir = (caseId) => path.join(TESTS_DIR, `${caseId}.spec.ts-snapshots`);
+/** Project-relative paths below `tests/` that git reports as new or modified. */
+export function gitChangedTests() {
+    try {
+        // `git status` prints paths relative to the repository root, which may be above this folder.
+        const top = execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd: ROOT, encoding: 'utf8' }).trim();
+        const out = execFileSync('git', ['status', '--porcelain', '--untracked-files=all', '--', 'tests'], { cwd: ROOT, encoding: 'utf8' });
+        return new Set(out
+            .split('\n')
+            .filter(Boolean)
+            .map((line) => path.relative(ROOT, path.join(top, line.slice(3).trim())).split(path.sep).join('/')));
+    }
+    catch {
+        return new Set();
+    }
+}
+/** The target a `toHaveScreenshot('<name>.png')` belongs to: the nearest `// target: T<n>` above it. */
+export function targetOfScreenshot(specText, name) {
+    const lines = specText.split('\n');
+    const at = lines.findIndex((line) => line.includes(`toHaveScreenshot('${name}.png'`) || line.includes(`toHaveScreenshot("${name}.png"`));
+    if (at < 0)
+        return null;
+    return /\/\/\s*target:\s*(T\d+)/.exec(lines.slice(Math.max(0, at - 4), at + 1).join('\n'))?.[1] ?? null;
+}
+/** The target of a PDF region check: its `name: '<name>'` is the baseline name without `-p<page>`; the target comment is above the call. */
+export function targetOfPdfRegion(specText, name) {
+    const lines = specText.split('\n');
+    const at = lines.findIndex((line) => line.includes(`name: '${name}'`) || line.includes(`name: "${name}"`));
+    if (at < 0)
+        return null;
+    return /\/\/\s*target:\s*(T\d+)/.exec(lines.slice(Math.max(0, at - 15), at + 1).join('\n'))?.[1] ?? null;
+}
+/** Splits `<name>-<profile-id>-<platform>.png` using the known profile ids (Playwright adds both). */
+export function parseBaselineName(file) {
+    const base = file.replace(/\.png$/i, '');
+    const beforePlatform = /^(.*)-[a-z0-9]+$/i.exec(base)?.[1];
+    if (!beforePlatform)
+        return { name: base, profile: null, env: null };
+    const profiles = loadProfiles();
+    const profile = profiles
+        .map((item) => item.id)
+        .sort((a, b) => b.length - a.length)
+        .find((id) => beforePlatform.endsWith(`-${id}`));
+    if (!profile)
+        return { name: base, profile: null, env: null };
+    return {
+        name: beforePlatform.slice(0, -profile.length - 1),
+        profile,
+        env: profiles.find((item) => item.id === profile)?.env ?? null,
+    };
+}
+/** The baselines of one case, or of every case (`caseIds` omitted). */
+export function listBaselines(caseIds, changedFiles = gitChangedTests()) {
+    const found = [];
+    for (const caseId of listCaseFileIds()) {
+        if (caseIds && !caseIds.includes(caseId))
+            continue;
+        const dir = snapshotsDir(caseId);
+        if (!fs.existsSync(dir))
+            continue;
+        const specFile = path.join(TESTS_DIR, `${caseId}.spec.ts`);
+        const specText = fs.existsSync(specFile) ? fs.readFileSync(specFile, 'utf8') : '';
+        const cards = parseTargets(readCaseText(caseId));
+        for (const file of fs.readdirSync(dir).filter((name) => name.toLowerCase().endsWith('.png')).sort()) {
+            const full = path.join(dir, file);
+            const rel = path.relative(ROOT, full).split(path.sep).join('/');
+            const { name, profile, env } = parseBaselineName(file);
+            const targetId = targetOfScreenshot(specText, name) ?? targetOfPdfRegion(specText, name.replace(/-p\d+$/, ''));
+            const card = cards.find((item) => item.id === targetId);
+            const stat = fs.statSync(full);
+            found.push({
+                caseId,
+                file,
+                rel,
+                profile,
+                env,
+                changed: changedFiles.has(rel),
+                size: stat.size,
+                mtimeMs: stat.mtimeMs,
+                targetId,
+                card: card
+                    ? {
+                        id: card.id,
+                        name: card.name,
+                        what: card.fields['what'] ?? null,
+                        where: card.fields['where'] ?? null,
+                        not: card.fields['not'] ?? null,
+                        pages: card.fields['pages'] ?? null,
+                        region: card.fields['region'] ?? null,
+                    }
+                    : null,
+                problem: !targetId
+                    ? 'The spec has no "// target: T<n>" for this screenshot, so nothing says what it must show.'
+                    : !card
+                        ? `${targetId} is not a card in "## Targets" of ${caseId}.`
+                        : null,
+            });
+        }
+    }
+    return found;
+}

package/dist/lib/case-id.d.ts

@@ -0,0 +1,11 @@
+export declare const NAME_PATTERN: RegExp;
+export declare const CASE_ID_PATTERN: RegExp;
+export declare const isValidCaseName: (name: string) => boolean;
+export declare const isValidCaseId: (id: string) => boolean;
+export declare function splitCaseId(id: string): {
+    group: string | null;
+    name: string;
+};
+export declare const joinCaseId: (group: string | null | undefined, name: string) => string;
+/** Folders between `tests/` and the spec; the import path to `lib/` is `../` times (depth + 1). */
+export declare const caseDepth: (id: string) => number;

package/dist/lib/case-id.js

@@ -0,0 +1,17 @@
+/**
+ * A case id is the path of its document below `cases/`, without `.md`: `hub-landing` or `documents/landing-page`.
+ * One optional folder level (the group). The spec of a case lives at the same path below `tests/`.
+ * No Node imports here: the web UI uses this file too.
+ */
+const WORD = '[a-z0-9]+(?:-[a-z0-9]+)*';
+export const NAME_PATTERN = new RegExp(`^${WORD}$`);
+export const CASE_ID_PATTERN = new RegExp(`^(?:${WORD}/)?${WORD}$`);
+export const isValidCaseName = (name) => NAME_PATTERN.test(name);
+export const isValidCaseId = (id) => CASE_ID_PATTERN.test(id);
+export function splitCaseId(id) {
+    const slash = id.indexOf('/');
+    return slash === -1 ? { group: null, name: id } : { group: id.slice(0, slash), name: id.slice(slash + 1) };
+}
+export const joinCaseId = (group, name) => (group ? `${group}/${name}` : name);
+/** Folders between `tests/` and the spec; the import path to `lib/` is `../` times (depth + 1). */
+export const caseDepth = (id) => (id.match(/\//g) ?? []).length;

package/dist/lib/case-ops.d.ts

@@ -0,0 +1,26 @@
+export declare class CaseError extends Error {
+    readonly status: 400 | 404 | 409;
+    constructor(message: string, status: 400 | 404 | 409);
+}
+export declare const caseFilePath: (id: string) => string;
+export declare const specFilePath: (id: string) => string;
+/** Playwright keeps the baseline images of a spec next to it, in `<spec file>-snapshots/`. */
+export declare const snapshotDirPath: (id: string) => string;
+export declare function assertValidNewId(id: string): void;
+/** Everything that belongs to one case besides its document. */
+export interface CaseImpact {
+    id: string;
+    caseFile: string;
+    specFile: string | null;
+    snapshotDir: string | null;
+    snapshotCount: number;
+}
+export declare function getCaseImpact(id: string): CaseImpact;
+/**
+ * What a spec says about its case: the document path, the id passed to `caseTags` / `configureCase` /
+ * `requireValues`, and the relative path to `lib/` (it depends on the folder depth).
+ */
+export declare function rewriteSpec(text: string, from: string, to: string): string;
+export declare function renameCase(from: string, to: string): CaseImpact;
+/** Deletes the document, the spec and the baseline images of one case. */
+export declare function deleteCase(id: string): CaseImpact;

package/dist/lib/case-ops.js

@@ -0,0 +1,110 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { caseDepth, isValidCaseId } from './case-id.js';
+import { listCaseFileIds } from './cases.js';
+import { CASES_DIR, ROOT, TESTS_DIR } from './paths.js';
+/** `memo` is the route of the "From memo" page of the web UI. */
+const RESERVED_IDS = ['memo'];
+export class CaseError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+export const caseFilePath = (id) => path.join(CASES_DIR, `${id}.md`);
+export const specFilePath = (id) => path.join(TESTS_DIR, `${id}.spec.ts`);
+/** Playwright keeps the baseline images of a spec next to it, in `<spec file>-snapshots/`. */
+export const snapshotDirPath = (id) => `${specFilePath(id)}-snapshots`;
+const relative = (file) => path.relative(ROOT, file).split(path.sep).join('/');
+export function assertValidNewId(id) {
+    if (!isValidCaseId(id)) {
+        throw new CaseError(`Invalid case id "${id}". Use lowercase words with dashes, optionally in one folder: "header-logo" or "documents/header-logo".`, 400);
+    }
+    if (RESERVED_IDS.includes(id))
+        throw new CaseError(`The id "${id}" is reserved.`, 400);
+}
+export function getCaseImpact(id) {
+    const spec = specFilePath(id);
+    const snapshots = snapshotDirPath(id);
+    const snapshotCount = fs.existsSync(snapshots) ? fs.readdirSync(snapshots, { recursive: true }).length : 0;
+    return {
+        id,
+        caseFile: relative(caseFilePath(id)),
+        specFile: fs.existsSync(spec) ? relative(spec) : null,
+        snapshotDir: fs.existsSync(snapshots) ? relative(snapshots) : null,
+        snapshotCount,
+    };
+}
+const writeAtomic = (file, text) => {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const temp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(temp, text);
+    fs.renameSync(temp, file);
+};
+/** Removes a group folder once its last file is gone. Never touches `cases/` or `tests/` themselves. */
+function pruneEmptyDir(dir, root) {
+    if (path.resolve(dir) === path.resolve(root) || !path.resolve(dir).startsWith(path.resolve(root)))
+        return;
+    if (fs.existsSync(dir) && fs.readdirSync(dir).length === 0)
+        fs.rmdirSync(dir);
+}
+function setFrontMatterId(text, id) {
+    const match = /^---\r?\n[\s\S]*?\r?\n---/.exec(text);
+    if (!match)
+        return text;
+    return match[0].replace(/^id:[ \t]*.*$/m, `id: ${id}`) + text.slice(match[0].length);
+}
+/**
+ * What a spec says about its case: the document path, the id passed to `caseTags` / `configureCase` /
+ * `requireValues`, and the relative path to `lib/` (it depends on the folder depth).
+ */
+export function rewriteSpec(text, from, to) {
+    const quoted = (value) => new RegExp(`(['"\`])${value.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&')}\\1`, 'g');
+    const result = text.replaceAll(`cases/${from}.md`, `cases/${to}.md`).replace(quoted(from), `$1${to}$1`);
+    const up = '../'.repeat(caseDepth(to) + 1);
+    return result.replace(/(\bfrom\s+['"]|\bimport\(\s*['"])\.\.\/(?:\.\.\/)*lib\//g, `$1${up}lib/`);
+}
+export function renameCase(from, to) {
+    assertValidNewId(to);
+    const ids = listCaseFileIds();
+    if (!isValidCaseId(from) || !ids.includes(from))
+        throw new CaseError(`Case "${from}" does not exist.`, 404);
+    if (from === to)
+        throw new CaseError('The new id is the same as the old one.', 400);
+    if (ids.includes(to))
+        throw new CaseError(`Case "${to}" already exists.`, 409);
+    for (const leftover of [specFilePath(to), snapshotDirPath(to)]) {
+        if (fs.existsSync(leftover)) {
+            throw new CaseError(`${relative(leftover)} already exists (a spec of a deleted case?). Remove it first.`, 409);
+        }
+    }
+    // Everything is checked; now move the files. New files first, the old ones are removed at the end.
+    const impact = getCaseImpact(from);
+    writeAtomic(caseFilePath(to), setFrontMatterId(fs.readFileSync(caseFilePath(from), 'utf8'), to));
+    if (impact.specFile) {
+        writeAtomic(specFilePath(to), rewriteSpec(fs.readFileSync(specFilePath(from), 'utf8'), from, to));
+    }
+    if (impact.snapshotDir) {
+        fs.mkdirSync(path.dirname(snapshotDirPath(to)), { recursive: true });
+        fs.renameSync(snapshotDirPath(from), snapshotDirPath(to));
+    }
+    fs.rmSync(caseFilePath(from));
+    if (impact.specFile)
+        fs.rmSync(specFilePath(from));
+    pruneEmptyDir(path.dirname(caseFilePath(from)), CASES_DIR);
+    pruneEmptyDir(path.dirname(specFilePath(from)), TESTS_DIR);
+    return getCaseImpact(to);
+}
+/** Deletes the document, the spec and the baseline images of one case. */
+export function deleteCase(id) {
+    if (!isValidCaseId(id) || !fs.existsSync(caseFilePath(id)))
+        throw new CaseError(`Case "${id}" does not exist.`, 404);
+    const impact = getCaseImpact(id);
+    fs.rmSync(caseFilePath(id));
+    fs.rmSync(specFilePath(id), { force: true });
+    fs.rmSync(snapshotDirPath(id), { recursive: true, force: true });
+    pruneEmptyDir(path.dirname(caseFilePath(id)), CASES_DIR);
+    pruneEmptyDir(path.dirname(specFilePath(id)), TESTS_DIR);
+    return impact;
+}

package/dist/lib/cases.d.ts

@@ -0,0 +1,29 @@
+/** The front matter of a case document that the tools care about. The case document is the single source of truth. */
+export interface CaseMeta {
+    id: string;
+    /** Suites the case belongs to, e.g. `['smoke', 'regression']`. A case runs in every suite it lists. */
+    suites: string[];
+    /**
+     * Environments in which the case may create or change data of the test accounts (and cleans it up), e.g.
+     * `['staging']`. Empty = the case never writes. In any other environment the case is skipped, not failed.
+     */
+    writes: string[];
+    /** What the case writes; required when `writes` is not empty. Shown to the person who confirms a production run. */
+    writesNote: string | null;
+    /** Environments the case may run in; `null` = all. */
+    envs: string[] | null;
+}
+/** Does the case write data at all (in some environment)? */
+export declare const caseWrites: (meta: CaseMeta) => boolean;
+/** May the case write data in this environment? A case that writes elsewhere only is skipped here. */
+export declare const caseWritesIn: (meta: CaseMeta, env: string) => boolean;
+/** Parses and validates the front matter. Throws an Error that starts with `label` and says what to fix. */
+export declare function parseCaseMeta(id: string, text: string, label?: string): CaseMeta;
+export declare const hasCaseFile: (caseId: string) => boolean;
+export declare function readCaseMeta(caseId: string): CaseMeta;
+/** Every case document except the template: `cases/<name>.md` and `cases/<group>/<name>.md` (one folder level). */
+export declare function listCaseFileIds(): string[];
+/** Playwright tags of a case: one `@<suite>` per suite, plus `@writes` for cases that write data. */
+export declare function caseTags(caseId: string): string[];
+/** Every distinct suite used by the cases. */
+export declare const listSuites: () => string[];

package/dist/lib/cases.js

@@ -0,0 +1,124 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse } from 'yaml';
+import { listEnvs } from './profiles.js';
+import { NAME_PATTERN } from './case-id.js';
+import { CASES_DIR } from './paths.js';
+const frontMatterOf = (text) => {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+    if (!match)
+        return null;
+    const value = parse(match[1]);
+    return value && typeof value === 'object' ? value : null;
+};
+function nameList(value, key, label) {
+    if (!Array.isArray(value) || value.length === 0 || value.some((item) => typeof item !== 'string' || !NAME_PATTERN.test(item))) {
+        throw new Error(`${label}: "${key}" must be a list of lowercase words (letters, digits, dashes), e.g. "${key}: [smoke, regression]"`);
+    }
+    const duplicate = value.find((item, i) => value.indexOf(item) !== i);
+    if (duplicate)
+        throw new Error(`${label}: "${key}" lists "${duplicate}" twice`);
+    return value;
+}
+/**
+ * `writes` is a list of environment names. Omitted, `none` or `[]` mean the case never writes. The old values
+ * `test-data` (and `staging` / `production` as a bare word) are refused with the fix, never guessed.
+ */
+function parseWrites(value, label) {
+    if (value === undefined || value === null || value === 'none')
+        return [];
+    if (value === 'test-data') {
+        throw new Error(`${label}: "writes: test-data" is the old form. List the environments instead, e.g. "writes: [staging]"`);
+    }
+    if (Array.isArray(value) && value.length === 0)
+        return [];
+    if (!Array.isArray(value)) {
+        throw new Error(`${label}: "writes" must be a list of environments, e.g. "writes: [staging]" (or omit it for read-only)`);
+    }
+    const writes = nameList(value, 'writes', label);
+    const known = listEnvs();
+    const unknown = writes.filter((env) => !known.includes(env));
+    if (unknown.length > 0) {
+        throw new Error(`${label}: unknown environment(s) in "writes": ${unknown.join(', ')}. Known: ${known.join(', ')}`);
+    }
+    return writes;
+}
+/** Does the case write data at all (in some environment)? */
+export const caseWrites = (meta) => meta.writes.length > 0;
+/** May the case write data in this environment? A case that writes elsewhere only is skipped here. */
+export const caseWritesIn = (meta, env) => meta.writes.includes(env);
+/** Parses and validates the front matter. Throws an Error that starts with `label` and says what to fix. */
+export function parseCaseMeta(id, text, label = `cases/${id}.md`) {
+    const front = frontMatterOf(text);
+    if (!front)
+        throw new Error(`${label}: the file must start with a front matter block (--- ... ---)`);
+    if (front.suites !== undefined && front.priority !== undefined) {
+        throw new Error(`${label}: use "suites: [...]" only; "priority" is the old name of the same setting`);
+    }
+    // `priority: smoke` is the old form of `suites: [smoke]`.
+    const suites = front.suites !== undefined
+        ? nameList(front.suites, 'suites', label)
+        : front.priority !== undefined
+            ? nameList([front.priority], 'priority', label)
+            : (() => {
+                throw new Error(`${label}: front matter needs "suites: [<suite>, ...]", e.g. "suites: [smoke, regression]"`);
+            })();
+    const note = front['writes-note'];
+    const writes = parseWrites(front.writes, label);
+    if (writes.length > 0 && (typeof note !== 'string' || note.trim() === '')) {
+        throw new Error(`${label}: "writes: [${writes.join(', ')}]" needs a "writes-note" that says what the case creates or changes`);
+    }
+    let envs = null;
+    if (front.envs !== undefined) {
+        envs = nameList(front.envs, 'envs', label);
+        const known = listEnvs();
+        const unknown = envs.filter((env) => !known.includes(env));
+        if (unknown.length > 0) {
+            throw new Error(`${label}: unknown environment(s) in "envs": ${unknown.join(', ')}. Known: ${known.join(', ')}`);
+        }
+    }
+    const unreachable = writes.filter((env) => envs !== null && !envs.includes(env));
+    if (unreachable.length > 0) {
+        throw new Error(`${label}: "writes" lists ${unreachable.join(', ')}, but "envs" does not run the case there`);
+    }
+    return {
+        id,
+        suites,
+        writes,
+        writesNote: typeof note === 'string' && note.trim() !== '' ? note.trim() : null,
+        envs,
+    };
+}
+const caseFile = (caseId) => path.join(CASES_DIR, `${caseId}.md`);
+export const hasCaseFile = (caseId) => fs.existsSync(caseFile(caseId));
+export function readCaseMeta(caseId) {
+    return parseCaseMeta(caseId, fs.readFileSync(caseFile(caseId), 'utf8'));
+}
+/** Every case document except the template: `cases/<name>.md` and `cases/<group>/<name>.md` (one folder level). */
+export function listCaseFileIds() {
+    const ids = [];
+    if (!fs.existsSync(CASES_DIR))
+        return ids;
+    const isCaseFile = (name) => name.endsWith('.md') && !name.startsWith('_');
+    for (const entry of fs.readdirSync(CASES_DIR, { withFileTypes: true })) {
+        if (entry.name.startsWith('_') || entry.name.startsWith('.'))
+            continue;
+        if (entry.isFile() && isCaseFile(entry.name)) {
+            ids.push(entry.name.slice(0, -3));
+        }
+        else if (entry.isDirectory()) {
+            for (const name of fs.readdirSync(path.join(CASES_DIR, entry.name))) {
+                if (isCaseFile(name))
+                    ids.push(`${entry.name}/${name.slice(0, -3)}`);
+            }
+        }
+    }
+    return ids.sort();
+}
+/** Playwright tags of a case: one `@<suite>` per suite, plus `@writes` for cases that write data. */
+export function caseTags(caseId) {
+    const meta = readCaseMeta(caseId);
+    return [...meta.suites.map((suite) => `@${suite}`), ...(caseWrites(meta) ? ['@writes'] : [])];
+}
+/** Every distinct suite used by the cases. */
+export const listSuites = () => [...new Set(listCaseFileIds().flatMap((id) => readCaseMeta(id).suites))].sort();

package/dist/lib/cli.d.ts

@@ -0,0 +1,10 @@
+/** Arguments shared by the single-profile commands: `<profile-id> [path]`. */
+export interface CliTarget {
+    profileId?: string;
+    /** Positional arguments after the profile id. */
+    rest: string[];
+    help: boolean;
+    /** Set when the caller passed `--env`; those commands do not need it (the profile has its env). */
+    envGiven: boolean;
+}
+export declare function parseCliTarget(args: string[]): CliTarget;

package/dist/lib/cli.js

@@ -0,0 +1,18 @@
+export function parseCliTarget(args) {
+    const positional = [];
+    let help = false;
+    let envGiven = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--help')
+            help = true;
+        else if (arg === '--env' || arg.startsWith('--env=')) {
+            envGiven = true;
+            if (arg === '--env')
+                i++;
+        }
+        else
+            positional.push(arg);
+    }
+    return { profileId: positional[0], rest: positional.slice(1), help, envGiven };
+}

package/dist/lib/downloads.d.ts

@@ -0,0 +1,42 @@
+import type { Page } from '@playwright/test';
+import { type PdfFile } from './pdf.js';
+export type DownloadKind = 'pdf' | 'png' | 'jpeg' | 'zip' | 'csv' | 'any';
+export interface DownloadOptions {
+    /** What the file must be; `any` only checks that it is not empty. */
+    kind?: DownloadKind;
+    /** The suggested file name must match. */
+    fileName?: RegExp;
+    /** Smallest plausible size in bytes. Default: 1 (a PDF: 500). */
+    minBytes?: number;
+    /** How long the download may take to start after the trigger, in ms. Default 30 s. */
+    startTimeout?: number;
+    /** How long it may take to finish once started, in ms. Default 120 s. */
+    finishTimeout?: number;
+    /** Extra check on the file; throw an Error with a plain message when it is not valid. */
+    validate?: (file: {
+        path: string;
+        bytes: Buffer;
+        fileName: string;
+    }) => void | Promise<void>;
+}
+export interface DownloadResult {
+    path: string;
+    fileName: string;
+    size: number;
+    bytes: Buffer;
+    /** `kind: 'pdf'` only: the opened PDF (its pages can be rendered and its text read), see `expectPdf` in `lib/pdf`. */
+    pdf?: PdfFile;
+}
+/**
+ * The one way a spec checks a download. Every stage has its own plain error, and any failure or timeout fails the
+ * whole verification:
+ *   1. the download starts after `trigger` (the browser reports it),
+ *   2. the download finishes,
+ *   3. the file exists and has content,
+ *   4. the file is valid for its kind (and for `validate`, when given). A PDF must open and have pages; its content is
+ *      then checked by reading it like a person, with `expectPdf(file.pdf!, {...})` from `lib/pdf`: every page is
+ *      rendered to an image, the logo areas are compared with the profile's baseline, the extracted text is checked.
+ *
+ *   const file = await verifyDownload(page, () => option.click(), {kind: 'pdf'});
+ */
+export declare function verifyDownload(page: Page, trigger: () => Promise<unknown>, options?: DownloadOptions): Promise<DownloadResult>;

package/dist/lib/downloads.js

@@ -0,0 +1,84 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { openPdf } from './pdf.js';
+const fail = (message) => {
+    throw new Error(message);
+};
+const startsWith = (bytes, signature) => signature.every((byte, index) => bytes[index] === byte);
+/** Content checks per kind: magic bytes first, then the structure that proves the file was written completely. */
+function checkKind(kind, bytes, fileName) {
+    if (kind === 'pdf') {
+        if (bytes.subarray(0, 5).toString('latin1') !== '%PDF-')
+            fail(`The downloaded file "${fileName}" is not a PDF (it does not start with %PDF-)`);
+        if (!bytes.subarray(Math.max(0, bytes.length - 2048)).toString('latin1').includes('%%EOF')) {
+            fail(`The downloaded PDF "${fileName}" is cut off (it has no end marker)`);
+        }
+    }
+    else if (kind === 'png') {
+        if (!startsWith(bytes, [0x89, 0x50, 0x4e, 0x47]))
+            fail(`The downloaded file "${fileName}" is not a PNG image`);
+    }
+    else if (kind === 'jpeg') {
+        if (!startsWith(bytes, [0xff, 0xd8, 0xff]))
+            fail(`The downloaded file "${fileName}" is not a JPEG image`);
+    }
+    else if (kind === 'zip') {
+        if (!startsWith(bytes, [0x50, 0x4b]))
+            fail(`The downloaded file "${fileName}" is not a ZIP-based file`);
+    }
+    else if (kind === 'csv') {
+        const head = bytes.subarray(0, 4096).toString('utf8');
+        if (head.includes('\u0000') || head.trim() === '')
+            fail(`The downloaded file "${fileName}" is not a text (CSV) file`);
+    }
+}
+/**
+ * The one way a spec checks a download. Every stage has its own plain error, and any failure or timeout fails the
+ * whole verification:
+ *   1. the download starts after `trigger` (the browser reports it),
+ *   2. the download finishes,
+ *   3. the file exists and has content,
+ *   4. the file is valid for its kind (and for `validate`, when given). A PDF must open and have pages; its content is
+ *      then checked by reading it like a person, with `expectPdf(file.pdf!, {...})` from `lib/pdf`: every page is
+ *      rendered to an image, the logo areas are compared with the profile's baseline, the extracted text is checked.
+ *
+ *   const file = await verifyDownload(page, () => option.click(), {kind: 'pdf'});
+ */
+export async function verifyDownload(page, trigger, options = {}) {
+    const { kind = 'any', fileName: namePattern, startTimeout = 30_000, finishTimeout = 120_000, validate } = options;
+    const minBytes = options.minBytes ?? (kind === 'pdf' ? 500 : 1);
+    // 1. Start. The waiter exists before the trigger, so a fast download is not missed.
+    const started = page.waitForEvent('download', { timeout: startTimeout }).then((download) => ({ download, error: null }), () => ({ download: null, error: new Error(`The download did not start within ${startTimeout / 1000}s after clicking`) }));
+    await trigger();
+    const { download, error } = await started;
+    if (!download)
+        throw error;
+    const fileName = download.suggestedFilename();
+    if (namePattern && !namePattern.test(fileName)) {
+        fail(`The download has an unexpected file name "${fileName}" (expected to match ${namePattern})`);
+    }
+    // 2. Finish. `path()` resolves when the file is complete; `failure()` says why it was not.
+    let timer;
+    const filePath = await Promise.race([
+        download.path(),
+        new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`The download "${fileName}" did not finish within ${finishTimeout / 1000}s`)), finishTimeout);
+        }),
+    ]).finally(() => clearTimeout(timer));
+    const failure = await download.failure();
+    if (failure)
+        fail(`The download "${fileName}" failed: ${failure}`);
+    if (!filePath)
+        fail(`The download "${fileName}" produced no file`);
+    // 3. The file exists and has content.
+    if (!fs.existsSync(filePath))
+        fail(`The downloaded file "${fileName}" does not exist on disk`);
+    const bytes = fs.readFileSync(filePath);
+    if (bytes.length < minBytes)
+        fail(`The downloaded file "${fileName}" is too small (${bytes.length} bytes, expected at least ${minBytes})`);
+    // 4. Valid for its kind.
+    checkKind(kind, bytes, fileName);
+    const pdf = kind === 'pdf' ? await openPdf(bytes) : undefined;
+    await validate?.({ path: filePath, bytes, fileName: path.basename(fileName) });
+    return { path: filePath, fileName, size: bytes.length, bytes, pdf };
+}

package/dist/lib/email.d.ts

@@ -0,0 +1,10 @@
+import type { Profile } from './profiles.js';
+/** Tests never send email in production. In other environments only when a real mailbox is connected (`email: true`). */
+export declare const emailAllowed: (profile: Profile) => boolean;
+/**
+ * Call at the start of a step that sends email. Returns false, and records the skip in the report, when
+ * email must not be sent here; the step then does nothing.
+ *
+ *   if (!emailStepAllowed(profile, '5. Send the document to the recipient')) return;
+ */
+export declare function emailStepAllowed(profile: Profile, stepTitle: string): boolean;

package/dist/lib/email.js

@@ -0,0 +1,19 @@
+import { test } from '@playwright/test';
+/** Tests never send email in production. In other environments only when a real mailbox is connected (`email: true`). */
+export const emailAllowed = (profile) => profile.env !== 'production' && profile.email;
+/**
+ * Call at the start of a step that sends email. Returns false, and records the skip in the report, when
+ * email must not be sent here; the step then does nothing.
+ *
+ *   if (!emailStepAllowed(profile, '5. Send the document to the recipient')) return;
+ */
+export function emailStepAllowed(profile, stepTitle) {
+    if (emailAllowed(profile))
+        return true;
+    const reason = profile.env === 'production'
+        ? 'email is never sent in production'
+        : `email is off for ${profile.id} (${profile.env}) (no mailbox connected: email: false in profiles.yaml)`;
+    test.info().annotations.push({ type: 'email-step-skipped', description: `${stepTitle}: ${reason}` });
+    console.log(`  skipped email step "${stepTitle}": ${reason}`);
+    return false;
+}

package/dist/lib/ffmpeg.d.ts

@@ -0,0 +1,8 @@
+/** The system `ffmpeg` if there is one, else the binary of the optional `ffmpeg-static` package, else null. */
+export declare function findFfmpeg(): string | null;
+/**
+ * Joins `inputs` (in order) into one webm at `output`. Re-encodes on purpose: Playwright's recordings have loose
+ * timestamps, and copying the streams gives files with a wrong duration that cannot be seeked.
+ * Returns an error message, or null on success.
+ */
+export declare function concatVideos(inputs: string[], output: string): string | null;