@sdods/core 0.7.1 → 0.8.0

package/dist/steps/browser.steps.js

@@ -1,6 +1,7 @@
-import { expect } from '@playwright/test';
+import { devices, expect } from '@playwright/test';
 import { Given, Then, When } from '../fixtures/test.js';
 import { renderStrict } from '../api/template.js';
+import { COLOR_SCHEMES, emulationTagProblem, findDevice, parseViewport, } from '../config/emulation.js';
 import { SdodsError } from '../errors.js';
 /**
  * Browser-state steps: cookies, web storage, viewport, colour scheme, locale and console.
@@ -292,11 +293,14 @@ function probeHorizontalOverflow() {
 // TRAP: a blank document also does not scroll sideways. The body-children guard is what stops this
 // step going green on a page that failed to render, which is the one case it must not bless.
 Then('the page should not scroll horizontally', async ({ page }) => {
-    requireNavigated(page, 'the page should not scroll horizontally');
+    await expectNoHorizontalScroll(page, 'the page should not scroll horizontally');
+});
+async function expectNoHorizontalScroll(page, step) {
+    requireNavigated(page, step);
     const report = (await page.evaluate(probeHorizontalOverflow));
     expect(report.bodyChildren, 'the document body is empty — a blank page cannot prove anything about reflow').toBeGreaterThan(0);
     expect(report.scrollWidth, `the document is ${report.scrollWidth}px wide inside a ${report.clientWidth}px viewport. Offenders: ${report.offenders.join(', ') || '(none measurable)'}`).toBeLessThanOrEqual(report.clientWidth + 1);
-});
+}
 // Proves ONE container contains its own width — a table, a code block or a chart that is allowed
 // to scroll internally must not push the page. Fails when the selector matches nothing, because a
 // containment claim about an element that is not on the page is not a claim.
@@ -651,4 +655,151 @@ Then('no uncaught page error should have been recorded', async ({ apiContext })
     const recording = recordingFor(apiContext, 'no uncaught page error should have been recorded');
     expect(recording.pageErrors, 'uncaught page errors').toEqual([]);
 });
+/* ── per-scenario emulation: the `I use …` family (#116) ─────────────── */
+// Locale, timezone and device are browser-CONTEXT options: Playwright fixes them when the context
+// is created and offers no way to change them afterwards. By the time the first step runs, the
+// context is open, so these steps cannot apply a value. The tags `@locale:` `@timezone:` and
+// `@device:` are resolved before the context opens; each step below passes when the context
+// already has the value (it then states the scenario's intent in its text) and otherwise fails,
+// naming the tag to use. Recreating the context was rejected: the page objects, the healer and the
+// screenshot narrator already hold the original page, and would silently act on a closed one.
+// Colour scheme and viewport CAN change on a live page, so those steps apply their value.
+function contextFixed(what, tag, actual) {
+    return new SdodsError('RUN_FAILED', 
+    // The tag is in the MESSAGE, not only the hint: a Playwright report shows the message alone.
+    `The browser context was created with ${what} ${actual === undefined ? '(the system default)' : `"${actual}"`}, and Playwright cannot change it on an open context — tag the scenario ${tag}.`, {
+        hint: `Tag the scenario ${tag} (or its Feature, or an Examples block) — the tag is applied before the context is created, and this step then passes.`,
+    });
+}
+// Proves the scenario runs under this locale: navigator.language, Intl formatting and the
+// Accept-Language header all come from it. Passes only when `@locale:` (or the env's `use.locale`)
+// already set it.
+Given('I use the locale {string}', async ({ locale, apiContext, env }, value) => {
+    const wanted = renderStrict(value, ...scopesOf(apiContext, env));
+    const problem = emulationTagProblem('locale', wanted);
+    if (problem)
+        throw new SdodsError('RUN_FAILED', problem);
+    const canon = (l) => Intl.getCanonicalLocales(l)[0];
+    if (!locale || canon(locale) !== canon(wanted))
+        throw contextFixed('locale', `@locale:${wanted}`, locale);
+});
+// Proves the scenario runs in this IANA time zone — the one that decides what "today" and every
+// rendered timestamp mean. Passes only when `@timezone:` (or `use.timezoneId`) already set it.
+Given('I use the timezone {string}', async ({ timezoneId, apiContext, env }, value) => {
+    const wanted = renderStrict(value, ...scopesOf(apiContext, env));
+    const problem = emulationTagProblem('timezone', wanted);
+    if (problem)
+        throw new SdodsError('RUN_FAILED', problem);
+    if (timezoneId !== wanted)
+        throw contextFixed('time zone', `@timezone:${wanted}`, timezoneId);
+});
+// Proves the OS-level colour preference for the rest of the scenario. Applied on the live page, so
+// it works mid-scenario; `@theme:` does the same before the first paint, which is what a
+// flash-of-wrong-theme check needs.
+Given('I use the {string} color scheme', async ({ page, apiContext, env }, scheme) => {
+    const wanted = renderStrict(scheme, ...scopesOf(apiContext, env));
+    if (!COLOR_SCHEMES.includes(wanted))
+        throw new SdodsError('RUN_FAILED', `"${wanted}" is not a color scheme.`, {
+            hint: `Use one of: ${COLOR_SCHEMES.join(', ')}.`,
+        });
+    await page.emulateMedia({ colorScheme: wanted });
+});
+// Resizes the live page. `@viewport:<W>x<H>` sets the size before the first navigation instead,
+// which matters for apps that choose a layout once, on load.
+Given('I use the viewport {int} by {int}', async ({ page }, width, height) => {
+    const size = parseViewport(`${width}x${height}`);
+    if (!size)
+        throw new SdodsError('RUN_FAILED', `Viewport ${width}x${height} is not a usable size.`, {
+            hint: 'Both dimensions must be positive integers, e.g. `Given I use the viewport 320 by 640`.',
+        });
+    await page.setViewportSize(size);
+});
+// Proves the scenario runs with this device's viewport, user agent, pixel ratio and touch. The
+// engine stays the run target's browser. Passes when the context carries the device's user agent —
+// from `@device:`, or from a mobile run target built on that descriptor (mobile-safari is iPhone 15).
+Given('I use the device {string}', async ({ $sdodsEmulation, userAgent, apiContext, env }, value) => {
+    const wanted = renderStrict(value, ...scopesOf(apiContext, env));
+    const name = findDevice(wanted);
+    if (!name)
+        throw new SdodsError('RUN_FAILED', `"${wanted}" is not a Playwright device.`, {
+            hint: 'Use a descriptor name such as "iPhone 15" or "Pixel 7".',
+        });
+    if ($sdodsEmulation.device?.name !== name && userAgent !== devices[name]?.userAgent)
+        throw contextFixed('device', `@device:${name.replace(/\s+/g, '-')}`, $sdodsEmulation.device?.name ?? 'no device emulation');
+});
+// The WCAG 1.4.10 phrasing of `the page should not scroll horizontally` — same measurement, same
+// blank-page guard. Pair it with `@viewport:320x640`.
+Then('the page should reflow without horizontal scrolling', async ({ page }) => {
+    await expectNoHorizontalScroll(page, 'the page should reflow without horizontal scrolling');
+});
+/**
+ * What counts as an untranslated key in visible text, by default:
+ *   * a whole text node shaped like a catalogue key — `nav.settings`, `checkout.summary.total`
+ *     (the same rule as {@link looksLikeMessageKey}: file names, hostnames and versions excluded);
+ *   * an unrendered interpolation placeholder — `Hello {{name}}`;
+ *   * a library's own missing marker — `[missing "fr.nav.home" translation]` (i18n-js) or
+ *     `translation missing: fr.nav.home` (Rails).
+ * A project whose keys look different passes its own pattern to the `matching {string}` step,
+ * which then replaces these defaults.
+ */
+export const UNTRANSLATED_MARKERS = [
+    /\{\{\s*[^{}\s][^{}]*\}\}/,
+    /\[missing\b[^\]]*\]/i,
+    /\btranslation missing:/i,
+];
+export function findUntranslated(texts, pattern) {
+    const found = new Set();
+    for (const raw of texts) {
+        const text = raw.trim();
+        if (!text)
+            continue;
+        const hit = pattern
+            ? pattern.test(text)
+            : (text.length < 80 && !/\s/.test(text) && looksLikeMessageKey(text)) ||
+                UNTRANSLATED_MARKERS.some((re) => re.test(text));
+        if (hit)
+            found.add(text.length > 120 ? `${text.slice(0, 117)}...` : text);
+    }
+    return [...found];
+}
+/** Every visible text node, whole, plus how many were examined. */
+function collectVisibleTexts() {
+    const skip = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEMPLATE', 'TITLE'];
+    const texts = [];
+    if (!document.body)
+        return { sampled: 0, texts };
+    const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+    let node = walker.nextNode();
+    while (node) {
+        const parent = node.parentElement;
+        const text = (node.textContent ?? '').trim();
+        if (text && parent && skip.indexOf(parent.tagName) === -1) {
+            const el = parent;
+            const visible = typeof el.checkVisibility === 'function' ? el.checkVisibility() : el.offsetParent !== null;
+            if (visible)
+                texts.push(text);
+        }
+        node = walker.nextNode();
+    }
+    return { sampled: texts.length, texts };
+}
+async function expectNoUntranslated(page, step, pattern) {
+    requireNavigated(page, step);
+    const seen = (await page.evaluate(collectVisibleTexts));
+    // TRAP: a page that rendered no text has no untranslated keys either — fail instead of passing.
+    expect(seen.sampled, 'the page rendered no visible text at all, so this step examined nothing').toBeGreaterThan(0);
+    expect(findUntranslated(seen.texts, pattern), `untranslated keys rendered as visible text${pattern ? ` (matching /${pattern.source}/)` : ''}`).toEqual([]);
+}
+// Proves the catalogue resolved for this locale: no raw key, no unrendered `{{placeholder}}` and
+// no library "missing translation" marker is visible. Run it under each `@locale:`.
+Then('the page should have no untranslated keys', async ({ page }) => {
+    await expectNoUntranslated(page, 'the page should have no untranslated keys');
+});
+// The same check with the project's own definition of an untranslated key (a JavaScript regular
+// expression tested against each visible text node), e.g. "^[A-Z0-9_]{3,}$" for SCREAMING_CASE keys.
+Then('the page should have no untranslated keys matching {string}', async ({ page, apiContext, env }, pattern) => {
+    const step = 'the page should have no untranslated keys matching …';
+    const rendered = renderStrict(pattern, ...scopesOf(apiContext, env));
+    await expectNoUntranslated(page, step, compilePattern(rendered, step));
+});
 //# sourceMappingURL=browser.steps.js.map

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/email.steps.d.ts

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