@asrunjs/asrun 0.0.0-stage → 0.5.2

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,62 @@
+export declare const DEFAULT_SESSION_CHECK_PATH = "/account/";
+/** The page "Visit" opens by default: the site root. */
+export declare const DEFAULT_START_PATH = "";
+/**
+ * How to tell "signed in" from "signed out" on one site. A site can say it in different ways: a redirect to
+ * a login page (server or client side), a 401/403, a login form on the same address, or a "you must sign in"
+ * message. Every profile names the signal it has; the defaults cover the most common one, a redirect to `/login`.
+ */
+export interface SessionCheck {
+    /** The address a visitor without a valid session is sent to: a path on the site, or a full URL (single sign-on). */
+    loggedOutUrl: string;
+    /** A selector that is only on the page while signed in, e.g. the username in the top bar. The most reliable signal. */
+    loggedInSelector: string | null;
+    /** A selector that shows the visitor is not signed in, e.g. the password field of the login form. */
+    loggedOutSelector: string | null;
+    /** How long to wait for one of those signals before closing the page again. */
+    timeoutMs: number;
+}
+export declare const DEFAULT_SESSION_CHECK: SessionCheck;
+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;
+    /** The page "Visit" opens after a login, e.g. `/app/home`; empty = the site root. */
+    startPath: string;
+    /** A page that only a signed-in visitor sees; the page "Verify" opens. */
+    sessionCheckPath: string;
+    /** How that page shows a missing or expired login (see `SessionCheck`). */
+    sessionCheck: SessionCheck;
+}
+/** 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 validateSessionCheck(where: string, raw: unknown): SessionCheck;
+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[];

package/dist/lib/profiles.js

@@ -0,0 +1,174 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse } from 'yaml';
+import { ROOT } from './paths.js';
+const NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+export const DEFAULT_SESSION_CHECK_PATH = '/account/';
+/** The page "Visit" opens by default: the site root. */
+export const DEFAULT_START_PATH = '';
+export const DEFAULT_SESSION_CHECK = {
+    loggedOutUrl: '/login',
+    loggedInSelector: null,
+    loggedOutSelector: null,
+    timeoutMs: 3000,
+};
+export const PRODUCTION = 'production';
+export const STAGING = 'staging';
+export const PROFILES_FILE = path.join(ROOT, 'profiles.yaml');
+/** The Playwright project name of a profile: its id. */
+export const projectName = (profile) => profile.id;
+export const profileLabel = (profile) => `${profile.id} (${profile.env})`;
+function validateTags(where, raw) {
+    if (raw === undefined || raw === null)
+        return [];
+    if (!Array.isArray(raw) || raw.some((tag) => typeof tag !== 'string' || !NAME_PATTERN.test(tag))) {
+        throw new Error(`${where}: "tags" must be a list of lowercase words (letters, digits, dashes), e.g. [us, core]`);
+    }
+    const duplicate = raw.find((tag, index) => raw.indexOf(tag) !== index);
+    if (duplicate)
+        throw new Error(`${where}: "tags" lists "${duplicate}" twice`);
+    return raw;
+}
+function validateSiteAddress(where, value) {
+    if (typeof value !== 'string' || value === '')
+        throw new Error(`${where} is missing "baseURL"`);
+    try {
+        const url = new URL(value);
+        if (url.protocol !== 'https:' && url.protocol !== 'http:')
+            throw new Error('protocol');
+    }
+    catch {
+        throw new Error(`${where}: "baseURL" must be a full http(s) URL, e.g. https://www.example.com`);
+    }
+    return value.replace(/\/$/, '');
+}
+export function validateSessionCheck(where, raw) {
+    if (raw === undefined || raw === null)
+        return DEFAULT_SESSION_CHECK;
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new Error(`${where}: "sessionCheck" must be a mapping with "loggedOutUrl", "loggedInSelector", "loggedOutSelector" or "timeoutMs"`);
+    }
+    const map = raw;
+    const known = ['loggedOutUrl', 'loggedInSelector', 'loggedOutSelector', 'timeoutMs'];
+    const unknown = Object.keys(map).find((key) => !known.includes(key));
+    if (unknown) {
+        throw new Error(`${where}: "sessionCheck" has an unknown key "${unknown}". Known: ${known.join(', ')}`);
+    }
+    const loggedOutUrl = map.loggedOutUrl ?? DEFAULT_SESSION_CHECK.loggedOutUrl;
+    if (typeof loggedOutUrl !== 'string' ||
+        (!loggedOutUrl.startsWith('/') && !/^https?:\/\//i.test(loggedOutUrl)) ||
+        /\s/.test(loggedOutUrl)) {
+        throw new Error(`${where}: "sessionCheck.loggedOutUrl" must be a path starting with "/" (e.g. /login) or a full http(s) URL`);
+    }
+    const selector = (key) => {
+        const value = map[key];
+        if (value === undefined || value === null || value === '')
+            return null;
+        if (typeof value !== 'string') {
+            throw new Error(`${where}: "sessionCheck.${key}" must be a selector such as "input[name='username']"`);
+        }
+        return value;
+    };
+    const timeoutMs = map.timeoutMs ?? DEFAULT_SESSION_CHECK.timeoutMs;
+    if (typeof timeoutMs !== 'number' || !Number.isInteger(timeoutMs) || timeoutMs < 500 || timeoutMs > 60000) {
+        throw new Error(`${where}: "sessionCheck.timeoutMs" must be a whole number of milliseconds between 500 and 60000`);
+    }
+    return {
+        loggedOutUrl,
+        loggedInSelector: selector('loggedInSelector'),
+        loggedOutSelector: selector('loggedOutSelector'),
+        timeoutMs,
+    };
+}
+function validate(raw, index) {
+    const label = `profiles.yaml: profile #${index + 1}`;
+    for (const key of ['id', 'name', 'env']) {
+        if (typeof raw?.[key] !== 'string' || raw[key] === '') {
+            throw new Error(`${label} is missing "${key}"`);
+        }
+    }
+    const where = `profiles.yaml: profile "${raw.id}"`;
+    if (!NAME_PATTERN.test(raw.id)) {
+        throw new Error(`${where}: "id" must be lowercase letters and digits, separated by single dashes (e.g. "example-staging")`);
+    }
+    if (!NAME_PATTERN.test(raw.env)) {
+        throw new Error(`${where}: "env" must be lowercase letters, digits and single dashes (e.g. "production", "staging")`);
+    }
+    if (raw.envs !== undefined) {
+        throw new Error(`${where} has an "envs" map. Each profile is one environment: give it an "env" and a "baseURL" instead.`);
+    }
+    if (raw.baseURL === undefined) {
+        throw new Error(`${where} is missing "baseURL" (the site address of ${raw.env})`);
+    }
+    const baseURL = validateSiteAddress(where, raw.baseURL);
+    if (raw.account !== undefined && raw.account !== null && typeof raw.account !== 'string') {
+        throw new Error(`${where}: "account" must be text (a mailbox or username), or omitted`);
+    }
+    if (raw.email !== undefined && typeof raw.email !== 'boolean') {
+        throw new Error(`${where}: "email" must be true or false`);
+    }
+    if (raw.env === PRODUCTION && raw.email === true) {
+        throw new Error(`${where}: "email: true" is not allowed. Tests never send email in production.`);
+    }
+    const sessionCheckPath = raw.sessionCheckPath ?? DEFAULT_SESSION_CHECK_PATH;
+    if (typeof sessionCheckPath !== 'string' || !sessionCheckPath.startsWith('/') || /\s/.test(sessionCheckPath)) {
+        throw new Error(`${where}: "sessionCheckPath" must start with "/" and contain no spaces`);
+    }
+    const startPath = raw.startPath ?? DEFAULT_START_PATH;
+    if (typeof startPath !== 'string' ||
+        (startPath !== '' && (!startPath.startsWith('/') || startPath.startsWith('//') || /\s/.test(startPath)))) {
+        throw new Error(`${where}: "startPath" must be empty (the site root) or a path on the site that starts with a single "/" and has no spaces`);
+    }
+    const account = typeof raw.account === 'string' && raw.account.trim() !== '' ? raw.account.trim() : null;
+    return {
+        id: raw.id,
+        name: raw.name,
+        env: raw.env,
+        baseURL,
+        account,
+        tags: validateTags(where, raw.tags),
+        email: raw.email === true,
+        startPath,
+        sessionCheckPath,
+        sessionCheck: validateSessionCheck(where, raw.sessionCheck),
+    };
+}
+export function loadProfiles(file = PROFILES_FILE) {
+    if (!fs.existsSync(file)) {
+        throw new Error(`profiles.yaml is missing. Create it in the project root (see the comments in the file for the fields).`);
+    }
+    const text = fs.readFileSync(file, 'utf8');
+    const parsed = parse(text, { merge: true });
+    const raw = parsed?.profiles;
+    if (!Array.isArray(raw)) {
+        throw new Error('profiles.yaml needs a "profiles:" list (it may be empty while you set the suite up).');
+    }
+    const profiles = raw.map(validate);
+    const ids = profiles.map((profile) => profile.id);
+    const duplicate = ids.find((id, index) => ids.indexOf(id) !== index);
+    if (duplicate)
+        throw new Error(`profiles.yaml: duplicate profile id "${duplicate}"`);
+    return profiles;
+}
+function sortProfiles(profiles) {
+    const rank = (env) => (env === PRODUCTION ? 0 : env === STAGING ? 1 : 2);
+    return [...profiles].sort((a, b) => rank(a.env) - rank(b.env) || a.id.localeCompare(b.id));
+}
+/** The profiles of one environment (`env` omitted: all of them), production first. */
+export const listProfiles = (env, profiles = loadProfiles()) => sortProfiles(profiles.filter((profile) => !env || profile.env === env));
+export function getProfile(id, profiles = loadProfiles()) {
+    const profile = profiles.find((candidate) => candidate.id === id);
+    if (!profile) {
+        const known = profiles.map((candidate) => candidate.id).join(', ') || '(none)';
+        throw new Error(`Unknown profile "${id}". Known profiles: ${known}. Check profiles.yaml.`);
+    }
+    return profile;
+}
+/** The profiles that carry this tag. */
+export const listProfilesWithTag = (tag, env, profiles = loadProfiles()) => listProfiles(env, profiles).filter((profile) => profile.tags.includes(tag));
+/** Every environment used by a profile: production, staging, then the rest. */
+export const listEnvs = (profiles = loadProfiles()) => {
+    const envs = [...new Set(profiles.map((profile) => profile.env))];
+    const rank = (env) => (env === PRODUCTION ? 0 : env === STAGING ? 1 : 2);
+    return envs.sort((a, b) => rank(a) - rank(b) || a.localeCompare(b));
+};

package/dist/lib/ready.d.ts

@@ -0,0 +1,36 @@
+import { type Locator, type Page } from '@playwright/test';
+export interface ReadyOptions {
+    /** Key requests the action starts (URL substring or RegExp). Each must finish with a status below 400. */
+    responses?: (string | RegExp)[];
+    /** What must be visible once the content is really there (not a spinner, a frame or a placeholder). */
+    ready?: Locator | Locator[];
+    /** Per request and per locator, in ms. */
+    timeout?: number;
+}
+/**
+ * Runs `action` (a click, a navigation) and waits until its result is there: first the key requests it starts have
+ * finished, then the `ready` locators are visible. Read the result only after this returns.
+ *
+ * The response waiters are registered before the action runs, so a fast response is never missed.
+ *
+ *   await actAndWait(page, () => share.click(), {responses: [/\/api\/documents\/.+\/email/], ready: composer.getByRole('textbox', {name: 'To'})});
+ */
+export declare function actAndWait<T>(page: Page, action: () => Promise<T>, options?: ReadyOptions): Promise<T>;
+/**
+ * For an action that may or may not raise a confirmation (a "Discard draft?" dialog after closing a composer): clicks
+ * `optional` whenever it is visible, and returns once `target` is hidden. Both happen in one retry loop, so a
+ * confirmation that shows up late is still clicked, and no confirmation does not cost a wait.
+ *
+ * `isVisible()` alone is not enough: it answers for this instant only and its `timeout` option is ignored.
+ * Prefer a `target` that stays on the same element (a role/name or test id locator); a `.last()` locator moves to the
+ * confirm dialog while that dialog is open.
+ *
+ *   await composer.getByRole('button', {name: 'close', exact: true}).click();
+ *   await clickOptionalUntilHidden(page.getByRole('button', {name: 'Discard', exact: true}), composer, {message: 'The email composer did not close'});
+ */
+export declare function clickOptionalUntilHidden(optional: Locator, target: Locator, options?: {
+    timeout?: number;
+    message?: string;
+}): Promise<void>;
+/** Waits until nothing inside `scope` says it is still loading (busy regions, progress bars, spinners and skeletons that have a role or test id). */
+export declare function expectNotBusy(scope: Locator | Page, timeout?: number): Promise<void>;

package/dist/lib/ready.js

@@ -0,0 +1,53 @@
+import { expect } from '@playwright/test';
+const matches = (pattern, url) => (typeof pattern === 'string' ? url.includes(pattern) : pattern.test(url));
+/**
+ * Runs `action` (a click, a navigation) and waits until its result is there: first the key requests it starts have
+ * finished, then the `ready` locators are visible. Read the result only after this returns.
+ *
+ * The response waiters are registered before the action runs, so a fast response is never missed.
+ *
+ *   await actAndWait(page, () => share.click(), {responses: [/\/api\/documents\/.+\/email/], ready: composer.getByRole('textbox', {name: 'To'})});
+ */
+export async function actAndWait(page, action, options = {}) {
+    const { responses = [], ready = [], timeout = 30_000 } = options;
+    const waiters = responses.map((pattern) => page
+        .waitForResponse((response) => matches(pattern, response.url()), { timeout })
+        .then((response) => ({ pattern, response }), () => ({ pattern, response: null })));
+    const result = await action();
+    for (const { pattern, response } of await Promise.all(waiters)) {
+        if (!response)
+            throw new Error(`The page did not finish loading: no response for the request ${pattern} within ${timeout / 1000}s`);
+        if (response.status() >= 400) {
+            throw new Error(`The page did not load its data: the request ${pattern} failed (HTTP ${response.status()})`);
+        }
+    }
+    for (const locator of Array.isArray(ready) ? ready : [ready]) {
+        await expect(locator, 'The content did not finish loading').toBeVisible({ timeout });
+    }
+    return result;
+}
+/**
+ * For an action that may or may not raise a confirmation (a "Discard draft?" dialog after closing a composer): clicks
+ * `optional` whenever it is visible, and returns once `target` is hidden. Both happen in one retry loop, so a
+ * confirmation that shows up late is still clicked, and no confirmation does not cost a wait.
+ *
+ * `isVisible()` alone is not enough: it answers for this instant only and its `timeout` option is ignored.
+ * Prefer a `target` that stays on the same element (a role/name or test id locator); a `.last()` locator moves to the
+ * confirm dialog while that dialog is open.
+ *
+ *   await composer.getByRole('button', {name: 'close', exact: true}).click();
+ *   await clickOptionalUntilHidden(page.getByRole('button', {name: 'Discard', exact: true}), composer, {message: 'The email composer did not close'});
+ */
+export async function clickOptionalUntilHidden(optional, target, options = {}) {
+    const { timeout = 30_000, message = 'The element did not close' } = options;
+    await expect(async () => {
+        if (await optional.isVisible())
+            await optional.click({ timeout: 2_000 });
+        await expect(target).toBeHidden({ timeout: 1_000 });
+    }, message).toPass({ timeout, intervals: [250, 500, 1_000] });
+}
+/** Waits until nothing inside `scope` says it is still loading (busy regions, progress bars, spinners and skeletons that have a role or test id). */
+export async function expectNotBusy(scope, timeout = 30_000) {
+    const busy = scope.locator('[aria-busy="true"], [role="progressbar"], [role="status"][aria-live][aria-busy="true"], [data-tn*="loading" i], [data-tn*="skeleton" i], [data-testid*="loading" i], [data-testid*="skeleton" i]');
+    await expect(busy, 'The content is still loading').toHaveCount(0, { timeout });
+}

package/dist/lib/records.d.ts

@@ -0,0 +1,33 @@
+/** Every piece of data a test creates carries this prefix, so it can never be mistaken for real data. */
+export declare const TEST_DATA_PREFIX = "[asrun]";
+export type RecordStatus = 'open' | 'cleaned' | 'leftover';
+/** One piece of test data a case created, as written to the ledger. */
+export interface LedgerEntry {
+    id: string;
+    runId: string;
+    env: string;
+    profile: string;
+    caseId: string;
+    /** What kind of thing it is, e.g. "Document draft". */
+    kind: string;
+    /** Its name in the product; always starts with TEST_DATA_PREFIX. */
+    name: string;
+    /** Where a person can find and remove it by hand, e.g. "/app/documents". */
+    where: string | null;
+    /** `open`: created, not yet removed (also what a crashed run leaves behind). */
+    status: RecordStatus;
+    error: string | null;
+    createdAt: string;
+}
+export declare const RECORDS_DIR: string;
+/** The ledger of one test: `.tmp/records/<runId>/<file>.json`. One file per test, so parallel workers never share a file. */
+export declare const ledgerFile: (runId: string, testId: string) => string;
+export declare function writeLedger(file: string, entries: LedgerEntry[]): void;
+/** Entries of one run (or of every run) that are not known to be removed. */
+export declare function findLeftovers(options?: {
+    runId?: string;
+    env?: string;
+}): LedgerEntry[];
+/** Forget the ledgers of runs whose leftovers a person has removed by hand. */
+export declare function forgetLedgers(env: string): number;
+export declare function describeLeftovers(entries: LedgerEntry[]): string;

package/dist/lib/records.js

@@ -0,0 +1,61 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { ROOT } from './paths.js';
+/** Every piece of data a test creates carries this prefix, so it can never be mistaken for real data. */
+export const TEST_DATA_PREFIX = '[asrun]';
+export const RECORDS_DIR = path.join(ROOT, '.tmp', 'records');
+/** The ledger of one test: `.tmp/records/<runId>/<file>.json`. One file per test, so parallel workers never share a file. */
+export const ledgerFile = (runId, testId) => path.join(RECORDS_DIR, runId, `${testId.replace(/[^\w-]/g, '_')}.json`);
+export function writeLedger(file, entries) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(entries, null, 2));
+}
+function readLedger(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return [];
+    }
+}
+/** Entries of one run (or of every run) that are not known to be removed. */
+export function findLeftovers(options = {}) {
+    if (!fs.existsSync(RECORDS_DIR))
+        return [];
+    const runs = options.runId ? [options.runId] : fs.readdirSync(RECORDS_DIR);
+    return runs
+        .flatMap((run) => {
+        const dir = path.join(RECORDS_DIR, run);
+        if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory())
+            return [];
+        return fs.readdirSync(dir).filter((name) => name.endsWith('.json')).flatMap((name) => readLedger(path.join(dir, name)));
+    })
+        .filter((entry) => entry.status !== 'cleaned' && (!options.env || entry.env === options.env));
+}
+/** Forget the ledgers of runs whose leftovers a person has removed by hand. */
+export function forgetLedgers(env) {
+    if (!fs.existsSync(RECORDS_DIR))
+        return 0;
+    let removed = 0;
+    for (const run of fs.readdirSync(RECORDS_DIR)) {
+        const dir = path.join(RECORDS_DIR, run);
+        if (!fs.statSync(dir).isDirectory())
+            continue;
+        for (const name of fs.readdirSync(dir)) {
+            const file = path.join(dir, name);
+            if (readLedger(file).some((entry) => entry.env === env)) {
+                fs.rmSync(file);
+                removed++;
+            }
+        }
+        if (fs.readdirSync(dir).length === 0)
+            fs.rmdirSync(dir);
+    }
+    return removed;
+}
+export function describeLeftovers(entries) {
+    return entries
+        .map((entry) => `  - [${entry.profile} (${entry.env})] ${entry.kind} "${entry.name}" (case ${entry.caseId}, run ${entry.runId}` +
+        `${entry.where ? `, look in ${entry.where}` : ''})${entry.error ? `\n      cleanup said: ${entry.error}` : ''}`)
+        .join('\n');
+}

package/dist/lib/run-filters.d.ts

@@ -0,0 +1,19 @@
+/** Matches the spec file of one case (`documents/published-flow` must not match `documents/published-flow-2`). */
+export declare const casePattern: (id: string) => string;
+export interface RunFilters {
+    env: string;
+    /** `null` = every profile of the environment (no `--project` filter). */
+    profiles: string[] | null;
+    suites: string[];
+    /** The user's own `--grep`. */
+    grep?: string;
+    /** Leave out the cases that write data. */
+    readOnly: boolean;
+    /** Only these cases (ids such as `documents/published-flow`), e.g. the ones whose baselines are being updated. */
+    only?: string[];
+}
+/**
+ * The Playwright arguments that decide WHICH tests run. Shared by `pnpm asrun` and by the web UI's
+ * "what would this run do" preview, so both always agree.
+ */
+export declare function filterArgs(filters: RunFilters): string[];

package/dist/lib/run-filters.js

@@ -0,0 +1,38 @@
+/** `--grep` pattern that matches a tag exactly (`@smoke` must not match `@smoke-extra`). */
+const tagPattern = (name) => `@${name}(?![\\w-])`;
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/**
+ * Playwright matches `--grep` against a title that holds the spec file with the separator of this platform
+ * (`conduit/header-navigation.spec.ts` on macOS and Linux, `conduit\header-navigation.spec.ts` on Windows), so a
+ * `/` in a case id or in the user's search has to match either one. `\/` is left alone: it is already a plain `/`.
+ */
+const bothSeparators = (text) => text.replace(/(?<!\\)\//g, '[\\\\/]');
+/** Matches the spec file of one case (`documents/published-flow` must not match `documents/published-flow-2`). */
+export const casePattern = (id) => `(?:^|\\s)${bothSeparators(escapeRegExp(id))}\\.spec\\.ts`;
+/**
+ * The Playwright arguments that decide WHICH tests run. Shared by `pnpm asrun` and by the web UI's
+ * "what would this run do" preview, so both always agree.
+ */
+export function filterArgs(filters) {
+    // Playwright accepts a single --grep and matches it against the file, titles and tags, so the
+    // suite filter and the user's own --grep are combined into one regular expression.
+    const grepParts = [];
+    if (filters.suites.length > 0) {
+        grepParts.push(`(?:${filters.suites.map(tagPattern).join('|')})`);
+    }
+    if (filters.grep) {
+        // A case id (`conduit/header-navigation`) and a part of one (`conduit/head`) both have to match the spec file
+        // in Playwright's title, whatever separator this platform puts in it.
+        grepParts.push(`(?:${bothSeparators(filters.grep)})`);
+    }
+    if (filters.only && filters.only.length > 0) {
+        grepParts.push(`(?:${filters.only.map(casePattern).join('|')})`);
+    }
+    const invert = ['@seed', ...(filters.readOnly ? ['@writes'] : [])].join('|');
+    return [
+        ...(filters.profiles ? filters.profiles.flatMap((id) => ['--project', id]) : []),
+        ...(grepParts.length > 0 ? ['--grep', grepParts.map((part) => `(?=.*${part})`).join('')] : []),
+        '--grep-invert',
+        invert,
+    ];
+}