lynkeus 0.2.0

package/lib/cases/__tests__/runner.test.js

@@ -0,0 +1,188 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { after, test } from 'node:test';
+import { driveCommands } from '../../commands/drive.js';
+import { osCommands } from '../../commands/os.js';
+import { find, register } from '../../registry.js';
+import { Fixtures } from '../fixtures.js';
+import { parseCase } from '../format.js';
+import { argvFor, newSince, runCase } from '../runner.js';
+import { FIXTURES } from '../templates.js';
+register([...driveCommands, ...osCommands]);
+const root = fs.mkdtempSync(path.join(os.tmpdir(), 'lynkeus-cases-'));
+fs.writeFileSync(path.join(root, 'fixtures.mjs'), FIXTURES);
+const fixtures = new Fixtures({ command: 'node fixtures.mjs' }, root);
+after(() => fixtures.close());
+// An app with one button that, pressed, shows the points the fixtures hold.
+const fakeApp = () => {
+    const calls = [];
+    let shown = 'Hello';
+    const screen = () => ({
+        route: 'Profile.Main',
+        path: ['Profile.Main'],
+        commit: 1,
+        busy: false,
+        window: { w: 390, h: 844 },
+        costMs: 1,
+        elements: [
+            { i: 0, kind: 'button', testId: 'refresh', enabled: true, depth: 0, frame: { x: 0, y: 0, w: 100, h: 40 } },
+            { i: 1, kind: 'text', text: shown, enabled: true, depth: 0, frame: { x: 0, y: 50, w: 100, h: 20 } },
+        ],
+    });
+    const server = {
+        connected: true,
+        call: async (method, params) => {
+            calls.push({ method, params });
+            if (method === 'find')
+                return screen().elements.find((e) => e.testId === params.testId) ?? null;
+            return null;
+        },
+    };
+    const device = {
+        server,
+        screen: async () => screen(),
+        trace: async () => ({ last: 0, events: [{ seq: 1, t: 0, kind: 'request', method: 'GET', url: 'http://x/api/points', status: 200 }] }),
+        press: async (params) => {
+            calls.push({ method: 'press', params });
+            shown = '25 points';
+            return { x: 0, y: 0, mode: 'native' };
+        },
+        waitFor: async () => ({ waitedMs: 0 }),
+        idle: async () => ({ settled: true }),
+        command: async (name) => (name === 'events' ? [{ name: 'points_viewed', properties: { points: 25 } }] : {}),
+    };
+    const base = {
+        root,
+        config: {},
+        attached: true,
+        err: () => undefined,
+        graph: () => {
+            throw new Error('no graph');
+        },
+        device: async () => device,
+    };
+    return { base, calls };
+};
+const config = { refs: { user: 'user_id' }, inspect: 'inspect' };
+test('a case prepares the backend, drives the app and reads both', async () => {
+    const c = parseCase(`---
+id: gift
+---
+setup:
+  - create_user: { as: u, name: "Ana" }
+steps:
+  - app.see: { text: "Hello" }
+  - give_points: { user: u, points: 25 }
+  - app.press: "#refresh"
+  - app.see: { text: "25 points", request: "GET /api/points", event: points_viewed, props: { points: 25 } }
+  - app.see: { text: "Hello", absent: true }
+  - assert: { user: u, path: points, equals: 25 }
+  - assert: { path: name, equals: "Ana" }
+`, 'gift.md');
+    const { base, calls } = fakeApp();
+    const report = await runCase(c, { base, config, fixtures });
+    assert.deepEqual(report.steps.map((s) => [s.status, s.error]), Array(8).fill(['passed', undefined]));
+    assert.equal(calls.filter((x) => x.method === 'press').length, 1);
+});
+test('the first step that fails stops the case and leaves the evidence', async () => {
+    const c = parseCase('---\nid: red\n---\nsteps:\n  - app.see: { text: "Goodbye", timeoutMs: 200 }\n  - app.press: "#refresh"\n', 'red.md');
+    const { base, calls } = fakeApp();
+    const report = await runCase(c, { base, config, fixtures });
+    assert.equal(report.result, 'failed');
+    assert.deepEqual(report.steps.map((s) => s.status), ['failed', 'skipped']);
+    assert.match(report.steps[0].error, /not on screen: "Goodbye"/);
+    assert.match(report.evidence.screen, /button #refresh/);
+    assert.equal(calls.filter((x) => x.method === 'press').length, 0);
+});
+test('an optional press of something that is not there is skipped, not failed', async () => {
+    const c = parseCase('---\nid: opt\n---\nsteps:\n  - app.press: { target: "#dismiss", optional: true }\n', 'opt.md');
+    const { base } = fakeApp();
+    const device = await base.device();
+    device.waitFor = async () => {
+        throw new Error('Timed out');
+    };
+    const report = await runCase(c, { base, config, fixtures });
+    assert.deepEqual(report.steps.map((s) => s.status), ['skipped']);
+});
+test('a macro is the steps a project gave a name to, with what the case passed', async () => {
+    const c = parseCase('---\nid: m\n---\nsetup:\n  - create_user: { as: u }\nsteps:\n  - app.enter: { as: u, then: "#refresh" }\n  - app.enter: { as: u }\n', 'm.md');
+    const { base, calls } = fakeApp();
+    const macros = {
+        'app.enter': [{ assert: { user_id: '{{param.as.user_id}}', path: 'user_id', matches: '^u_' } }, { when: 'then', do: { 'app.press': '{{param.then}}' } }],
+    };
+    const report = await runCase(c, { base, config: { ...config, macros }, fixtures });
+    assert.equal(report.result, 'passed', JSON.stringify(report.steps));
+    assert.equal(calls.filter((x) => x.method === 'press').length, 1);
+});
+test("a step that is neither the app's nor a declared fixture says so", async () => {
+    const c = parseCase('---\nid: f\n---\nsteps:\n  - teleport: { to: "moon" }\n', 'f.md');
+    const { base } = fakeApp();
+    const report = await runCase(c, { base, config, fixtures });
+    assert.match(report.steps[0].error, /no fixture teleport/);
+});
+test('a step becomes the argv of the command it names', () => {
+    assert.deepEqual(argvFor(find('type'), { text: 'ana', target: '#search', submit: true }), ['type', 'ana', '#search', '--submit']);
+    assert.deepEqual(argvFor(find('wait'), { target: '#row-25', scroll: true, timeoutMs: 9000 }), ['wait', '#row-25', '--scroll', '--timeout', '9000']);
+    assert.deepEqual(argvFor(find('press'), { target: '#like', within: 'hi from Ana' }), ['press', '#like', '--in', 'hi from Ana']);
+    assert.deepEqual(argvFor(find('mock'), { request: 'POST /pay', lost: true, times: 1 }), ['mock', 'POST /pay', '--lost', '--times', '1']);
+    assert.deepEqual(argvFor(find('swipe'), { from: '10,20', to: '10,300', durationMs: 300 }), [
+        'swipe',
+        '--from',
+        '10,20',
+        '--to',
+        '10,300',
+        '--duration',
+        '300',
+    ]);
+    assert.deepEqual(argvFor(find('mock'), 'clear'), ['mock', '--clear']);
+    assert.throws(() => argvFor(find('press'), { target: '#x', sideways: true }), /press has no sideways/);
+});
+test('what a buffer gained is found whichever end it grows from', () => {
+    const a = { name: 'a' };
+    const b = { name: 'b' };
+    const c = { name: 'c' };
+    assert.deepEqual(newSince([a], [a, b, c]), [b, c]);
+    assert.deepEqual(newSince([a], [c, b, a]), [b, c]);
+    assert.deepEqual(newSince([a, b], [a, b]), []);
+    assert.deepEqual(newSince([a, b], [c]), [c]);
+});
+test('a run that asks for events keeps each with the step that caused it', async () => {
+    const c = parseCase('---\nid: ev\n---\nsteps:\n  - app.see: { text: "Hello" }\n  - app.press: "#refresh"\n', 'ev.md');
+    const { base } = fakeApp();
+    const device = await base.device();
+    let buffer = [];
+    device.command = async () => buffer;
+    const press = device.press.bind(device);
+    device.press = async (p) => {
+        buffer = [{ name: 'refreshed', properties: { by: 'button' } }, ...buffer];
+        return press(p);
+    };
+    const report = await runCase(c, { base, config, fixtures, events: true });
+    assert.deepEqual(report.events, [{ name: 'refreshed', props: { by: 'button' }, step: 2, route: 'Profile.Main' }]);
+});
+test('what the app puts in the way of a step is dealt with before it, unless the step is about it', async () => {
+    const { base, calls } = fakeApp();
+    const interruptions = [{ see: '#refresh', unless: 'refresh', do: [{ 'app.press': '#refresh' }] }];
+    const c = parseCase('---\nid: t\n---\nsteps:\n  - app.see: { testId: refresh }\n  - app.see: { text: "25 points" }\n', 't.md');
+    const report = await runCase(c, { base, config: { ...config, interruptions }, fixtures });
+    assert.equal(report.result, 'passed');
+    assert.equal(calls.filter((call) => call.method === 'press').length > 0, true);
+});
+test('a dry run names the step nobody answers and the argument a command does not take', async () => {
+    const { base } = fakeApp();
+    const c = parseCase('---\nid: t\n---\nsteps:\n  - app.teleport: somewhere\n  - app.clock: { sideways: 1 }\n  - app.clock: { advanceMs: 1000 }\n', 't.md');
+    const report = await runCase(c, { base, config, fixtures, dry: true });
+    assert.equal(report.result, 'failed');
+    assert.deepEqual(report.steps.map((s) => s.status), ['failed', 'failed', 'passed']);
+});
+test('a step kept to a device is skipped on a host, and one kept to the host runs there', async () => {
+    const { base, calls } = fakeApp();
+    const c = parseCase('---\nid: t\n---\nsteps:\n  - on: device\n    do:\n      - app.press: "#nowhere"\n  - on: headless\n    do: { app.press: "#refresh" }\n  - app.see: { text: "25 points" }\n', 't.md');
+    assert.equal(c.steps[0].on, 'device');
+    const report = await runCase(c, { base, config, fixtures });
+    assert.equal(report.result, 'passed', JSON.stringify(report.steps));
+    assert.deepEqual(report.steps.map((s) => s.status), ['skipped', 'passed', 'passed']);
+    assert.equal(calls.filter((call) => call.method === 'press').length, 1);
+});

package/lib/cases/fixtures.d.ts

@@ -0,0 +1,13 @@
+export type FixturesConfig = {
+    command: string;
+    cwd?: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+};
+export type Answer = Record<string, unknown>;
+export declare class Fixtures {
+    #private;
+    constructor(config: FixturesConfig, root: string);
+    call(command: string, params: Record<string, unknown>): Promise<Answer>;
+    close(): void;
+}

package/lib/cases/fixtures.js

@@ -0,0 +1,100 @@
+/**
+ * Fixtures are how a case prepares and reads the backend, and lynkeus knows
+ * nothing about them: a project declares one long-lived command and lynkeus
+ * speaks JSON lines to it. One line in per step —
+ *
+ *   {"command": "create_user", "params": {"plan": "pro"}, "env": {"PLAN": "pro"}}
+ *
+ * — and one line out, the step's answer: any JSON object, `"ok": false` and an
+ * `error` when it failed. `params` is the step as written; `env` is the same
+ * flattened to upper-case strings, for a server that hands them to a script.
+ */
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import readline from 'node:readline';
+const envOf = (params) => Object.fromEntries(Object.entries(params)
+    .filter(([, v]) => v !== undefined && v !== null)
+    .map(([k, v]) => [k.replace(/([a-z])([A-Z])/g, '$1_$2').toUpperCase(), typeof v === 'object' ? JSON.stringify(v) : String(v)]));
+export class Fixtures {
+    #config;
+    #root;
+    #child = null;
+    #lines = [];
+    #waiting = null;
+    #stderr = '';
+    constructor(config, root) {
+        this.#config = config;
+        this.#root = root;
+    }
+    #start() {
+        if (this.#child)
+            return this.#child;
+        const child = spawn(this.#config.command, {
+            shell: true,
+            // Its own process group, so closing takes the shell and what it started.
+            detached: true,
+            cwd: path.resolve(this.#root, this.#config.cwd ?? '.'),
+            env: { ...process.env, ...this.#config.env },
+        });
+        child.stderr.on('data', (chunk) => {
+            this.#stderr = (this.#stderr + chunk.toString()).slice(-4000);
+        });
+        const reader = readline.createInterface({ input: child.stdout });
+        reader.on('line', (line) => {
+            if (!line.trim().startsWith('{'))
+                return;
+            if (this.#waiting) {
+                const resolve = this.#waiting;
+                this.#waiting = null;
+                resolve(line);
+            }
+            else
+                this.#lines.push(line);
+        });
+        child.on('close', () => {
+            this.#child = null;
+            this.#waiting?.(null);
+            this.#waiting = null;
+        });
+        this.#child = child;
+        return child;
+    }
+    async call(command, params) {
+        const child = this.#start();
+        child.stdin.write(`${JSON.stringify({ command, params, env: envOf(params) })}\n`);
+        const timeoutMs = this.#config.timeoutMs ?? 120_000;
+        const line = await new Promise((resolve, reject) => {
+            const ready = this.#lines.shift();
+            if (ready !== undefined)
+                return resolve(ready);
+            const timer = setTimeout(() => {
+                this.#waiting = null;
+                reject(new Error(`${command}: the fixtures command did not answer within ${timeoutMs} ms`));
+            }, timeoutMs);
+            this.#waiting = (answer) => {
+                clearTimeout(timer);
+                resolve(answer);
+            };
+        });
+        if (line === null)
+            throw new Error(`${command}: the fixtures command ended${this.#stderr ? `: ${this.#stderr.trim().split('\n').slice(-3).join(' · ')}` : ''}`);
+        const answer = JSON.parse(line);
+        if (answer.ok === false)
+            throw new Error(`${command}: ${String(answer.error ?? answer.message ?? 'ok=false')}`);
+        return answer;
+    }
+    close() {
+        const child = this.#child;
+        this.#child = null;
+        if (!child)
+            return;
+        child.stdin.end();
+        try {
+            if (child.pid)
+                process.kill(-child.pid, 'SIGTERM');
+        }
+        catch {
+            // already gone
+        }
+    }
+}

package/lib/cases/format.d.ts

@@ -0,0 +1,37 @@
+export type StepValue = string | number | boolean | null | Record<string, unknown> | unknown[];
+export type Step = {
+    verb: string;
+    value: StepValue;
+    on?: string;
+};
+export type Case = {
+    file: string;
+    id: string;
+    title?: string;
+    meta: Record<string, unknown>;
+    setup: Step[];
+    steps: Step[];
+    expected?: string;
+};
+/** A bare verb, or one `verb: value`. */
+export declare const stepOf: (item: unknown, where?: string) => Step;
+export declare const parseCase: (text: string, file: string) => Case;
+export declare const readCases: (file: string) => Case[];
+/** `a.b.0.c` into a value; `a.*.b` collects b from every element of the list a. */
+export declare const dig: (json: unknown, dotted: string) => unknown;
+export type Scope = Record<string, unknown>;
+/** `{{alias.path}}` from what earlier steps answered, `{{random.letters}}`, `{{env.NAME}}`. */
+export declare const interpolate: <T>(value: T, scope: Scope) => T;
+export type Matcher = {
+    equals?: unknown;
+    near?: unknown;
+    gte?: unknown;
+    lte?: unknown;
+    present?: boolean;
+    absent?: boolean;
+    includes?: unknown;
+    matches?: string;
+};
+export declare const matcherOf: (params: Record<string, unknown>) => Matcher | undefined;
+/** Whether a value read from the backend is what the case said it would be. */
+export declare const matches: (got: unknown, m: Matcher) => boolean;

package/lib/cases/format.js

@@ -0,0 +1,169 @@
+/**
+ * A case is a markdown file a person can read: YAML frontmatter that says what
+ * it is, and a YAML body that says what to prepare (`setup`), what to do
+ * (`steps`) and what that proves (`expected`). Each step is one key: an
+ * `app.<verb>` drives the app, `assert` reads the backend, `exec` runs a shell
+ * command, and any other name is a fixture the project declared.
+ */
+import fs from 'node:fs';
+import { parse } from 'yaml';
+/** A bare verb, or one `verb: value`. */
+export const stepOf = (item, where = 'a step') => {
+    if (typeof item === 'string')
+        return { verb: item, value: null };
+    const keys = item && typeof item === 'object' ? Object.keys(item) : [];
+    if (keys.length !== 1)
+        throw new Error(`${where} must be one step, as \`verb: value\`, not ${JSON.stringify(item)}`);
+    return { verb: keys[0], value: item[keys[0]] };
+};
+const stepsOf = (list, file, section) => {
+    if (list === undefined || list === null)
+        return [];
+    if (!Array.isArray(list))
+        throw new Error(`${file}: ${section} is not a list`);
+    return list.flatMap((item, i) => {
+        const entry = item;
+        if (entry && typeof entry === 'object' && 'do' in entry) {
+            if (typeof entry.on !== 'string')
+                throw new Error(`${file}: ${section}[${i}] has \`do\` without \`on\``);
+            const inner = Array.isArray(entry.do) ? entry.do : [entry.do];
+            return inner.map((s, j) => ({ ...stepOf(s, `${file}: ${section}[${i}].do[${j}]`), on: entry.on }));
+        }
+        return [stepOf(item, `${file}: ${section}[${i}]`)];
+    });
+};
+export const parseCase = (text, file) => {
+    const match = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/.exec(text);
+    if (!match)
+        throw new Error(`${file}: no frontmatter (a case starts with --- and its id)`);
+    const meta = (parse(match[1]) ?? {});
+    const body = (parse(match[2]) ?? {});
+    const id = typeof meta.id === 'string' ? meta.id : file.replace(/^.*\//, '').replace(/\.md$/, '');
+    return {
+        file,
+        id,
+        title: typeof meta.title === 'string' ? meta.title : undefined,
+        meta,
+        setup: stepsOf(body.setup, file, 'setup'),
+        steps: stepsOf(body.steps, file, 'steps'),
+        expected: typeof body.expected === 'string' ? body.expected.trim() : undefined,
+    };
+};
+const variantsOf = (text) => {
+    const head = /^---\n([\s\S]*?)\n---\n/.exec(text);
+    const matrix = head ? (parse(head[1]) ?? {}).matrix : undefined;
+    if (!matrix || typeof matrix !== 'object' || Array.isArray(matrix) || Object.keys(matrix).length === 0)
+        return [];
+    return Object.entries(matrix).reduce((combos, [key, values]) => combos.flatMap((combo) => (Array.isArray(values) ? values : [values]).map((v) => ({ ...combo, [key]: v }))), [{}]);
+};
+export const readCases = (file) => {
+    const text = fs.readFileSync(file, 'utf8');
+    const variants = variantsOf(text);
+    if (variants.length === 0)
+        return [parseCase(text, file)];
+    return variants.map((variant) => {
+        const filled = text.replace(/\{\{\s*matrix\.(\w+)\s*\}\}/g, (ref, key) => {
+            if (!(key in variant))
+                throw new Error(`${file}: ${ref} is not in its matrix`);
+            return String(variant[key]);
+        });
+        const c = parseCase(filled, file);
+        return {
+            ...c,
+            id: `${c.id}[${Object.entries(variant)
+                .map(([k, v]) => `${k}=${String(v)}`)
+                .join(',')}]`,
+        };
+    });
+};
+/** `a.b.0.c` into a value; `a.*.b` collects b from every element of the list a. */
+export const dig = (json, dotted) => {
+    const star = dotted.indexOf('.*.');
+    if (star !== -1) {
+        const list = dig(json, dotted.slice(0, star));
+        return Array.isArray(list) ? list.map((item) => dig(item, dotted.slice(star + 3))) : undefined;
+    }
+    let current = json;
+    for (const key of dotted.split('.')) {
+        if (Array.isArray(current))
+            current = current[Number(key)];
+        else if (current && typeof current === 'object')
+            current = current[key];
+        else
+            return undefined;
+    }
+    return current;
+};
+const LETTERS = 'abcdefghijklmnopqrstuvwxyz';
+const random = (kind) => {
+    if (kind === 'letters')
+        return Array.from({ length: 6 }, () => LETTERS[Math.floor(Math.random() * 26)]).join('');
+    if (kind === 'digits')
+        return Array.from({ length: 6 }, () => Math.floor(Math.random() * 10)).join('');
+    return undefined;
+};
+/** `{{alias.path}}` from what earlier steps answered, `{{random.letters}}`, `{{env.NAME}}`. */
+export const interpolate = (value, scope) => {
+    if (typeof value === 'string') {
+        const whole = /^\{\{\s*([\w-]+)\.([\w.*-]+)\s*\}\}$/.exec(value);
+        const lookup = (name, path) => {
+            if (name === 'random')
+                return random(path);
+            if (name === 'env')
+                return process.env[path];
+            if (!(name in scope))
+                throw new Error(`no alias '${name}' (add \`as: ${name}\` to the step that creates it)`);
+            return dig(scope[name], path);
+        };
+        // A value that is one reference keeps its type; inside a sentence it is text.
+        if (whole) {
+            const found = lookup(whole[1], whole[2]);
+            if (found === undefined || found === null)
+                throw new Error(`${value} is empty`);
+            return found;
+        }
+        return value.replace(/\{\{\s*([\w-]+)\.([\w.*-]+)\s*\}\}/g, (ref, name, path) => {
+            const found = lookup(name, path);
+            if (found === undefined || found === null)
+                throw new Error(`${ref} is empty`);
+            return typeof found === 'object' ? JSON.stringify(found) : String(found);
+        });
+    }
+    if (Array.isArray(value))
+        return value.map((v) => interpolate(v, scope));
+    if (value && typeof value === 'object')
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, interpolate(v, scope)]));
+    return value;
+};
+const MATCHERS = ['equals', 'near', 'gte', 'lte', 'present', 'absent', 'includes', 'matches'];
+export const matcherOf = (params) => {
+    const found = MATCHERS.filter((m) => m in params);
+    return found.length ? Object.fromEntries(found.map((m) => [m, params[m]])) : undefined;
+};
+const num = (v) => {
+    const n = typeof v === 'number' ? v : typeof v === 'string' && v.trim() !== '' ? Number(v) : Number.NaN;
+    return Number.isFinite(n) ? n : undefined;
+};
+/** Whether a value read from the backend is what the case said it would be. */
+export const matches = (got, m) => {
+    if ('equals' in m) {
+        const a = num(got);
+        const b = num(m.equals);
+        return a !== undefined && b !== undefined ? a === b : String(got) === String(m.equals);
+    }
+    if ('near' in m)
+        return num(got) !== undefined && num(m.near) !== undefined && Math.abs(num(got) - num(m.near)) <= 0.01;
+    if ('gte' in m)
+        return num(got) !== undefined && num(got) >= (num(m.gte) ?? Number.NaN);
+    if ('lte' in m)
+        return num(got) !== undefined && num(got) <= (num(m.lte) ?? Number.NaN);
+    if ('present' in m)
+        return m.present ? got !== undefined && got !== null : got === undefined || got === null;
+    if ('absent' in m)
+        return m.absent ? got === undefined || got === null : got !== undefined && got !== null;
+    if ('includes' in m)
+        return Array.isArray(got) ? got.some((v) => String(v).includes(String(m.includes))) : String(got ?? '').includes(String(m.includes));
+    if ('matches' in m)
+        return new RegExp(m.matches).test(String(got ?? ''));
+    return false;
+};

package/lib/cases/runner.d.ts

@@ -0,0 +1,61 @@
+import { type AppEvent, type RunEvent } from '../knowledge/events.js';
+import { type Base, type Command } from '../registry.js';
+import type { Fixtures, FixturesConfig } from './fixtures.js';
+import { type Case, type StepValue } from './format.js';
+export type CasesConfig = {
+    /** The folder of the file that declared this, set when the configuration is read. */
+    base?: string;
+    /** Where cases live (default `cases`). */
+    dir?: string;
+    /** Where the flows a case runs live (default `flows`). */
+    flows?: string;
+    /** The long-lived command that answers fixture steps, as JSON lines. */
+    fixtures?: FixturesConfig;
+    /** The fixture `assert` reads the backend through (default `inspect`). */
+    inspect?: string;
+    /** `{ "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. */
+    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;
+    }[];
+};
+export type StepReport = {
+    step: string;
+    status: 'passed' | 'failed' | 'skipped';
+    ms: number;
+    error?: string;
+};
+export type CaseReport = {
+    id: string;
+    title?: string;
+    file: string;
+    result: 'passed' | 'failed';
+    ms: number;
+    steps: StepReport[];
+    /** 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. */
+    events?: RunEvent[];
+};
+export type RunOptions = {
+    base: Base;
+    config: CasesConfig;
+    fixtures?: Fixtures;
+    dry?: boolean;
+    events?: boolean;
+    log?: (line: string) => void;
+};
+/** What a buffer holds that it did not before, whichever end it grows from. */
+export declare const newSince: (before: AppEvent[], now: AppEvent[]) => AppEvent[];
+/** A step's value as the argv of the command it names: what matches a positional by name goes in place, the rest are flags. */
+export declare const argvFor: (command: Command, value: StepValue) => string[];
+export declare const runCase: (c: Case, options: RunOptions) => Promise<CaseReport>;