@asrunjs/asrun 0.0.0-stage → 0.2.0

package/dist/lib/summary-reporter.js

@@ -0,0 +1,146 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { getProfile } from './profiles.js';
+import { caseWrites, hasCaseFile, readCaseMeta } from './cases.js';
+import { concatVideos } from './ffmpeg.js';
+import { ROOT } from './paths.js';
+import { findLeftovers } from './records.js';
+import { caseIdFromFile, parseError, RUN_SETTINGS_ENV, } from './run-summary.js';
+const runId = process.env.ASRUN_RUN_ID ?? 'adhoc';
+const runEnv = process.env.ASRUN_ENV;
+function readSettings() {
+    try {
+        return process.env[RUN_SETTINGS_ENV] ? JSON.parse(process.env[RUN_SETTINGS_ENV]) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+const settings = readSettings();
+function writesData(caseId) {
+    try {
+        return hasCaseFile(caseId) && caseWrites(readCaseMeta(caseId));
+    }
+    catch {
+        return false;
+    }
+}
+function splitProject(name) {
+    try {
+        return { profile: name, env: getProfile(name).env };
+    }
+    catch {
+        return { profile: name };
+    }
+}
+/** Where the HTML reporter stores an attachment: `data/<sha1 of the content><extension>`. */
+function reportDataPath(file) {
+    try {
+        const sha1 = createHash('sha1').update(fs.readFileSync(file)).digest('hex');
+        return `data/${sha1}${path.extname(file)}`;
+    }
+    catch {
+        return null;
+    }
+}
+function firstFailedStep(steps) {
+    for (const step of steps) {
+        if (!step.error)
+            continue;
+        return (step.category === 'test.step' ? step.title : null) ?? firstFailedStep(step.steps);
+    }
+    return null;
+}
+function attachmentFiles(result, prefix) {
+    return result.attachments
+        .filter((attachment) => attachment.path && attachment.contentType.startsWith(prefix))
+        .map((attachment) => attachment.path);
+}
+function attachmentPaths(result, prefix) {
+    return attachmentFiles(result, prefix)
+        .map(reportDataPath)
+        .filter((value) => value !== null);
+}
+/** Joins the recordings of all pages of one test (a new tab has its own) into `reports/<runId>/videos/<testId>.webm`. */
+function joinVideos(result, testId) {
+    const inputs = attachmentFiles(result, 'video/').filter((file) => fs.existsSync(file));
+    if (inputs.length < 2)
+        return undefined;
+    const name = `videos/${testId.replace(/[^\w-]/g, '_')}.webm`;
+    const error = concatVideos(inputs, path.join(ROOT, 'reports', runId, name));
+    if (error) {
+        console.warn(`Could not join the ${inputs.length} videos of test ${testId}, showing them separately: ${error}`);
+        return undefined;
+    }
+    return name;
+}
+/**
+ * Writes `reports/<runId>/summary.json`: one entry per test (case x profile) with the error split into
+ * a readable headline and the technical details, so the UI can show what went wrong at a glance.
+ */
+export default class SummaryReporter {
+    startedAt = new Date();
+    tests = [];
+    errors = [];
+    onBegin() {
+        this.startedAt = new Date();
+    }
+    onTestEnd(test) {
+        this.tests.push(test);
+    }
+    // Errors outside any test, e.g. a spec that fails to load never reaches onTestEnd.
+    onError(error) {
+        const parsed = parseError(error);
+        const known = this.errors.some((item) => item.headline === parsed.headline && item.stack === parsed.stack);
+        if (!known)
+            this.errors.push(parsed);
+    }
+    onEnd(fullResult) {
+        const results = [...new Map(this.tests.map((test) => [test.id, test])).values()].map((test) => this.summarize(test));
+        const counts = { passed: 0, failed: 0, flaky: 0, skipped: 0 };
+        for (const result of results)
+            counts[result.status]++;
+        const summary = {
+            runId,
+            ...(runEnv && { env: runEnv }),
+            ...(settings && { settings }),
+            startedAt: this.startedAt.toISOString(),
+            durationMs: Date.now() - this.startedAt.getTime(),
+            status: fullResult.status,
+            errors: this.errors,
+            counts,
+            leftovers: findLeftovers({ runId }),
+            results,
+        };
+        const dir = path.join(ROOT, 'reports', runId);
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, 'summary.json'), JSON.stringify(summary, null, 2));
+    }
+    printsToStdio() {
+        return false;
+    }
+    summarize(test) {
+        const outcome = test.outcome();
+        const status = outcome === 'expected' ? 'passed' : outcome === 'skipped' ? 'skipped' : outcome === 'flaky' ? 'flaky' : 'failed';
+        // The last attempt explains a failure; for a flaky test the last attempt passed, so use the last failed one.
+        const attempt = [...test.results].reverse().find((result) => result.status !== 'passed') ?? test.results.at(-1);
+        const failed = status === 'failed' || status === 'flaky';
+        const caseId = caseIdFromFile(test.location.file);
+        return {
+            testId: test.id,
+            caseId,
+            ...splitProject(test.parent.project()?.name ?? ''),
+            writes: writesData(caseId),
+            title: test.title,
+            status,
+            durationMs: test.results.reduce((total, result) => total + result.duration, 0),
+            attempts: test.results.length,
+            failedStep: failed && attempt ? firstFailedStep(attempt.steps) : null,
+            errors: failed && attempt ? attempt.errors.map(parseError) : [],
+            screenshots: attempt ? attachmentPaths(attempt, 'image/') : [],
+            videos: attempt ? attachmentPaths(attempt, 'video/') : [],
+            video: attempt ? joinVideos(attempt, test.id) : undefined,
+        };
+    }
+}

package/dist/lib/targets.d.ts

@@ -0,0 +1,27 @@
+/**
+ * An assertion target card: the exact image, text, file or place that a check looks at, written in the case under
+ * `## Targets` as `### T<n> <name>` with `- What:`, `- Where:`, `- Identified by:` and `- Reference <profile-id>:` bullets.
+ */
+export interface TargetCard {
+    /** `T1`, `T2`, ... */
+    id: string;
+    name: string;
+    /** Field name (lower case, e.g. `what`, `where`, `identified by`, `not`, `ready when`, `kind`) to its text. */
+    fields: Record<string, string>;
+    /** `- Reference <profile-id>: <path>` bullets, keyed by what is written after `Reference`. */
+    references: Record<string, string>;
+    /** The card still has an open `🚫 TODO [blocking]` block: the target is not settled and no check may be built on it. */
+    blocking: boolean;
+}
+export declare const TARGET_REF: RegExp;
+export declare const REQUIRED_FIELDS: readonly ['what', 'where', 'identified by'];
+export declare function parseTargets(text: string): TargetCard[];
+export declare const readCaseText: (id: string) => string;
+/** The target ids that a text mentions as `[T1]`. */
+export declare const targetRefsIn: (text: string) => string[];
+/** The lines of "Expected" and "Visual checks" (and their sub-bullets) that need a target card. */
+export declare const NEEDS_TARGET: RegExp;
+export declare function checksNeedingTarget(text: string): {
+    line: string;
+    section: string;
+}[];

package/dist/lib/targets.js

@@ -0,0 +1,51 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { CASES_DIR } from './paths.js';
+export const TARGET_REF = /\[(T\d+)\]/g;
+export const REQUIRED_FIELDS = ['what', 'where', 'identified by'];
+const section = (text, name) => new RegExp(`^## ${name}\\s*$([\\s\\S]*?)(?=^## |(?![\\s\\S]))`, 'm').exec(text)?.[1] ?? '';
+export function parseTargets(text) {
+    const body = section(text, 'Targets');
+    const cards = [];
+    const parts = body.split(/^### /m).slice(1);
+    for (const part of parts) {
+        const [heading, ...lines] = part.split('\n');
+        const head = /^(T\d+)\b[\s:.-]*(.*)$/.exec(heading.trim());
+        if (!head)
+            continue;
+        const card = { id: head[1], name: head[2], fields: {}, references: {}, blocking: false };
+        for (const line of lines) {
+            if (/^\s*-\s*🚫 TODO \[blocking\]/.test(line))
+                card.blocking = true;
+            const reference = /^-\s+Reference\s+([^:]+):\s*(.*)$/.exec(line);
+            if (reference) {
+                card.references[reference[1].trim()] = reference[2].trim();
+                continue;
+            }
+            const field = /^-\s+([A-Za-z][A-Za-z ]*?):\s*(.*)$/.exec(line);
+            if (field)
+                card.fields[field[1].trim().toLowerCase()] = field[2].trim();
+        }
+        cards.push(card);
+    }
+    return cards;
+}
+export const readCaseText = (id) => fs.readFileSync(path.join(CASES_DIR, `${id}.md`), 'utf8');
+/** The target ids that a text mentions as `[T1]`. */
+export const targetRefsIn = (text) => [...new Set([...text.matchAll(TARGET_REF)].map((match) => match[1]))];
+/** The lines of "Expected" and "Visual checks" (and their sub-bullets) that need a target card. */
+export const NEEDS_TARGET = /\b(logo|image|icon|screenshot|snapshot|pdf|download(?:ed)?|file|photo|picture|banner|favicon|wordmark|colou?r)\b/i;
+export function checksNeedingTarget(text) {
+    const found = [];
+    for (const name of ['Expected', 'Visual checks']) {
+        for (const line of section(text, name).split('\n')) {
+            // A bullet that is only a question or an answer is part of a TODO block, not a check.
+            if (!/^\s*-\s/.test(line) || /TODO|Answer:/.test(line))
+                continue;
+            if (NEEDS_TARGET.test(line) && !TARGET_REF.test(line))
+                found.push({ line: line.trim(), section: name });
+            TARGET_REF.lastIndex = 0;
+        }
+    }
+    return found;
+}

package/dist/lib/ui-build.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The built web app. It is shipped inside the package (`prepack` builds it), so an installed asrun needs no
+ * front-end toolchain; in the framework repository it is rebuilt on demand.
+ */
+export declare const UI_DIST: string;
+/** True when a front-end toolchain is present (the framework repository, not an installed package). */
+export declare const canBuildUi: () => boolean;
+/** Builds the web UI into {@link UI_DIST}. Returns the exit code; `null` when there is no toolchain to build with. */
+export declare function buildUi(): number | null;
+export declare const uiIsBuilt: () => boolean;

package/dist/lib/ui-build.js

@@ -0,0 +1,30 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { commandScript } from './node-cli.js';
+import { FRAMEWORK_ROOT, ROOT } from './paths.js';
+/**
+ * The built web app. It is shipped inside the package (`prepack` builds it), so an installed asrun needs no
+ * front-end toolchain; in the framework repository it is rebuilt on demand.
+ */
+export const UI_DIST = path.join(FRAMEWORK_ROOT, 'ui', 'dist');
+/** True when a front-end toolchain is present (the framework repository, not an installed package). */
+export const canBuildUi = () => {
+    try {
+        commandScript('vite');
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/** Builds the web UI into {@link UI_DIST}. Returns the exit code; `null` when there is no toolchain to build with. */
+export function buildUi() {
+    if (!canBuildUi())
+        return null;
+    const result = spawnSync(process.execPath, [commandScript('vite'), 'build', '--config', path.join(FRAMEWORK_ROOT, 'ui', 'web', 'vite.config.ts')], { cwd: ROOT, stdio: 'inherit', env: { ...process.env, ASRUN_UI_DIST: UI_DIST } });
+    if (result.error)
+        throw result.error;
+    return result.status ?? 1;
+}
+export const uiIsBuilt = () => fs.existsSync(path.join(UI_DIST, 'index.html'));

package/dist/lib/values.d.ts

@@ -0,0 +1,29 @@
+import { type Profile } from './profiles.js';
+/**
+ * The values a case asserts, written in the case document itself under `## Values`:
+ *
+ * ```md
+ * ## Values
+ * ```yaml
+ * default:
+ *   createButton: Create New
+ * example-staging:
+ *   previewLogoAlt: Example
+ * ```
+ * ```
+ *
+ * `default` applies to every profile; an entry named after a profile id is deep-merged over it.
+ * The case document is the single source of truth: profiles.yaml never holds expected values.
+ */
+export type RawCaseValues = Record<string, Record<string, unknown>>;
+/** Parses and validates the `## Values` block. Throws an Error that starts with `label` and says what to fix. */
+export declare function parseCaseValues(text: string, label?: string): RawCaseValues;
+export declare function readCaseValues(caseId: string): RawCaseValues;
+/** `default`, then the values of the profile, deep-merged. */
+export declare function resolveValues(values: RawCaseValues, profileId: string): Record<string, any>;
+/**
+ * The expected values of one case for the profile that is running.
+ * Fails with a plain-language message, instead of a "cannot read properties of undefined" crash,
+ * when the case has no values for this profile yet or still has empty/TODO values.
+ */
+export declare function requireValues<T>(caseId: string, profile: Profile): T;

package/dist/lib/values.js

@@ -0,0 +1,85 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse } from 'yaml';
+import { CASES_DIR } from './paths.js';
+import { loadProfiles } from './profiles.js';
+const section = (text, name) => new RegExp(`^## ${name}\\s*$([\\s\\S]*?)(?=^## |(?![\\s\\S]))`, 'm').exec(text)?.[1] ?? '';
+const isPlainObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const caseFile = (caseId) => path.join(CASES_DIR, `${caseId}.md`);
+/** Parses and validates the `## Values` block. Throws an Error that starts with `label` and says what to fix. */
+export function parseCaseValues(text, label = 'case document') {
+    const body = section(text, 'Values').trim();
+    if (body === '')
+        return {};
+    const block = /```ya?ml\r?\n([\s\S]*?)```/i.exec(body);
+    if (!block) {
+        throw new Error(`${label}: "## Values" must hold one fenced yaml block (\`\`\`yaml ... \`\`\`)`);
+    }
+    let parsed;
+    try {
+        parsed = parse(block[1]);
+    }
+    catch (error) {
+        throw new Error(`${label}: the yaml in "## Values" is not valid: ${error.message}`);
+    }
+    if (parsed === null || parsed === undefined)
+        return {};
+    if (!isPlainObject(parsed)) {
+        throw new Error(`${label}: "## Values" must be a map of profile id (or "default") to a map of values`);
+    }
+    const known = new Set(['default', ...loadProfiles().map((profile) => profile.id)]);
+    const values = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        if (!isPlainObject(value)) {
+            throw new Error(`${label}: "## Values" entry "${key}" must be a map of keys to values`);
+        }
+        if (!known.has(key)) {
+            const others = [...known].join(', ');
+            throw new Error(`${label}: "## Values" has an entry for unknown profile "${key}". Known: ${others}`);
+        }
+        values[key] = value;
+    }
+    return values;
+}
+export function readCaseValues(caseId) {
+    const file = caseFile(caseId);
+    if (!fs.existsSync(file))
+        throw new Error(`Case "${caseId}" does not exist (expected ${path.relative(process.cwd(), file)}).`);
+    return parseCaseValues(fs.readFileSync(file, 'utf8'), `cases/${caseId}.md`);
+}
+/** `default`, then the values of the profile, deep-merged. */
+export function resolveValues(values, profileId) {
+    const merge = (base, override) => {
+        const result = { ...base };
+        for (const [key, value] of Object.entries(override)) {
+            result[key] = isPlainObject(value) && isPlainObject(result[key]) ? merge(result[key], value) : value;
+        }
+        return result;
+    };
+    return merge(values.default ?? {}, values[profileId] ?? {});
+}
+const isPlaceholder = (value) => value === null || value === undefined || value === '' || (typeof value === 'string' && /^\s*TODO\b/i.test(value));
+function findPlaceholders(value, prefix) {
+    if (value !== null && typeof value === 'object') {
+        return Object.entries(value).flatMap(([key, child]) => findPlaceholders(child, `${prefix}.${key}`));
+    }
+    return isPlaceholder(value) ? [prefix] : [];
+}
+/**
+ * The expected values of one case for the profile that is running.
+ * Fails with a plain-language message, instead of a "cannot read properties of undefined" crash,
+ * when the case has no values for this profile yet or still has empty/TODO values.
+ */
+export function requireValues(caseId, profile) {
+    const values = resolveValues(readCaseValues(caseId), profile.id);
+    if (Object.keys(values).length === 0) {
+        throw new Error(`Missing values: cases/${caseId}.md has no "## Values" for profile "${profile.id}" and no "default" entry. ` +
+            `Add the expected values for this profile to the case document.`);
+    }
+    const placeholders = findPlaceholders(values, 'values');
+    if (placeholders.length > 0) {
+        throw new Error(`Incomplete values: cases/${caseId}.md still has empty or TODO values for profile "${profile.id}": ${placeholders.join(', ')}. ` +
+            `Fill them in before running this test.`);
+    }
+    return values;
+}

package/dist/lib/write-gate.d.ts

@@ -0,0 +1,41 @@
+import { type RunFilters } from './run-filters.js';
+/** Set by `pnpm asrun` once a human confirmed that cases may write test data in this (protected) environment. */
+export declare const ALLOW_WRITES_ENV = "ASRUN_ALLOW_WRITES";
+/** Every environment except staging needs an explicit permission before a case may write data. */
+export declare const isProtectedEnv: (env: string) => boolean;
+export interface WriteCase {
+    id: string;
+    note: string;
+    /** Profiles whose test data the case will write to in this run. */
+    profiles: string[];
+}
+/** The write cases of a run, split by whether the environment is one the case may write in. */
+export interface WriteCases {
+    /** The case lists this environment under `writes`: it writes here, after the confirmation in a protected one. */
+    writing: WriteCase[];
+    /** The case writes only in other environments: it is skipped here with a notice, not failed. */
+    skipped: WriteCase[];
+}
+/** Can a case run in this environment at all (`envs` in its front matter)? */
+export declare function caseRunsIn(caseId: string, env: string): boolean;
+/** One case of a run and the profiles it runs for. `skip` says why it is skipped in this environment, if it is. */
+export interface PlannedCase {
+    id: string;
+    profiles: string[];
+    writes: boolean;
+    skip: string | null;
+}
+/**
+ * Every case that a run with these filters would list, as Playwright itself reports it (`--list`), so project, grep
+ * and suite filters are applied exactly as in the real run. Async, so a slow list of tests never blocks the UI server.
+ * Rejects with a readable message when Playwright cannot list the tests (for example an invalid grep expression).
+ */
+export declare function planRun(filters: RunFilters): Promise<PlannedCase[]>;
+/**
+ * The cases that a run with these filters would execute and that write data, split into those that write in this
+ * environment and those that are skipped here. Asks Playwright itself
+ * (`--list`), so project, grep and suite filters are applied exactly as in the real run.
+ */
+export declare function findWriteCases(filters: RunFilters): WriteCases;
+export declare function describeWriteCases(env: string, cases: WriteCase[]): string;
+export declare function describeSkippedWriteCases(env: string, cases: WriteCase[]): string;

package/dist/lib/write-gate.js

@@ -0,0 +1,129 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { STAGING } from './profiles.js';
+import { caseWrites, caseWritesIn, readCaseMeta } from './cases.js';
+import { commandScript } from './node-cli.js';
+import { ROOT } from './paths.js';
+import { filterArgs } from './run-filters.js';
+import { caseIdFromFile } from './run-summary.js';
+/** Set by `pnpm asrun` once a human confirmed that cases may write test data in this (protected) environment. */
+export const ALLOW_WRITES_ENV = 'ASRUN_ALLOW_WRITES';
+/** Every environment except staging needs an explicit permission before a case may write data. */
+export const isProtectedEnv = (env) => env !== STAGING;
+/** Can a case run in this environment at all (`envs` in its front matter)? */
+export function caseRunsIn(caseId, env) {
+    const { envs } = readCaseMeta(caseId);
+    return envs === null || envs.includes(env);
+}
+const PLAYWRIGHT = commandScript('@playwright/test', 'playwright');
+const listArgs = (filters) => ['test', '--list', '--reporter=json', ...filterArgs(filters)];
+const listEnv = (env) => ({ ...process.env, ASRUN_ENV: env });
+/** The profiles that a `--list` report schedules for each case. Throws when Playwright reported a real error. */
+function profilesByCaseOf(stdout, stderr) {
+    let report;
+    try {
+        report = JSON.parse(stdout);
+    }
+    catch {
+        throw new Error(`Could not list the tests: ${(stderr || stdout).trim().slice(0, 400)}`);
+    }
+    // "No tests found" is an empty result, not a failure; anything else (an invalid expression, a broken spec) is.
+    const problem = (report.errors ?? []).find((error) => !/No tests found/.test(error.message ?? ''));
+    if (problem)
+        throw new Error(String(problem.message ?? 'Playwright could not list the tests.').trim().slice(0, 400));
+    const profilesByCase = new Map();
+    const visit = (suite) => {
+        for (const spec of suite.specs ?? []) {
+            const caseId = caseIdFromFile(spec.file);
+            for (const test of spec.tests ?? []) {
+                const profile = String(test.projectName);
+                if (!profilesByCase.has(caseId))
+                    profilesByCase.set(caseId, new Set());
+                profilesByCase.get(caseId).add(profile);
+            }
+        }
+        for (const child of suite.suites ?? [])
+            visit(child);
+    };
+    for (const suite of report.suites ?? [])
+        visit(suite);
+    return profilesByCase;
+}
+/**
+ * Every case that a run with these filters would list, as Playwright itself reports it (`--list`), so project, grep
+ * and suite filters are applied exactly as in the real run. Async, so a slow list of tests never blocks the UI server.
+ * Rejects with a readable message when Playwright cannot list the tests (for example an invalid grep expression).
+ */
+export async function planRun(filters) {
+    const { stdout, stderr } = await new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [PLAYWRIGHT, ...listArgs(filters)], { cwd: ROOT, env: listEnv(filters.env) });
+        let out = '';
+        let err = '';
+        child.stdout.on('data', (chunk) => (out += chunk));
+        child.stderr.on('data', (chunk) => (err += chunk));
+        child.on('error', reject);
+        // The exit code is not checked: "no tests found" exits with 1 but still prints a valid (empty) report.
+        child.on('close', () => resolve({ stdout: out, stderr: err }));
+    });
+    const planned = [];
+    for (const [id, profiles] of profilesByCaseOf(stdout, stderr)) {
+        let meta;
+        try {
+            meta = readCaseMeta(id);
+        }
+        catch {
+            continue; // seed.spec.ts and other specs without a case document
+        }
+        const skip = !caseRunsIn(id, filters.env)
+            ? `Limited to: ${meta.envs?.join(', ')}`
+            : caseWrites(meta) && !caseWritesIn(meta, filters.env)
+                ? `Writes data, no permission in ${filters.env.toUpperCase()}`
+                : null;
+        planned.push({ id, profiles: [...profiles].sort(), writes: caseWrites(meta), skip });
+    }
+    return planned.sort((a, b) => a.id.localeCompare(b.id));
+}
+/**
+ * The cases that a run with these filters would execute and that write data, split into those that write in this
+ * environment and those that are skipped here. Asks Playwright itself
+ * (`--list`), so project, grep and suite filters are applied exactly as in the real run.
+ */
+export function findWriteCases(filters) {
+    const env = filters.env;
+    const result = spawnSync(process.execPath, [PLAYWRIGHT, ...listArgs(filters)], {
+        cwd: ROOT,
+        encoding: 'utf8',
+        env: listEnv(env),
+        maxBuffer: 50_000_000,
+    });
+    const profilesByCase = profilesByCaseOf(result.stdout, result.stderr);
+    const writing = [];
+    const skipped = [];
+    for (const [id, profiles] of profilesByCase) {
+        let meta;
+        try {
+            meta = readCaseMeta(id);
+        }
+        catch {
+            continue; // seed.spec.ts and other specs without a case document
+        }
+        if (!caseWrites(meta) || !caseRunsIn(id, env))
+            continue;
+        (caseWritesIn(meta, env) ? writing : skipped).push({ id, note: meta.writesNote ?? '', profiles: [...profiles].sort() });
+    }
+    const byId = (a, b) => a.id.localeCompare(b.id);
+    return { writing: writing.sort(byId), skipped: skipped.sort(byId) };
+}
+export function describeWriteCases(env, cases) {
+    return [
+        `${cases.length} case(s) in this run write data in ${env.toUpperCase()}:`,
+        ...cases.flatMap((item) => [`  - ${item.id}  (profiles: ${item.profiles.join(', ')})`, `      ${item.note}`]),
+        'They only touch data of the test accounts. They never send email in production.',
+    ].join('\n');
+}
+export function describeSkippedWriteCases(env, cases) {
+    return [
+        `Skipped: ${cases.length} case(s) write data but have no permission to write in ${env.toUpperCase()}:`,
+        ...cases.map((item) => `  - ${item.id}`),
+        `To allow one, add "${env}" to "writes" in its front matter (and make sure it cleans up).`,
+    ].join('\n');
+}

package/dist/playwright.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("@playwright/test").PlaywrightTestConfig<{}, {}>;
+export default _default;

package/dist/playwright.config.js

@@ -0,0 +1,92 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { defineConfig, devices } from '@playwright/test';
+import { listProfiles } from './lib/profiles.js';
+import { authFile, isFrameworkRoot, REPORTS_DIR, ROOT, TEMPLATES_DIR, TMP_DIR } from './lib/paths.js';
+import { parseNotLoggedIn } from './lib/session.js';
+import { PRODUCT_NAME } from './ui/shared/product.js';
+const runId = process.env.ASRUN_RUN_ID ?? 'adhoc';
+// Set by `pnpm asrun --env <env>`. Without it (MCP exploration, `--list`) every profile is a project.
+const runEnv = process.env.ASRUN_ENV;
+const stepText = process.env.ASRUN_STEP_TEXT === '1';
+// Exploration through the MCP (and `--list`) has no environment. Nobody needs videos, traces or screenshots there,
+// and encoding a video of a long, busy session can stall the browser.
+const recording = runEnv !== undefined;
+const notLoggedIn = parseNotLoggedIn();
+const profiles = listProfiles();
+const selected = profiles.filter((profile) => !runEnv || profile.env === runEnv);
+if (profiles.length === 0) {
+    throw new Error(`No profiles in ${path.join(ROOT, 'profiles.yaml')}. Add one entry per environment (see ` +
+        `${path.join(TEMPLATES_DIR, 'profiles.yaml')}), then log in with "pnpm signin <profile-id>".` +
+        (isFrameworkRoot()
+            ? ' This looks like the framework folder itself: run the command in a project that uses the framework, or set ASRUN_ROOT.'
+            : ''));
+}
+if (runEnv !== undefined && selected.length === 0) {
+    throw new Error(`profiles.yaml has no profile with "env: ${runEnv}". Known environments: ${[...new Set(profiles.map((profile) => profile.env))].join(', ')}.`);
+}
+// Every path is absolute on purpose: a project that uses the framework re-exports this file from its own
+// `playwright.config.ts`, and Playwright resolves relative paths against the file that holds them (this one).
+// The compiled package has `summary-reporter.js`; the framework repository runs the `.ts` source.
+const summaryReporter = [path.join(import.meta.dirname, 'lib', 'summary-reporter.js'), path.join(import.meta.dirname, 'lib', 'summary-reporter.ts')].find((file) => fs.existsSync(file));
+export default defineConfig({
+    testDir: path.join(ROOT, 'tests'),
+    outputDir: path.join(TMP_DIR, 'results'),
+    timeout: 60_000,
+    expect: {
+        timeout: 10_000,
+        toHaveScreenshot: { maxDiffPixelRatio: 0.01, animations: 'disabled' },
+    },
+    retries: 1,
+    // Be gentle with the sites under test.
+    workers: 2,
+    metadata: {
+        environment: runEnv ? runEnv.toUpperCase() : 'not set',
+        runId,
+        workspace: ROOT,
+    },
+    reporter: [
+        ['list'],
+        [
+            'html',
+            {
+                outputFolder: path.join(REPORTS_DIR, runId, 'html'),
+                open: 'never',
+                title: runEnv ? `${PRODUCT_NAME} report - ${runEnv.toUpperCase()} - ${runId}` : `${PRODUCT_NAME} report - ${runId}`,
+            },
+        ],
+        [summaryReporter],
+    ],
+    use: {
+        // Project convention in uc-frontend: data-tn attributes.
+        testIdAttribute: 'data-tn',
+        // `pnpm asrun --step-text` overlays the current test.step() title on the video.
+        video: recording
+            ? {
+                mode: 'on',
+                size: { width: 1440, height: 900 },
+                ...(stepText && { show: { test: { level: 'step', position: 'top-left' } } }),
+            }
+            : 'off',
+        trace: recording ? 'on' : 'off',
+        screenshot: recording ? 'on' : 'off',
+        // Without these a locator that matches nothing (a dialog that never opened) waits for ever. In a test the 60 s
+        // test timeout ended it anyway; in an MCP exploration nothing did, and the agent hung.
+        actionTimeout: 15_000,
+        navigationTimeout: 30_000,
+        locale: 'en-US',
+        timezoneId: 'America/New_York',
+    },
+    // One project per profile. Baseline images are stored per project, so every environment keeps its own.
+    projects: selected.map((profile) => ({
+        name: profile.id,
+        // Retrying cannot fix a missing login.
+        ...(notLoggedIn.has(profile.id) && { retries: 0 }),
+        use: {
+            ...devices['Desktop Chrome'],
+            viewport: { width: 1440, height: 900 },
+            baseURL: profile.baseURL,
+            ...(fs.existsSync(authFile(profile.id)) && { storageState: authFile(profile.id) }),
+        },
+    })),
+});

package/dist/scripts/build.d.ts

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