@asrunjs/asrun 0.0.0-stage → 0.5.2

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,16 @@
+import { type CaseMeta } from './case-doc.js';
+export type { CaseMeta } from './case-doc.js';
+/** 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,51 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseCaseFrontMatter, validateCaseMeta } from './case-doc.js';
+import { listEnvs } from './profiles.js';
+import { CASES_DIR } from './paths.js';
+/** 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 = parseCaseFrontMatter(text);
+    if (!front)
+        throw new Error(`${label}: the file must start with a front matter block (--- ... ---)`);
+    if (front.problem)
+        throw new Error(`${label}: ${front.problem}`);
+    return validateCaseMeta(id, front.data, listEnvs(), label);
+}
+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/command.d.ts

@@ -0,0 +1,24 @@
+/**
+ * How a command on PATH is started: the executable itself, or, on Windows, a `.cmd`/`.bat` shim that only cmd.exe
+ * can run. A CLI installed globally with npm or pnpm is such a shim (it ends up as `opencode.cmd`), and `spawn`
+ * without a shell can never start it: the bare name is not found (ENOENT) and the shim itself is refused (EINVAL).
+ */
+export interface SpawnTarget {
+    /** The file to spawn. */
+    file: string;
+    args: string[];
+    /** The file that was found on PATH, for messages. */
+    path: string;
+    /** True when `file` is cmd.exe and `args` carry the quoted command line. */
+    throughShell: boolean;
+}
+/**
+ * The file a command starts. A path (absolute or with a separator) is taken as it is; anything else is looked up
+ * on PATH, trying PATHEXT on Windows, so `opencode` finds `opencode.cmd`. Returns null when nothing matches.
+ */
+export declare function findCommand(command: string): string | null;
+/**
+ * What to spawn for a command, or null when the command is not installed. Only a Windows shim goes through a shell;
+ * everything else is spawned directly, as before.
+ */
+export declare function spawnTarget(command: string, args?: string[]): SpawnTarget | null;

package/dist/lib/command.js

@@ -0,0 +1,90 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/** The extensions Windows would try when it looks a command up; PATHEXT normally lists them. */
+const WINDOWS_EXTENSIONS = ['.COM', '.EXE', '.BAT', '.CMD'];
+const pathEntries = () => (process.env.PATH ?? process.env.Path ?? '')
+    .split(path.delimiter)
+    .map((entry) => entry.trim().replace(/^"(.*)"$/, '$1'))
+    .filter((entry) => entry !== '');
+const windowsExtensions = () => {
+    const listed = (process.env.PATHEXT ?? '').split(';').filter((entry) => entry !== '');
+    return listed.length > 0 ? listed : WINDOWS_EXTENSIONS;
+};
+/** A file that exists and, off Windows, may be executed. */
+function executable(file) {
+    try {
+        if (!fs.statSync(file).isFile())
+            return false;
+        fs.accessSync(file, process.platform === 'win32' ? fs.constants.F_OK : fs.constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The file a command starts. A path (absolute or with a separator) is taken as it is; anything else is looked up
+ * on PATH, trying PATHEXT on Windows, so `opencode` finds `opencode.cmd`. Returns null when nothing matches.
+ */
+export function findCommand(command) {
+    if (path.isAbsolute(command) || command.includes('/') || command.includes('\\')) {
+        return executable(command) ? command : null;
+    }
+    const given = path.extname(command).toLowerCase();
+    const extensions = process.platform === 'win32'
+        ? windowsExtensions().some((extension) => extension.toLowerCase() === given)
+            ? ['']
+            : windowsExtensions()
+        : [''];
+    for (const dir of pathEntries()) {
+        for (const extension of extensions) {
+            const candidate = path.join(dir, command + extension);
+            if (executable(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+/** MSVC quoting of one argument: a backslash is literal unless it comes right before a quote. */
+function quoteWindows(value) {
+    let quoted = '"';
+    let slashes = 0;
+    for (const char of value) {
+        if (char === '\\') {
+            slashes += 1;
+        }
+        else if (char === '"') {
+            quoted += `${'\\'.repeat(slashes * 2 + 1)}"`;
+            slashes = 0;
+        }
+        else {
+            quoted += '\\'.repeat(slashes) + char;
+            slashes = 0;
+        }
+    }
+    return `${quoted}${'\\'.repeat(slashes * 2)}"`;
+}
+/** A `.cmd`/`.bat` shim, started through cmd.exe the way npm's own shims are: one command line, every part quoted. */
+function shimTarget(file, args) {
+    // cmd.exe takes a single line, so a line break inside an argument would end the command.
+    const line = [file, ...args].map((value) => quoteWindows(value.replace(/[\r\n]+/g, ' '))).join(' ');
+    // `/s` strips exactly one pair of outer quotes, so the whole line is wrapped once more.
+    return {
+        file: process.env.ComSpec ?? 'cmd.exe',
+        args: ['/d', '/s', '/c', `"${line}"`],
+        path: file,
+        throughShell: true,
+    };
+}
+/**
+ * What to spawn for a command, or null when the command is not installed. Only a Windows shim goes through a shell;
+ * everything else is spawned directly, as before.
+ */
+export function spawnTarget(command, args = []) {
+    const found = findCommand(command);
+    if (found === null)
+        return null;
+    if (process.platform === 'win32' && /\.(cmd|bat)$/i.test(found))
+        return shimTarget(found, args);
+    return { file: found, args, path: found, throughShell: false };
+}

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;

package/dist/lib/ffmpeg.js

@@ -0,0 +1,50 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import os from 'node:os';
+import path from 'node:path';
+let cached;
+/** The system `ffmpeg` if there is one, else the binary of the optional `ffmpeg-static` package, else null. */
+export function findFfmpeg() {
+    if (cached !== undefined)
+        return cached;
+    if (spawnSync('ffmpeg', ['-version'], { stdio: 'ignore' }).status === 0)
+        return (cached = 'ffmpeg');
+    try {
+        const bundled = createRequire(import.meta.url)('ffmpeg-static');
+        if (bundled && fs.existsSync(bundled))
+            return (cached = bundled);
+    }
+    catch {
+        // ffmpeg-static is optional and may not be installed.
+    }
+    return (cached = 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 function concatVideos(inputs, output) {
+    const ffmpeg = findFfmpeg();
+    if (!ffmpeg)
+        return 'ffmpeg not found (install ffmpeg or the optional ffmpeg-static package)';
+    fs.mkdirSync(path.dirname(output), { recursive: true });
+    const listDir = fs.mkdtempSync(path.join(os.tmpdir(), 'asrun-concat-'));
+    const list = path.join(listDir, 'inputs.txt');
+    try {
+        fs.writeFileSync(list, inputs.map((file) => `file '${file.replace(/'/g, "'\\''")}'`).join('\n'));
+        const result = spawnSync(ffmpeg, [
+            ...['-y', '-loglevel', 'error', '-f', 'concat', '-safe', '0', '-i', list],
+            ...['-vf', 'fps=25', '-c:v', 'libvpx', '-b:v', '0', '-crf', '30', '-deadline', 'realtime', '-cpu-used', '8'],
+            ...['-an', output],
+        ], { encoding: 'utf8' });
+        if (result.status === 0 && fs.existsSync(output))
+            return null;
+        fs.rmSync(output, { force: true });
+        return (result.error?.message ?? result.stderr?.trim()) || `ffmpeg exited with ${result.status}`;
+    }
+    finally {
+        fs.rmSync(listDir, { recursive: true, force: true });
+    }
+}

package/dist/lib/fixtures.d.ts

@@ -0,0 +1,40 @@
+import { expect } from '@playwright/test';
+import { type Profile } from './profiles.js';
+/** What a case tells the framework about the data it creates; see `records.track`. */
+export interface TrackedData {
+    /** What it is, e.g. "Document draft". */
+    kind: string;
+    /** Its name in the product. Must start with `[asrun]`, so cleanup can never touch real data. */
+    name: string;
+    /** Where a person finds it by hand if the cleanup fails, e.g. "/app/documents". */
+    where?: string;
+}
+export interface Records {
+    /**
+     * Register data right after the case created it, with the function that removes it. All registered data
+     * is removed after the test, newest first, also when the test failed. A cleanup that fails fails the test
+     * and the data is listed as leftover in the run summary. A cleanup function must open its own page
+     * (it cannot assume where the test stopped) and must not assume the data still exists.
+     */
+    track(data: TrackedData, remove: () => Promise<void>): Promise<void>;
+}
+interface TestFixtures {
+    sessionExpiryHint: void;
+    caseGate: void;
+    accountLock: void;
+    records: Records;
+}
+interface WorkerFixtures {
+    /** The profile of the current Playwright project (the project name is the profile id). */
+    profile: Profile;
+    /** Set `test.use({mustLogin: false})` in specs for public pages. */
+    mustLogin: boolean;
+    sessionGuard: void;
+}
+export declare const test: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & TestFixtures, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions & WorkerFixtures>;
+/**
+ * Call at the top of the `test.describe` of every spec (`configureCase('<id>')`). Cases that write data are
+ * never retried (a retry would create the data a second time) and get more time than a read-only case.
+ */
+export declare function configureCase(caseId: string): void;
+export { expect };