lynkeus 0.4.0 → 0.5.0

package/lib/cases/runner.js

@@ -9,12 +9,16 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { promisify } from 'node:util';
 import { describeScreen } from '../device/driver.js';
+import { trafficEvents } from '../knowledge/analyticsTraffic.js';
 import { normalizeEvents } from '../knowledge/events.js';
 import { find } from '../registry.js';
 import { execute } from '../runtime.js';
 import { isRoute, parseTarget, scopedTarget } from '../targets.js';
+import { compactFrame } from './frames.js';
 import { newSpanId, newTraceId, traceparent } from './traces.js';
 import { dig, interpolate, matcherOf, matches, seeded, stepOf } from './format.js';
+// A host that could not write AVIF once (an older one) is asked for PNG from then on.
+let avifRefused = false;
 /** 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');
@@ -133,6 +137,17 @@ const requestMatches = (event, wanted, status) => {
         return false;
     return status === undefined ? true : event.status === status;
 };
+const aboutOf = (c) => {
+    const text = (v) => (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']);
 const BUILT_IN = ['press', 'type', 'swipe', 'see', 'requests', 'wait', 'nav', 'call', 'run', 'events', 'event'];
@@ -167,6 +182,50 @@ export const missingFixtures = (c, config, known) => {
 };
 /** 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];
+// 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, spans) => {
+    const started = new Map([...spans.values()].map((v) => [v.index, v.startedMs]));
+    const pathOf = (u) => {
+        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 = [];
+        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, options) => {
     const { base, config } = options;
     const log = options.log ?? (() => undefined);
@@ -177,6 +236,11 @@ export const runCase = async (c, options) => {
     const started = Date.now();
     const steps = [];
     let mark;
+    // 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;
+    let lastFrame;
     // 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.
@@ -185,17 +249,22 @@ export const runCase = async (c, options) => {
     let why;
     const recorded = [];
     let buffer = [];
+    // 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) => {
-        if (!options.events)
+        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;
+        const provider = config.appEvents?.provider;
         for (const e of newSince(buffer, now))
-            recorded.push({ ...e, step: index, route });
+            recorded.push({ ...e, step: index, route, ...(provider ? { provider } : {}) });
         buffer = now;
     };
     const device = () => base.device();
@@ -391,8 +460,12 @@ export const runCase = async (c, options) => {
                 await sleep(150);
                 continue;
             }
-            if (Date.now() > deadline)
-                throw new Error(absent ? `still there: ${label({ verb: '', value: { ...params, absent: undefined } }).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 }).trim()}`);
+            }
             await sleep(150);
         }
     };
@@ -531,10 +604,14 @@ export const runCase = async (c, options) => {
     const app = async (name, value) => {
         const params = value && typeof value === 'object' && !Array.isArray(value) ? value : 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);
+            await markRequests(d).catch(() => undefined);
         switch (name) {
             case 'press': {
                 await interrupted(value);
@@ -573,8 +650,10 @@ export const runCase = async (c, options) => {
                 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 = typeof value === 'string' ? { what: value } : { ...(params ?? {}) };
+                        const asked = { ...(typeof value === 'string' ? { what: value } : (params ?? {})), ...since };
                         const deadline = Date.now() + (typeof asked.timeoutMs === 'number' ? asked.timeoutMs : 10_000);
                         for (;;) {
                             await interrupted(value);
@@ -589,9 +668,8 @@ export const runCase = async (c, options) => {
                         }
                     }
                     else
-                        await cli(argvFor(find('wait'), value));
+                        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);
                 }
@@ -724,14 +802,15 @@ export const runCase = async (c, options) => {
     };
     if (options.events && !options.dry) {
         const d = await base.device().catch(() => undefined);
-        if (d?.server.connected)
+        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) => !!(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;
@@ -743,6 +822,37 @@ export const runCase = async (c, options) => {
     // 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;
+    // Requests filed while still waiting for an answer: read again later and completed where they were filed.
+    const inFlight = new Map();
+    const answered = (r) => r.status !== undefined || !!r.error;
+    const completeInFlight = async (d) => {
+        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 = [];
+    // Frames a simulator or emulator gave as PNG, being encoded again as AVIF while the case goes on.
+    const compacting = [];
+    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 () => {
         if (!filming || !evidence?.video)
             return undefined;
@@ -750,17 +860,87 @@ export const runCase = async (c, options) => {
         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) => {
+    const record = async (report, index, startedAt, begunMs) => {
         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 : [];
+            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);
+                return named
+                    ? [
+                        {
+                            provider: String(e.provider ?? provider ?? 'backend'),
+                            name: named,
+                            ...(props && typeof props === 'object' ? { props } : {}),
+                            via: 'server',
+                        },
+                    ]
+                    : [];
+            });
+            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(() => []));
-            const sent = (Array.isArray(raw) ? raw : []).flatMap((e) => e?.name ? [{ provider: String(e.sdk ?? 'unknown'), name: String(e.name), ...(e.properties ? { props: e.properties } : {}) }] : []);
+            const sent = (Array.isArray(raw) ? raw : []).flatMap((e) => e?.name ? [{ provider: String(e.sdk ?? 'unknown'), name: String(e.name), ...(e.properties ? { props: e.properties } : {}), via: 'sdk' }] : []);
+            // Added to what the backend told its analytics, read above for the same step, not in its place.
             if (sent.length > 0)
-                report.sent = sent;
+                report.sent = [...(report.sent ?? []), ...sent];
+        }
+        if (logging) {
+            const raw = (await d.command('logs', { take: true }).catch(() => []));
+            const logs = (Array.isArray(raw) ? raw : []).flatMap((l) => 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' }));
+                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;
+        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 (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
@@ -770,31 +950,106 @@ export const runCase = async (c, options) => {
             // 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(evidence.dir, `${String(index).padStart(2, '0')}-${report.step
+            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;
-            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)) {
+            // 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;
+            const hostShot = async (file) => d.command('screenshot', { path: file, inline: true, ...(hostStill ? { sign: true } : {}) }).then((answer) => {
+                const { png, moving: animating, signature: signed } = (answer ?? {});
+                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;
+            let file = `${stem}.png`;
+            let taken;
+            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 ?? {});
+                        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));
+                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) => ((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 } : {}) }));
+                    fs.writeFileSync(file.replace(/\.(png|avif)$/, '.json'), JSON.stringify({ ...screen, settled, ...(still === undefined ? {} : { still }), ...(moving ? { moving } : {}) }));
             }
         }
     };
@@ -857,7 +1112,7 @@ export const runCase = async (c, options) => {
             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);
@@ -876,19 +1131,39 @@ export const runCase = async (c, options) => {
             steps.push(broke);
             log(`  ❌ ${text}  — ${message.split('\n')[0]}  (${Date.now() - t0}ms)`);
             if (evidence || capturing)
-                await record(broke, steps.length, at);
+                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.
+            // 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, 400);
+                s.backend = spans.slice(0, 1500);
         }
+        fileRequestsByTrace(steps, tracing.steps);
     }
     if (options.setupOnly && !failed)
         options.setupOnly.keep({ scope, latest, ran: [...ran], steps });
@@ -897,6 +1172,7 @@ export const runCase = async (c, options) => {
     const report = {
         id: c.id,
         title: c.title,
+        ...aboutOf(c),
         file: c.file,
         result: failed ? 'failed' : unsupported ? 'unsupported' : 'passed',
         ms: Date.now() - started,

package/lib/cases/templates.d.ts

@@ -3,8 +3,8 @@
  * format next to it, and a fixtures server with two empty fixtures, so a
  * project starts from something that runs instead of from a blank folder.
  */
-export declare const EXAMPLE_CASE = "---\nid: example\ntitle: \"A user who was given points sees them on the first screen\"\ndescription: >\n  What this proves and why it matters, in a sentence or two. A case reads top\n  to bottom: what has to exist, what the person does, what must be true after.\n---\nsetup:\n  # Anything that is not an app step is a fixture: fixtures.mjs answers it.\n  - create_user: { as: u, name: \"Ana\" }\n\nsteps:\n  - app.see: { text: \"Hello\" }\n  # `user: u` points at what `create_user` answered (cases.refs in lynkeus.config.json).\n  - give_points: { user: u, points: 25 }\n  - app.see: { text: \"25 points\", timeoutMs: 10000 }\n  - assert: { user: u, path: points, equals: 25 }\n\nexpected: |\n  The points on screen and the points the backend holds are both 25.\n";
-export declare const FORMAT = "# Cases\n\nA case is a markdown file: frontmatter that names it, then `setup`, `steps`\nand `expected`. `lynkeus case run cases/example.md` runs one; without files\nit runs every case in this folder. A step that fails stops the case, and the\nreport carries the screen, the requests and the reason.\n\n## Steps that drive the app\n\n| Step | Value | |\n|---|---|---|\n| `app.press` | target, or `{ target, within?, nth?, optional?, hold?, timeoutMs? }` | Waits for the control to be there and enabled. `optional` presses only if it is on screen. |\n| `app.type` | `{ text, target?, submit?, clear?, timeoutMs? }` | `target` is tapped first, once it is there (`timeoutMs` is how long that may take); `submit` ends with the return key. |\n| `app.swipe` | `{ direction, target?, distance? }` or `{ from, to }` | |\n| `app.wait` | route, target, ms, `{ target, scroll? }` or `{ request, status? }` | `scroll` swipes until the target is in the window. A `request` is `METHOD /path`. |\n| `app.see` | target, or `{ testId?, text?, route?, request?, event?, layer?, absent?, timeoutMs? }` | An assertion on what the app shows or did. Everything named must hold. |\n| `app.nav` | route, or `{ route, params }` | A teleport, for getting to where the case starts. |\n| `app.back` | | |\n| `app.requests` | `mark` | A `request` counts only what the app asked for after the step before it began; this marks further back, until a step has looked for a request. |\n| `app.call` | `{ command, params?, expect?, as? }` | A command the app registered with `qa.register`. |\n| `app.run` | `{ flow, vars? }` | A lynkeus flow, from the flows folder. |\n| `app.events` / `app.event` | `clear` / `{ name, props?, absent? }` | What the app told its analytics. |\n| `app.<command>` | its arguments by name | Any other lynkeus command: `app.mock`, `app.network`, `app.appstate`, `app.deeplink`\u2026 |\n\nA target is `#testId`, a text, an index or `x,y`. Where a step takes `target` it also takes `testId`. A text inside quotes of its own (`'\"Next\"'`) is always a text, where `app.wait: Next` would wait for a route called `Next`.\n\nA case that runs over several inputs declares `matrix: { locale: [en, fr] }`\nin its frontmatter and runs once per combination; `{{matrix.locale}}` is that\nrun's value.\n\nOne case runs on a host and on a device. What only one of them needs \u2014 closing a\nnative screen the host never shows \u2014 is kept to it:\n\n```yaml\n  - on: device        # or headless, ios, android\n    do:\n      - app.press: \"364,84\"\n```\n\n## Steps that prepare and read the backend\n\nAny other step name is a **fixture**: lynkeus sends it to the command in\n`cases.fixtures` (lynkeus.config.json) as one JSON line and reads one back.\n\n```\n\u2192 {\"command\": \"create_user\", \"params\": {\"name\": \"Ana\"}, \"env\": {\"NAME\": \"Ana\"}}\n\u2190 {\"ok\": true, \"user_id\": \"u_1\", \"name\": \"Ana\"}\n```\n\nBefore the first case lynkeus sends `{\"command\": \"lynkeus.describe\"}`. A\nserver that answers `{\"commands\": [\"create_user\", \u2026]}` gets its cases checked\nfirst: one that names a fixture missing from the list is refused before\nanything runs. A server that answers `\"ok\": false` is not checked.\n\n`as: u` keeps the answer; `{{u.user_id}}` reads it later. `assert` calls\nthe `inspect` fixture and checks one path of its answer with `equals`,\n`includes`, `gte`, `lte`, `near`, `matches`, `present` or `absent`.\n`exec: { run: \"\u2026\", as? }` runs a shell command and keeps its JSON output.\n\n## Steps of your own\n\n`cases.macros` names a step and the steps it stands for. Inside,\n`{{param.x}}` is what the case passed, and a parameter that names an alias\nis that alias.\n\n```json\n\"macros\": {\n  \"app.login\": [\n    { \"app.call\": { \"command\": \"reset\" } },\n    { \"app.deeplink\": \"myapp://dev-login?user={{param.as.user_id}}\" },\n    { \"when\": \"wait\", \"do\": { \"app.wait\": \"{{param.wait}}\" } }\n  ]\n}\n```\n\n`when` runs a step only if the case passed that parameter (`\"when\": \"wait\"`)\nor passed that value (`\"when\": \"method=phone\"`); `unless` is the opposite.\n\n`cases.interruptions` names what the app may put in the way of any step \u2014 a\nlock screen, a consent sheet \u2014 and the steps that get past it:\n`{ \"see\": \"#unlock-keypad\", \"do\": [\"app.unlock\"], \"unless\": \"keypad\" }`. It\nruns before a press, a type, a swipe or a see finds it there; a step whose own\nwords match `unless` is about it, and is left alone.\n\nCases and fixtures often live in a repository of their own: `LYNKEUS_CONFIG`\nnames a second configuration file, read over the app's, and the paths under\nits `cases` are relative to it.\n";
+export declare const EXAMPLE_CASE = "---\nid: example\ntitle: \"A user who was given points sees them on the first screen\"\ndescription: >\n  What this proves, in a sentence or two. A case reads top to bottom: what has\n  to exist, what the person does, what must be true after.\nwhy: >\n  Optional: what breaks for people if this fails. The report shows it above the steps.\ngiven: >\n  Optional: what is true when it starts (who the user is, what is installed).\nticket: \"[TICKET-ID]\"\n---\nsetup:\n  # Anything that is not an app step is a fixture: fixtures.mjs answers it.\n  - create_user: { as: u, name: \"Ana\" }\n\nsteps:\n  - app.see: { text: \"Hello\" }\n  # `user: u` points at what `create_user` answered (cases.refs in lynkeus.config.json).\n  - give_points: { user: u, points: 25 }\n  - app.see: { text: \"25 points\", timeoutMs: 10000 }\n  - assert: { user: u, path: points, equals: 25 }\n\nexpected: |\n  The points on screen and the points the backend holds are both 25.\n";
+export declare const FORMAT = "# Cases\n\nA case is a markdown file: frontmatter that names it, then `setup`, `steps`\nand `expected`. `lynkeus case run cases/example.md` runs one; without files\nit runs every case in this folder. A step that fails stops the case, and the\nreport carries the screen, the requests and the reason.\n\n## Frontmatter\n\n| Key | | |\n|---|---|---|\n| `id`, `title` | required, a line | how runs and reports name the case |\n| `description` | a paragraph | what the case proves |\n| `why` | optional | what breaks for people if it fails |\n| `given` | optional | what is true when it starts |\n| `ticket` | optional | the ticket it covers |\n\nA report shows `description`, `why`, `given`, `ticket` and `expected` above the steps, so a reader\nwho never opened the file knows what they are looking at.\n\n## Steps that drive the app\n\n| Step | Value | |\n|---|---|---|\n| `app.press` | target, or `{ target, within?, nth?, optional?, hold?, timeoutMs? }` | Waits for the control to be there and enabled. `optional` presses only if it is on screen. |\n| `app.type` | `{ text, target?, submit?, clear?, timeoutMs? }` | `target` is tapped first, once it is there (`timeoutMs` is how long that may take); `submit` ends with the return key. |\n| `app.swipe` | `{ direction, target?, distance? }` or `{ from, to }` | |\n| `app.wait` | route, target, ms, `{ target, scroll? }` or `{ request, status? }` | `scroll` swipes until the target is in the window. A `request` is `METHOD /path`. |\n| `app.see` | target, or `{ testId?, text?, route?, request?, event?, layer?, absent?, timeoutMs? }` | An assertion on what the app shows or did. Everything named must hold. |\n| `app.nav` | route, or `{ route, params }` | A teleport, for getting to where the case starts. |\n| `app.back` | | |\n| `app.requests` | `mark` | A `request` counts only what the app asked for after the step before it began; this marks further back, until a step has looked for a request. |\n| `app.call` | `{ command, params?, expect?, as? }` | A command the app registered with `qa.register`. |\n| `app.run` | `{ flow, vars? }` | A lynkeus flow, from the flows folder. |\n| `app.events` / `app.event` | `clear` / `{ name, props?, absent? }` | What the app told its analytics. |\n| `app.<command>` | its arguments by name | Any other lynkeus command: `app.mock`, `app.network`, `app.appstate`, `app.deeplink`\u2026 |\n\nA target is `#testId`, a text, an index or `x,y`. Where a step takes `target` it also takes `testId`. A text inside quotes of its own (`'\"Next\"'`) is always a text, where `app.wait: Next` would wait for a route called `Next`.\n\nA case that runs over several inputs declares `matrix: { locale: [en, fr] }`\nin its frontmatter and runs once per combination; `{{matrix.locale}}` is that\nrun's value.\n\nOne case runs on a host and on a device. What only one of them needs \u2014 closing a\nnative screen the host never shows \u2014 is kept to it:\n\n```yaml\n  - on: device        # or headless, ios, android\n    do:\n      - app.press: \"364,84\"\n```\n\n## Steps that prepare and read the backend\n\nAny other step name is a **fixture**: lynkeus sends it to the command in\n`cases.fixtures` (lynkeus.config.json) as one JSON line and reads one back.\n\n```\n\u2192 {\"command\": \"create_user\", \"params\": {\"name\": \"Ana\"}, \"env\": {\"NAME\": \"Ana\"}}\n\u2190 {\"ok\": true, \"user_id\": \"u_1\", \"name\": \"Ana\"}\n```\n\nBefore the first case lynkeus sends `{\"command\": \"lynkeus.describe\"}`. A\nserver that answers `{\"commands\": [\"create_user\", \u2026]}` gets its cases checked\nfirst: one that names a fixture missing from the list is refused before\nanything runs. A server that answers `\"ok\": false` is not checked.\n\n`as: u` keeps the answer; `{{u.user_id}}` reads it later. `assert` calls\nthe `inspect` fixture and checks one path of its answer with `equals`,\n`includes`, `gte`, `lte`, `near`, `matches`, `present` or `absent`.\n`exec: { run: \"\u2026\", as? }` runs a shell command and keeps its JSON output.\n\n## Steps of your own\n\n`cases.macros` names a step and the steps it stands for. Inside,\n`{{param.x}}` is what the case passed, and a parameter that names an alias\nis that alias.\n\n```json\n\"macros\": {\n  \"app.login\": [\n    { \"app.call\": { \"command\": \"reset\" } },\n    { \"app.deeplink\": \"myapp://dev-login?user={{param.as.user_id}}\" },\n    { \"when\": \"wait\", \"do\": { \"app.wait\": \"{{param.wait}}\" } }\n  ]\n}\n```\n\n`when` runs a step only if the case passed that parameter (`\"when\": \"wait\"`)\nor passed that value (`\"when\": \"method=phone\"`); `unless` is the opposite.\n\n`cases.interruptions` names what the app may put in the way of any step \u2014 a\nlock screen, a consent sheet \u2014 and the steps that get past it:\n`{ \"see\": \"#unlock-keypad\", \"do\": [\"app.unlock\"], \"unless\": \"keypad\" }`. It\nruns before a press, a type, a swipe or a see finds it there; a step whose own\nwords match `unless` is about it, and is left alone.\n\nCases and fixtures often live in a repository of their own: `LYNKEUS_CONFIG`\nnames a second configuration file, read over the app's, and the paths under\nits `cases` are relative to it.\n";
 export declare const FIXTURES = "#!/usr/bin/env node\n// The fixtures of this project: how a case prepares the backend and reads it.\n// lynkeus starts this once per run and talks JSON lines to it: one line in per\n// step, one line out. Replace the bodies with calls to your backend \u2014 its\n// admin API, a script, a database seed.\nimport readline from 'node:readline';\n\nconst users = new Map();\n\nconst fixtures = {\n  async create_user({ name = 'Test user' }) {\n    const user = { user_id: `u_${users.size + 1}`, name, points: 0 };\n    users.set(user.user_id, user);\n    return user;\n  },\n  async give_points({ user_id, points }) {\n    const user = users.get(user_id);\n    if (!user) throw new Error(`no user ${user_id}`);\n    user.points += Number(points);\n    return { user_id, points: user.points };\n  },\n  // What `assert` reads.\n  async inspect({ user_id }) {\n    return users.get(user_id) ?? {};\n  },\n};\n\nfor await (const line of readline.createInterface({ input: process.stdin })) {\n  if (!line.trim()) continue;\n  const { command, params } = JSON.parse(line);\n  // lynkeus asks once what this server answers, and refuses a case that names anything else.\n  if (command === 'lynkeus.describe') {\n    console.log(JSON.stringify({ commands: Object.keys(fixtures) }));\n    continue;\n  }\n  try {\n    const fixture = fixtures[command];\n    if (!fixture) throw new Error(`no fixture ${command}`);\n    console.log(JSON.stringify({ ok: true, ...(await fixture(params ?? {})) }));\n  } catch (error) {\n    console.log(JSON.stringify({ ok: false, error: error.message }));\n  }\n}\n";
 export declare const CONFIG: {
     dir: string;

package/lib/cases/templates.js

@@ -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.
@@ -31,6 +36,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 | |

package/lib/cases/traces.js

@@ -145,7 +145,7 @@ export const decodeJson = (body) => {
     return spans;
 };
 // What a report keeps of a span's attributes: what it did, not every label an instrumentation adds.
-const KEEP = /^(http\.(request\.)?method|http\.(response\.)?status_code|http\.route|http\.target|url\.(path|full)|server\.address|net\.peer\.name|db\.(system|statement|operation|sql\.table)|messaging\.|code\.(namespace|function)|rpc\.|exception\.message|enduser\.id)/;
+const KEEP = /^(http\.(request\.)?method|http\.(response\.)?status_code|http\.route|http\.target|url\.(path|full)|server\.address|net\.peer\.name|messaging\.|code\.(namespace|function)|rpc\.|exception\.message|enduser\.id)/;
 /**
  * Listens for OTLP traces while a run goes on: a backend with OTEL_EXPORTER_OTLP_ENDPOINT pointed here sends
  * what each request did, and the steps that sent those requests (their ids travel in `traceparent`) get it.
@@ -224,6 +224,9 @@ export class TraceSink {
             return undefined;
         };
         for (const span of [...spans].sort((a, b) => (a.startNs < b.startNs ? -1 : 1))) {
+            // A database query never leaves the machine: its statement names the backend's tables and columns.
+            if (span.attributes['db.system'] !== undefined)
+                continue;
             const where = place(span);
             if (!where)
                 continue;