lynkeus 0.2.0 → 0.3.0

package/lib/cases/runner.js

@@ -5,6 +5,7 @@
  * logs in or what a user is belongs to the project, as macros and fixtures.
  */
 import { exec } from 'node:child_process';
+import fs from 'node:fs';
 import path from 'node:path';
 import { promisify } from 'node:util';
 import { describeScreen } from '../device/driver.js';
@@ -12,7 +13,11 @@ import { normalizeEvents } from '../knowledge/events.js';
 import { find } from '../registry.js';
 import { execute } from '../runtime.js';
 import { isRoute, parseTarget, scopedTarget } from '../targets.js';
-import { dig, interpolate, matcherOf, matches, stepOf } from './format.js';
+import { newSpanId, newTraceId, traceparent } from './traces.js';
+import { dig, interpolate, matcherOf, matches, seeded, stepOf } from './format.js';
+/** A setup made only of the project's fixtures can run before the case, with no app attached. */
+export const preparable = (c, config) => c.setup.length > 0 &&
+    c.setup.every((step) => !step.on && !step.verb.startsWith('app.') && !config.macros?.[step.verb] && step.verb !== 'exec' && step.verb !== 'assert');
 /** What a buffer holds that it did not before, whichever end it grows from. */
 export const newSince = (before, now) => {
     if (now.length < before.length)
@@ -69,6 +74,11 @@ export const argvFor = (command, value) => {
         return [...argv, ...(Array.isArray(value) ? value.map(String) : [String(value)])];
     const given = { ...value };
     const positionals = command.positionals ?? [];
+    // A case names a control by `testId` wherever a command takes a target (`wait` calls its own `what`).
+    if ('testId' in given && !('target' in given) && !('testId' in (command.flags ?? {})) && positionals.some((p) => p.name === 'target' || p.name === 'what')) {
+        given.target = `#${String(given.testId)}`;
+        delete given.testId;
+    }
     // A case says `target` or `request` where a command may call its first argument something else.
     const first = positionals[0]?.name;
     for (const alias of ['target', 'request', 'route', 'url', 'state', 'text']) {
@@ -107,7 +117,7 @@ export const argvFor = (command, value) => {
 const presented = (screen) => screen.elements.filter((e) => !e.hidden || e.hidden === 'inert');
 const textOf = (e) => e.text ?? e.value ?? e.accessibilityLabel ?? '';
 const requestMatches = (event, wanted, status) => {
-    if (event.kind !== 'request')
+    if (event.status === undefined)
         return false;
     const [method, route] = wanted.includes(' ') ? wanted.split(/\s+/, 2) : ['*', wanted];
     let pathname = event.url;
@@ -123,6 +133,8 @@ const requestMatches = (event, wanted, status) => {
         return false;
     return status === undefined ? true : event.status === status;
 };
+// Steps that look at the app rather than act on it: a request they wait for was caused by the action before them.
+const LOOKING = new Set(['see', 'wait', 'event', 'requests', 'events']);
 const BUILT_IN = ['press', 'type', 'swipe', 'see', 'requests', 'wait', 'nav', 'call', 'run', 'events', 'event'];
 const unknownStep = (step, config) => {
     if (config.macros?.[step.verb] || !step.verb.startsWith('app.'))
@@ -141,15 +153,35 @@ const unknownStep = (step, config) => {
     }
     return undefined;
 };
+/**
+ * The fixtures a case names that the project's server did not list. A macro's
+ * own steps are the project's to keep right; these are the ones written in the case.
+ */
+export const missingFixtures = (c, config, known) => {
+    const names = [...c.setup, ...c.steps].flatMap((step) => {
+        if (step.verb.startsWith('app.') || config.macros?.[step.verb] || step.verb === 'exec')
+            return [];
+        return [step.verb === 'assert' ? (config.inspect ?? 'inspect') : step.verb];
+    });
+    return [...new Set(names)].filter((name) => !known.includes(name));
+};
+/** What the app or its host answers to a method it does not have; the name is what it lacks. */
+export const lacking = (message) => /Unknown method (\S+)/.exec(message)?.[1];
 export const runCase = async (c, options) => {
     const { base, config } = options;
     const log = options.log ?? (() => undefined);
-    const scope = {};
-    const ran = new Set();
-    const latest = {};
+    const scope = structuredClone(options.prepared?.scope ?? {});
+    seeded(scope, c.id);
+    const ran = new Set(options.prepared?.ran ?? []);
+    const latest = structuredClone(options.prepared?.latest ?? {});
     const started = Date.now();
     const steps = [];
     let mark;
+    // The app numbers its requests as they start. A step that looks for one counts only those started after the
+    // action before it began: an earlier screen's request to the same path would otherwise pass for the one the
+    // action caused. `app.requests` marks by hand, and holds until a step has looked for a request.
+    let requestsAfter;
+    let markedByHand = false;
     let why;
     const recorded = [];
     let buffer = [];
@@ -167,7 +199,21 @@ export const runCase = async (c, options) => {
         buffer = now;
     };
     const device = () => base.device();
-    const sinceMark = async () => (await (await device()).trace(mark)).events;
+    const lastRequest = async (d) => Math.max(0, ...(await d.requests()).requests.map((r) => r.id));
+    const markRequests = async (d, byHand = false) => {
+        if (markedByHand && !byHand)
+            return;
+        requestsAfter = await lastRequest(d);
+        markedByHand = byHand;
+    };
+    const requestsSinceMark = async () => {
+        const d = await device();
+        const { requests } = await d.requests(requestsAfter);
+        // An app started again numbers its requests from 1.
+        if (requests.length === 0 && requestsAfter && (await lastRequest(d)) < requestsAfter)
+            requestsAfter = 0;
+        return requests;
+    };
     const cli = async (argv) => {
         const outcome = await execute(argv, base);
         if (outcome.error || outcome.code !== 0) {
@@ -207,6 +253,8 @@ export const runCase = async (c, options) => {
             if (answer[field] !== undefined)
                 latest[field] = answer[field];
     };
+    // What the backend answered, until a step that can change it.
+    const inspected = new Map();
     const assert = async (value) => {
         const params = (value ?? {});
         const matcher = matcherOf(params);
@@ -215,7 +263,15 @@ export const runCase = async (c, options) => {
         if (!options.fixtures)
             throw new Error('assert reads the backend through fixtures, and the project declares none');
         const rest = Object.fromEntries(Object.entries(params).filter(([k]) => k !== 'path' && !(k in matcher)));
-        const answer = await options.fixtures.call(config.inspect ?? 'inspect', withRefs(rest));
+        // `section` is the part of the answer the path reads: a server that works its answer out part by part
+        // need only do that part. Asserts in a row on the same section read one answer.
+        const ask = withRefs({ ...rest, section: params.path.split('.')[0] });
+        const key = JSON.stringify(ask);
+        let answer = inspected.get(key);
+        if (!answer) {
+            answer = await options.fixtures.call(config.inspect ?? 'inspect', ask);
+            inspected.set(key, answer);
+        }
         const got = dig(answer, params.path);
         if (!matches(got, matcher))
             throw new Error(`${params.path} is ${JSON.stringify(got)}`);
@@ -252,8 +308,9 @@ export const runCase = async (c, options) => {
             return `not on screen: ${JSON.stringify(text)}`;
         if (typeof params.request === 'string') {
             const status = typeof params.status === 'number' ? params.status : undefined;
-            if (!(await sinceMark()).some((e) => requestMatches(e, params.request, status)))
-                return `not requested since the mark: ${params.request}`;
+            if (!(await requestsSinceMark()).some((e) => requestMatches(e, params.request, status)))
+                return `not requested since ${markedByHand ? 'the mark' : 'the step before began'}: ${params.request}`;
+            markedByHand = false;
         }
         if (typeof params.event === 'string') {
             const wanted = (params.props ?? params.properties ?? {});
@@ -264,17 +321,68 @@ export const runCase = async (c, options) => {
         }
         return undefined;
     };
+    /**
+     * A device, and a host that draws like one, lists what is in the window: what
+     * a step looks for may be further down the page. This scrolls the window
+     * itself, most of a screenful at a time, until `there` holds or the screen
+     * stops changing; then back up in short pulls (at the top of a sheet a short
+     * pull springs back, where a long one would drag the sheet shut).
+     */
+    const scrollTo = async (there, upward = false) => {
+        const d = await device();
+        if (!d.server.hello?.native)
+            return false;
+        const { w, h } = (await d.screen()).window;
+        const x = Math.round(w / 2);
+        const listing = async () => JSON.stringify(presented(await d.screen()).map((e) => [e.testId, textOf(e), Math.round(e.frame.y)]));
+        const pull = async (from, to, times) => {
+            let before;
+            for (let i = 0; i < times; i++) {
+                if (await there())
+                    return true;
+                const now = await listing();
+                if (now === before)
+                    return false;
+                before = now;
+                await execute(['swipe', '--from', `${x},${from}`, '--to', `${x},${to}`], base);
+                await d.idle({ quietMs: 150, timeoutMs: 1500 }).catch(() => undefined);
+            }
+            return there();
+        };
+        if (!upward && (await pull(Math.round(h * 0.75), Math.round(h * 0.3), 12)))
+            return true;
+        const middle = Math.round(h * 0.5);
+        return pull(middle, middle + 110, 30);
+    };
     const see = async (value) => {
         const params = typeof value === 'string' ? { target: value } : (value ?? {});
         const absent = params.absent === true;
         const wait = typeof params.timeoutMs === 'number' ? params.timeoutMs : 3000;
         const deadline = Date.now() + wait;
         const hard = Date.now() + Math.max(wait, 12_000);
+        // Where the listing is what the window shows, something missing gets three more looks before the
+        // deadline counts: a short wait (it may be arriving), a scroll (it may be further down), and a long
+        // wait (a carousel shows it a few seconds from now, and a host with its own clock gets there fast).
+        const what = targetIn(params) ?? (typeof params.text === 'string' ? { text: params.text } : undefined);
+        let looks = absent || !what || !(await device()).server.hello?.native ? 3 : 0;
         while (true) {
             await interrupted(value);
             const missing = await seen(params);
             if (absent ? missing !== undefined : missing === undefined)
                 return;
+            if (looks < 3 && what && missing?.startsWith('not on screen')) {
+                const d = await device();
+                looks += 1;
+                if (looks === 1)
+                    await d.waitFor({ target: what, timeoutMs: 1500 }).catch(() => undefined);
+                else if (looks === 2) {
+                    if (await scrollTo(async () => (await seen(params)) === undefined))
+                        return;
+                }
+                else
+                    await d.waitFor({ target: what, timeoutMs: 20_000 }).catch(() => undefined);
+                continue;
+            }
             if (Date.now() > deadline && Date.now() < hard && (await (await device()).screen()).busy) {
                 await sleep(150);
                 continue;
@@ -289,36 +397,75 @@ export const runCase = async (c, options) => {
         const deadline = Date.now() + timeoutMs;
         const status = typeof params.status === 'number' ? params.status : undefined;
         while (true) {
-            const events = await sinceMark();
-            const hit = events.some((e) => requestMatches(e, String(params.request), status) && (status !== undefined || (e.kind === 'request' && String(e.status).startsWith('2'))));
-            if (hit)
+            const events = await requestsSinceMark();
+            const hit = events.some((e) => requestMatches(e, String(params.request), status) && (status !== undefined || String(e.status).startsWith('2')));
+            if (hit) {
+                markedByHand = false;
                 return;
+            }
             if (Date.now() > deadline)
                 throw new Error(`no ${status ?? '2xx'} ${String(params.request)} within ${timeoutMs} ms`);
             await sleep(300);
         }
     };
     const press = async (value) => {
-        const params = typeof value === 'string' ? { target: value } : (value ?? {});
+        const given = typeof value === 'string' ? { target: value } : (value ?? {});
+        const { text, ...named } = given;
+        const params = 'target' in given || 'testId' in given || typeof text !== 'string' ? given : { ...named, target: text };
         const target = targetIn(params);
         if (!target)
             throw new Error('app.press needs a target');
         const d = await device();
         if (params.optional === true) {
+            // Decided once the app has gone quiet: what it presses (a one-time question, a promo) arrives a moment
+            // after the screen before it, and a fast host gets here first.
+            await d.idle({ quietMs: 150, timeoutMs: 1000 }).catch(() => undefined);
             const there = await d.waitFor({ target, timeoutMs: 300 }).then(() => true, () => false);
             if (!there)
                 return 'skipped';
         }
-        // The control may still be arriving, or disabled while what it depends on loads.
+        // Not listed at all: arriving, or further down a page that only lists its window. A short wait, then
+        // a scroll, rather than spending the whole deadline on something that is below the fold.
+        const listed = async () => !!(await d.server.call('find', target));
+        if (!(await listed())) {
+            await d.waitFor({ target, timeoutMs: 500 }).catch(() => undefined);
+            if (!(await listed()))
+                await scrollTo(listed);
+        }
+        // Listed, but scrolled out of the window, cut by its edge or under the header or tab bar (a page left
+        // further down than the control): towards it, until it is clear.
+        const outside = async () => {
+            const found = (await d.server.call('find', target));
+            if (!found)
+                return undefined;
+            const { h } = (await d.screen()).window;
+            // Covered near an edge is the screen's own header or tab bar over a scrolled page, not an overlay.
+            const top = found.frame.y, bottom = found.frame.y + found.frame.h;
+            if (top < 0 || (found.covered && top < h * 0.2))
+                return 'above';
+            if (bottom > h || (found.covered && bottom > h * 0.8))
+                return 'below';
+            return undefined;
+        };
+        const side = await outside();
+        if (side)
+            await scrollTo(async () => (await outside()) === undefined, side === 'above');
+        // The control may still be disabled while what it depends on loads. The waits go through the app,
+        // so a host with its own clock moves it on instead of standing still while this one sleeps.
         const deadline = Date.now() + (typeof params.timeoutMs === 'number' ? params.timeoutMs : 3000);
         const hard = Date.now() + 15_000;
+        let was;
         while (Date.now() < hard && 'testId' in target) {
             const found = (await d.server.call('find', target));
-            if (found?.enabled)
+            // Covered or still moving is often for a moment (a screen or button sliding in, a sheet still
+            // closing), and a press then lands on whatever covers it or where the control no longer is.
+            const at = found ? JSON.stringify(found.frame) : undefined;
+            if (found?.enabled && !found.covered && at === was)
                 break;
+            was = at;
             if (Date.now() > deadline && !(await d.screen()).busy)
                 break;
-            await sleep(200);
+            await d.idle({ quietMs: 50, timeoutMs: 200 }).catch(() => undefined);
         }
         const { optional: _optional, timeoutMs: _timeout, ...rest } = params;
         await cli(argvFor(find('press'), rest));
@@ -345,14 +492,10 @@ export const runCase = async (c, options) => {
             await sleep(250);
         }
     };
-    // Nobody acts on a screen that is still asking for what it shows: a press
-    // that lands before the data does is a different case from the one written.
-    const ready = async () => {
-        const d = await device();
-        const deadline = Date.now() + 5000;
-        while ((await d.screen()).busy && Date.now() < deadline)
-            await sleep(100);
-    };
+    // A host that keeps its own clock lets an animation finish before it answers. A phone runs on the
+    // wall's and keeps moving after the last render, so only there is a pause worth its time; and a case's
+    // `on: device` steps are written for that phone.
+    const onWallClock = (d) => !!d.server.hello?.native && !d.server.hello.commands?.includes('clock');
     let handling = false;
     const interrupted = async (value) => {
         if (handling || !config.interruptions?.length)
@@ -385,29 +528,40 @@ export const runCase = async (c, options) => {
         const params = value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
         const d = await device();
         mark ??= (await d.trace()).last;
+        // An interruption handled inside a wait is not the action the wait is about.
+        if ((!LOOKING.has(name) && !handling && macroDepth === 0) || requestsAfter === undefined)
+            await markRequests(d);
         switch (name) {
             case 'press': {
                 await interrupted(value);
-                await ready();
                 const outcome = await press(value);
                 // One touch, one render: the next step reads what this one caused.
                 await d.idle({ quietMs: 50, timeoutMs: 400 }).catch(() => undefined);
                 return outcome;
             }
             case 'type':
-            case 'swipe':
+            case 'swipe': {
                 await interrupted(value);
-                await ready();
-                await cli(argvFor(find(name), value));
+                // A field that arrives with its screen (a code input that mounts a moment after the keyboard) takes
+                // what is typed only once it is there: under load that moment is longer than the step's own wait.
+                const field = name === 'type' && params ? targetIn(params) : undefined;
+                if (field) {
+                    await d.waitFor({ target: field, timeoutMs: typeof params?.timeoutMs === 'number' ? params.timeoutMs : 5000 }).catch(() => undefined);
+                    await d.idle({ quietMs: 100, timeoutMs: 800 }).catch(() => undefined);
+                }
+                const { timeoutMs: _timeout, ...typed } = params ?? {};
+                await cli(argvFor(find(name), name === 'type' && params ? typed : value));
                 // A pager on a device keeps moving after the finger lifts, and swallows a swipe sent into that momentum.
-                if (name === 'swipe' && d.server.hello?.native)
+                if (name === 'swipe' && onWallClock(d))
                     await d.idle({ quietMs: 700, timeoutMs: 8000 }).catch(() => undefined);
                 return undefined;
+            }
             case 'see':
                 await see(value);
                 return undefined;
             case 'requests':
                 mark = (await d.trace()).last;
+                await markRequests(d, true);
                 return undefined;
             case 'wait': {
                 if (typeof value === 'number' || (typeof value === 'string' && /^\d+$/.test(value)))
@@ -434,7 +588,7 @@ export const runCase = async (c, options) => {
                         await cli(argvFor(find('wait'), value));
                     // A screen that just arrived on a device is still sliding in, which no render shows: a press then lands on the one it left.
                     const what = typeof value === 'string' ? value : String(params?.what ?? '');
-                    if (d.server.hello?.native && isRoute(what))
+                    if (onWallClock(d) && isRoute(what))
                         await d.idle({ quietMs: 700, timeoutMs: 8000 }).catch(() => undefined);
                 }
                 return undefined;
@@ -481,7 +635,24 @@ export const runCase = async (c, options) => {
         const json = /\{[\s\S]*\}/.exec(stdout)?.[0];
         scope[params.as] = json ? JSON.parse(json) : { out: stdout.trim() };
     };
+    // A macro is one step of the case: the requests it waits for are the ones it set off, from its first
+    // action on, not only those of its last (`app.refresh` asks for a refresh, then waits for it to settle).
+    let macroDepth = 0;
     const macro = async (steps, value) => {
+        if (macroDepth === 0 && !handling) {
+            const d = await device().catch(() => undefined);
+            if (d)
+                await markRequests(d);
+        }
+        macroDepth++;
+        try {
+            await runMacro(steps, value);
+        }
+        finally {
+            macroDepth--;
+        }
+    };
+    const runMacro = async (steps, value) => {
         const given = value && typeof value === 'object' && !Array.isArray(value) ? value : { value };
         // A parameter that names an alias is that alias: `as: u` makes `{{param.as.user_id}}` the user's.
         const param = Object.fromEntries(Object.entries(given).map(([k, v]) => [k, typeof v === 'string' && v in scope ? scope[v] : v]));
@@ -508,19 +679,31 @@ export const runCase = async (c, options) => {
             scope.param = outer;
         }
     };
+    /**
+     * `device`, `headless`, a platform, or `has:<command>` for a host whose app
+     * registered that command (a hosted build often has commands a store build
+     * does not); `!` in front turns any of them around. One case then carries the
+     * way each host does a thing, and runs on all of them.
+     */
     const runsHere = async (on) => {
+        if (on.startsWith('!'))
+            return !(await runsHere(on.slice(1)));
         const hello = (await device()).server.hello;
-        const native = !!hello?.native;
+        const phone = onWallClock(await device());
         if (on === 'device')
-            return native;
+            return phone;
         if (on === 'headless')
-            return !native;
+            return !phone;
+        if (on.startsWith('has:'))
+            return !!hello?.commands?.includes(on.slice(4));
         return hello?.platform === on;
     };
     const perform = async (step) => {
         if (step.on && !(await runsHere(step.on)))
             return 'skipped';
         ran.add(step.verb);
+        if (!['assert', 'app.see', 'app.wait'].includes(step.verb))
+            inspected.clear();
         const value = interpolate(step.value, scope);
         const custom = config.macros?.[step.verb];
         if (custom) {
@@ -540,10 +723,100 @@ export const runCase = async (c, options) => {
         if (d?.server.connected)
             buffer = normalizeEvents(await d.command('events').catch(() => []));
     }
+    const evidence = options.dry ? undefined : options.evidence;
+    const offers = async (command) => !!(await base.device().catch(() => undefined))?.server.hello?.commands?.includes(command);
+    const film = evidence?.video && (await offers('record')) ? path.join(evidence.dir, 'video.mp4') : undefined;
+    // Asked only when the run keeps events: it is a call per step.
+    const capturing = !options.dry && !!options.events && (await offers('analytics'));
+    if (evidence)
+        fs.mkdirSync(evidence.dir, { recursive: true });
+    let filming = false;
+    if (film && evidence?.video) {
+        const d = await device();
+        filming = await d.command('record', { path: film, fps: evidence.video.fps }).then(() => true, () => false);
+    }
+    // What the app sent before the case began is not the case's.
+    if (capturing)
+        await (await device()).command('analytics', { take: true }).catch(() => undefined);
+    const frameAt = async () => {
+        if (!filming || !evidence?.video)
+            return undefined;
+        const answer = (await (await device()).command('record', { frames: true }).catch(() => undefined));
+        return typeof answer?.frames === 'number' ? Math.round((answer.frames / evidence.video.fps) * 100) / 100 : undefined;
+    };
+    // What a step leaves for a report: the frame after it and what it sent. Nothing here may fail the case.
+    const record = async (report, index, startedAt) => {
+        if (startedAt !== undefined)
+            report.videoS = startedAt;
+        const d = await device().catch(() => undefined);
+        if (!d?.server.connected)
+            return;
+        if (capturing) {
+            const raw = (await d.command('analytics', { take: true }).catch(() => []));
+            const sent = (Array.isArray(raw) ? raw : []).flatMap((e) => e?.name ? [{ provider: String(e.sdk ?? 'unknown'), name: String(e.name), ...(e.properties ? { props: e.properties } : {}) }] : []);
+            if (sent.length > 0)
+                report.sent = sent;
+        }
+        if (evidence?.screenshots) {
+            // A step may end mid-transition (a screen fading in, the splash fading out): the frame is of where the
+            // step left the app, so two runs' frames of the same step show the same screen.
+            // Long enough for what arrives after a short delay; a screen that never settles (an animation that
+            // keeps going) is noted as such, and its frame is of a moment, not of a state.
+            const settled = await d.idle({ quietMs: 700, timeoutMs: 3000 }).then((r) => r.idle, () => false);
+            const file = path.join(evidence.dir, `${String(index).padStart(2, '0')}-${report.step
+                .toLowerCase()
+                .replace(/[^a-z0-9]+/g, '-')
+                .slice(0, 48)
+                .replace(/^-|-$/g, '')}.png`);
+            // A host on another machine writes the file there; `inline` asks it for the picture as well.
+            // A host that knows what was still animating says so, as frames in points.
+            let moving;
+            const taken = (await offers('screenshot'))
+                ? await d.command('screenshot', { path: file, inline: true }).then((answer) => {
+                    const { png, moving: animating } = (answer ?? {});
+                    if (typeof png === 'string' && !fs.existsSync(file))
+                        fs.writeFileSync(file, Buffer.from(png, 'base64'));
+                    if (Array.isArray(animating))
+                        moving = animating;
+                    return true;
+                }, () => false)
+                : (await execute(['screenshot', file], base)).code === 0;
+            if (taken && fs.existsSync(file)) {
+                report.screenshot = file;
+                // What each pixel shows: comparing two runs' frames needs to tell the data they were given (a name,
+                // a balance) from how it was drawn.
+                const screen = await d.screen().catch(() => undefined);
+                if (screen)
+                    fs.writeFileSync(file.replace(/\.png$/, '.json'), JSON.stringify({ ...screen, settled, ...(moving ? { moving } : {}) }));
+            }
+        }
+    };
     let failed = false;
-    for (const step of [...c.setup, ...c.steps]) {
+    // A setup that failed leaves the steps nothing to stand on, with or without `continue`.
+    let setupFailed = false;
+    let unsupported = false;
+    let routesFrom;
+    // The screen a reused app was left on: a reset reports it once more before the case's own screens.
+    let routesStale;
+    if (options.prepared) {
+        steps.push(...options.prepared.steps);
+        log(`  ⚡ setup made ahead (${options.prepared.steps.length} steps)`);
+    }
+    // What native SDKs answer in this case starts as the config says, whatever the last case on this app set.
+    if (config.nativeMocks && !options.setupOnly && !options.dry) {
+        const d = await device().catch(() => undefined);
+        await d?.command('nativeMocks', { replace: config.nativeMocks }).catch(() => undefined);
+    }
+    // Each app step gets a span id the host puts in the `traceparent` of every request the app sends while it
+    // runs; a backend that exports traces to the run files what it did under that step.
+    const tracing = options.traces && !options.dry && !options.setupOnly && (await offers('traceContext'))
+        ? { traceId: newTraceId(), steps: new Map() }
+        : undefined;
+    const todo = options.setupOnly ? c.setup : options.prepared ? c.steps : [...c.setup, ...c.steps];
+    const setupLength = todo === c.steps ? 0 : c.setup.length;
+    for (const [index, step] of todo.entries()) {
         const text = label(step);
-        if (failed) {
+        if (unsupported || setupFailed || (failed && !options.continue)) {
             steps.push({ step: text, status: 'skipped', ms: 0 });
             continue;
         }
@@ -555,27 +828,95 @@ export const runCase = async (c, options) => {
             continue;
         }
         const t0 = Date.now();
+        // Where the app's trace stood before the case first touched it: the screens after it are the case's.
+        if (options.routes && routesFrom === undefined && (step.verb.startsWith('app.') || config.macros?.[step.verb])) {
+            const d = await device().catch(() => undefined);
+            routesFrom = await d?.trace().then((t) => t.last, () => undefined);
+            // An app started for this case begins where it begins; one reused from a case before was left elsewhere.
+            if (options.routes !== 'fresh')
+                routesStale = await d?.screen().then((sc) => sc.route, () => undefined);
+        }
+        const at = step.verb.startsWith('app.') || config.macros?.[step.verb] ? await frameAt() : undefined;
+        if (tracing && (step.verb.startsWith('app.') || config.macros?.[step.verb])) {
+            const spanId = newSpanId();
+            tracing.steps.set(spanId, { index: steps.length, startedMs: t0 });
+            await (await device()).command('traceContext', { traceparent: traceparent(tracing.traceId, spanId) }).catch(() => undefined);
+        }
         try {
             const outcome = await perform(step);
             if (step.verb.startsWith('app.') || config.macros?.[step.verb])
                 await collect(steps.length + 1);
-            steps.push({ step: text, status: outcome === 'skipped' ? 'skipped' : 'passed', ms: Date.now() - t0 });
+            const done = { step: text, status: outcome === 'skipped' ? 'skipped' : 'passed', ms: Date.now() - t0 };
+            steps.push(done);
             log(`  ${outcome === 'skipped' ? '⏭️' : '✅'} ${text}  (${Date.now() - t0}ms)`);
+            if ((evidence || capturing) && outcome !== 'skipped' && (step.verb.startsWith('app.') || config.macros?.[step.verb]))
+                await record(done, steps.length, at);
         }
         catch (error) {
-            failed = true;
             const message = error instanceof Error ? error.message : String(error);
-            steps.push({ step: text, status: 'failed', ms: Date.now() - t0, error: message });
+            const missing = lacking(message);
+            if (missing) {
+                // Not the app's doing: the rest of the case would be standing on a step that never happened.
+                unsupported = true;
+                steps.push({ step: text, status: 'unsupported', ms: Date.now() - t0, error: `this host has no ${missing}` });
+                log(`  🚫 ${text}  — this host has no ${missing}`);
+                continue;
+            }
+            failed = true;
+            if (index < setupLength)
+                setupFailed = true;
+            const broke = { step: text, status: 'failed', ms: Date.now() - t0, error: message };
+            steps.push(broke);
             log(`  ❌ ${text}  — ${message.split('\n')[0]}  (${Date.now() - t0}ms)`);
+            if (evidence || capturing)
+                await record(broke, steps.length, at);
+        }
+    }
+    if (tracing && options.traces) {
+        await (await device().catch(() => undefined))?.command('traceContext', { traceparent: null }).catch(() => undefined);
+        // A backend exports in batches, a moment after the requests it served.
+        await options.traces.settle(tracing.traceId);
+        for (const [index, spans] of options.traces.take(tracing.traceId, tracing.steps)) {
+            const s = steps[index];
+            // A step that set off thousands of queries keeps the first ones; a report is not a profiler.
+            if (s)
+                s.backend = spans.slice(0, 400);
         }
     }
+    if (options.setupOnly && !failed)
+        options.setupOnly.keep({ scope, latest, ran: [...ran], steps });
     if (options.dry)
         failed = steps.some((s) => s.status === 'failed');
-    const report = { id: c.id, title: c.title, file: c.file, result: failed ? 'failed' : 'passed', ms: Date.now() - started, steps };
+    const report = {
+        id: c.id,
+        title: c.title,
+        file: c.file,
+        result: failed ? 'failed' : unsupported ? 'unsupported' : 'passed',
+        ms: Date.now() - started,
+        steps,
+    };
     if (options.events)
         report.events = recorded;
-    if (failed && !options.dry) {
+    if (routesFrom !== undefined) {
+        const events = await device()
+            .then((d) => d.trace(routesFrom))
+            .then((t) => t.events)
+            .catch(() => []);
+        const walked = events.flatMap((e) => (e.kind === 'route' && e.route ? [e.route] : []));
+        while (walked.length > 0 && walked[0] === routesStale)
+            walked.shift();
+        report.routes = [...new Set(walked)].sort();
+    }
+    if (filming) {
+        await (await device()).command('record', { stop: true }).catch(() => undefined);
+        if (film && fs.existsSync(film))
+            report.video = film;
+    }
+    if (failed && !options.dry && !options.setupOnly) {
         const d = await device().catch(() => undefined);
+        // A step that failed on its own reading of the screen left no reasons; ask for them.
+        if (!why && d?.server.connected)
+            why = (await execute(['why'], base).catch(() => undefined))?.text || undefined;
         if (d?.server.connected) {
             const screen = await d.screen().catch(() => undefined);
             const events = await d.trace(mark).catch(() => undefined);
@@ -585,6 +926,12 @@ export const runCase = async (c, options) => {
                 why,
             };
         }
+        const reasons = (why ?? '')
+            .split('\n')
+            .map((l) => l.replace(/^\s*•\s*/, '').trim())
+            .filter((l) => l.length > 0);
+        if (reasons.length > 0)
+            report.diagnosis = reasons;
     }
     return report;
 };