@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/runtime/scenario/record.js

@@ -0,0 +1,100 @@
+/**
+ * What a passing request step keeps: its call, the values it saves into scope, the claims it reads
+ * from a token, the account those values descend from, and the observation each of its asserts makes.
+ */
+import { interpolate } from "../steps/interpolate.js";
+import { jwtClaims } from "../../credentials/jwt.js";
+import { cookiesFromRecordedHeaders } from "../cookies/set-cookie.js";
+import { readSaveAs } from "../cookies/save-as.js";
+import { readPath } from "../../client/read-path.js";
+import { blamed, StepFailure } from "./failure.js";
+import { keep, tagOf } from "./lineage.js";
+import { shownValue } from "./want.js";
+export function record(run, passed) {
+    const { stepOp } = passed;
+    /* An observed call keeps its pair; a later repeat of the operation proves nothing new. */
+    if (stepOp !== undefined && !run.observations.has(stepOp))
+        run.calls.set(stepOp, passed.exchange);
+    saveValues(run, passed);
+    saveClaims(run, passed);
+    keep(run.lineage, passed.step, tagOf(run.lineage, passed.step, run.input.accounts?.madeBy(passed.exchange)));
+    if (passed.wants.length === 0)
+        return;
+    observe(run, passed);
+}
+/** `saveAs`: each value into scope, an object, number or boolean also kept whole. */
+function saveValues(run, passed) {
+    const { exchange, step, stepOp } = passed;
+    const { objects, scope } = run;
+    const cookies = exchange.cookies ?? cookiesFromRecordedHeaders(exchange.responseHeaders);
+    for (const [name, template] of Object.entries(step.saveAs ?? {})) {
+        const path = String(interpolate(template, scope));
+        const value = readSaveAs(path, {
+            body: exchange.responseBody,
+            cookies,
+            headers: exchange.responseHeaders,
+            readJson: readPath,
+        });
+        if (value === undefined || value === null) {
+            throw new StepFailure(`saveAs.${name} = "${path}" is not in the response`, [exchange], blamed(stepOp));
+        }
+        if (typeof value === "object") {
+            objects.set(name, value);
+            scope[name] = JSON.stringify(value);
+        }
+        else {
+            if (typeof value === "number" || typeof value === "boolean")
+                objects.set(name, value);
+            else
+                objects.delete(name);
+            scope[name] = String(value);
+        }
+    }
+}
+/** `saveClaimsFrom`: claims of the JWT in scope or in the response, into scope. */
+function saveClaims(run, passed) {
+    const { exchange, step, stepOp } = passed;
+    const { scope } = run;
+    if (step.saveClaimsFrom === undefined)
+        return;
+    const from = step.saveClaimsFrom.token;
+    const token = !from.startsWith("$") && scope[from] !== undefined ? scope[from] : readPath(exchange.responseBody, from);
+    const claims = typeof token === "string" ? jwtClaims(token) : null;
+    if (claims === null) {
+        throw new StepFailure(`saveClaimsFrom: no JWT at ${from}`, [exchange], blamed(stepOp));
+    }
+    for (const [name, claim] of Object.entries(step.saveClaimsFrom.bind)) {
+        const value = readPath(claims, claim);
+        if (value === undefined || value === null) {
+            throw new StepFailure(`saveClaimsFrom: the token carries no "${claim}"`, [exchange], blamed(stepOp));
+        }
+        scope[name] = String(value);
+    }
+}
+/** Each assert observes the operations it names; the step's own operation is shown by its first assert. */
+function observe(run, passed) {
+    const { exchange, stepOp, wants } = passed;
+    const { calls, observations } = run;
+    /* Every assert held on this exchange, so each shows a value. */
+    const observationOf = (want) => want.mode === "excludes" || want.mode === "omits"
+        ? { absent: true, path: want.from, seq: exchange.seq, value: want.value }
+        : { path: want.from, seq: exchange.seq, value: shownValue(exchange, want.from, want) };
+    /* A write's own response is its claim, not a later read of it: it proves nothing about itself. */
+    const reads = /^(GET|HEAD)$/i.test(exchange.method);
+    const prove = (id, want) => {
+        if (!calls.has(id))
+            return;
+        if (calls.get(id) === exchange && !reads)
+            return;
+        observations.set(id, observationOf(want));
+    };
+    for (const { assert, want } of wants) {
+        for (const id of assert.observes ?? [])
+            prove(id, want);
+    }
+    /* `record` observes only when the step asserts something. */
+    const first = wants[0];
+    if (stepOp !== undefined)
+        prove(stepOp, first.want);
+}
+//# sourceMappingURL=record.js.map

package/dist/api/runtime/scenario/request.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A request step: sent as the scenario's principal, another configured one, or anonymously, and
+ * re-sent within its poll window until what it asserts shows.
+ */
+import type { ScenarioRequestStep } from "../../config/types/steps.ts";
+import type { ScenarioRun } from "./types.ts";
+export declare function requestStep(run: ScenarioRun, step: ScenarioRequestStep, index: number): Promise<void>;
+//# sourceMappingURL=request.d.ts.map

package/dist/api/runtime/scenario/request.js

@@ -0,0 +1,89 @@
+/**
+ * A request step: sent as the scenario's principal, another configured one, or anonymously, and
+ * re-sent within its poll window until what it asserts shows.
+ */
+import { resolveRequest } from "../steps/request.js";
+import { blamed, ScenarioStopped, StepFailure } from "./failure.js";
+import { selfDeleted } from "./lineage.js";
+import { durationMs, nextPollWait } from "./poll.js";
+import { record } from "./record.js";
+import { principalOf } from "./state.js";
+import { stepOperation } from "./validate.js";
+import { holds, wantsOf } from "./want.js";
+export async function requestStep(run, step, index) {
+    const stepOp = stepOperation(step);
+    const deadline = step.poll === undefined ? 0 : Date.now() + durationMs(step.poll.within);
+    let waitMs = step.poll?.everyMs ?? 500;
+    for (;;) {
+        const { exchange, request } = await send(run, { index, step, stepOp });
+        const ok = succeeded(step, exchange);
+        const wants = wantsOf(step, run.scope);
+        const unmet = wants.find(({ want }) => !holds(exchange, want.from, want))?.want;
+        if (ok && unmet === undefined) {
+            record(run, { exchange, step, stepOp, wants });
+            return;
+        }
+        if (Date.now() < deadline) {
+            if (run.input.stopped?.() === true)
+                throw new ScenarioStopped();
+            await run.sleep(waitMs);
+            if (run.input.stopped?.() === true)
+                throw new ScenarioStopped();
+            waitMs = nextPollWait(waitMs, step.poll?.everyMs ?? 500);
+            continue;
+        }
+        throw unshown(run, { exchange, ok, request, stepOp, unmet, wants });
+    }
+}
+/** The step's request, resolved against the scope and sent as the actor it names, through its origin's client. */
+async function send(run, at) {
+    const { step, stepOp } = at;
+    const request = await resolveRequest(run.context, step, run.scope, at.index);
+    const exchange = await request.client.request(request.method, request.path, {
+        ...(request.body === undefined ? {} : { body: request.body }),
+        ...(request.contentType === undefined ? {} : { contentType: request.contentType }),
+        as: actorOf(run, step),
+        headers: request.headers ?? {},
+        ...(request.query === undefined ? {} : { query: request.query }),
+        ...(stepOp === undefined ? {} : { operationId: stepOp }),
+        ...(request.redirect === undefined ? {} : { redirect: request.redirect }),
+    });
+    run.sent.push(exchange);
+    /* An accepted delete removed the account, whatever the step then asserts of its answer. */
+    selfDeleted(run.lineage, { accounts: run.input.accounts, exchange, step });
+    return { exchange, request };
+}
+/** Nobody for an anonymous step, else the principal the step names or the scenario's, on the scheme it names. */
+function actorOf(run, step) {
+    if (step.anonymous === true)
+        return { anonymous: true };
+    const principal = step.principal ?? run.principal;
+    /* Refuses a principal the config does not have, before anything is sent as it. */
+    principalOf(run.input, run.scenario, principal);
+    return step.scheme === undefined ? { principal } : { principal, scheme: step.scheme };
+}
+function succeeded(step, exchange) {
+    const accepted = step.expect ?? [];
+    if (accepted.length > 0)
+        return accepted.includes(exchange.status);
+    return exchange.status >= 200 && exchange.status < 300;
+}
+/**
+ * The failure of a step whose window ran out: a refused request blames the step's operation, an
+ * unmet assert blames every operation it would have proved. The calls those operations already
+ * made are evidence beside this one.
+ */
+function unshown(run, last) {
+    const { exchange, request, stepOp } = last;
+    const proves = [...last.wants.flatMap(({ assert }) => assert.observes ?? []), ...blamed(stepOp)];
+    const earlier = proves
+        .map((id) => run.calls.get(id))
+        .filter((call) => call !== undefined && call !== exchange);
+    if (!last.ok) {
+        return new StepFailure(`${request.method} ${request.path} returned ${exchange.status}`, [...earlier, exchange], blamed(stepOp));
+    }
+    /* A request that succeeded reaches here only with an assert unmet. */
+    const unmet = last.unmet;
+    return new StepFailure(`${request.method} ${request.path} did not show ${unmet.mode} "${unmet.value}" at ${unmet.from}`, [...earlier, exchange], proves);
+}
+//# sourceMappingURL=request.js.map

package/dist/api/runtime/scenario/run.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Every configured scenario that touches the run's scope, in order: its steps run until one fails
+ * or the run is told to stop, and what they observed is graded.
+ */
+import type { ScenarioInput } from "./types.ts";
+export declare function runScenarios(input: ScenarioInput): Promise<void>;
+//# sourceMappingURL=run.d.ts.map

package/dist/api/runtime/scenario/run.js

@@ -0,0 +1,90 @@
+/**
+ * Every configured scenario that touches the run's scope, in order: its steps run until one fails
+ * or the run is told to stop, and what they observed is graded.
+ */
+import { failureOf, ScenarioStopped } from "./failure.js";
+import { gradeScenario, proveCalled } from "./grade.js";
+import { wait } from "./poll.js";
+import { startScenario } from "./state.js";
+import { runStep } from "./step.js";
+import { scenarioCheckId, stepOperation } from "./validate.js";
+export async function runScenarios(input) {
+    const sleep = input.sleep ?? wait;
+    for (const scenario of input.scenarios) {
+        if (input.stopped?.() === true)
+            return;
+        const graded = scenario.covers.filter((id) => input.mode === "full" || input.inScope(id));
+        const reaches = touches(input, scenario);
+        if (graded.length === 0 && !reaches)
+            continue;
+        const check = scenarioCheckId(scenario);
+        input.checksRun.add(check);
+        if (skippedBy(input, scenario, graded) || blockedBy(input, scenario, { check, graded }))
+            continue;
+        const run = startScenario(input, scenario, sleep);
+        const ended = await runSteps(run);
+        /* Stopped from outside: what completed is graded; nothing unreached is a verdict. */
+        if (ended === "stopped") {
+            proveCalled(run, graded, check);
+            return;
+        }
+        gradeScenario(run, graded, ended);
+    }
+}
+/* A scenario the profile leaves out is not run: a gap with the reason, and what it covers stays ungraded. */
+function skippedBy(input, scenario, graded) {
+    const reason = input.skipped?.(scenario) ?? null;
+    if (reason === null)
+        return false;
+    input.findings.attributed([...graded]).gap("profile.skip", scenario.id, {
+        detail: `${reason}. What it covers stays ungraded under this profile.`,
+        summary: `scenario "${scenario.id}" skipped by the profile`,
+    });
+    return true;
+}
+/*
+ * A scenario that sends as a principal BLOCKED at sign-in, itself or in a step, is not run: it is
+ * BLOCKED by that principal, and what it covers stays ungraded. True when it was.
+ */
+function blockedBy(input, scenario, at) {
+    const named = [
+        scenario.principal,
+        ...scenario.steps.map((step) => ("principal" in step ? step.principal : undefined)),
+    ];
+    const principal = named.find((id) => id !== undefined && input.blocked.has(id));
+    if (principal === undefined)
+        return false;
+    const cause = `principal "${principal}" is BLOCKED: ${input.blocked.get(principal)}`;
+    input.findings
+        .attributed([...at.graded])
+        .ownedBy(at.check)
+        .blocked(at.check, scenario.id, {
+        cause,
+        summary: `scenario "${scenario.id}" sends as a principal that is BLOCKED`,
+    });
+    return true;
+}
+/** True when a step of the scenario calls an operation in scope. */
+function touches(input, scenario) {
+    return scenario.steps.some((step) => {
+        const id = stepOperation(step);
+        return id !== undefined && input.inScope(id);
+    });
+}
+/** The scenario's steps in order: where one failed, `"stopped"` when the run was told to stop, else `null`. */
+async function runSteps(run) {
+    for (const [index, step] of run.scenario.steps.entries()) {
+        try {
+            if (run.input.stopped?.() === true)
+                throw new ScenarioStopped();
+            await runStep(run, step, index);
+        }
+        catch (error) {
+            if (error instanceof ScenarioStopped)
+                return "stopped";
+            return { failure: failureOf(error), index };
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=run.js.map

package/dist/api/runtime/scenario/state.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A scenario's running state: the principal it sends as, its scope, and the values its steps
+ * keep whole, which its requests and external inputs send as they are.
+ */
+import type { Scenario } from "../../config/types/steps.ts";
+import type { ScenarioInput, ScenarioPrincipal, ScenarioRun } from "./types.ts";
+/** The configured principal `id`; a scenario that names another is refused. */
+export declare function principalOf(input: ScenarioInput, scenario: Scenario, id: string): ScenarioPrincipal;
+export declare function startScenario(input: ScenarioInput, scenario: Scenario, sleep: (ms: number) => Promise<void>): ScenarioRun;
+//# sourceMappingURL=state.d.ts.map

package/dist/api/runtime/scenario/state.js

@@ -0,0 +1,40 @@
+/**
+ * A scenario's running state: the principal it sends as, its scope, and the values its steps
+ * keep whole, which its requests and external inputs send as they are.
+ */
+/** The configured principal `id`; a scenario that names another is refused. */
+export function principalOf(input, scenario, id) {
+    const found = input.principals.get(id);
+    if (found === undefined)
+        throw new Error(`testing api: scenario "${scenario.id}" names principal "${id}", which is not configured`);
+    return found;
+}
+export function startScenario(input, scenario, sleep) {
+    const principal = scenario.principal ?? input.defaultPrincipal;
+    const own = principalOf(input, scenario, principal);
+    /* One map: what a step keeps, every later step's request and input send whole. */
+    const objects = new Map();
+    return {
+        calls: new Map(),
+        context: {
+            client: input.client,
+            hooks: input.hooks,
+            kept: objects,
+            model: input.model,
+            principalId: principal,
+            ...(input.originClients === undefined ? {} : { originClients: input.originClients }),
+            ...(input.outOfBand === undefined ? {} : { outOfBand: input.outOfBand }),
+        },
+        input,
+        lineage: new Map(),
+        objects,
+        observations: new Map(),
+        principal,
+        scenario,
+        /* The parameters bound for the principal (organization, project …) are there from the first step, as in the matrix. */
+        scope: { ...own.scope },
+        sent: [],
+        sleep,
+    };
+}
+//# sourceMappingURL=state.js.map

package/dist/api/runtime/scenario/step.d.ts

@@ -0,0 +1,8 @@
+/**
+ * One scenario step: its binds first, then a value delivered outside HTTP, a hook only a person or
+ * a browser can answer, or a request.
+ */
+import type { ScenarioStep } from "../../config/types/steps.ts";
+import type { ScenarioRun } from "./types.ts";
+export declare function runStep(run: ScenarioRun, step: ScenarioStep, index: number): Promise<void>;
+//# sourceMappingURL=step.d.ts.map

package/dist/api/runtime/scenario/step.js

@@ -0,0 +1,51 @@
+/**
+ * One scenario step: its binds first, then a value delivered outside HTTP, a hook only a person or
+ * a browser can answer, or a request.
+ */
+import { interpolate } from "../steps/interpolate.js";
+import { resolveOutOfBandValue, triggerSentAt } from "../steps/out-of-band.js";
+import { StepFailure } from "./failure.js";
+import { requestStep } from "./request.js";
+import { isExternal, isOutOfBand } from "./validate.js";
+export async function runStep(run, step, index) {
+    for (const [name, literal] of Object.entries("bind" in step && step.bind !== undefined ? step.bind : {})) {
+        run.scope[name] = String(interpolate(literal, run.scope));
+    }
+    if (isOutOfBand(step))
+        return outOfBandStep(run, step);
+    if (isExternal(step))
+        return externalStep(run, step, index);
+    return requestStep(run, step, index);
+}
+async function outOfBandStep(run, step) {
+    const { input, scope } = run;
+    const address = String(interpolate(step.outOfBand.address, scope));
+    const since = step.outOfBand.sentEarlier === true ? undefined : triggerSentAt(run.sent, address);
+    scope[step.outOfBand.as] = await resolveOutOfBandValue(input.hooks.resolveOutOfBand, address, {
+        kind: step.outOfBand.kind,
+        label: `scenario "${run.scenario.id}"`,
+        scope: { ...scope },
+        ...(since === undefined ? {} : { since }),
+        ...(input.outOfBand === undefined ? {} : { outOfBand: input.outOfBand }),
+    });
+}
+async function externalStep(run, step, index) {
+    const { hooks } = run.input;
+    if (hooks.external === undefined) {
+        throw new StepFailure(`step ${index + 1} needs hooks.external for "${step.external}"`, [], []);
+    }
+    const value = await hooks.external(step.external, interpolate(step.input ?? {}, run.scope, run.objects));
+    if (value === null || value === "") {
+        throw new StepFailure(`hooks.external("${step.external}") returned nothing`, [], []);
+    }
+    run.scope[step.as] = value;
+    if (/^\s*[[{]/.test(value)) {
+        try {
+            run.objects.set(step.as, JSON.parse(value));
+        }
+        catch {
+            /* A string that only looks like JSON stays a string. */
+        }
+    }
+}
+//# sourceMappingURL=step.js.map

package/dist/api/runtime/scenario/types.d.ts

@@ -0,0 +1,63 @@
+import type { Hooks } from "../../config/types/hooks.ts";
+import type { Scenario } from "../../config/types/steps.ts";
+import type { SpecModel } from "../../spec/graph/types.ts";
+import type { OriginClient, StepContext } from "../steps/request.ts";
+import type { Client } from "../../client/client.ts";
+import type { Exchange } from "../exchange.ts";
+import type { FindingCollector } from "../finding.ts";
+import type { BackoffConfig } from "../poll.ts";
+import type { GradeLedger, PassEvidence } from "../grades.ts";
+import type { Lineage, ScenarioAccounts } from "./lineage.ts";
+/** A configured principal as a scenario sends as it, `as: { principal: id }`: the parameters bound for it. */
+export interface ScenarioPrincipal {
+    scope: Readonly<Record<string, string>>;
+}
+export interface ScenarioInput {
+    /** True once the run must stop: no further scenario, step or poll starts. */
+    stopped?: () => boolean;
+    scenarios: readonly Scenario[];
+    model: SpecModel;
+    client: Client;
+    findings: FindingCollector;
+    grades: GradeLedger;
+    hooks: Hooks;
+    checksRun: Set<string>;
+    inScope: (operationId: string) => boolean;
+    mode: "full" | "targeted";
+    principals: ReadonlyMap<string, ScenarioPrincipal>;
+    /** Configured principals whose sign-in was refused, with why: a scenario that needs one cannot run. */
+    blocked: ReadonlyMap<string, string>;
+    defaultPrincipal: string;
+    /** Why the active profile leaves a scenario out, or `null` when it runs. */
+    skipped?: (scenario: Scenario) => string | null;
+    outOfBand?: Partial<BackoffConfig>;
+    originClients?: ReadonlyMap<string, OriginClient>;
+    /** The run's account ledger, which a self delete sent through a session settles, when the document has one. */
+    accounts?: ScenarioAccounts;
+    sleep?: (ms: number) => Promise<void>;
+}
+/** One scenario as it runs: where it sends from, and what its steps have bound, sent and shown. */
+export interface ScenarioRun {
+    input: ScenarioInput;
+    scenario: Scenario;
+    sleep: (ms: number) => Promise<void>;
+    /** The principal the scenario acts as: a step sends `as` it unless it names another, or none. */
+    principal: string;
+    context: StepContext;
+    /** `{name}` values, the parameters bound for the principal among them from the first step. */
+    scope: Record<string, string>;
+    /**
+     * Values a response or a hook handed back, kept whole: a field that is exactly `{name}` sends
+     * the object itself (a WebAuthn credential), or the number or boolean with its type, not its
+     * string form.
+     */
+    objects: Map<string, unknown>;
+    /** The exchange that called each operation, the one its grade cites. */
+    calls: Map<string, Exchange>;
+    /** What this scenario sent, so a value delivered outside HTTP finds the request it answers. */
+    sent: Exchange[];
+    observations: Map<string, PassEvidence["observation"]>;
+    /** The account each scope name descends from. */
+    lineage: Lineage;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/api/runtime/scenario/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/api/runtime/scenario/validate.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Declared flows. The matrix reaches what the document lets it infer; a scenario is the config
+ * saying how to reach the rest — a passkey ceremony, a paid checkout, an invite accepted by a
+ * second user. The API tester runs the steps and grades what they observed. It never learns the product.
+ */
+import type { ExternalStep, OutOfBandStep, Scenario, ScenarioStep } from "../../config/types/steps.ts";
+export declare function scenarioCheckId(scenario: Scenario): string;
+export declare function isExternal(step: ScenarioStep): step is ExternalStep;
+export declare function isOutOfBand(step: ScenarioStep): step is OutOfBandStep;
+export declare function stepOperation(step: ScenarioStep): string | undefined;
+/**
+ * Fails fast on a scenario that names what it cannot grade — before any request is sent. A step on
+ * another origin names that origin's operation and is checked against its document; it supports
+ * the scenario but never covers a main operation.
+ */
+export declare function assertScenarios(scenarios: readonly Scenario[], known: (operationId: string, origin?: string) => boolean): void;
+//# sourceMappingURL=validate.d.ts.map

package/dist/api/runtime/scenario/validate.js

@@ -0,0 +1,64 @@
+/**
+ * Declared flows. The matrix reaches what the document lets it infer; a scenario is the config
+ * saying how to reach the rest — a passkey ceremony, a paid checkout, an invite accepted by a
+ * second user. The API tester runs the steps and grades what they observed. It never learns the product.
+ */
+export function scenarioCheckId(scenario) {
+    return `scenario.${scenario.id}`;
+}
+export function isExternal(step) {
+    return "external" in step;
+}
+export function isOutOfBand(step) {
+    return "outOfBand" in step;
+}
+export function stepOperation(step) {
+    return "operationId" in step && typeof step.operationId === "string" ? step.operationId : undefined;
+}
+/** The secondary origin a step is sent to, or undefined for the main document. */
+function stepOriginOf(step) {
+    return "origin" in step && typeof step.origin === "string" && step.origin !== "" ? step.origin : undefined;
+}
+/* An anonymous step sends no credential, so a scheme it names would be silently dropped. */
+function refuseAnonymousScheme(scenario, step, index) {
+    if (!("anonymous" in step) || step.anonymous !== true || step.scheme === undefined)
+        return;
+    throw new Error(`testing api: scenario "${scenario.id}" step ${index + 1} is anonymous, so it cannot send the "${step.scheme}" scheme`);
+}
+/**
+ * Fails fast on a scenario that names what it cannot grade — before any request is sent. A step on
+ * another origin names that origin's operation and is checked against its document; it supports
+ * the scenario but never covers a main operation.
+ */
+export function assertScenarios(scenarios, known) {
+    const seen = new Set();
+    for (const scenario of scenarios) {
+        if (seen.has(scenario.id))
+            throw new Error(`testing api: two scenarios share the id "${scenario.id}"`);
+        seen.add(scenario.id);
+        const called = calledOperations(scenario, known);
+        for (const id of scenario.covers) {
+            if (!called.has(id))
+                throw new Error(`testing api: scenario "${scenario.id}" covers ${id} but no step calls it`);
+        }
+    }
+}
+/** The main operations a scenario's steps call, each checked against the document it names. */
+function calledOperations(scenario, known) {
+    const called = new Set();
+    for (const [index, step] of scenario.steps.entries()) {
+        refuseAnonymousScheme(scenario, step, index);
+        const id = stepOperation(step);
+        if (id === undefined)
+            continue;
+        const origin = stepOriginOf(step);
+        if (!known(id, origin)) {
+            const where = origin === undefined ? "the document" : `the "${origin}" origin's document`;
+            throw new Error(`testing api: scenario "${scenario.id}" calls ${id}, which is not in ${where}`);
+        }
+        if (origin === undefined)
+            called.add(id);
+    }
+    return called;
+}
+//# sourceMappingURL=validate.js.map

package/dist/api/runtime/scenario/want.d.ts

@@ -0,0 +1,21 @@
+/**
+ * What a scenario step asserts, and whether a response shows it.
+ */
+import type { ScenarioAssert, ScenarioRequestStep } from "../../config/types/steps.ts";
+import type { Exchange } from "../exchange.ts";
+/** What an assert wants, with `{name}` already filled in its path and its value. */
+export type Want = {
+    from: string;
+    mode: "atLeast" | "contains" | "equals" | "excludes" | "omits";
+    value: string;
+};
+export declare function expected(assert: ScenarioAssert, scope: Record<string, string>): Want;
+/** The first value at `path` that meets `want`, as text — what the evidence records. */
+export declare function shownValue(exchange: Exchange, path: string, want: Want): string | undefined;
+/** A step's asserts, one or a list, each with what it wants. */
+export declare function wantsOf(step: ScenarioRequestStep, scope: Record<string, string>): Array<{
+    assert: ScenarioAssert;
+    want: Want;
+}>;
+export declare function holds(exchange: Exchange, path: string, want: Want): boolean;
+//# sourceMappingURL=want.d.ts.map

package/dist/api/runtime/scenario/want.js

@@ -0,0 +1,59 @@
+/**
+ * What a scenario step asserts, and whether a response shows it.
+ */
+import { interpolate } from "../steps/interpolate.js";
+import { cookiesFromRecordedHeaders } from "../cookies/set-cookie.js";
+import { describeSaveAs, readSaveAs } from "../cookies/save-as.js";
+import { readAll, readPath } from "../../client/read-path.js";
+export function expected(assert, scope) {
+    const from = String(interpolate(assert.from, scope));
+    if (assert.equals !== undefined)
+        return { from, mode: "equals", value: String(interpolate(assert.equals, scope)) };
+    if (assert.contains !== undefined)
+        return { from, mode: "contains", value: String(interpolate(assert.contains, scope)) };
+    if (assert.excludes !== undefined)
+        return { from, mode: "excludes", value: String(interpolate(assert.excludes, scope)) };
+    if (assert.atLeast !== undefined)
+        return { from, mode: "atLeast", value: String(assert.atLeast) };
+    if (assert.omits !== undefined)
+        return { from, mode: "omits", value: String(interpolate(assert.omits, scope)) };
+    throw new Error(`testing api: an assert on ${assert.from} needs equals, contains, excludes, omits or atLeast`);
+}
+/** The values at `from`: a JSON path into the body, or `header:Name` / `cookie:name` as saveAs reads them. */
+function observed(exchange, from) {
+    if (describeSaveAs(from).kind === "json")
+        return readAll(exchange.responseBody, from);
+    const value = readSaveAs(from, {
+        body: exchange.responseBody,
+        cookies: exchange.cookies ?? cookiesFromRecordedHeaders(exchange.responseHeaders),
+        headers: exchange.responseHeaders,
+        readJson: readPath,
+    });
+    return value === undefined ? [] : [value];
+}
+/** The first value at `path` that meets `want`, as text — what the evidence records. */
+export function shownValue(exchange, path, want) {
+    const nodes = observed(exchange, path).map((node) => (typeof node === "string" ? node : JSON.stringify(node)));
+    if (want.mode === "excludes")
+        return nodes.includes(want.value) ? undefined : want.value;
+    if (want.mode === "omits")
+        return nodes.some((text) => text.includes(want.value)) ? undefined : want.value;
+    if (want.mode === "atLeast") {
+        const floor = Number(want.value);
+        return nodes.find((text) => text.trim() !== "" && Number(text) >= floor);
+    }
+    return nodes.some((text) => (want.mode === "equals" ? text === want.value : text.includes(want.value)))
+        ? want.value
+        : undefined;
+}
+/** A step's asserts, one or a list, each with what it wants. */
+export function wantsOf(step, scope) {
+    if (step.assert === undefined)
+        return [];
+    const asserts = Array.isArray(step.assert) ? step.assert : [step.assert];
+    return asserts.map((assert) => ({ assert, want: expected(assert, scope) }));
+}
+export function holds(exchange, path, want) {
+    return shownValue(exchange, path, want) !== undefined;
+}
+//# sourceMappingURL=want.js.map