@asrunjs/asrun 0.0.0-stage → 0.2.0

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

package/dist/lib/fixtures.js

@@ -0,0 +1,149 @@
+import { expect, test as base } from '@playwright/test';
+import { getProfile } from './profiles.js';
+import { caseWrites, caseWritesIn, hasCaseFile, readCaseMeta } from './cases.js';
+import { acquireAccountLock } from './account-lock.js';
+import { ledgerFile, TEST_DATA_PREFIX, writeLedger } from './records.js';
+import { caseIdFromFile } from './run-summary.js';
+import { ALLOW_WRITES_ENV, isProtectedEnv } from './write-gate.js';
+import { checkSession, isLoginUrl, parseNotLoggedIn, sessionProblemMessage, signinCommand, } from './session.js';
+export const test = base.extend({
+    profile: [
+        async ({}, use, workerInfo) => {
+            await use(getProfile(workerInfo.project.name));
+        },
+        { scope: 'worker' },
+    ],
+    mustLogin: [true, { scope: 'worker', option: true }],
+    // Login is not something we test: a profile without a valid session fails right away with an
+    // actionable message instead of a confusing login-page failure.
+    sessionGuard: [
+        async ({ browser, profile, mustLogin }, use) => {
+            if (mustLogin) {
+                // `pnpm asrun` already checked every profile before the run; reuse its result.
+                const status = parseNotLoggedIn().get(profile.id) ?? (await checkSession(browser, profile));
+                if (status !== 'ok') {
+                    throw new Error(sessionProblemMessage(profile, status));
+                }
+            }
+            await use();
+        },
+        { scope: 'worker', auto: true },
+    ],
+    // Enforced here, not only in `pnpm asrun`, so that running `playwright test` directly cannot bypass it:
+    // a case may be limited to some environments (`envs`), a case that writes data only runs in the environments
+    // it lists under `writes` (elsewhere it is skipped), and writing in any environment except staging needs a
+    // human's confirmation.
+    caseGate: [
+        async ({ profile }, use, testInfo) => {
+            const caseId = caseIdFromFile(testInfo.file);
+            if (hasCaseFile(caseId)) {
+                const meta = readCaseMeta(caseId);
+                testInfo.skip(meta.envs !== null && !meta.envs.includes(profile.env), `This case is limited to: ${meta.envs?.join(', ')}`);
+                testInfo.skip(caseWrites(meta) && !caseWritesIn(meta, profile.env), `This case writes data and has no permission to write in ${profile.env.toUpperCase()} (it lists: ${meta.writes.join(', ')}).`);
+                if (caseWritesIn(meta, profile.env) && isProtectedEnv(profile.env) && process.env[ALLOW_WRITES_ENV] !== profile.env) {
+                    throw new Error(`This case writes data and has no permission to run in ${profile.env.toUpperCase()}. ` +
+                        `Start it with "pnpm asrun --env ${profile.env}" and confirm, or run it in staging.`);
+                }
+            }
+            await use();
+        },
+        { scope: 'test', auto: true },
+    ],
+    // Cases that write to an account run one at a time per profile, whatever the worker count.
+    accountLock: [
+        async ({ profile, caseGate: _gate }, use, testInfo) => {
+            const caseId = caseIdFromFile(testInfo.file);
+            if (!hasCaseFile(caseId) || !caseWrites(readCaseMeta(caseId))) {
+                await use();
+                return;
+            }
+            const release = await acquireAccountLock(profile.id, WRITE_CASE_TIMEOUT_MS);
+            try {
+                await use();
+            }
+            finally {
+                release();
+            }
+        },
+        { scope: 'test', auto: true },
+    ],
+    // Tracks test data and removes it again, newest first. See `Records.track`.
+    records: async ({ profile, page: _page }, use, testInfo) => {
+        const caseId = caseIdFromFile(testInfo.file);
+        const runId = process.env.ASRUN_RUN_ID ?? 'adhoc';
+        const file = ledgerFile(runId, testInfo.testId);
+        const entries = [];
+        const save = () => writeLedger(file, entries.map((item) => item.entry));
+        await use({
+            async track(data, remove) {
+                if (!data.name.startsWith(TEST_DATA_PREFIX)) {
+                    throw new Error(`Test data must be named with the prefix "${TEST_DATA_PREFIX}" (got "${data.name}"). ` +
+                        `Only data that is clearly a test's own may be created and removed.`);
+                }
+                entries.push({
+                    entry: {
+                        id: `${entries.length + 1}`,
+                        runId,
+                        env: profile.env,
+                        profile: profile.id,
+                        caseId,
+                        kind: data.kind,
+                        name: data.name,
+                        where: data.where ?? null,
+                        status: 'open',
+                        error: null,
+                        createdAt: new Date().toISOString(),
+                    },
+                    remove,
+                });
+                // Written at once: if the process dies, the ledger still says what was left behind.
+                save();
+            },
+        });
+        const failures = [];
+        for (const item of [...entries].reverse()) {
+            try {
+                await item.remove();
+                item.entry.status = 'cleaned';
+            }
+            catch (error) {
+                item.entry.status = 'leftover';
+                item.entry.error = error.message.split('\n')[0];
+                failures.push(`${item.entry.kind} "${item.entry.name}"${item.entry.where ? ` (look in ${item.entry.where})` : ''}`);
+            }
+            save();
+        }
+        if (failures.length > 0) {
+            testInfo.annotations.push({ type: 'leftover-data', description: failures.join('; ') });
+            throw new Error(`Test data was not removed and must be deleted by hand: ${failures.join('; ')}`);
+        }
+    },
+    // The session can also expire in the middle of a run; say so when a failed test ends on /login.
+    sessionExpiryHint: [
+        async ({ page, profile, mustLogin }, use, testInfo) => {
+            await use();
+            if (!mustLogin || testInfo.status === testInfo.expectedStatus) {
+                return;
+            }
+            if (page.isClosed() || !isLoginUrl(page.url())) {
+                return;
+            }
+            const description = `The session of profile "${profile.id}" in ${profile.env} expired during the run. Log in again: ${signinCommand(profile)}`;
+            testInfo.annotations.push({ type: 'session-expired', description });
+            console.error(`\n${description}\n`);
+        },
+        { scope: 'test', auto: true },
+    ],
+});
+/** Longest a write case may take, and how long it waits for another case that uses the same account. */
+const WRITE_CASE_TIMEOUT_MS = 180_000;
+/**
+ * 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 function configureCase(caseId) {
+    if (hasCaseFile(caseId) && caseWrites(readCaseMeta(caseId))) {
+        test.describe.configure({ retries: 0, timeout: WRITE_CASE_TIMEOUT_MS });
+    }
+}
+export { expect };

package/dist/lib/node-cli.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Arguments that run one of the framework's own scripts (for example `login.ts`): the compiled file when the package
+ * is built, the TypeScript source in the framework repository.
+ */
+export declare function scriptArgs(name: string): string[];
+/**
+ * The JavaScript entry point of a package's command-line tool. The shims in `node_modules/.bin` are POSIX shell
+ * scripts on Windows and cannot be spawned there, so tools are always started with the current Node instead.
+ * The path comes from the package manifest, so a dependency upgrade cannot silently break it.
+ */
+export declare function commandScript(packageName: string, command?: string): string;

package/dist/lib/node-cli.js

@@ -0,0 +1,26 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { FRAMEWORK_ROOT, packageDir } from './paths.js';
+/**
+ * Arguments that run one of the framework's own scripts (for example `login.ts`): the compiled file when the package
+ * is built, the TypeScript source in the framework repository.
+ */
+export function scriptArgs(name) {
+    const compiled = path.join(FRAMEWORK_ROOT, 'dist', 'scripts', name.replace(/\.ts$/, '.js'));
+    if (fs.existsSync(compiled))
+        return [compiled];
+    return [commandScript('tsx'), path.join(FRAMEWORK_ROOT, 'scripts', name)];
+}
+/**
+ * The JavaScript entry point of a package's command-line tool. The shims in `node_modules/.bin` are POSIX shell
+ * scripts on Windows and cannot be spawned there, so tools are always started with the current Node instead.
+ * The path comes from the package manifest, so a dependency upgrade cannot silently break it.
+ */
+export function commandScript(packageName, command = packageName) {
+    const dir = packageDir(packageName);
+    const manifest = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+    const script = typeof manifest.bin === 'string' ? manifest.bin : manifest.bin?.[command];
+    if (!script)
+        throw new Error(`${packageName} has no command-line entry point "${command}".`);
+    return path.join(dir, script);
+}

package/dist/lib/paths.d.ts

@@ -0,0 +1,25 @@
+export declare const FRAMEWORK_ROOT: string;
+/**
+ * The workspace root: the project that uses the framework. Everything the framework reads or writes for a project
+ * (`profiles.yaml`, `cases/`, `tests/`, `.auth/`, `reports/`, `.tmp/`) is relative to it.
+ *
+ * `ASRUN_ROOT` chooses it explicitly. Otherwise it is the nearest folder at or above the current working
+ * directory that holds `profiles.yaml` or `.asrun.json`; without one the framework's own folder is used, which is
+ * how the framework runs against `examples/`.
+ */
+export declare const ROOT: string;
+/** True when `ROOT` is the framework folder itself, i.e. no workspace was found. */
+export declare const isFrameworkRoot: () => boolean;
+/** One saved login per profile: `.auth/<profile-id>.json`. */
+export declare const authFile: (profileId: string) => string;
+export declare const CASES_DIR: string;
+export declare const TESTS_DIR: string;
+export declare const REPORTS_DIR: string;
+export declare const TMP_DIR: string;
+export declare const TEMPLATES_DIR: string;
+export declare const SKILLS_DIR: string;
+/**
+ * The `node_modules/<package>` folder of the framework's own install, or the workspace's (a hoisted or linked
+ * install). Tools that need a package folder rather than a module (vite's config, pdfjs assets) use this.
+ */
+export declare function packageDir(packageName: string): string;

package/dist/lib/paths.js

@@ -0,0 +1,88 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Where the framework's own code and assets live: the package folder (`node_modules/@asrunjs/asrun`). The compiled files sit in
+ * `dist/lib`, so one level up from there is the package root again.
+ */
+const MODULE_DIR = import.meta.dirname;
+export const FRAMEWORK_ROOT = path.basename(path.dirname(MODULE_DIR)) === 'dist' ? path.resolve(MODULE_DIR, '..', '..') : path.resolve(MODULE_DIR, '..');
+/**
+ * Reads a `.env` file into `process.env`. A variable that already exists (a real environment variable, or one from an
+ * earlier file) is never overridden. `ASRUN_ROOT` is resolved against the folder of the file, so `.` in
+ * `<workspace>/.env` means the workspace and `examples/demo` in the framework's `.env` means that folder.
+ */
+function loadEnvFile(file) {
+    let text;
+    try {
+        text = fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return;
+    }
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line === '' || line.startsWith('#'))
+            continue;
+        const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+        if (!match)
+            continue;
+        const [, key, rawValue] = match;
+        if (process.env[key] !== undefined)
+            continue;
+        const value = rawValue.trim().replace(/^(['"])(.*)\1$/, '$2');
+        process.env[key] = key === 'ASRUN_ROOT' ? path.resolve(path.dirname(file), value) : value;
+    }
+}
+// The workspace can be chosen per machine without exporting anything: the `.env` next to the command, or the
+// framework's own `.env` (that is how the framework itself develops against examples/).
+loadEnvFile(path.join(process.cwd(), '.env'));
+if (process.env.ASRUN_ROOT === undefined)
+    loadEnvFile(path.join(FRAMEWORK_ROOT, '.env'));
+/** Files that mark the root of a workspace: the project that owns `profiles.yaml`, `cases/` and `tests/`. */
+const WORKSPACE_MARKERS = ['.asrun.json', 'profiles.yaml'];
+function findWorkspace(from) {
+    let dir = path.resolve(from);
+    for (;;) {
+        if (WORKSPACE_MARKERS.some((marker) => fs.existsSync(path.join(dir, marker))))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/**
+ * The workspace root: the project that uses the framework. Everything the framework reads or writes for a project
+ * (`profiles.yaml`, `cases/`, `tests/`, `.auth/`, `reports/`, `.tmp/`) is relative to it.
+ *
+ * `ASRUN_ROOT` chooses it explicitly. Otherwise it is the nearest folder at or above the current working
+ * directory that holds `profiles.yaml` or `.asrun.json`; without one the framework's own folder is used, which is
+ * how the framework runs against `examples/`.
+ */
+export const ROOT = process.env.ASRUN_ROOT ? path.resolve(process.env.ASRUN_ROOT) : (findWorkspace(process.cwd()) ?? FRAMEWORK_ROOT);
+// Children (Playwright, the web UI jobs) inherit the resolved absolute path: a relative ASRUN_ROOT would point
+// somewhere else once the working directory changes.
+process.env.ASRUN_ROOT = ROOT;
+/** True when `ROOT` is the framework folder itself, i.e. no workspace was found. */
+export const isFrameworkRoot = () => path.resolve(ROOT) === path.resolve(FRAMEWORK_ROOT);
+/** One saved login per profile: `.auth/<profile-id>.json`. */
+export const authFile = (profileId) => path.join(ROOT, '.auth', `${profileId}.json`);
+export const CASES_DIR = path.join(ROOT, 'cases');
+export const TESTS_DIR = path.join(ROOT, 'tests');
+export const REPORTS_DIR = path.join(ROOT, 'reports');
+export const TMP_DIR = path.join(ROOT, '.tmp');
+export const TEMPLATES_DIR = path.join(FRAMEWORK_ROOT, 'templates');
+export const SKILLS_DIR = path.join(FRAMEWORK_ROOT, '.claude', 'skills');
+/**
+ * The `node_modules/<package>` folder of the framework's own install, or the workspace's (a hoisted or linked
+ * install). Tools that need a package folder rather than a module (vite's config, pdfjs assets) use this.
+ */
+export function packageDir(packageName) {
+    // The package's own install, the pnpm virtual store that holds its dependencies, or a hoisted install in the workspace.
+    for (const base of [FRAMEWORK_ROOT, path.dirname(path.dirname(FRAMEWORK_ROOT)), ROOT]) {
+        const dir = path.join(base, 'node_modules', packageName);
+        if (fs.existsSync(dir))
+            return dir;
+    }
+    throw new Error(`Package "${packageName}" is not installed. Run "pnpm install" in the workspace root.`);
+}

package/dist/lib/pdf.d.ts

@@ -0,0 +1,71 @@
+type PdfJs = typeof import('pdfjs-dist/legacy/build/pdf.mjs');
+type PdfTask = ReturnType<PdfJs['getDocument']>;
+type PdfDoc = Awaited<PdfTask['promise']>;
+/** Which pages a check covers: all of them, the first, the last, or the listed 1-based page numbers. */
+export type PageSelection = 'all' | 'first' | 'last' | number[];
+/** A rectangle of the page in fractions (0 to 1) of its width and height, from the top-left corner. */
+export interface Region {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export type Corner = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+/** A corner of the page. Defaults: 30% of the width and 12% of the height, enough for a logo and nothing else. */
+export declare function corner(name: Corner, size?: {
+    width?: number;
+    height?: number;
+}): Region;
+export declare function selectPages(selection: PageSelection, pageCount: number): number[];
+export interface RenderedRegion {
+    png: Buffer;
+    width: number;
+    height: number;
+    /** Share of pixels that are not (almost) white: 0 is a blank region. */
+    inkRatio: number;
+}
+export declare class PdfFile {
+    private readonly doc;
+    private readonly task;
+    readonly pageCount: number;
+    /** The text of each page, in reading order. */
+    readonly texts: string[];
+    constructor(doc: PdfDoc, task: PdfTask, pageCount: number, 
+    /** The text of each page, in reading order. */
+    texts: string[]);
+    /** Renders one page (or a region of it) to a PNG. Scale 2 is about 150 dpi. */
+    render(pageNumber: number, region?: Region, scale?: number): Promise<RenderedRegion>;
+    close(): Promise<void>;
+}
+export declare function openPdf(bytes: Buffer): Promise<PdfFile>;
+export interface PdfRegionCheck {
+    /** Short name of the check, used in messages and in the baseline file name (`<name>-p<page>.png`). Lower case words and dashes. */
+    name: string;
+    pages: PageSelection;
+    region: Region;
+    /** The region must show something (not blank). Default true. */
+    notBlank?: boolean;
+    /** Compare the region with the baseline image of the profile (2% tolerance). Default true. */
+    baseline?: boolean;
+}
+export interface PdfChecks {
+    regions?: PdfRegionCheck[];
+    /** Texts that must appear somewhere in the PDF (case-insensitive). */
+    textContains?: string[];
+    /** Texts that must not appear on any page (for example the names that belong to another profile). */
+    textNotContains?: string[];
+    /** At least this many pages. */
+    minPages?: number;
+    scale?: number;
+}
+/**
+ * The one way a spec checks the content of a downloaded PDF. For every region check it renders each selected page,
+ * fails when the region is blank, and compares the region with the profile's baseline image (the first run with
+ * `--update-snapshots` creates it; a person must look at it). Then it checks the extracted text.
+ * Every failure names the page and the check. Pair every call with `// target: T<n>` in the spec.
+ *
+ *   const pdf = await openPdf(file.bytes);
+ *   await expectPdf(pdf, {regions: [{name: 'logo', pages: 'first', region: corner('top-left')}], textNotContains: otherProfileNames});
+ */
+export declare function expectPdf(pdf: PdfFile, checks: PdfChecks): Promise<void>;
+export {};

package/dist/lib/pdf.js

@@ -0,0 +1,140 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createCanvas } from '@napi-rs/canvas';
+import { expect } from '@playwright/test';
+import { packageDir } from './paths.js';
+let pdfjs;
+const loadPdfjs = () => (pdfjs ??= import('pdfjs-dist/legacy/build/pdf.mjs'));
+// pdf.js loads its fonts, cmaps and wasm files from the package folder, not from the consuming project.
+let pdfjsDir;
+const dirUrl = (dir) => pathToFileURL(path.join((pdfjsDir ??= packageDir('pdfjs-dist')), dir)).href + '/';
+/** A corner of the page. Defaults: 30% of the width and 12% of the height, enough for a logo and nothing else. */
+export function corner(name, size = {}) {
+    const width = size.width ?? 0.3;
+    const height = size.height ?? 0.12;
+    return {
+        x: name.endsWith('left') ? 0 : 1 - width,
+        y: name.startsWith('top') ? 0 : 1 - height,
+        width,
+        height,
+    };
+}
+export function selectPages(selection, pageCount) {
+    if (selection === 'all')
+        return Array.from({ length: pageCount }, (_, i) => i + 1);
+    if (selection === 'first')
+        return [1];
+    if (selection === 'last')
+        return [pageCount];
+    const outside = selection.filter((n) => !Number.isInteger(n) || n < 1 || n > pageCount);
+    if (outside.length > 0)
+        throw new Error(`The PDF has ${pageCount} page(s), but the check asks for page ${outside.join(', ')}`);
+    return selection;
+}
+export class PdfFile {
+    doc;
+    task;
+    pageCount;
+    texts;
+    constructor(doc, task, pageCount, 
+    /** The text of each page, in reading order. */
+    texts) {
+        this.doc = doc;
+        this.task = task;
+        this.pageCount = pageCount;
+        this.texts = texts;
+    }
+    /** Renders one page (or a region of it) to a PNG. Scale 2 is about 150 dpi. */
+    async render(pageNumber, region, scale = 2) {
+        const page = await this.doc.getPage(pageNumber);
+        const viewport = page.getViewport({ scale });
+        const full = createCanvas(Math.ceil(viewport.width), Math.ceil(viewport.height));
+        const context = full.getContext('2d');
+        context.fillStyle = '#ffffff';
+        context.fillRect(0, 0, full.width, full.height);
+        await page.render({ canvas: full, canvasContext: context, viewport }).promise;
+        let out = full;
+        if (region) {
+            const x = Math.round(region.x * full.width);
+            const y = Math.round(region.y * full.height);
+            const width = Math.max(1, Math.round(region.width * full.width));
+            const height = Math.max(1, Math.round(region.height * full.height));
+            out = createCanvas(width, height);
+            out.getContext('2d').drawImage(full, x, y, width, height, 0, 0, width, height);
+        }
+        const data = out.getContext('2d').getImageData(0, 0, out.width, out.height).data;
+        let ink = 0;
+        for (let i = 0; i < data.length; i += 4) {
+            if (data[i + 3] > 0 && (data[i] < 245 || data[i + 1] < 245 || data[i + 2] < 245))
+                ink++;
+        }
+        return { png: out.toBuffer('image/png'), width: out.width, height: out.height, inkRatio: ink / (out.width * out.height) };
+    }
+    async close() {
+        await this.task.destroy();
+    }
+}
+export async function openPdf(bytes) {
+    const lib = await loadPdfjs();
+    let doc;
+    const task = lib.getDocument({
+        data: new Uint8Array(bytes),
+        standardFontDataUrl: dirUrl('standard_fonts'),
+        cMapUrl: dirUrl('cmaps'),
+        cMapPacked: true,
+        iccUrl: dirUrl('iccs'),
+        wasmUrl: dirUrl('wasm'),
+        useSystemFonts: false,
+        verbosity: 0,
+    });
+    try {
+        doc = await task.promise;
+    }
+    catch (error) {
+        throw new Error(`The downloaded PDF cannot be opened: ${error.message}`);
+    }
+    if (doc.numPages < 1)
+        throw new Error('The downloaded PDF has no pages');
+    const texts = [];
+    for (let n = 1; n <= doc.numPages; n++) {
+        const content = await (await doc.getPage(n)).getTextContent();
+        texts.push(content.items.map((item) => ('str' in item ? item.str : '')).join(' ').replace(/\s+/g, ' ').trim());
+    }
+    return new PdfFile(doc, task, doc.numPages, texts);
+}
+/**
+ * The one way a spec checks the content of a downloaded PDF. For every region check it renders each selected page,
+ * fails when the region is blank, and compares the region with the profile's baseline image (the first run with
+ * `--update-snapshots` creates it; a person must look at it). Then it checks the extracted text.
+ * Every failure names the page and the check. Pair every call with `// target: T<n>` in the spec.
+ *
+ *   const pdf = await openPdf(file.bytes);
+ *   await expectPdf(pdf, {regions: [{name: 'logo', pages: 'first', region: corner('top-left')}], textNotContains: otherProfileNames});
+ */
+export async function expectPdf(pdf, checks) {
+    const { regions = [], textContains = [], textNotContains = [], minPages, scale = 2 } = checks;
+    if (minPages !== undefined)
+        expect(pdf.pageCount, `The PDF has too few pages (${pdf.pageCount}, expected at least ${minPages})`).toBeGreaterThanOrEqual(minPages);
+    for (const check of regions) {
+        for (const page of selectPages(check.pages, pdf.pageCount)) {
+            const shown = await pdf.render(page, check.region, scale);
+            if (check.notBlank ?? true) {
+                expect(shown.inkRatio, `The "${check.name}" area on page ${page} of the PDF is blank (nothing is drawn there)`).toBeGreaterThan(0.002);
+            }
+            if (check.baseline ?? true) {
+                expect(shown.png, `The "${check.name}" area on page ${page} of the PDF does not look right`).toMatchSnapshot(`${check.name}-p${page}.png`, {
+                    maxDiffPixelRatio: 0.02,
+                });
+            }
+        }
+    }
+    const all = pdf.texts.join(' \n ').toLowerCase();
+    for (const text of textContains) {
+        expect(all.includes(text.toLowerCase()), `The PDF does not contain the text "${text}"`).toBe(true);
+    }
+    for (const text of textNotContains) {
+        const lower = text.toLowerCase();
+        const page = pdf.texts.findIndex((value) => value.toLowerCase().includes(lower));
+        expect(page, `The PDF shows the text "${text}" on page ${page + 1}, which does not belong to this profile`).toBe(-1);
+    }
+}

package/dist/lib/profiles.d.ts

@@ -0,0 +1,38 @@
+export declare const PRODUCTION = "production";
+export declare const STAGING = "staging";
+export declare const PROFILES_FILE: string;
+/**
+ * One entry of profiles.yaml: one environment of the system under test. It holds only connection
+ * settings. Expected values belong to the case document that checks them (see `lib/values.ts`).
+ */
+export interface Profile {
+    id: string;
+    name: string;
+    /** The environment this profile points at, e.g. `production` or `staging`. */
+    env: string;
+    baseURL: string;
+    /** A label for humans (a mailbox or username). Never a password. */
+    account: string | null;
+    /** Free-form labels for grouping and `--tag`; lowercase words. */
+    tags: string[];
+    /** Tests may send real email in this environment. Never true in production. */
+    email: boolean;
+    /** A page that redirects to /login when the session is missing or expired. */
+    sessionCheckPath: string;
+}
+/** The Playwright project name of a profile: its id. */
+export declare const projectName: (profile: {
+    id: string;
+}) => string;
+export declare const profileLabel: (profile: {
+    id: string;
+    env: string;
+}) => string;
+export declare function loadProfiles(file?: string): Profile[];
+/** The profiles of one environment (`env` omitted: all of them), production first. */
+export declare const listProfiles: (env?: string, profiles?: Profile[]) => Profile[];
+export declare function getProfile(id: string, profiles?: Profile[]): Profile;
+/** The profiles that carry this tag. */
+export declare const listProfilesWithTag: (tag: string, env?: string, profiles?: Profile[]) => Profile[];
+/** Every environment used by a profile: production, staging, then the rest. */
+export declare const listEnvs: (profiles?: Profile[]) => string[];