@sdods/core 0.7.2 → 0.9.0

package/dist/steps/canvas.steps.d.ts

@@ -0,0 +1,9 @@
+import { type CanvasConfig } from '@sdods/contracts';
+import './params.js';
+/**
+ * Fills a selector template. An unknown placeholder throws instead of being left in place: a
+ * selector with a literal `{nodeId}` in it matches nothing, which fails a positive step for the
+ * wrong reason and passes the negative edge step without testing anything.
+ */
+export declare function expandCanvasSelector(key: keyof CanvasConfig, template: string, values: Record<string, string>, testIdAttribute: string): string;
+//# sourceMappingURL=canvas.steps.d.ts.map

package/dist/steps/canvas.steps.js

@@ -0,0 +1,331 @@
+import { expect } from '@playwright/test';
+import { CANVAS_DEFAULTS } from '@sdods/contracts';
+import './params.js';
+import { Then, When } from '../fixtures/test.js';
+import { renderStrict } from '../api/template.js';
+import { SdodsError } from '../errors.js';
+const arg = ({ apiContext, env }, value) => renderStrict(value, apiContext.vars.toObject(), env.vars);
+/** Pointer moves between press and release. Enough for every drag threshold we know of. */
+const DRAG_STEPS = 12;
+/** Size of the first move after the press, which starts a drag in libraries with a threshold. */
+const NUDGE_PX = 4;
+/** The editable control a field wrapper holds, when the field selector names a wrapper. */
+const EDITABLE = 'input:not([type="hidden"]), textarea, select, [contenteditable=""], [contenteditable="true"]';
+/** Places inside a node a press would NOT reach the node through: a drag or click there is eaten. */
+const NOT_A_GRAB_POINT = `${EDITABLE}, button, a[href], .nodrag, .react-flow__handle`;
+function canvasOf(config) {
+    return {
+        config: { ...CANVAS_DEFAULTS, ...(config.project.canvas ?? {}) },
+        testIdAttribute: config.project.testIdAttribute ?? 'data-testid',
+    };
+}
+/** A value inside a quoted CSS string: backslashes, both quotes and newlines escaped. */
+function cssString(value) {
+    return value
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/'/g, "\\'")
+        .replace(/\n/g, '\\a ');
+}
+/**
+ * Fills a selector template. An unknown placeholder throws instead of being left in place: a
+ * selector with a literal `{nodeId}` in it matches nothing, which fails a positive step for the
+ * wrong reason and passes the negative edge step without testing anything.
+ */
+export function expandCanvasSelector(key, template, values, testIdAttribute) {
+    return template.replace(/\{(\w+)\}/g, (_whole, name) => {
+        if (name === 'testIdAttribute')
+            return testIdAttribute;
+        const value = values[name];
+        if (value === undefined) {
+            throw new SdodsError('CONFIG_INVALID', `canvas.${key} "${template}" uses {${name}}, which is not a placeholder for this selector.`, {
+                hint: `canvas.${key} may use ${Object.keys(values)
+                    .map((v) => `{${v}}`)
+                    .concat('{testIdAttribute}')
+                    .join(', ')}.`,
+            });
+        }
+        return cssString(value);
+    });
+}
+function rootOf(page, c) {
+    return page.locator(expandCanvasSelector('root', c.config.root, {}, c.testIdAttribute));
+}
+/** Every node on the canvas (`canvas.nodes`), scoped inside the root. */
+function allNodes(page, c) {
+    return rootOf(page, c).locator(expandCanvasSelector('nodes', c.config.nodes, {}, c.testIdAttribute));
+}
+function nodeLocator(page, c, id) {
+    return rootOf(page, c).locator(expandCanvasSelector('node', c.config.node, { id }, c.testIdAttribute));
+}
+/** Exactly one node with that id, or a failure that names it. */
+async function oneNode(page, c, id) {
+    const node = nodeLocator(page, c, id);
+    await expect(node, `no single node "${id}" on the canvas (canvas.node)`).toHaveCount(1);
+    return node;
+}
+async function viewport(page) {
+    return page.viewportSize() ?? page.evaluate(() => ({ width: innerWidth, height: innerHeight }));
+}
+async function boxOf(locator, what) {
+    const box = await locator.boundingBox();
+    if (!box || box.width === 0 || box.height === 0) {
+        throw new SdodsError('RUN_FAILED', `${what} has no size on screen, so it cannot be dragged.`, {
+            hint: 'It is in the DOM but not laid out: hidden, collapsed, or virtualised off the canvas.',
+        });
+    }
+    return box;
+}
+/** The centre of a drop target or a handle: the point a release or a connection aims at. */
+async function centreOf(locator, what) {
+    await expect(locator, `${what} is not visible`).toBeVisible();
+    await locator.scrollIntoViewIfNeeded();
+    const box = await boxOf(locator, what);
+    return { x: box.x + box.width / 2, y: box.y + box.height / 2 };
+}
+/**
+ * A point on an element that a press reaches the ELEMENT through — used for every drag source and
+ * for selecting. The centre of a real workflow block is usually a text field, and editors
+ * deliberately ignore presses there (React Flow's `nodrag`), so a drag or click at the centre does
+ * nothing. Tries the centre, then the header strip, then the edges, and takes the first point whose
+ * hit target is the element or a plain part of it. A palette item with nothing inside it resolves
+ * to its centre.
+ */
+async function grabPointOf(node, what) {
+    await expect(node, `${what} is not visible`).toBeVisible();
+    await node.scrollIntoViewIfNeeded();
+    const box = await boxOf(node, what);
+    const offset = await node.evaluate((el, skip) => {
+        const r = el.getBoundingClientRect();
+        const inset = Math.min(8, r.height / 4, r.width / 4);
+        const candidates = [
+            [r.width / 2, r.height / 2],
+            [r.width / 2, inset],
+            [inset * 2, inset],
+            [r.width - inset * 2, inset],
+            [r.width / 2, r.height - inset],
+            [inset, r.height / 2],
+            [r.width - inset, r.height / 2],
+        ];
+        for (const [x, y] of candidates) {
+            const hit = document.elementFromPoint(r.left + x, r.top + y);
+            if (!hit || !el.contains(hit))
+                continue;
+            const blocker = hit.closest(skip);
+            if (blocker && el.contains(blocker))
+                continue;
+            return { x, y, found: true };
+        }
+        return { x: r.width / 2, y: r.height / 2, found: false };
+    }, NOT_A_GRAB_POINT);
+    // Scale by the laid-out box, which is in page coordinates even inside a frame.
+    return { x: box.x + offset.x, y: box.y + offset.y };
+}
+/** One real pointer drag. The press is always released, even when a move throws. */
+async function pointerDrag(page, from, to, what) {
+    const { width, height } = await viewport(page);
+    for (const [label, p] of [
+        ['starts', from],
+        ['ends', to],
+    ]) {
+        if (p.x < 0 || p.y < 0 || p.x > width || p.y > height) {
+            throw new SdodsError('RUN_FAILED', `Dragging ${what} ${label} at (${Math.round(p.x)}, ${Math.round(p.y)}), outside the viewport (${width}x${height}).`, {
+                hint: 'A pointer cannot be pressed or released off screen, so the drop would land short. Use a smaller offset, scroll or zoom the canvas first, or enlarge the viewport.',
+            });
+        }
+    }
+    const dx = to.x - from.x;
+    const dy = to.y - from.y;
+    const distance = Math.hypot(dx, dy);
+    await page.mouse.move(from.x, from.y);
+    await page.mouse.down();
+    try {
+        if (distance > NUDGE_PX) {
+            await page.mouse.move(from.x + (dx / distance) * NUDGE_PX, from.y + (dy / distance) * NUDGE_PX);
+        }
+        await page.mouse.move(to.x, to.y, { steps: DRAG_STEPS });
+        // The LAST move is what drop targets read (React Flow's connection target, HTML5 dragover).
+        await page.mouse.move(to.x, to.y);
+    }
+    finally {
+        await page.mouse.up();
+    }
+}
+function assertOffset(dx, dy, what) {
+    if (!Number.isInteger(dx) || !Number.isInteger(dy) || (dx === 0 && dy === 0)) {
+        throw new SdodsError('RUN_FAILED', `Moving ${what} by ${dx} and ${dy} is not a drag.`, {
+            hint: 'Offsets are whole screen pixels, right/down positive, and at least one must be non-zero: a press and release in place is a click, and editors treat it as one.',
+        });
+    }
+}
+/* ── dragging ─────────────────────────────────────────────────────────── */
+// Adds a block from a palette, or moves anything onto a drop zone. The source is pressed on a
+// plain part of it (see `grabPointOf`) and released at the target's centre.
+When('I drag the element with test id {string} onto the element with test id {string}', async ({ page, apiContext, env }, sourceId, targetId) => {
+    const s = arg({ apiContext, env }, sourceId);
+    const t = arg({ apiContext, env }, targetId);
+    const target = page.getByTestId(t);
+    const source = page.getByTestId(s);
+    // Target first: scrolling the source into view last keeps the press point on screen.
+    await centreOf(target, `the element with test id "${t}"`);
+    const from = await grabPointOf(source, `the element with test id "${s}"`);
+    const to = await centreOf(target, `the element with test id "${t}"`);
+    await pointerDrag(page, from, to, `the element with test id "${s}"`);
+});
+// Moves an element by an offset in screen pixels (right/down positive). On a zoomed canvas the
+// node moves by the offset divided by the zoom, in flow coordinates.
+When('I drag the element with test id {string} by {int} and {int}', async ({ page, apiContext, env }, id, dx, dy) => {
+    const testId = arg({ apiContext, env }, id);
+    const what = `the element with test id "${testId}"`;
+    assertOffset(dx, dy, what);
+    const from = await grabPointOf(page.getByTestId(testId), what);
+    await pointerDrag(page, from, { x: from.x + dx, y: from.y + dy }, what);
+});
+// Moves a node addressed by its id rather than a test id — the one a workflow canvas actually has.
+// Pressed on a plain part of the node, never on a field inside it (see `grabPointOf`).
+When('I drag the node {string} by {int} and {int}', async ({ page, config, apiContext, env }, id, dx, dy) => {
+    const c = canvasOf(config);
+    const nodeId = arg({ apiContext, env }, id);
+    const what = `node "${nodeId}"`;
+    assertOffset(dx, dy, what);
+    const from = await grabPointOf(await oneNode(page, c, nodeId), what);
+    await pointerDrag(page, from, { x: from.x + dx, y: from.y + dy }, what);
+});
+/* ── connecting ───────────────────────────────────────────────────────── */
+// Draws an edge the way a user does: press on the source handle, move onto the target handle,
+// release. Both handles are looked up inside their own node, so two nodes that both have an "out"
+// handle are never confused. Whether the editor ACCEPTED the connection is the next step's job:
+// `the canvas should contain an edge from ... to ...`.
+When('I connect the {string} handle of node {string} to the {string} handle of node {string}', async ({ page, config, apiContext, env }, sourceHandle, sourceNode, targetHandle, targetNode) => {
+    const c = canvasOf(config);
+    const v = { apiContext, env };
+    const [sh, sn, th, tn] = [sourceHandle, sourceNode, targetHandle, targetNode].map((s) => arg(v, s));
+    const handleIn = async (nodeId, handle) => {
+        const node = await oneNode(page, c, nodeId);
+        const h = node.locator(expandCanvasSelector('handle', c.config.handle, { handle }, c.testIdAttribute));
+        await expect(h, `the "${handle}" handle of node "${nodeId}" is not on the canvas (canvas.handle)`).toHaveCount(1);
+        return h;
+    };
+    const target = await handleIn(tn, th);
+    const source = await handleIn(sn, sh);
+    await centreOf(target, `the "${th}" handle of node "${tn}"`);
+    const from = await centreOf(source, `the "${sh}" handle of node "${sn}"`);
+    const to = await centreOf(target, `the "${th}" handle of node "${tn}"`);
+    await pointerDrag(page, from, to, `the "${sh}" handle of node "${sn}"`);
+});
+/* ── selecting and editing ────────────────────────────────────────────── */
+// Selects a node by clicking a plain part of it, then waits until it matches `canvas.selected`
+// (React Flow's `.selected` class by default), so a click the editor swallowed fails here rather
+// than as a confusing failure in whatever the scenario does with the selection next.
+When('I select the node {string}', async ({ page, config, apiContext, env }, id) => {
+    const c = canvasOf(config);
+    const nodeId = arg({ apiContext, env }, id);
+    const node = await oneNode(page, c, nodeId);
+    const at = await grabPointOf(node, `node "${nodeId}"`);
+    await page.mouse.click(at.x, at.y);
+    const marker = c.config.selected;
+    if (!marker)
+        return;
+    await expect
+        .poll(async () => node.evaluate((el, s) => el.matches(s), marker), {
+        message: `node "${nodeId}" is not selected after clicking it: it does not match ${marker} (canvas.selected)`,
+    })
+        .toBe(true);
+});
+// Fills a field that lives inside a node. `canvas.field` may name the control itself or a wrapper
+// around it; for a wrapper, the first visible input, textarea, select or contenteditable inside it
+// is used. A select is set by option value or label.
+When('I set the {string} field of node {string} to {string}', async ({ page, config, apiContext, env }, field, id, value) => {
+    const c = canvasOf(config);
+    const v = { apiContext, env };
+    const name = arg(v, field);
+    const nodeId = arg(v, id);
+    const text = arg(v, value);
+    const node = await oneNode(page, c, nodeId);
+    const match = node
+        .locator(expandCanvasSelector('field', c.config.field, { field: name }, c.testIdAttribute))
+        .first();
+    await expect(match, `node "${nodeId}" has no "${name}" field (canvas.field)`).toBeAttached();
+    const isEditable = await match.evaluate((el, sel) => el.matches(sel), EDITABLE);
+    const control = isEditable ? match : match.locator(EDITABLE).filter({ visible: true }).first();
+    await expect(control, `the "${name}" field of node "${nodeId}" holds no visible editable control`).toBeVisible();
+    const tag = await control.evaluate((el) => el.tagName);
+    if (tag === 'SELECT')
+        await control.selectOption(text);
+    else
+        await control.fill(text);
+});
+/* ── assertions ───────────────────────────────────────────────────────── */
+// Counts every node on the canvas (`canvas.nodes`). Exact, so a duplicated drop fails too.
+Then('the canvas should contain {int} node(s)', async ({ page, config }, count) => {
+    if (!Number.isInteger(count) || count < 0) {
+        throw new SdodsError('RUN_FAILED', `"${count}" is not a number of nodes.`, {
+            hint: 'Node counts are whole numbers, 0 or more.',
+        });
+    }
+    const c = canvasOf(config);
+    await expect(allNodes(page, c)).toHaveCount(count);
+});
+// Proves the editor holds an edge from one node to the other, in that direction.
+Then('the canvas should contain an edge from {string} to {string}', async ({ page, config, apiContext, env }, source, target) => {
+    const c = canvasOf(config);
+    const s = arg({ apiContext, env }, source);
+    const t = arg({ apiContext, env }, target);
+    const edges = rootOf(page, c).locator(expandCanvasSelector('edge', c.config.edge, { source: s, target: t }, c.testIdAttribute));
+    await expect
+        .poll(async () => edges.count(), {
+        message: `the canvas has no edge from "${s}" to "${t}" (canvas.edge)`,
+    })
+        .toBeGreaterThan(0);
+});
+// Proves an edge is gone, or was never drawn. Refuses a canvas with no visible nodes: on an editor
+// that has not rendered, every edge in existence is absent, which is not an assertion. React Flow
+// keeps unmeasured nodes in the DOM with `visibility: hidden` and draws edges only once the nodes
+// are measured, so right after a load a node being attached proves nothing: the step waits until
+// every node is visible and the editor has painted, and only then checks that the edge is absent.
+Then('the canvas should not contain an edge from {string} to {string}', async ({ page, config, apiContext, env }, source, target) => {
+    const c = canvasOf(config);
+    const s = arg({ apiContext, env }, source);
+    const t = arg({ apiContext, env }, target);
+    const root = rootOf(page, c);
+    const nodes = allNodes(page, c);
+    try {
+        await expect(nodes.filter({ visible: true }).first()).toBeVisible();
+    }
+    catch {
+        throw new SdodsError('RUN_FAILED', 'The canvas has rendered no nodes, or none is visible.', {
+            hint: `Asserting there is no edge from "${s}" to "${t}" on an empty or unrendered canvas proves nothing: editors such as React Flow draw edges only after their nodes are measured and shown. Check canvas.root and canvas.nodes, or assert a node first.`,
+        });
+    }
+    await expect
+        .poll(async () => (await nodes.count()) - (await nodes.filter({ visible: true }).count()), {
+        message: `nodes on the canvas are still hidden (not yet measured), so its edges may not be drawn yet; the absent-edge check from "${s}" to "${t}" waits for them`,
+    })
+        .toBe(0);
+    // Edges are drawn in the render that follows the measurement: let the editor paint first.
+    await page.evaluate(() => new Promise((done) => {
+        const timer = setTimeout(done, 250);
+        requestAnimationFrame(() => requestAnimationFrame(() => {
+            clearTimeout(timer);
+            done();
+        }));
+    }));
+    const edges = root.locator(expandCanvasSelector('edge', c.config.edge, { source: s, target: t }, c.testIdAttribute));
+    await expect(edges, `the canvas has an edge from "${s}" to "${t}"`).toHaveCount(0);
+});
+// Proves the node is rendered and shown.
+Then('the node {string} should be visible', async ({ page, config, apiContext, env }, id) => {
+    const c = canvasOf(config);
+    const nodeId = arg({ apiContext, env }, id);
+    await expect(nodeLocator(page, c, nodeId), `node "${nodeId}" is not visible`).toBeVisible();
+});
+// Proves THIS node shows the badge — a run state (running, success, error) or a validation marker.
+Then('the node {string} should show the {string} badge', async ({ page, config, apiContext, env }, id, badge) => {
+    const c = canvasOf(config);
+    const nodeId = arg({ apiContext, env }, id);
+    const b = arg({ apiContext, env }, badge);
+    const node = await oneNode(page, c, nodeId);
+    const marker = node.locator(expandCanvasSelector('badge', c.config.badge, { badge: b }, c.testIdAttribute));
+    await expect(marker.first(), `node "${nodeId}" does not show the "${b}" badge (canvas.badge)`).toBeVisible();
+});
+//# sourceMappingURL=canvas.steps.js.map

package/dist/steps/data.steps.js

@@ -3,6 +3,7 @@ import './params.js';
 import { Given, When } from '../fixtures/test.js';
 import { tokenFileFor } from '../auth/capture.js';
 import { renderStrict } from '../api/template.js';
+import { scenarioLeaseClock } from '../data/user-pool.js';
 import { SdodsError } from '../errors.js';
 import { Logger } from '../logger.js';
 const log = new Logger('data');
@@ -20,8 +21,8 @@ Given('I generate a {string} from the factory as {string}', async ({ data, apiCo
     apiContext.vars.set(as, await data.factory(factory));
 });
 /* ── user pool ────────────────────────────────────────────────────────── */
-Given('I use a leased user with role {string}', async ({ userPool, authCache, auth, sdods, apiContext, page, context, browser, $testInfo }, role) => {
-    const user = await userPool.lease(role, $testInfo.parallelIndex);
+Given('I use a leased user with role {string}', async ({ userPool, authCache, auth, sdods, apiContext, page, context, browser, config, $testInfo }, role) => {
+    const user = await leaseInScenario(userPool, config, role, $testInfo);
     apiContext.vars.setAll({
         username: user.username,
         password: user.password,
@@ -33,12 +34,12 @@ Given('I use a leased user with role {string}', async ({ userPool, authCache, au
     if (sdods.layer !== 'api')
         await authCache.apply({ context, page, user, auth, browser });
 });
-Given('I use the user {string} from the pool', async ({ userPool, apiContext, $testInfo }, username) => {
+Given('I use the user {string} from the pool', async ({ userPool, apiContext, config, $testInfo }, username) => {
     const status = await userPool.status();
     const entry = status.find((u) => u.username === username);
     if (!entry)
         throw new SdodsError('DATASET_ROW_NOT_FOUND', `No pool user named "${username}".`);
-    const user = await userPool.lease(entry.role, $testInfo.parallelIndex);
+    const user = await leaseInScenario(userPool, config, entry.role, $testInfo);
     apiContext.vars.setAll({
         username: user.username,
         password: user.password,
@@ -84,7 +85,7 @@ Given('I use the user {string} from the pool', async ({ userPool, apiContext, $t
  * Either way the attached credential is logged at info.
  */
 Given('I use a leased user with role {string} for API calls', async ({ userPool, apiContext, auth, config, $testInfo }, role) => {
-    const user = await userPool.lease(role, $testInfo.parallelIndex);
+    const user = await leaseInScenario(userPool, config, role, $testInfo);
     apiContext.vars.setAll({
         username: user.username,
         password: user.password,
@@ -126,6 +127,17 @@ Given("I authenticate the API with the leased user's token", async ({ apiContext
 });
 /** The user the scenario leased, so the explicit token step authenticates as that same account. */
 const LEASED = new WeakMap();
+/**
+ * Lease for this scenario. With `leaseScope: scenario` the wait for a free account is added to the
+ * scenario's timeout, and `$sdodsScenarioLeases` releases the account when the scenario ends.
+ */
+async function leaseInScenario(userPool, config, role, testInfo) {
+    // `data` is always present on a resolved config; unit tests hand steps a partial one.
+    const clock = scenarioLeaseClock(config.project.data?.userPool, testInfo);
+    const user = await userPool.lease(role, testInfo.parallelIndex);
+    clock.settle();
+    return user;
+}
 function apiTokenMode(config, auth) {
     return config.project.auth?.apiToken ?? (auth?.strategy === 'custom' ? 'explicit' : 'implicit');
 }

package/dist/steps/email.steps.d.ts

@@ -0,0 +1,2 @@
+import './params.js';
+//# sourceMappingURL=email.steps.d.ts.map

package/dist/steps/email.steps.js

@@ -0,0 +1,182 @@
+import { expect } from '@playwright/test';
+import './params.js';
+import { BeforeScenario, Then, When } from '../fixtures/test.js';
+import { renderStrict } from '../api/template.js';
+import { SdodsError } from '../errors.js';
+import { createMailInbox } from '../mail/index.js';
+import { extractLinks, findCode, findLinkMatching, findLinkNamed, readableText, } from '../mail/extract.js';
+// Keyed by the per-scenario ApiContext, so state never outlives or crosses a scenario.
+const states = new WeakMap();
+function stateFor(apiContext) {
+    let s = states.get(apiContext);
+    if (!s) {
+        s = { since: Date.now(), cleared: new Map(), pinned: new Map() };
+        states.set(apiContext, s);
+    }
+    return s;
+}
+/**
+ * Opens the window when the scenario starts rather than at the first email step: in the typical
+ * flow the application sends the message during a UI step, before any email step has run.
+ */
+BeforeScenario({ name: 'sdods:mail:window' }, async ({ apiContext }) => {
+    stateFor(apiContext);
+});
+function requireMail(env) {
+    if (!env.mail) {
+        throw new SdodsError('MAIL_REQUIRED', 'This scenario reads email but no mail catcher is configured.', {
+            hint: 'Declare `mail: { provider: mailpit, url: http://localhost:8025 }` in the environment yaml, and point the application under test at the same Mailpit for SMTP (port 1025 by default).',
+            docsPath: '/docs/reference/env-yaml',
+        });
+    }
+    return {
+        provider: env.mail.provider ?? 'mailpit',
+        url: env.mail.url,
+        auth: env.mail.auth,
+        pollIntervalMs: env.mail.pollIntervalMs ?? 1000,
+        clockSkewMs: env.mail.clockSkewMs ?? 2000,
+        timeoutSeconds: env.mail.timeoutSeconds ?? 15,
+    };
+}
+const scopesOf = ({ apiContext, env }) => [apiContext.vars.toObject(), env.vars];
+const arg = (fx, value) => renderStrict(value, ...scopesOf(fx));
+const addressArg = (fx, value) => arg(fx, value).trim().toLowerCase();
+function windowStart(fx, config, address) {
+    const s = stateFor(fx.apiContext);
+    return new Date(Math.max(s.since, s.cleared.get(address) ?? 0) - config.clockSkewMs);
+}
+/** Search until something matches or the deadline passes; `[]` on timeout. */
+async function pollSearch(inbox, query, timeoutMs, intervalMs) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const found = await inbox.search(query);
+        if (found.length > 0)
+            return found;
+        const left = deadline - Date.now();
+        if (left <= 0)
+            return [];
+        await new Promise((r) => setTimeout(r, Math.min(intervalMs, left)));
+    }
+}
+function describeSeen(seen) {
+    if (seen.length === 0)
+        return 'No email at all reached that address in this scenario.';
+    const list = seen
+        .slice(0, 10)
+        .map((m) => `  - "${m.subject}" from ${m.from.address} at ${m.receivedAt.toISOString()}`)
+        .join('\n');
+    return `Emails that did reach it in this scenario (newest first):\n${list}`;
+}
+/** The message "the latest email to <address>" refers to. See the header for the rules. */
+async function latestEmail(fx, rawAddress) {
+    const config = requireMail(fx.env);
+    const inbox = createMailInbox(config);
+    const address = addressArg(fx, rawAddress);
+    const pinned = stateFor(fx.apiContext).pinned.get(address);
+    if (pinned)
+        return inbox.get(pinned);
+    const since = windowStart(fx, config, address);
+    const found = await pollSearch(inbox, { to: address, since }, config.timeoutSeconds * 1000, config.pollIntervalMs);
+    if (found.length === 0) {
+        throw new SdodsError('MAIL_NOT_RECEIVED', `No email to ${address} arrived within ${config.timeoutSeconds} s.`, {
+            hint: 'Only mail received after the scenario started (or after `I clear the inbox for` that address) counts. Check that the application sends SMTP to the Mailpit in `mail.url`, or wait explicitly with `the inbox for … should receive an email with subject containing … within … seconds`.',
+            details: { address, since: since.toISOString(), mailpit: config.url },
+        });
+    }
+    return inbox.get(found[0].id);
+}
+When('I clear the inbox for {string}', async ({ apiContext, env }, rawAddress) => {
+    const fx = { apiContext, env };
+    const config = requireMail(env);
+    const address = addressArg(fx, rawAddress);
+    await createMailInbox(config).clear(address);
+    const s = stateFor(apiContext);
+    s.cleared.set(address, Date.now());
+    s.pinned.delete(address);
+});
+Then('the inbox for {string} should receive an email with subject containing {string} within {int} seconds', async ({ apiContext, env }, rawAddress, rawSubject, seconds) => {
+    const fx = { apiContext, env };
+    const config = requireMail(env);
+    const inbox = createMailInbox(config);
+    const address = addressArg(fx, rawAddress);
+    const subject = arg(fx, rawSubject);
+    const since = windowStart(fx, config, address);
+    const found = await pollSearch(inbox, { to: address, subjectContains: subject, since }, seconds * 1000, config.pollIntervalMs);
+    if (found.length === 0) {
+        // "Nothing arrived" and "something with the wrong subject arrived" are different bugs, so
+        // the failure says which one this is.
+        const seen = await inbox.search({ to: address, since });
+        throw new SdodsError('MAIL_NOT_RECEIVED', `No email to ${address} with subject containing "${subject}" arrived within ${seconds} s.\n${describeSeen(seen)}`, {
+            hint: 'The subject match is a case-sensitive substring. Only mail received after the scenario started (or after `I clear the inbox for` that address) counts; check that the application sends SMTP to the Mailpit in `mail.url`.',
+            details: {
+                address,
+                subject,
+                since: since.toISOString(),
+                seen: seen.map((m) => ({
+                    subject: m.subject,
+                    from: m.from.address,
+                    receivedAt: m.receivedAt.toISOString(),
+                })),
+            },
+        });
+    }
+    stateFor(apiContext).pinned.set(address, found[0].id);
+});
+Then('the latest email to {string} should contain the text {string}', async ({ apiContext, env }, rawAddress, rawText) => {
+    const fx = { apiContext, env };
+    const message = await latestEmail(fx, rawAddress);
+    const needle = arg(fx, rawText);
+    expect(readableText(message), `the latest email to ${message.to.map((t) => t.address).join(', ')} ("${message.subject}")`).toContain(needle);
+});
+Then('the latest email to {string} should have been sent from {string}', async ({ apiContext, env }, rawAddress, rawFrom) => {
+    const fx = { apiContext, env };
+    const message = await latestEmail(fx, rawAddress);
+    const wanted = arg(fx, rawFrom).trim();
+    const { name, address } = message.from;
+    const candidates = [address, name, `${name} <${address}>`].map((s) => s.toLowerCase());
+    if (!candidates.includes(wanted.toLowerCase())) {
+        expect(name ? `${name} <${address}>` : address, `sender of "${message.subject}" (compare the address, the display name, or "Name <address>")`).toBe(wanted);
+    }
+});
+When('I save the link matching {string} from the latest email to {string} as {string}', async ({ apiContext, env }, rawPattern, rawAddress, name) => {
+    const fx = { apiContext, env };
+    const message = await latestEmail(fx, rawAddress);
+    const pattern = arg(fx, rawPattern);
+    const link = findLinkMatching(message, pattern);
+    if (!link)
+        throw noLink(message, `matching ${pattern}`);
+    // `name` is the variable being written, an identifier rather than a template.
+    apiContext.vars.set(name, link.href);
+});
+When('I save the code matching {string} from the latest email to {string} as {string}', async ({ apiContext, env }, rawPattern, rawAddress, name) => {
+    const fx = { apiContext, env };
+    const message = await latestEmail(fx, rawAddress);
+    const pattern = arg(fx, rawPattern);
+    const code = findCode(message, pattern);
+    if (code === undefined) {
+        throw new SdodsError('RUN_FAILED', `Nothing in "${message.subject}" matches ${pattern}.`, {
+            hint: 'The pattern is a regular expression over the text part (or the HTML part rendered to text). With a capture group, group 1 is saved: `code: (\\d{6})`.',
+            details: { subject: message.subject, text: readableText(message).slice(0, 1000) },
+        });
+    }
+    apiContext.vars.set(name, code);
+});
+When('I open the link {string} from the latest email to {string}', async ({ apiContext, env, page }, rawName, rawAddress) => {
+    const fx = { apiContext, env };
+    const message = await latestEmail(fx, rawAddress);
+    const name = arg(fx, rawName);
+    const link = findLinkNamed(message, name);
+    if (!link)
+        throw noLink(message, `named "${name}"`);
+    await page.goto(link.href, { waitUntil: 'domcontentloaded' });
+});
+function noLink(message, what) {
+    const links = extractLinks(message);
+    return new SdodsError('RUN_FAILED', `No link ${what} in "${message.subject}".`, {
+        hint: links.length
+            ? `Links in that email:\n${links.map((l) => `  - ${l.text ? `"${l.text}" ` : ''}${l.href}`).join('\n')}`
+            : 'That email has no links at all: no <a href> in the HTML part and no http(s) URL in the text part.',
+        details: { subject: message.subject, links },
+    });
+}
+//# sourceMappingURL=email.steps.js.map

package/dist/steps/hooks.steps.d.ts

@@ -1,2 +1,3 @@
 import '../shots/hooks.js';
+import '../quality/hooks.js';
 //# sourceMappingURL=hooks.steps.d.ts.map

package/dist/steps/hooks.steps.js

@@ -1,5 +1,7 @@
-// Registers the screenshot-narrative, finalize, browser-skip and HAR hooks when bddgen loads the core step glob.
+// Registers the screenshot-narrative, finalize, browser-skip, HAR, @a11y and @perf hooks when bddgen loads the core step glob.
 import '../shots/hooks.js';
+// After the screenshot hooks: after-hooks run in reverse order, so these run before sdods:finalize.
+import '../quality/hooks.js';
 import { registerHarHooks } from '../har/hooks.js';
 import { Before } from '../fixtures/test.js';
 registerHarHooks({ Before });

package/dist/steps/hybrid.steps.js

@@ -1,7 +1,7 @@
 import { expect } from '@playwright/test';
 import './params.js';
 import { Then, When } from '../fixtures/test.js';
-import { getPath } from '../api/json-path.js';
+import { matchedPath } from '../api/json-path.js';
 import { renderJson, renderStrict } from '../api/template.js';
 /* Hybrid glue: seed through the API, verify in the browser. */
 When('I seed via {method} {string} with body:', async ({ api, apiContext, env }, method, path, body) => {
@@ -10,7 +10,7 @@ When('I seed via {method} {string} with body:', async ({ api, apiContext, env },
 });
 Then('the UI should show the text from JSON path {string}', async ({ page, apiContext, env }, jsonPath) => {
     const path = renderStrict(jsonPath, apiContext.vars.toObject(), env.vars);
-    const value = getPath(apiContext.last().response.body, path);
+    const value = matchedPath(apiContext.last().response.body, path);
     await expect(page.getByText(String(value), { exact: false }).first()).toBeVisible();
 });
 When('I replay HAR {string} for {string}', async ({ page, config, apiContext, env }, harName, glob) => {

package/dist/steps/index.d.ts

@@ -17,6 +17,9 @@ import './browser.steps.js';
 import './dom.steps.js';
 import './net.steps.js';
 import './perf.steps.js';
+import './email.steps.js';
+import './canvas.steps.js';
 import '../shots/hooks.js';
+import '../quality/hooks.js';
 export { coreStepsGlob, coreStepsPatterns, coreStepNames, coreStepsDir } from './glob.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/steps/index.js

@@ -17,6 +17,9 @@ import './browser.steps.js';
 import './dom.steps.js';
 import './net.steps.js';
 import './perf.steps.js';
+import './email.steps.js';
+import './canvas.steps.js';
 import '../shots/hooks.js';
+import '../quality/hooks.js';
 export { coreStepsGlob, coreStepsPatterns, coreStepNames, coreStepsDir } from './glob.js';
 //# sourceMappingURL=index.js.map