@asrunjs/asrun 0.0.0-stage → 0.5.2

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

@@ -0,0 +1,90 @@
+import type { LedgerEntry } from './records.js';
+/** One failure, split so that people read the meaning first and the technical noise only on demand. */
+export interface ParsedError {
+    /** First line of the message: what went wrong, in the words of the assertion message. */
+    headline: string;
+    /** The rest of the message before the call log (Locator / Expected / Received ...). */
+    context: string;
+    /** Playwright's call log: what it tried and waited for. */
+    callLog: string;
+    /** Code frame around the failing line. */
+    snippet: string;
+    /** Stack frames only (no message). */
+    stack: string;
+}
+export type ResultStatus = 'passed' | 'failed' | 'flaky' | 'skipped';
+export interface TestRunResult {
+    /** Playwright's id of the test (unique per project); the HTML report deep-links with it. */
+    testId: string;
+    caseId: string;
+    /** Profile id, without the environment. */
+    profile: string;
+    /** Environment of the run (`production`, `staging`, ...). Absent in summaries written before environments existed. */
+    env?: string;
+    /** The case writes test data (`writes` in its front matter). Absent in older summaries. */
+    writes?: boolean;
+    title: string;
+    status: ResultStatus;
+    durationMs: number;
+    /** How many times the test ran (retries included). */
+    attempts: number;
+    /** Title of the `test.step` that failed, e.g. "2. Find the first published document". */
+    failedStep: string | null;
+    errors: ParsedError[];
+    /** Paths relative to the HTML report folder (`data/<sha1>.png`). */
+    screenshots: string[];
+    /** Per-page recordings (`data/<sha1>.webm`). */
+    videos: string[];
+    /** All recordings of the test joined in order, relative to the report folder (`videos/<testId>.webm`). */
+    video?: string;
+}
+/** Playwright's overall result of the run. */
+export type RunStatus = 'passed' | 'failed' | 'timedout' | 'interrupted';
+/** How the run was started, so the report can run it again the same way. */
+export interface RunSettings {
+    stepText: boolean;
+    readOnly: boolean;
+    /** The profiles that were selected; null = every profile of the environment. */
+    profiles: string[] | null;
+    /** Tags that selected the profiles (absent = no tag filter). */
+    tags?: string[];
+    suites: string[];
+    /** The user's own `--grep`. */
+    grep?: string;
+    /** The run was limited to these cases (the part of an `--update-baselines` run that is not, or is, being rewritten). */
+    only?: string[];
+}
+/** Environment variable that carries the settings (JSON) from `pnpm asrun` to the summary reporter. */
+export declare const RUN_SETTINGS_ENV = "ASRUN_RUN_SETTINGS";
+export interface RunSummary {
+    runId: string;
+    /** Absent in summaries written before settings were recorded, and for runs not started by `pnpm asrun`. */
+    settings?: RunSettings;
+    /** Environment the whole run targeted. Absent in summaries written before environments existed (those were production). */
+    env?: string;
+    startedAt: string;
+    durationMs: number;
+    /** Absent in summaries written before run status was recorded. */
+    status?: RunStatus;
+    /**
+     * Errors that belong to the run, not to a test: a spec that fails to load (broken import, syntax
+     * error), a failing global setup or worker teardown. Absent in older summaries.
+     */
+    errors?: ParsedError[];
+    counts: Record<ResultStatus, number>;
+    /** Test data that was created and not removed again (needs a person). Absent in older summaries. */
+    leftovers?: LedgerEntry[];
+    results: TestRunResult[];
+}
+/** Turns a Playwright `TestError` into the parts shown by the UI. */
+export declare function parseError(error: {
+    message?: string;
+    stack?: string;
+    snippet?: string;
+    value?: string;
+}): ParsedError;
+/**
+ * `tests/<caseId>.spec.ts` -> `<caseId>`, with the group folder: `tests/documents/landing-page.spec.ts` -> `documents/landing-page`.
+ * Accepts the absolute path (`testInfo.file`) and the path relative to `tests/` (what `--list` reports).
+ */
+export declare function caseIdFromFile(file: string): string;

package/dist/lib/run-summary.js

@@ -0,0 +1,35 @@
+import { stripVTControlCharacters } from 'node:util';
+import path from 'node:path';
+import { TESTS_DIR } from './paths.js';
+/** Environment variable that carries the settings (JSON) from `pnpm asrun` to the summary reporter. */
+export const RUN_SETTINGS_ENV = 'ASRUN_RUN_SETTINGS';
+const CALL_LOG = /\n[ \t]*Call log:[ \t]*\n/;
+/** Turns a Playwright `TestError` into the parts shown by the UI. */
+export function parseError(error) {
+    const message = stripVTControlCharacters(error.message ?? error.value ?? 'Unknown error')
+        .replace(/^Error: /, '')
+        .trim();
+    const [body, callLog = ''] = message.split(CALL_LOG, 2);
+    const [headline = '', ...rest] = body.trim().split('\n');
+    const stack = stripVTControlCharacters(error.stack ?? '')
+        .split('\n')
+        .filter((line) => /^\s+at /.test(line))
+        .join('\n');
+    return {
+        headline: headline.trim(),
+        context: rest.join('\n').trim(),
+        callLog: callLog.trim(),
+        snippet: stripVTControlCharacters(error.snippet ?? '').trim(),
+        stack,
+    };
+}
+/**
+ * `tests/<caseId>.spec.ts` -> `<caseId>`, with the group folder: `tests/documents/landing-page.spec.ts` -> `documents/landing-page`.
+ * Accepts the absolute path (`testInfo.file`) and the path relative to `tests/` (what `--list` reports).
+ */
+export function caseIdFromFile(file) {
+    let relative = path.isAbsolute(file) ? path.relative(TESTS_DIR, file) : file;
+    if (relative.startsWith('..'))
+        relative = path.basename(file);
+    return relative.split(path.sep).join('/').replace(/\.spec\.[cm]?[jt]s$/, '');
+}

package/dist/lib/session.d.ts

@@ -0,0 +1,30 @@
+import type { Browser } from '@playwright/test';
+import { type Profile, type SessionCheck } from './profiles.js';
+export type SessionStatus = 'ok' | 'missing' | 'expired';
+/**
+ * Set by `pnpm asrun` after its pre-run login check: `profile-id:status,profile-id:status`
+ * for every profile that is not logged in. Lets the config and fixtures skip a second check.
+ */
+export declare const NOT_LOGGED_IN_ENV = "ASRUN_NOT_LOGGED_IN";
+export declare const hasSessionFile: (profile: Profile) => boolean;
+/** True when the address is (or starts below) the address a site sends a signed-out visitor to. */
+export declare function isLoggedOutUrl(url: string, check?: SessionCheck): boolean;
+/** Kept for callers that only ask about the conventional `/login` address. */
+export declare const isLoginUrl: (url: string) => boolean;
+/**
+ * Opens `sessionCheckPath` with the saved session and decides whether the profile is still signed in.
+ *
+ * A site can show "signed out" in more than one way, so every signal the profile names is watched at the
+ * same time: a redirect to `sessionCheck.loggedOutUrl` (server side or, in a single-page app, after the app
+ * has started), a 401/403 response, `loggedOutSelector`, or `loggedInSelector` proving the opposite. The
+ * page is read only after a signal arrived, never right after the navigation (which would still show the
+ * page before a client-side redirect happened).
+ */
+export declare function checkSession(browser: Browser, profile: Profile): Promise<SessionStatus>;
+export declare function parseNotLoggedIn(value?: string | undefined): Map<string, SessionStatus>;
+export declare const formatNotLoggedIn: (entries: Map<string, SessionStatus>) => string;
+export declare const signinCommand: (profile: {
+    id: string;
+}) => string;
+export declare const skipProfileHint: (profileIds: string[], env: string) => string;
+export declare const sessionProblemMessage: (profile: Profile, status: SessionStatus) => string;

package/dist/lib/session.js

@@ -0,0 +1,111 @@
+import fs from 'node:fs';
+import { DEFAULT_SESSION_CHECK } from './profiles.js';
+import { authFile } from './paths.js';
+/**
+ * Set by `pnpm asrun` after its pre-run login check: `profile-id:status,profile-id:status`
+ * for every profile that is not logged in. Lets the config and fixtures skip a second check.
+ */
+export const NOT_LOGGED_IN_ENV = 'ASRUN_NOT_LOGGED_IN';
+/** A response that means "you are not allowed in", for sites that answer with a status instead of a redirect. */
+const EXPIRED_STATUSES = new Set([401, 403]);
+export const hasSessionFile = (profile) => fs.existsSync(authFile(profile.id));
+/** True when the address is (or starts below) the address a site sends a signed-out visitor to. */
+export function isLoggedOutUrl(url, check = DEFAULT_SESSION_CHECK) {
+    let target;
+    try {
+        target = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    if (/^https?:\/\//i.test(check.loggedOutUrl)) {
+        try {
+            const expected = new URL(check.loggedOutUrl);
+            return target.origin === expected.origin && underPath(target.pathname, expected.pathname);
+        }
+        catch {
+            return false;
+        }
+    }
+    return underPath(target.pathname, check.loggedOutUrl);
+}
+const underPath = (pathname, expected) => pathname === expected || pathname.startsWith(expected.endsWith('/') ? expected : `${expected}/`);
+/** Kept for callers that only ask about the conventional `/login` address. */
+export const isLoginUrl = (url) => isLoggedOutUrl(url);
+/**
+ * Opens `sessionCheckPath` with the saved session and decides whether the profile is still signed in.
+ *
+ * A site can show "signed out" in more than one way, so every signal the profile names is watched at the
+ * same time: a redirect to `sessionCheck.loggedOutUrl` (server side or, in a single-page app, after the app
+ * has started), a 401/403 response, `loggedOutSelector`, or `loggedInSelector` proving the opposite. The
+ * page is read only after a signal arrived, never right after the navigation (which would still show the
+ * page before a client-side redirect happened).
+ */
+export async function checkSession(browser, profile) {
+    if (!hasSessionFile(profile))
+        return 'missing';
+    const check = profile.sessionCheck;
+    const context = await browser.newContext({ storageState: authFile(profile.id) });
+    try {
+        const page = await context.newPage();
+        const response = await page.goto(new URL(profile.sessionCheckPath, profile.baseURL).href, {
+            waitUntil: 'domcontentloaded',
+        });
+        if (response && EXPIRED_STATUSES.has(response.status()))
+            return 'expired';
+        if (isLoggedOutUrl(page.url(), check))
+            return 'expired';
+        const signal = await firstSignal(page, check);
+        if (signal)
+            return signal;
+        // Nothing showed up: fall back to the address, which is all a plain redirect leaves behind. A profile
+        // that named a signed-in marker gets an error instead, so a wrong check path is visible instead of "ok".
+        if (isLoggedOutUrl(page.url(), check))
+            return 'expired';
+        if (check.loggedInSelector) {
+            throw new Error(`${profile.sessionCheckPath} neither showed \`${check.loggedInSelector}\` nor went to ${check.loggedOutUrl} ` +
+                `within ${check.timeoutMs} ms, so the session could not be checked. Fix "sessionCheck" in profiles.yaml.`);
+        }
+        return 'ok';
+    }
+    finally {
+        await context.close();
+    }
+}
+/** The first signal that arrives wins; null when every one of them times out. */
+async function firstSignal(page, check) {
+    const timeout = check.timeoutMs;
+    const signals = [
+        page
+            .waitForURL((url) => isLoggedOutUrl(url.href, check), { timeout, waitUntil: 'commit' })
+            .then(() => 'expired'),
+    ];
+    if (check.loggedOutSelector) {
+        signals.push(page
+            .waitForSelector(check.loggedOutSelector, { state: 'visible', timeout })
+            .then(() => 'expired'));
+    }
+    if (check.loggedInSelector) {
+        signals.push(page.waitForSelector(check.loggedInSelector, { state: 'visible', timeout }).then(() => 'ok'));
+    }
+    try {
+        return await Promise.any(signals);
+    }
+    catch {
+        // Every signal timed out: the caller decides what an inconclusive page means.
+        return null;
+    }
+}
+export function parseNotLoggedIn(value = process.env[NOT_LOGGED_IN_ENV]) {
+    const result = new Map();
+    for (const entry of (value ?? '').split(',').filter(Boolean)) {
+        const [id, status] = entry.split(':');
+        result.set(id, status === 'missing' ? 'missing' : 'expired');
+    }
+    return result;
+}
+export const formatNotLoggedIn = (entries) => [...entries].map(([id, status]) => `${id}:${status}`).join(',');
+export const signinCommand = (profile) => `pnpm signin ${profile.id}`;
+export const skipProfileHint = (profileIds, env) => `pnpm asrun --env ${env} --skip-profile ${profileIds.join(',')}`;
+export const sessionProblemMessage = (profile, status) => `Profile "${profile.id}" is not logged in to ${profile.env} (session ${status}). ` +
+    `Log in first: ${signinCommand(profile)}  -  or skip this profile: ${skipProfileHint([profile.id], profile.env)}`;

package/dist/lib/summary-reporter.d.ts

@@ -0,0 +1,16 @@
+import type { FullResult, Reporter, TestCase, TestError } from '@playwright/test/reporter';
+/**
+ * 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 implements Reporter {
+    private startedAt;
+    private readonly tests;
+    private readonly errors;
+    onBegin(): void;
+    onTestEnd(test: TestCase): void;
+    onError(error: TestError): void;
+    onEnd(fullResult: FullResult): void;
+    printsToStdio(): boolean;
+    private summarize;
+}

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,19 @@
+import { type CaseTargetCard } from './case-doc.js';
+/**
+ * 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.
+ * Parsing lives in `lib/case-doc.ts` (pure), so the web panel reads the same cards.
+ */
+export type TargetCard = CaseTargetCard;
+export declare const TARGET_REF: RegExp;
+export declare const REQUIRED_FIELDS: readonly ["what", "where", "identified by"];
+export declare const 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,26 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { caseSectionText, parseTargetCards, TARGET_REQUIRED_FIELDS } from './case-doc.js';
+import { CASES_DIR } from './paths.js';
+export const TARGET_REF = /\[(T\d+)\]/g;
+export const REQUIRED_FIELDS = TARGET_REQUIRED_FIELDS;
+export const parseTargets = (text) => parseTargetCards(text);
+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 caseSectionText(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 { caseSectionText } from './case-doc.js';
+import { CASES_DIR } from './paths.js';
+import { loadProfiles } from './profiles.js';
+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 = caseSectionText(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;
+}