scenescout 3.18.0 → 3.19.1

package/dist/engine/browser.js

@@ -9,12 +9,12 @@ import { POSTMESSAGE_BINDING, describeTokenPost, postMessageCaptureScript, token
 import { describeInjection, newInjections, probeQueries, probeScript, probeShape, rememberProbe } from "./injection.js";
 import { AuthLossTracker } from "./authloss.js";
 import { captureClip, cutByViewport } from "./capture.js";
-import { STOP_ANIMATIONS_SCRIPT } from "./baseline.js";
+import { NEXT_FRAME_SCRIPT, NEXT_FRAME_WAIT_MS, STOP_ANIMATIONS_SCRIPT, steadyPicture, unsteadyNote } from "./baseline.js";
 import { COLLECT_INTERACTABLES_SCRIPT, COLLECTOR_CAP, NAME_SRC, POLICY_TEXT_SRC, VISIBLE_SRC, XPATH_OF_SRC, affordanceFlags, cutSummary, matchPrevious, geometryIssues, BROKEN_IMAGES_SCRIPT, brokenImageIssues, frameLines, hasVisibleFrame, frameElementKey, frameLabel, masksForeignName, MASKED_NAME, capForeignName, stripForeignHref, frameToPageRect, displayName, missingName, placeholderOnly, placeholderEvidence, describeControl, labelFlag, stateFlags, stateChange, trackedElements, inertKeys, MAIN_REGION_SCRIPT, mainRegionLine, mainRegionTag, mainState, describeCover, } from "./collector.js";
 import { OracleMonitor, formatViolations, httpErrorDetail, planStopsAt, requestKey } from "./oracles.js";
 import { extractCreatedIds, isOwnedResource, normalizeId } from "./ownership.js";
 import { formatJourney, journeyTime, measureJourney } from "./journey.js";
-import { describeStep, FLOW_AFTER_LAST_STEP_MS, isAction, matchRequest, parseTarget, splitRefusals, TARGET_HELP, urlMatches, } from "./flow.js";
+import { describeStep, elementStateMatches, FLOW_AFTER_LAST_STEP_MS, isAction, matchRequest, notActionable, parseTarget, repeatFailure, splitRefusals, TARGET_HELP, urlMatches, } from "./flow.js";
 import { framePath, RECORD_MAX_FRAMES } from "./replay.js";
 import { InFlightRequests, keepWatchingUrl, normalizePace, SETTLE_TICK_MS, shouldKeepWaiting } from "./settle.js";
 import { crawledRoute, crawlLine, isFileMediaType, isNonPageResource, mainStateFlag, mediaTypeOf } from "./crawl.js";
@@ -263,6 +263,8 @@ function actionabilityDiagnostic(message) {
 const SCREENCAST_PAGELESS_TICKS = 20;
 /** A frame for the record is worth a moment, not a stall: the action has already happened. */
 const RECORD_SHOT_TIMEOUT_MS = 2500;
+/** How long a repeat step waits for its condition after each round of its actions, before running them again. */
+const REPEAT_CHECK_MS = 1000;
 export class BrowserEngine {
     browser = null;
     /** How long an action and a page load may take; set at attach (limits.ts). */
@@ -4990,6 +4992,46 @@ export class BrowserEngine {
                 return page.getByRole(target.role, target.name === undefined ? {} : { name: target.name });
         }
     }
+    /**
+     * Wait up to the action limit for a visible target to accept `action`, and
+     * say why it never did (flow.ts notActionable), or null once it can. Without
+     * this a disabled control failed as a bare action timeout that never said the
+     * control was there but disabled.
+     */
+    async waitUntilActionable(loc, action) {
+        const read = async () => notActionable(action, {
+            enabled: await loc.isEnabled({ timeout: 1000 }).catch(() => true),
+            editable: action === "type" ? await loc.isEditable({ timeout: 1000 }).catch(() => null) : null,
+        });
+        const until = Date.now() + this.limits.actionMs;
+        let reason = await read();
+        while (reason && Date.now() < until) {
+            await loc
+                .page()
+                .waitForTimeout(100)
+                .catch(() => { });
+            reason = await read();
+        }
+        return reason;
+    }
+    /**
+     * What an expect-element step asks of its target, read once: whether any
+     * match is visible, and, for the first visible match (or the first match when
+     * none is), whether it is enabled and checked. Null when nothing matches.
+     * The verdict is flow.ts's elementStateMatches, so the rules stay testable.
+     */
+    static async elementFacts(matches) {
+        const total = await matches.count().catch(() => 0);
+        if (total === 0)
+            return null;
+        const visible = matches.filter({ visible: true });
+        const anyVisible = (await visible.count().catch(() => 0)) > 0;
+        const el = anyVisible ? visible.first() : matches.first();
+        const enabled = await el.isEnabled({ timeout: 1000 }).catch(() => null);
+        // isChecked throws for an element that is not a checkbox, radio or [role=checkbox]: it has no checked state.
+        const checked = await el.isChecked({ timeout: 1000 }).catch(() => null);
+        return { visible: anyVisible, enabled, checked };
+    }
     /**
      * Replay one saved flow for `scenescout check`. Acts and reports only: the
      * schema, the matching rules and what an outcome means live in flow.ts and
@@ -5005,6 +5047,10 @@ export class BrowserEngine {
         // The write policy judges by writeRule, so the flow's rule holds from here until the flow has handed back (finally).
         const crawlMode = this.mode;
         this.setMode(mode);
+        // A flow's navigate means leave, and so does handing back: a page that asks to confirm leaving (an unsaved-changes
+        // guard on a form a failed step left half filled) is left, or it would cancel the next flow's first navigate.
+        const leaveBefore = this.leaveChoice;
+        this.leaveChoice = true;
         const context = this.context;
         const violations = [];
         const here = () => {
@@ -5045,8 +5091,8 @@ export class BrowserEngine {
                 if (v.detail !== except)
                     violations.push({ path, violation: { kind: v.kind, severity: v.severity, detail: v.detail, url: v.url, ...(v.embed ? { embed: v.embed } : {}) } });
         };
-        const poll = async (done) => {
-            const until = Date.now() + this.limits.actionMs;
+        const poll = async (done, ms = this.limits.actionMs) => {
+            const until = Date.now() + ms;
             for (;;) {
                 if (done())
                     return true;
@@ -5055,119 +5101,170 @@ export class BrowserEngine {
                 await (this.page ?? page).waitForTimeout(100).catch(() => { });
             }
         };
-        try {
-            for (const [i, step] of steps.entries()) {
-                const n = i + 1;
-                const did = describeStep(step);
-                if (isAction(step))
-                    seen = [];
-                let failure = null;
-                let refusal = null;
-                this.actionStartedAt = Date.now();
-                if (step.action === "click" || step.action === "type" || step.action === "select" || step.action === "press")
-                    await this.beginInput();
-                try {
-                    const current = this.requirePage();
-                    if (step.action === "navigate") {
-                        const resolved = resolveTarget(this.baseUrl, step.target);
-                        if (!("url" in resolved))
-                            throw new Error(resolved.problem);
-                        const url = resolved.url;
-                        const resp = await current
-                            .goto(url, { waitUntil: "domcontentloaded", timeout: this.limits.crawlNavMs })
-                            .catch((err) => Promise.reject(explainTimeout(err, "nav", this.limits.crawlNavMs)));
+        /**
+         * Run one step that acts or asserts once, with the bookkeeping every step gets: the requests it caused, the
+         * writes the policy refused while it ran, and the oracles' violations. `actionMs` is how long it may wait; a
+         * repeat's condition is checked with a shorter wait, since the next repeat is what it waits for.
+         */
+        const runStep = async (step, actionMs = this.limits.actionMs) => {
+            if (isAction(step))
+                seen = [];
+            let failure = null;
+            let refusal = null;
+            this.actionStartedAt = Date.now();
+            if (step.action === "click" || step.action === "type" || step.action === "select" || step.action === "press")
+                await this.beginInput();
+            try {
+                const current = this.requirePage();
+                if (step.action === "navigate") {
+                    const resolved = resolveTarget(this.baseUrl, step.target);
+                    if (!("url" in resolved))
+                        throw new Error(resolved.problem);
+                    const url = resolved.url;
+                    const resp = await current
+                        .goto(url, { waitUntil: "domcontentloaded", timeout: this.limits.crawlNavMs })
+                        .catch((err) => Promise.reject(explainTimeout(err, "nav", this.limits.crawlNavMs)));
+                    await this.settle();
+                    const status = resp?.status() ?? null;
+                    if (status !== null && status >= 400) {
+                        failure = `the page answered HTTP ${status}`;
+                        // The page's own status is this step's failure; the oracle's record of the same response is not a second issue.
+                        // The oracle stores its details redacted (redactViolation), so the comparison is redacted too.
+                        collect(redactSecrets(httpErrorDetail("GET", current.url().replace(/#.*$/, ""), status)));
+                    }
+                }
+                else if (step.action === "upload") {
+                    const loc = step.target ? BrowserEngine.locatorFor(current, parseTarget(step.target)).first() : null;
+                    const outcome = await this.performUpload(loc, { ...(step.fixture ? { fixture: step.fixture } : {}), ...(step.name ? { name: step.name } : {}) });
+                    if (outcome.refused)
+                        failure = outcome.refused.split("\n")[0];
+                    else
+                        await this.settle();
+                }
+                else if (step.action === "press") {
+                    refusal = await this.vetFocusedActivation(step.value);
+                    if (!refusal) {
+                        await current.keyboard.press(step.value);
                         await this.settle();
-                        const status = resp?.status() ?? null;
-                        if (status !== null && status >= 400) {
-                            failure = `the page answered HTTP ${status}`;
-                            // The page's own status is this step's failure; the oracle's record of the same response is not a second issue.
-                            // The oracle stores its details redacted (redactViolation), so the comparison is redacted too.
-                            collect(redactSecrets(httpErrorDetail("GET", current.url().replace(/#.*$/, ""), status)));
-                        }
                     }
-                    else if (step.action === "press") {
-                        refusal = await this.vetFocusedActivation(step.value);
-                        if (!refusal) {
-                            await current.keyboard.press(step.value);
-                            await this.settle();
-                        }
+                }
+                else if (step.action === "click" || step.action === "type" || step.action === "select") {
+                    const loc = BrowserEngine.locatorFor(current, parseTarget(step.target)).first();
+                    const found = await loc
+                        .waitFor({ state: "visible", timeout: actionMs })
+                        .then(() => true)
+                        .catch(() => false);
+                    const blocked = found ? await this.waitUntilActionable(loc, step.action) : null;
+                    if (!found) {
+                        failure = `nothing visible matches ${step.target} within ${actionMs / 1000}s — ${limitHint("action", actionMs)}`;
+                    }
+                    else if (blocked) {
+                        // The state first, since it is what is true; the hint still applies when the app enables it late.
+                        failure = `${step.target} ${blocked} after ${actionMs / 1000}s — ${limitHint("action", actionMs)}`;
                     }
-                    else if (step.action === "click" || step.action === "type" || step.action === "select") {
-                        const loc = BrowserEngine.locatorFor(current, parseTarget(step.target)).first();
-                        const found = await loc
-                            .waitFor({ state: "visible", timeout: this.limits.actionMs })
-                            .then(() => true)
-                            .catch(() => false);
-                        if (!found) {
-                            failure = `nothing visible matches ${step.target} within ${this.limits.actionMs / 1000}s — ${limitHint("action", this.limits.actionMs)}`;
+                    else {
+                        const label = ((await loc.getAttribute("aria-label").catch(() => null)) ??
+                            (await loc.textContent({ timeout: 1000 }).catch(() => null)) ??
+                            "").trim();
+                        // A dropdown is named by all its options; a select step is judged by the option it picks (destructiveLabelOf).
+                        const isSelect = step.action === "select" && (await loc.evaluate((n) => n.tagName.toLowerCase() === "select").catch(() => false));
+                        const testid = await loc.getAttribute("data-testid").catch(() => null);
+                        if (this.readOnly &&
+                            step.action !== "type" &&
+                            (isSelect
+                                ? pickIsDestructive(step.value, testid, await BrowserEngine.chosenOptionLabel(loc, step.value))
+                                : isDestructive(label, step.action === "select" ? step.value : undefined))) {
+                            refusal = destructiveRefusal(label || step.target, this.mode);
+                        }
+                        else if (step.action === "click") {
+                            await loc.click({ timeout: actionMs });
+                        }
+                        else if (step.action === "select") {
+                            await loc.selectOption(step.value, { timeout: actionMs });
                         }
                         else {
-                            const label = ((await loc.getAttribute("aria-label").catch(() => null)) ??
-                                (await loc.textContent({ timeout: 1000 }).catch(() => null)) ??
-                                "").trim();
-                            // A dropdown is named by all its options; a select step is judged by the option it picks (destructiveLabelOf).
-                            const isSelect = step.action === "select" && (await loc.evaluate((n) => n.tagName.toLowerCase() === "select").catch(() => false));
-                            const testid = await loc.getAttribute("data-testid").catch(() => null);
-                            if (this.readOnly &&
-                                step.action !== "type" &&
-                                (isSelect
-                                    ? pickIsDestructive(step.value, testid, await BrowserEngine.chosenOptionLabel(loc, step.value))
-                                    : isDestructive(label, step.action === "select" ? step.value : undefined))) {
-                                refusal = destructiveRefusal(label || step.target, this.mode);
-                            }
-                            else if (step.action === "click") {
-                                await loc.click({ timeout: this.limits.actionMs });
-                            }
-                            else if (step.action === "select") {
-                                await loc.selectOption(step.value, { timeout: this.limits.actionMs });
-                            }
-                            else {
-                                await this.noteProbe(step.value, step.target);
-                                await this.fillOrAppend(loc, step.value, step.replace ?? false);
-                                if (step.pressEnter) {
-                                    const submit = loc.locator("xpath=ancestor::form[1]").locator('[type="submit"], button:not([type="button"]):not([type="reset"])').first();
-                                    const submitLabel = ((await submit.textContent({ timeout: 1000 }).catch(() => "")) ?? "").trim();
-                                    if (this.readOnly && isDestructive(submitLabel))
-                                        refusal = destructiveRefusal(submitLabel, this.mode);
-                                    else
-                                        await loc.press("Enter", { timeout: this.limits.actionMs });
-                                }
+                            await this.noteProbe(step.value, step.target);
+                            await this.fillOrAppend(loc, step.value, step.replace ?? false);
+                            if (step.pressEnter) {
+                                const submit = loc.locator("xpath=ancestor::form[1]").locator('[type="submit"], button:not([type="button"]):not([type="reset"])').first();
+                                const submitLabel = ((await submit.textContent({ timeout: 1000 }).catch(() => "")) ?? "").trim();
+                                if (this.readOnly && isDestructive(submitLabel))
+                                    refusal = destructiveRefusal(submitLabel, this.mode);
+                                else
+                                    await loc.press("Enter", { timeout: actionMs });
                             }
-                            if (!refusal)
-                                await this.settle();
                         }
+                        if (!refusal)
+                            await this.settle();
                     }
-                    else if (step.action === "expect-text") {
-                        const visible = current.getByText(step.text, { exact: false }).filter({ visible: true }).first();
-                        const ok = await visible
-                            .waitFor({ state: "visible", timeout: this.limits.actionMs })
-                            .then(() => true)
-                            .catch(() => false);
-                        if (!ok)
-                            failure = `no visible text ${JSON.stringify(step.text)} within ${this.limits.actionMs / 1000}s — ${limitHint("action", this.limits.actionMs)}`;
-                    }
-                    else if (step.action === "expect-url") {
-                        const ok = await poll(() => urlMatches(step.pattern, this.page?.url() ?? ""));
-                        if (!ok)
-                            failure = `the page is at ${here()}, which does not match /${step.pattern}/`;
-                    }
-                    else {
-                        let last = { ok: false, reason: "" };
-                        await poll(() => (last = matchRequest(step, seen)).ok);
-                        if (!last.ok)
-                            failure = last.reason;
+                }
+                else if (step.action === "expect-text") {
+                    const visible = current.getByText(step.text, { exact: false }).filter({ visible: true }).first();
+                    const ok = await visible
+                        .waitFor({ state: "visible", timeout: actionMs })
+                        .then(() => true)
+                        .catch(() => false);
+                    if (!ok)
+                        failure = `no visible text ${JSON.stringify(step.text)} within ${actionMs / 1000}s — ${limitHint("action", actionMs)}`;
+                }
+                else if (step.action === "expect-element") {
+                    const matches = BrowserEngine.locatorFor(current, parseTarget(step.target));
+                    const until = Date.now() + actionMs;
+                    let verdict = elementStateMatches(step.state, await BrowserEngine.elementFacts(matches));
+                    while (!verdict.ok && Date.now() < until) {
+                        await current.waitForTimeout(100).catch(() => { });
+                        verdict = elementStateMatches(step.state, await BrowserEngine.elementFacts(matches));
                     }
+                    if (!verdict.ok)
+                        failure = `${step.target} ${verdict.actual}, expected ${step.state}, after ${actionMs / 1000}s`;
                 }
-                catch (err) {
-                    failure = firstLineOf(explainTimeout(err, "action", this.limits.actionMs));
+                else if (step.action === "expect-url") {
+                    const ok = await poll(() => urlMatches(step.pattern, this.page?.url() ?? ""), actionMs);
+                    if (!ok)
+                        failure = `the page is at ${here()}, which does not match /${step.pattern}/`;
                 }
-                await this.scanForInjections().catch(() => { });
-                await this.scanForContradictions().catch(() => { });
-                // What the write policy refused of the app's own requests while this step ran is the step's, whatever caused it.
-                const blocked = ownRefusals();
-                if (!refusal && blocked.length > 0)
-                    refusal = `the ${this.writeRule.at()} write policy refused ${blocked.join(", ")}`;
-                collect();
+                else {
+                    let last = { ok: false, reason: "" };
+                    await poll(() => (last = matchRequest(step, seen)).ok, actionMs);
+                    if (!last.ok)
+                        failure = last.reason;
+                }
+            }
+            catch (err) {
+                failure = firstLineOf(explainTimeout(err, "action", actionMs));
+            }
+            await this.scanForInjections().catch(() => { });
+            await this.scanForContradictions().catch(() => { });
+            // What the write policy refused of the app's own requests while this step ran is the step's, whatever caused it.
+            const blocked = ownRefusals();
+            if (!refusal && blocked.length > 0)
+                refusal = `the ${this.writeRule.at()} write policy refused ${blocked.join(", ")}`;
+            collect();
+            return { failure, refusal };
+        };
+        /** A repeat step: its condition first, then its actions and the condition again, at most `max` times. */
+        const runRepeat = async (step) => {
+            for (let k = 0;; k++) {
+                // A short wait every time, the first look included: an instant one misses what is already on the page.
+                const check = await runStep(step.until, Math.min(REPEAT_CHECK_MS, this.limits.actionMs));
+                if (check.refusal)
+                    return check;
+                if (!check.failure)
+                    return { failure: null, refusal: null };
+                if (k === step.max)
+                    return { failure: repeatFailure(step.until, step.max, check.failure), refusal: null };
+                for (const inner of step.steps) {
+                    const r = await runStep(inner);
+                    if (r.refusal || r.failure)
+                        return { failure: r.failure && `repeat ${k + 1} of at most ${step.max}, ${describeStep(inner)}: ${r.failure}`, refusal: r.refusal };
+                }
+            }
+        };
+        try {
+            for (const [i, step] of steps.entries()) {
+                const n = i + 1;
+                const did = describeStep(step);
+                const { failure, refusal } = step.action === "repeat" ? await runRepeat(step) : await runStep(step);
                 if (refusal)
                     return done({ status: "refused", step: n, did, reason: refusal.split("\n")[0], path: here() });
                 if (failure)
@@ -5207,6 +5304,7 @@ export class BrowserEngine {
             // Pages the session no longer drives are closed only now, at about:blank and under the held rule, and each only
             // once what it sent as it was left has been judged (leftSettled).
             await BrowserEngine.settleWithin(Promise.allSettled(context.pages().map(async (p) => (p === this.page ? undefined : (await this.leftSettled(p), await p.close().catch(() => { }))))), 5000);
+            this.leaveChoice = leaveBefore;
             page.off("websocket", onSocket);
             context.off("response", onResponse);
             this.refs.clear();
@@ -5383,7 +5481,9 @@ export class BrowserEngine {
      * stopped, then either the viewport from the top (no target) or one element,
      * found the way a saved flow finds its target, with `how.margin` around it.
      * The screenshot is taken with `how`'s animation and caret settings, at one
-     * picture pixel per CSS pixel. Reads only. Throws a sentence when it cannot
+     * picture pixel per CSS pixel, and again a frame later until two in a row
+     * are the same (steadyPicture); `unsteady` says so when the page never held
+     * still within the action limit. Reads only. Throws a sentence when it cannot
      * take the picture. `cut` says when an element reaches outside the window.
      * What is compared and what it means is baseline.ts, which also holds the
      * settings; the rectangle is capture.ts. Call endBaselineCaptures when done.
@@ -5422,11 +5522,10 @@ export class BrowserEngine {
         const viewport = page.viewportSize() ?? (await page.evaluate("({ width: innerWidth, height: innerHeight })"));
         const deviceScaleFactor = Number(await page.evaluate("window.devicePixelRatio"));
         const settings = { type: "png", animations: how.animations, caret: how.caret, scale: "css", timeout: this.limits.actionMs };
-        let png;
+        let clip;
         let cut = null;
         if (!target) {
             await page.evaluate("window.scrollTo(0, 0)");
-            png = await action(page.screenshot(settings));
         }
         else {
             const locator = BrowserEngine.locatorFor(page, target).first();
@@ -5437,14 +5536,18 @@ export class BrowserEngine {
             const box = await action(locator.boundingBox({ timeout: this.limits.actionMs }));
             if (!box)
                 throw new Error("it is not displayed");
-            const clip = captureClip(box, how.margin, viewport);
+            clip = captureClip(box, how.margin, viewport) ?? undefined;
             if (!clip)
                 throw new Error("it is outside the viewport");
             cut = cutByViewport(box, viewport);
-            png = await action(page.screenshot({ ...settings, clip }));
         }
+        // Two pictures in a row the same, a frame apart: the page has drawn the stop and stopped changing (steadyPicture).
+        const { png, steady } = await steadyPicture(() => action(page.screenshot(clip ? { ...settings, clip } : settings)), 
+        // Bounded here too, since a page whose main thread is stuck never runs the script's own fallback. A wait that
+        // fails (the page navigated) is not the picture's error: the next take reports what is wrong with the page.
+        () => BrowserEngine.settleWithin(page.evaluate(NEXT_FRAME_SCRIPT), NEXT_FRAME_WAIT_MS), this.limits.actionMs);
         this.logAction({ action: "capture", target: target ? `baseline ${pathOnApp}` : `baseline ${pathOnApp} (page)`, url: page.url() });
-        return { png, viewport, deviceScaleFactor, cut };
+        return { png, viewport, deviceScaleFactor, cut, unsteady: steady ? null : unsteadyNote(this.limits.actionMs) };
     }
     /** Stop telling the page to reduce motion, so what runs after the baselines (saved flows) sees the page as a user does. */
     async endBaselineCaptures() {

package/dist/engine/check.js

@@ -359,15 +359,32 @@ export function checkFindings(routes, origin, ignore = [], flows = [], baselines
 export function issuesFromRoutes(routes, origin, ignore = [], flows = [], ignorePaths = [], signedIn = true) {
     return checkFindings(routes, origin, ignore, flows, null, ignorePaths, signedIn).issues;
 }
+/**
+ * Fewest controls a start page must show for a check that measured nothing
+ * else to count as having measured the app (unmeasuredReason).
+ */
+export const START_PAGE_MIN_CONTROLS = 2;
 /**
  * Why a check has nothing to give a verdict on, or null when it measured the
  * app. Neither case is a pass: a gate that goes green on a login page or a
  * dead server would pass every pull request while the app was down.
  */
-export function unmeasuredReason(routes, startIsFirst) {
+export function unmeasuredReason(routes, startIsFirst, unvisited = []) {
     const loaded = routes.filter((r) => r.loadError === undefined);
     if (loaded.length === 0)
         return "no page loaded. Is the app running at that URL?";
+    // A start page measured before the app drew it (a client-rendered shell still loading, a blank page) links nowhere,
+    // so the crawl ends there and every rule is silent: a pass that checked nothing. A real one-page app has controls.
+    const start = routes[0];
+    // `unvisited` empty: the page linked nowhere. A crawl that --max-routes cut short did find more, and measured what it was asked to.
+    if (startIsFirst &&
+        unvisited.length === 0 &&
+        loaded.length === 1 &&
+        start === loaded[0] &&
+        !start.loginRedirect &&
+        start.elements < START_PAGE_MIN_CONTROLS) {
+        return `only the start page was measured, and it showed ${start.elements} control(s) and linked nowhere, so the app may not have finished drawing. Check again, raise --nav-timeout-ms if the app is slow to render, pass --project so routes come from the source, or name them with --paths.`;
+    }
     // Without --paths the first route is the start page. When it bounces, what follows is the sign-in
     // page's own links (sign-up, forgot password): pages that load, but not the app.
     // With --paths there is no start page, only a list, and one walled path among public ones is an auth-redirect issue.
@@ -861,7 +878,7 @@ const BASELINE_MARK = {
 /** One target's line in the report. */
 function baselineLine(r, run) {
     const what = `${BASELINE_MARK[r.status]} ${code(r.element)} on ${code(r.path)}`;
-    const notes = [r.platformNote, r.partial]
+    const notes = [r.platformNote, r.partial, r.unsteady]
         .filter(Boolean)
         .map((n) => ` _(${cell(n)})_`)
         .join("");
@@ -1035,11 +1052,12 @@ export function formatCheck(result) {
         lines.push("", `## Flows (${result.flows.length})`, "");
         for (const f of result.flows) {
             const o = f.outcome;
+            const as = f.role === undefined ? "" : ` as ${code(f.role)}`;
             lines.push(o.status === "passed"
-                ? `- ✓ ${cell(f.name)} (${code(f.file)}): ${f.steps} step(s) passed`
+                ? `- ✓ ${cell(f.name)} (${code(f.file)})${as}: ${f.steps} step(s) passed`
                 : o.status === "refused"
-                    ? `- ⊘ ${cell(f.name)} (${code(f.file)}): could not run — step ${o.step} of ${f.steps}, ${cell(o.did)}: ${cell(o.reason)} _(--flow-writes ${result.settings.flowWrites})_`
-                    : `- ✗ ${cell(f.name)} (${code(f.file)}): step ${o.step} of ${f.steps}, ${cell(o.did)}: ${cell(o.reason)}`);
+                    ? `- ⊘ ${cell(f.name)} (${code(f.file)})${as}: could not run — step ${o.step} of ${f.steps}, ${cell(o.did)}: ${cell(o.reason)} _(--flow-writes ${result.settings.flowWrites})_`
+                    : `- ✗ ${cell(f.name)} (${code(f.file)})${as}: step ${o.step} of ${f.steps}, ${cell(o.did)}: ${cell(o.reason)}`);
             if (f.refusedBackground.length > 0)
                 lines.push(`  - refused background requests (beacons and pings, not charged to a step): ${f.refusedBackground.map(code).join(", ")}`);
             if (f.websockets.length > 0)
@@ -1113,6 +1131,7 @@ export function toSummaryJson(result, toolVersion) {
         flows: result.flows.map((f) => ({
             name: f.name,
             file: f.file,
+            ...(f.role === undefined ? {} : { role: f.role }),
             steps: f.steps,
             status: f.outcome.status,
             ...(f.outcome.status === "passed" ? {} : { step: f.outcome.step, did: f.outcome.did, reason: f.outcome.reason, path: f.outcome.path }),

package/dist/engine/dedup.js

@@ -83,6 +83,17 @@ export function buildPairs(archives, keys) {
     }
     return out;
 }
+/**
+ * The archives dated on or after `since` (YYYY-MM-DD), so a decider can be
+ * scored out of sample: on pairs from runs made after it was tuned, none of
+ * whose findings it has seen. Filtered before pairing, so a pair never joins
+ * a new finding to an old one.
+ */
+export function archivesSince(archives, since) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(since))
+        throw new Error(`The date must be YYYY-MM-DD, not ${JSON.stringify(since)}.`);
+    return archives.filter((a) => a.date >= since);
+}
 /**
  * At most `cap` pairs, chosen by a hash of their texts: the same pairs every
  * time for the same archives, whatever order they were built in, and no

package/dist/engine/design.js

@@ -412,6 +412,10 @@ function contrastFailures(records) {
     for (const r of records) {
         if (!r.text || r.bg === "image" || r.bg === "unknown" || r.color === "unknown")
             continue;
+        // Text whose own colour is fully transparent is not painted: a selectable text layer laid over a rendered
+        // document (a PDF viewer's), or text hidden for screen readers. Its 1:1 ratio is not what anyone sees.
+        if (parseRgb(r.color)?.[3] === 0)
+            continue;
         const ratio = contrastRatio(r.color, r.bg);
         if (ratio === null)
             continue;