lynkeus 0.3.0 → 0.5.0

package/src/cases/runner.ts

@@ -12,11 +12,13 @@ import { promisify } from 'node:util';
 import type { Element, RequestRecord, Screen, Target } from 'lynkeus-protocol';
 
 import { type Device, describeScreen } from '../device/driver.js';
+import { trafficEvents } from '../knowledge/analyticsTraffic.js';
 import { type AppEvent, normalizeEvents, type RunEvent } from '../knowledge/events.js';
 import { type Base, type Command, find } from '../registry.js';
 import { execute } from '../runtime.js';
 import { isRoute, parseTarget, scopedTarget } from '../targets.js';
 import type { Fixtures, FixturesConfig } from './fixtures.js';
+import { compactFrame } from './frames.js';
 import { type BackendSpan, newSpanId, newTraceId, type TraceSink, traceparent } from './traces.js';
 import { type Case, dig, interpolate, matcherOf, matches, type Scope, seeded, type Step, stepOf, type StepValue } from './format.js';
 
@@ -47,13 +49,24 @@ export type CasesConfig = {
   /** `{ "user": "user_id" }` turns `user: u` into `user_id: <u.user_id>`, and gives a step that names no user the latest one. */
   refs?: Record<string, string>;
   /** Steps this project adds: `{ "app.login": [...] }`. Inside, `{{param.x}}` is what the case passed. */
+  /** The screen a case begins on, for drafts (`case new`): the first the app shows a signed-in person, say. */
+  start?: string;
   macros?: Record<string, unknown[]>;
   /** What the app may put in the way of a step and the steps that get past it; a step whose own words match `unless` is about it, and is left alone. */
   interruptions?: { see: string; do: unknown[]; unless?: string }[];
+  /**
+   * What the backend told its own analytics while a step ran, for a report: after each app step the fixture is
+   * asked with `{ since }` (the step's start, ISO) and answers `{ events: [{ name | event, props | payload,
+   * provider? }] }`. `provider` names the service when the fixture does not (an Olympus that sends to Mixpanel).
+   */
+  serverEvents?: { fixture: string; provider?: string };
+  /** The service the app's own event list feeds (its `events` command), so a report names it instead of "App". */
+  appEvents?: { provider: string };
 };
 
 /** What a host's analytics capture saw a step send: the SDK it went to and the event. */
-export type SentEvent = { provider: string; name: string; props?: Record<string, unknown> };
+/** `via`: the SDK's native module (a host that stands in for it), the request it sent, or the backend's own analytics. */
+export type SentEvent = { provider: string; name: string; props?: Record<string, unknown>; via?: 'sdk' | 'network' | 'server' };
 
 /** `unsupported`: the host the case ran on has no such thing to do (a real device has no mocked responses), which says nothing about the app. */
 export type StepReport = {
@@ -69,7 +82,14 @@ export type StepReport = {
   sent?: SentEvent[];
   /** What the backend did for it, from the traces it exported to the run. */
   backend?: BackendSpan[];
+  /** The requests the app sent while it ran, with headers and bodies (secrets hidden), when the run keeps evidence. */
+  requests?: RequestRecord[];
+  /** What the app printed while it ran: its console and the errors it did not catch, when the run keeps evidence. */
+  logs?: LogLine[];
 };
+
+/** A line the app printed: `at` in ms since the epoch, `source` where it came from (`js`, `native`, `host`). */
+export type LogLine = { at: number; level: 'debug' | 'info' | 'warn' | 'error'; source: string; text: string; stack?: string };
 export type CaseReport = {
   id: string;
   title?: string;
@@ -78,6 +98,11 @@ export type CaseReport = {
   result: 'passed' | 'failed' | 'unsupported';
   ms: number;
   steps: StepReport[];
+  /**
+   * What a reader needs before the steps: what the case proves (`description`), why it matters (`why`), what
+   * has to be true when it starts (`given`), the ticket it covers and the outcome it expects. From its frontmatter.
+   */
+  about?: { description?: string; why?: string; given?: string; ticket?: string; expected?: string };
   /** When a step failed: the screen, the requests since the mark, and why. */
   evidence?: { screen?: string; requests?: string[]; why?: string };
   /** What the app told its analytics, each with the step that caused it, when the run asked for it. */
@@ -91,7 +116,22 @@ export type CaseReport = {
 };
 
 /** Where a case keeps what it can show of itself: a frame per step, a film. Each is taken only where the host can. */
-export type Evidence = { dir: string; screenshots?: boolean; video?: { fps: number } };
+/** `frames`: AVIF where the host writes it (a fifth of a PNG's bytes, lossy), or PNG, exact, for frames two runs are compared by. */
+export type Evidence = {
+  dir: string;
+  screenshots?: boolean;
+  settleMs?: number;
+  /** Wait for the screen to stand still: two frames alike this many ms apart, on a host's own clock where it offers
+   * that (`still`), or taken again on a device. */
+  stillMs?: number;
+  /** A looking step on an unchanged screen shares the last frame instead of taking one. */
+  onChange?: boolean;
+  frames?: 'avif' | 'png';
+  video?: { fps: number; scale?: number };
+};
+
+// A host that could not write AVIF once (an older one) is asked for PNG from then on.
+let avifRefused = false;
 
 export type RunOptions = {
   base: Base;
@@ -110,7 +150,8 @@ export type RunOptions = {
   /** Keep running a case's steps after one fails, to see everything that is wrong in one pass. */
   continue?: boolean;
   /** Collect the screens the app went through, for a coverage map. `fresh`: the app was started for this case. */
-  routes?: boolean | 'fresh';
+  routes?: boolean | 'fresh' /** The app's native log on a simulator or an emulator, read step by step into each step's logs. */;
+  nativeLogs?: { take: () => LogLine[] };
 };
 
 /** What a case's setup leaves for its steps: the aliases and what they answered, and what ran. */
@@ -224,6 +265,20 @@ const requestMatches = (event: RequestRecord, wanted: string, status?: number):
   return status === undefined ? true : event.status === status;
 };
 
+const aboutOf = (c: Case): { about?: CaseReport['about'] } => {
+  const text = (v: unknown) => (typeof v === 'string' && v.trim() ? v.trim() : undefined);
+  const about = Object.fromEntries(
+    Object.entries({
+      description: text(c.meta.description),
+      why: text(c.meta.why),
+      given: text(c.meta.given),
+      ticket: text(c.meta.ticket),
+      expected: c.expected,
+    }).filter(([, v]) => v !== undefined),
+  );
+  return Object.keys(about).length ? { about } : {};
+};
+
 // 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']);
 
@@ -258,6 +313,48 @@ export const missingFixtures = (c: Case, config: CasesConfig, known: string[]):
 /** What the app or its host answers to a method it does not have; the name is what it lacks. */
 export const lacking = (message: string): string | undefined => /Unknown method (\S+)/.exec(message)?.[1];
 
+// A request is read from the app at the end of the step after the one that sent it when it leaves at the very
+// end of a step (a GET the app sends as an action finishes): its trace, carrying the step it left in, says where
+// it belongs. Each request without a trace in its own step moves to the step whose trace served the same method
+// and path at the same moment.
+export const fileRequestsByTrace = (steps: StepReport[], spans: Map<string, { index: number; startedMs: number }>) => {
+  const started = new Map([...spans.values()].map((v) => [v.index, v.startedMs]));
+  const pathOf = (u: unknown) => {
+    try {
+      return new URL(String(u)).pathname;
+    } catch {
+      return String(u ?? '').split('?')[0]!;
+    }
+  };
+  const roots = steps.flatMap((st, index) =>
+    (st.backend ?? [])
+      .filter((sp) => sp.depth === 0)
+      .map((sp) => ({
+        index,
+        method: String(sp.attributes?.['http.method'] ?? sp.attributes?.['http.request.method'] ?? '').toUpperCase(),
+        path: pathOf(sp.attributes?.['http.target'] ?? sp.attributes?.['url.path'] ?? ''),
+        at: (started.get(index) ?? 0) + sp.at,
+      })),
+  );
+  if (!roots.length) return;
+  steps.forEach((st, index) => {
+    const keep: RequestRecord[] = [];
+    for (const q of st.requests ?? []) {
+      const method = String(q.method).toUpperCase(),
+        path = pathOf(q.url);
+      const same = roots.filter((r) => r.method === method && r.path === path);
+      const here = same.some((r) => r.index === index);
+      const near = same
+        .filter((r) => typeof q.startedAt === 'number' && Math.abs(r.at - q.startedAt) < 1500)
+        .sort((a, b) => Math.abs(a.at - q.startedAt!) - Math.abs(b.at - q.startedAt!))[0];
+      if (here || !near || near.index === index || !steps[near.index]) keep.push(q);
+      else steps[near.index]!.requests = [...(steps[near.index]!.requests ?? []), q].sort((a, b) => (a.startedAt ?? 0) - (b.startedAt ?? 0));
+    }
+    if (st.requests) st.requests = keep.length ? keep : undefined;
+    if (st.requests === undefined) delete st.requests;
+  });
+};
+
 export const runCase = async (c: Case, options: RunOptions): Promise<CaseReport> => {
   const { base, config } = options;
   const log = options.log ?? (() => undefined);
@@ -268,6 +365,11 @@ export const runCase = async (c: Case, options: RunOptions): Promise<CaseReport>
   const started = Date.now();
   const steps: StepReport[] = [];
   let mark: number | undefined;
+  // Where the trace stood as the last action began: a screen it led to that closes itself (a success screen) can
+  // come and go while that step's frame settles or a wait for a request runs, and a wait for it still counts it.
+  // Waits and looks change nothing, so they keep the mark of the action before them.
+  let actedFrom: number | undefined;
+  let lastFrame: { file: string; shape?: string } | undefined;
   // 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.
@@ -276,14 +378,19 @@ export const runCase = async (c: Case, options: RunOptions): Promise<CaseReport>
   let why: string | undefined;
   const recorded: RunEvent[] = [];
   let buffer: AppEvent[] = [];
+  // A host that records what each SDK was handed (fastsim, the headless host) already has every event. Asking the
+  // app for its own list as well turns on the app's tracking debug, which may draw on the screen (a counter in
+  // every frame of the film).
+  let sdkRecorded = false;
   // Read, never emptied: a case may be asserting on the buffer.
   const collect = async (index: number) => {
-    if (!options.events) return;
+    if (!options.events || sdkRecorded) return;
     const d = await base.device().catch(() => undefined);
     if (!d?.server.connected) return;
     const now = normalizeEvents(await d.command('events').catch(() => []));
     const route = (await d.screen().catch(() => undefined))?.route;
-    for (const e of newSince(buffer, now)) recorded.push({ ...e, step: index, route });
+    const provider = config.appEvents?.provider;
+    for (const e of newSince(buffer, now)) recorded.push({ ...e, step: index, route, ...(provider ? { provider } : {}) });
     buffer = now;
   };
 
@@ -449,15 +556,23 @@ export const runCase = async (c: Case, options: RunOptions): Promise<CaseReport>
         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);
+        } else {
+          // A step that names its own timeout gets no more than what is left of it; one that does not may
+          // wait for a carousel to come round.
+          const long = typeof params.timeoutMs === 'number' ? Math.max(0, deadline - Date.now()) : 20_000;
+          await d.waitFor({ target: what, timeoutMs: long }).catch(() => undefined);
+        }
         continue;
       }
       if (Date.now() > deadline && Date.now() < hard && (await (await device()).screen()).busy) {
         await sleep(150);
         continue;
       }
-      if (Date.now() > deadline)
-        throw new Error(absent ? `still there: ${label({ verb: '', value: { ...params, absent: undefined } as StepValue }).trim()}` : missing!);
+      if (Date.now() > deadline) {
+        if (!absent) throw new Error(missing!);
+        const { absent: _, ...what } = params;
+        throw new Error(`still on screen: ${label({ verb: '', value: what as StepValue }).trim()}`);
+      }
       await sleep(150);
     }
   };
@@ -586,9 +701,16 @@ export const runCase = async (c: Case, options: RunOptions): Promise<CaseReport>
   const app = async (name: string, value: StepValue): Promise<'skipped' | undefined> => {
     const params = value && typeof value === 'object' && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
     const d = await device();
-    mark ??= (await d.trace()).last;
+    // An app in the background has no connection to answer with: the step that brings it back must still run.
+    const lastSeq = () =>
+      d.trace().then(
+        (t) => t.last,
+        () => undefined,
+      );
+    mark ??= await lastSeq();
+    if (!LOOKING.has(name)) actedFrom = await lastSeq();
     // 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);
+    if ((!LOOKING.has(name) && !handling && macroDepth === 0) || requestsAfter === undefined) await markRequests(d).catch(() => undefined);
     switch (name) {
       case 'press': {
         await interrupted(value);
@@ -624,8 +746,10 @@ export const runCase = async (c: Case, options: RunOptions): Promise<CaseReport>
         if (typeof value === 'number' || (typeof value === 'string' && /^\d+$/.test(value))) await sleep(Number(value));
         else if (params?.request) await waitForRequest(params);
         else {
+          const what = typeof value === 'string' ? value : String(params?.what ?? '');
+          const since = isRoute(what) && actedFrom !== undefined ? { since: actedFrom } : {};
           if (config.interruptions?.length) {
-            const asked: Record<string, unknown> = typeof value === 'string' ? { what: value } : { ...(params ?? {}) };
+            const asked: Record<string, unknown> = { ...(typeof value === 'string' ? { what: value } : (params ?? {})), ...since };
             const deadline = Date.now() + (typeof asked.timeoutMs === 'number' ? asked.timeoutMs : 10_000);
             for (;;) {
               await interrupted(value);
@@ -637,9 +761,8 @@ export const runCase = async (c: Case, options: RunOptions): Promise<CaseReport>
                 throw new Error(outcome.error ?? outcome.text ?? 'wait failed');
               }
             }
-          } else await cli(argvFor(find('wait')!, value));
+          } else await cli(argvFor(find('wait')!, 'since' in since ? { ...(typeof value === 'string' ? { what: value } : (params ?? {})), ...since } : 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 (onWallClock(d) && isRoute(what)) await d.idle({ quietMs: 700, timeoutMs: 8000 }).catch(() => undefined);
         }
         return undefined;
@@ -757,79 +880,268 @@ export const runCase = async (c: Case, options: RunOptions): Promise<CaseReport>
 
   if (options.events && !options.dry) {
     const d = await base.device().catch(() => undefined);
-    if (d?.server.connected) buffer = normalizeEvents(await d.command('events').catch(() => []));
+    sdkRecorded = !!d?.server.hello?.commands?.includes('analytics');
+    if (d?.server.connected && !sdkRecorded) buffer = normalizeEvents(await d.command('events').catch(() => []));
   }
 
   const evidence = options.dry ? undefined : options.evidence;
   const offers = async (command: string) => !!(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'));
+  // Asked when the run keeps events or a report: it is a call per step.
+  const capturing = !options.dry && (!!options.events || !!options.evidence) && (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(
+    // A host that films at one size only ignores the scale.
+    filming = await d.command('record', { path: film, fps: evidence.video.fps, ...(evidence.video.scale ? { scale: evidence.video.scale } : {}) }).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);
+  // The same for what it printed.
+  const logging = !!evidence && (await offers('logs'));
+  if (logging) await (await device()).command('logs', { take: true }).catch(() => undefined);
+  options.nativeLogs?.take();
+  // A report shows what each request sent and got: the app keeps headers and bodies only while this case runs.
+  let requestsSeen: number | undefined;
+  // Requests filed while still waiting for an answer: read again later and completed where they were filed.
+  const inFlight = new Map<number, RequestRecord>();
+  const answered = (r: RequestRecord) => r.status !== undefined || !!r.error;
+  const completeInFlight = async (d: Device) => {
+    if (!inFlight.size) return;
+    const again = await d.requests(Math.min(...inFlight.keys()) - 1).then(
+      (r) => r.requests,
+      () => [],
+    );
+    for (const r of again) {
+      const kept = inFlight.get(r.id);
+      if (kept && answered(r)) {
+        Object.assign(kept, r);
+        inFlight.delete(r.id);
+      }
+    }
+  };
+  // Frames the host is still encoding: the case waits for them before it says it is done.
+  const encoding: string[] = [];
+  // Frames a simulator or emulator gave as PNG, being encoded again as AVIF while the case goes on.
+  const compacting: Promise<void>[] = [];
+  if (evidence && (await offers('networkBodies'))) {
+    const d = await device();
+    await d.command('networkBodies', { on: true }).catch(() => undefined);
+    requestsSeen = await d.requests().then(
+      (r) => r.requests.at(-1)?.id ?? 0,
+      () => undefined,
+    );
+  }
   const frameAt = async (): Promise<number | undefined> => {
     if (!filming || !evidence?.video) return undefined;
     const answer = (await (await device()).command('record', { frames: true }).catch(() => undefined)) as { frames?: number } | 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: StepReport, index: number, startedAt: number | undefined) => {
+  const record = async (report: StepReport, index: number, startedAt: number | undefined, begunMs: number) => {
     if (startedAt !== undefined) report.videoS = startedAt;
+    if (config.serverEvents && options.fixtures) {
+      const { fixture: name, provider } = config.serverEvents;
+      const answer = await options.fixtures.call(name, { since: new Date(begunMs).toISOString() }).catch(() => undefined);
+      const list = Array.isArray(answer?.events) ? (answer.events as Record<string, unknown>[]) : [];
+      const server = list.flatMap((e) => {
+        const named = typeof e?.name === 'string' ? e.name : typeof e?.event === 'string' ? e.event : undefined;
+        const props = (e?.props ?? e?.payload) as Record<string, unknown> | undefined;
+        return named
+          ? [
+              {
+                provider: String(e.provider ?? provider ?? 'backend'),
+                name: named,
+                ...(props && typeof props === 'object' ? { props } : {}),
+                via: 'server' as const,
+              },
+            ]
+          : [];
+      });
+      if (server.length > 0) report.sent = [...(report.sent ?? []), ...server];
+    }
     const d = await device().catch(() => undefined);
     if (!d?.server.connected) return;
     if (capturing) {
       const raw = (await d.command('analytics', { take: true }).catch(() => [])) as { sdk?: string; name?: string; properties?: Record<string, unknown> }[];
       const sent = (Array.isArray(raw) ? raw : []).flatMap((e) =>
-        e?.name ? [{ provider: String(e.sdk ?? 'unknown'), name: String(e.name), ...(e.properties ? { props: e.properties } : {}) }] : [],
+        e?.name ? [{ provider: String(e.sdk ?? 'unknown'), name: String(e.name), ...(e.properties ? { props: e.properties } : {}), via: 'sdk' as const }] : [],
+      );
+      // Added to what the backend told its analytics, read above for the same step, not in its place.
+      if (sent.length > 0) report.sent = [...(report.sent ?? []), ...sent];
+    }
+    if (logging) {
+      const raw = (await d.command('logs', { take: true }).catch(() => [])) as Partial<LogLine>[];
+      const logs = (Array.isArray(raw) ? raw : []).flatMap((l): LogLine[] =>
+        typeof l?.text === 'string' && typeof l.at === 'number'
+          ? [
+              {
+                at: l.at,
+                level: l.level === 'debug' || l.level === 'warn' || l.level === 'error' ? l.level : 'info',
+                source: typeof l.source === 'string' ? l.source : 'js',
+                text: l.text,
+                ...(typeof l.stack === 'string' ? { stack: l.stack } : {}),
+              },
+            ]
+          : [],
+      );
+      if (logs.length > 0) report.logs = logs;
+    }
+    const native = options.nativeLogs?.take() ?? [];
+    // In the order they were printed, whichever side printed them.
+    if (native.length > 0) report.logs = [...(report.logs ?? []), ...native].sort((x, y) => x.at - y.at);
+    if (requestsSeen !== undefined) {
+      await completeInFlight(d);
+      const made = await d.requests(requestsSeen).then(
+        (r) => r.requests,
+        () => [],
+      );
+      // A reload (app.refresh) turns the app's keeping of bodies off with everything else it held: ask again.
+      await d.command('networkBodies', { on: true }).catch(() => undefined);
+      if (made.length > 0) {
+        report.requests = made;
+        requestsSeen = made.at(-1)!.id;
+        for (const r of made) if (!answered(r)) inFlight.set(r.id, r);
+        // A JS SDK (Segment, PostHog…) never reaches a native module: what it sent is in its requests.
+        const traffic = trafficEvents(made).map((e) => ({ ...e, via: 'network' as const }));
+        if (traffic.length > 0) report.sent = [...(report.sent ?? []), ...traffic];
+      }
+    }
+    // A step that only looks (app.see, app.wait) on a screen no different from the last frame's shares that frame:
+    // its wait and capture are what make a frame per step slow on a device. The shape is the route and each
+    // element's id, text and place, read from the app, so a change in any of them still takes a frame.
+    let shape: string | undefined;
+    if (evidence?.screenshots && evidence.onChange) {
+      shape = await d.screen().then(
+        (sc) => `${sc.route}|${sc.elements.map((e) => `${e.testId ?? ''}:${e.text ?? ''}:${Math.round(e.frame.x)},${Math.round(e.frame.y)}`).join(';')}`,
+        () => undefined,
       );
-      if (sent.length > 0) report.sent = sent;
+      if (shape !== undefined && shape === lastFrame?.shape && /^app\.(see|wait)\b/.test(report.step)) {
+        report.screenshot = lastFrame.file;
+        return;
+      }
     }
     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(
+      // 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. The wait is paid on every step: short for a report, and long enough for what
+      // arrives after a short delay (700 ms) where two runs' frames are compared pixel by pixel.
+      const quietMs = evidence.settleMs ?? 150;
+      const settled = await d.idle({ quietMs, timeoutMs: Math.max(1000, quietMs * 4) }).then(
         (r) => r.idle,
         () => false,
       );
-      const file = path.join(
+      const stem = path.join(
         evidence.dir,
         `${String(index).padStart(2, '0')}-${report.step
           .toLowerCase()
           .replace(/[^a-z0-9]+/g, '-')
           .slice(0, 48)
-          .replace(/^-|-$/g, '')}.png`,
+          .replace(/^-|-$/g, '')}`,
       );
       // 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: unknown;
-      const taken = (await offers('screenshot'))
-        ? await d.command('screenshot', { path: file, inline: true }).then(
-            (answer) => {
-              const { png, moving: animating } = (answer ?? {}) as { png?: unknown; moving?: unknown };
-              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)) {
+      // A host that waits for a still screen on its own clock signs each picture, so it can say whether the screen
+      // it settled on is still the one in the picture.
+      const hostStill = !!evidence.stillMs && (await offers('still'));
+      let signature: string | undefined;
+      const hostShot = async (file: string) =>
+        d.command('screenshot', { path: file, inline: true, ...(hostStill ? { sign: true } : {}) }).then(
+          (answer) => {
+            const { png, moving: animating, signature: signed } = (answer ?? {}) as { png?: unknown; moving?: unknown; signature?: unknown };
+            if (typeof png === 'string' && !fs.existsSync(file)) fs.writeFileSync(file, Buffer.from(png, 'base64'));
+            if (Array.isArray(animating)) moving = animating;
+            if (typeof signed === 'string') signature = signed;
+            return fs.existsSync(file);
+          },
+          () => false,
+        );
+      let still: boolean | undefined;
+      let file = `${stem}.png`;
+      let taken: boolean;
+      if (await offers('screenshot')) {
+        const avif = evidence.frames !== 'png' && !avifRefused;
+        file = `${stem}.${avif ? 'avif' : 'png'}`;
+        // A host on this machine encodes an AVIF frame after it answers, so the step does not wait for it;
+        // the case waits for all its frames once, at its end.
+        const later = avif
+          ? await d.command('screenshot', { path: file, background: true }).then(
+              (answer) => {
+                const { background, moving: animating } = (answer ?? {}) as { background?: unknown; moving?: unknown };
+                if (Array.isArray(animating)) moving = animating;
+                return background === true;
+              },
+              () => false,
+            )
+          : false;
+        if (later) encoding.push(file);
+        taken = later || (await hostShot(file));
+        if (!taken && avif) {
+          avifRefused = true;
+          file = `${stem}.png`;
+          taken = await hostShot(file);
+        }
+      } else taken = (await execute(['screenshot', file], base)).code === 0;
+      // An animation the agent cannot see (a device's native transition, a host's printer running on its own clock)
+      // leaves a quiet app on a moving screen: the picture itself says when it stopped. Two frames alike, taken
+      // stillMs apart, are a still screen. Frames still being encoded (AVIF on a host) are left as they are.
+      if (taken && hostStill && signature !== undefined && !encoding.includes(file)) {
+        // No real time passes and no picture is made while the host waits; the picture is taken again only when
+        // the screen it settled on is another one.
+        const stillMs = evidence.stillMs!;
+        const answer = (await d.command('still', { stepMs: stillMs, timeoutMs: Math.max(2000, stillMs * 8), since: signature }).catch(() => undefined)) as
+          | { still?: unknown; changed?: unknown; moving?: unknown }
+          | undefined;
+        if (answer) {
+          still = answer.still === true;
+          if (answer.changed === true) {
+            fs.rmSync(file, { force: true });
+            taken = await hostShot(file);
+          }
+          // A screen that never stood still: what moved during the wait is of a moment too.
+          if (Array.isArray(answer.moving)) moving = [...(Array.isArray(moving) ? moving : []), ...answer.moving];
+        }
+      } else if (taken && evidence.stillMs && !encoding.includes(file)) {
+        const stillMs = evidence.stillMs;
+        const take = async (to: string) => ((await offers('screenshot')) ? hostShot(to) : (await execute(['screenshot', to], base)).code === 0);
+        still = false;
+        const until = Date.now() + Math.max(2000, stillMs * 8);
+        let last = fs.readFileSync(file);
+        while (!still && Date.now() < until) {
+          await sleep(stillMs);
+          const again = `${file}.again${path.extname(file)}`;
+          if (!(await take(again))) break;
+          const now = fs.readFileSync(again);
+          fs.renameSync(again, file);
+          still = now.equals(last);
+          last = now;
+        }
+      }
+      if (taken && (encoding.includes(file) || fs.existsSync(file))) {
         report.screenshot = file;
+        lastFrame = { file, shape };
+        if (file.endsWith('.png') && evidence.frames !== 'png') {
+          const taken = file;
+          compacting.push(
+            compactFrame(taken).then((compact) => {
+              if (report.screenshot === taken) report.screenshot = compact;
+            }),
+          );
+        }
         // 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 } : {}) }));
+        if (screen)
+          fs.writeFileSync(
+            file.replace(/\.(png|avif)$/, '.json'),
+            JSON.stringify({ ...screen, settled, ...(still === undefined ? {} : { still }), ...(moving ? { moving } : {}) }),
+          );
       }
     }
   };
@@ -898,7 +1210,7 @@ export const runCase = async (c: Case, options: RunOptions): Promise<CaseReport>
       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);
+        await record(done, steps.length, at, t0);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       const missing = lacking(message);
@@ -914,25 +1226,43 @@ export const runCase = async (c: Case, options: RunOptions): Promise<CaseReport>
       const broke: StepReport = { 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 (evidence || capturing) await record(broke, steps.length, at, t0);
     }
   }
 
+  if (requestsSeen !== undefined) {
+    const d = await device().catch(() => undefined);
+    // The last answers of the case, given a moment to arrive.
+    for (let i = 0; d && inFlight.size && i < 5; i++) {
+      await sleep(200);
+      await completeInFlight(d);
+    }
+    await d?.command('networkBodies', { on: false }).catch(() => undefined);
+  }
+  await Promise.all(compacting);
+  if (encoding.length > 0) {
+    const until = Date.now() + 15_000;
+    while (encoding.some((f) => !fs.existsSync(f)) && Date.now() < until) await sleep(25);
+    // A frame that never arrived is not offered to a report.
+    for (const s of steps) if (s.screenshot && encoding.includes(s.screenshot) && !fs.existsSync(s.screenshot)) delete s.screenshot;
+  }
   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);
+      // A step that set off thousands of spans keeps the first ones; a report is not a profiler.
+      if (s) s.backend = spans.slice(0, 1500);
     }
+    fileRequestsByTrace(steps, tracing.steps);
   }
   if (options.setupOnly && !failed) options.setupOnly.keep({ scope, latest, ran: [...ran], steps });
   if (options.dry) failed = steps.some((s) => s.status === 'failed');
   const report: CaseReport = {
     id: c.id,
     title: c.title,
+    ...aboutOf(c),
     file: c.file,
     result: failed ? 'failed' : unsupported ? 'unsupported' : 'passed',
     ms: Date.now() - started,

package/src/cases/templates.ts

@@ -7,8 +7,13 @@ export const EXAMPLE_CASE = `---
 id: example
 title: "A user who was given points sees them on the first screen"
 description: >
-  What this proves and why it matters, in a sentence or two. A case reads top
-  to bottom: what has to exist, what the person does, what must be true after.
+  What this proves, in a sentence or two. A case reads top to bottom: what has
+  to exist, what the person does, what must be true after.
+why: >
+  Optional: what breaks for people if this fails. The report shows it above the steps.
+given: >
+  Optional: what is true when it starts (who the user is, what is installed).
+ticket: "[TICKET-ID]"
 ---
 setup:
   # Anything that is not an app step is a fixture: fixtures.mjs answers it.
@@ -32,6 +37,19 @@ and \`expected\`. \`lynkeus case run cases/example.md\` runs one; without files
 it runs every case in this folder. A step that fails stops the case, and the
 report carries the screen, the requests and the reason.
 
+## Frontmatter
+
+| Key | | |
+|---|---|---|
+| \`id\`, \`title\` | required, a line | how runs and reports name the case |
+| \`description\` | a paragraph | what the case proves |
+| \`why\` | optional | what breaks for people if it fails |
+| \`given\` | optional | what is true when it starts |
+| \`ticket\` | optional | the ticket it covers |
+
+A report shows \`description\`, \`why\`, \`given\`, \`ticket\` and \`expected\` above the steps, so a reader
+who never opened the file knows what they are looking at.
+
 ## Steps that drive the app
 
 | Step | Value | |