lynkeus 0.2.0

package/lib/cases/runner.js

@@ -0,0 +1,590 @@
+/**
+ * Runs a case's setup, then its steps, stopping at the first that fails. The
+ * app is driven through the terminal's own commands on one connection; the
+ * backend is prepared and read through the project's fixtures. How this app
+ * logs in or what a user is belongs to the project, as macros and fixtures.
+ */
+import { exec } from 'node:child_process';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { describeScreen } from '../device/driver.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 { dig, interpolate, matcherOf, matches, stepOf } from './format.js';
+/** What a buffer holds that it did not before, whichever end it grows from. */
+export const newSince = (before, now) => {
+    if (now.length < before.length)
+        return now;
+    if (now.length === before.length)
+        return [];
+    const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+    const extra = now.length - before.length;
+    if (same(now.slice(0, before.length), before))
+        return now.slice(before.length);
+    if (same(now.slice(extra), before))
+        return now.slice(0, extra).reverse();
+    return now;
+};
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const run = promisify(exec);
+const label = (step) => {
+    const value = step.value;
+    if (value === null || value === undefined)
+        return step.verb;
+    const text = typeof value === 'object'
+        ? Object.entries(value)
+            .map(([k, v]) => `${k}: ${typeof v === 'object' ? JSON.stringify(v) : String(v)}`)
+            .join(', ')
+        : String(value);
+    return `${step.verb} ${text}`.slice(0, 140);
+};
+const FLAG_NAMES = {
+    within: 'in',
+    advanceMs: 'advance',
+    timeoutMs: 'timeout',
+    delayMs: 'delay',
+    durationMs: 'duration',
+    holdMs: 'hold',
+};
+/** `wait` holds when the case passed it; `method=phone` when it passed that value. */
+const holds = (condition, param, ran = new Set()) => {
+    if (condition.startsWith('ran:'))
+        return ran.has(condition.slice(4));
+    const [name, value] = condition.split('=', 2);
+    const given = param[name];
+    if (value !== undefined)
+        return String(given) === value;
+    return given !== undefined && given !== null && given !== false && given !== 'none';
+};
+/** 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 const argvFor = (command, value) => {
+    const argv = command.name.split(' ');
+    if (value === null || value === undefined)
+        return argv;
+    if (typeof value === 'string' && command.flags?.[value]?.type === 'boolean')
+        return [...argv, `--${value}`];
+    if (typeof value !== 'object' || Array.isArray(value))
+        return [...argv, ...(Array.isArray(value) ? value.map(String) : [String(value)])];
+    const given = { ...value };
+    const positionals = command.positionals ?? [];
+    // A case says `target` or `request` where a command may call its first argument something else.
+    const first = positionals[0]?.name;
+    for (const alias of ['target', 'request', 'route', 'url', 'state', 'text']) {
+        if (first && !(first in given) && alias in given && !positionals.some((p) => p.name === alias) && !(alias in (command.flags ?? {}))) {
+            given[first] = given[alias];
+            delete given[alias];
+            break;
+        }
+    }
+    for (const p of positionals) {
+        if (!(p.name in given)) {
+            if (positionals.slice(positionals.indexOf(p) + 1).some((later) => later.name in given))
+                throw new Error(`${command.name} needs ${p.name}`);
+            break;
+        }
+        const v = given[p.name];
+        argv.push(typeof v === 'object' ? JSON.stringify(v) : String(v));
+        delete given[p.name];
+    }
+    for (const [key, v] of Object.entries(given)) {
+        const flag = FLAG_NAMES[key] ?? key;
+        if (!(flag in (command.flags ?? {})))
+            throw new Error(`${command.name} has no ${key}`);
+        if (v === false || v === undefined || v === null)
+            continue;
+        if (v === true)
+            argv.push(`--${flag}`);
+        else if (Array.isArray(v))
+            for (const item of v)
+                argv.push(`--${flag}`, String(item));
+        else
+            argv.push(`--${flag}`, typeof v === 'object' ? JSON.stringify(v) : String(v));
+    }
+    return argv;
+};
+const presented = (screen) => screen.elements.filter((e) => !e.hidden || e.hidden === 'inert');
+const textOf = (e) => e.text ?? e.value ?? e.accessibilityLabel ?? '';
+const requestMatches = (event, wanted, status) => {
+    if (event.kind !== 'request')
+        return false;
+    const [method, route] = wanted.includes(' ') ? wanted.split(/\s+/, 2) : ['*', wanted];
+    let pathname = event.url;
+    try {
+        pathname = new URL(event.url).pathname;
+    }
+    catch {
+        pathname = event.url.split('?')[0];
+    }
+    if (method !== '*' && event.method.toUpperCase() !== method.toUpperCase())
+        return false;
+    if (!pathname.endsWith(route))
+        return false;
+    return status === undefined ? true : event.status === status;
+};
+const BUILT_IN = ['press', 'type', 'swipe', 'see', 'requests', 'wait', 'nav', 'call', 'run', 'events', 'event'];
+const unknownStep = (step, config) => {
+    if (config.macros?.[step.verb] || !step.verb.startsWith('app.'))
+        return undefined;
+    const name = step.verb.slice(4);
+    if (BUILT_IN.includes(name))
+        return undefined;
+    const command = find(name) ?? find(`os ${name}`);
+    if (!command)
+        return `${step.verb} is not a step: lynkeus has no command ${name}, and the project declares no macro for it`;
+    try {
+        argvFor(command, step.value);
+    }
+    catch (error) {
+        return error.message;
+    }
+    return undefined;
+};
+export const runCase = async (c, options) => {
+    const { base, config } = options;
+    const log = options.log ?? (() => undefined);
+    const scope = {};
+    const ran = new Set();
+    const latest = {};
+    const started = Date.now();
+    const steps = [];
+    let mark;
+    let why;
+    const recorded = [];
+    let buffer = [];
+    // Read, never emptied: a case may be asserting on the buffer.
+    const collect = async (index) => {
+        if (!options.events)
+            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 });
+        buffer = now;
+    };
+    const device = () => base.device();
+    const sinceMark = async () => (await (await device()).trace(mark)).events;
+    const cli = async (argv) => {
+        const outcome = await execute(argv, base);
+        if (outcome.error || outcome.code !== 0) {
+            why = outcome.why;
+            throw new Error(outcome.error || outcome.text || `${argv.join(' ')} failed`);
+        }
+        return outcome;
+    };
+    const withRefs = (params) => {
+        const out = { ...params };
+        for (const [param, field] of Object.entries(config.refs ?? {})) {
+            const alias = out[param];
+            delete out[param];
+            if (typeof alias === 'string') {
+                if (!(alias in scope))
+                    throw new Error(`no alias '${alias}'`);
+                const found = dig(scope[alias], field);
+                if (found === undefined)
+                    throw new Error(`alias '${alias}' has no ${field}`);
+                out[field] = found;
+            }
+            else if (!(field in out) && latest[field] !== undefined)
+                out[field] = latest[field];
+        }
+        return out;
+    };
+    const fixture = async (name, value) => {
+        if (!options.fixtures)
+            throw new Error(`${name} is not a step lynkeus has, and the project declares no fixtures (cases.fixtures in lynkeus.config.json)`);
+        const given = value && typeof value === 'object' && !Array.isArray(value) ? { ...value } : {};
+        const as = typeof given.as === 'string' ? given.as : undefined;
+        delete given.as;
+        const answer = await options.fixtures.call(name, withRefs(given));
+        if (as)
+            scope[as] = answer;
+        for (const field of Object.values(config.refs ?? {}))
+            if (answer[field] !== undefined)
+                latest[field] = answer[field];
+    };
+    const assert = async (value) => {
+        const params = (value ?? {});
+        const matcher = matcherOf(params);
+        if (!matcher || typeof params.path !== 'string')
+            throw new Error('assert needs a path and a matcher (equals, includes, gte, …)');
+        if (!options.fixtures)
+            throw new Error('assert reads the backend through fixtures, and the project declares none');
+        const rest = Object.fromEntries(Object.entries(params).filter(([k]) => k !== 'path' && !(k in matcher)));
+        const answer = await options.fixtures.call(config.inspect ?? 'inspect', withRefs(rest));
+        const got = dig(answer, params.path);
+        if (!matches(got, matcher))
+            throw new Error(`${params.path} is ${JSON.stringify(got)}`);
+    };
+    const targetIn = (params) => {
+        const raw = typeof params.target === 'string' ? params.target : params.testId ? `#${String(params.testId)}` : undefined;
+        return raw === undefined ? undefined : scopedTarget(raw, { in: params.within, nth: params.nth });
+    };
+    /** Every condition a `see` names, read off one screen and the trace since the mark; what is missing, or nothing. */
+    const seen = async (params) => {
+        const d = await device();
+        const screen = await d.screen();
+        const elements = presented(screen);
+        if (typeof params.route === 'string' && screen.route !== params.route)
+            return `on ${screen.route ?? 'no route'}, not ${params.route}`;
+        if ('layer' in params) {
+            const open = screen.presenting;
+            const wanted = params.layer;
+            const ok = wanted === true ? !!open : wanted === false ? !open : !!open && `${open.testId ?? ''}`.includes(String(wanted));
+            if (!ok)
+                return wanted === false ? 'a layer is open' : `no layer${wanted === true ? '' : ` ${String(wanted)}`} is open`;
+        }
+        const target = targetIn(params);
+        const text = typeof params.text === 'string' ? params.text : undefined;
+        if (target) {
+            const found = (await d.server.call('find', target));
+            if (!found || (found.hidden && found.hidden !== 'inert'))
+                return `not on screen: ${JSON.stringify(target)}`;
+            if (text !== undefined && !textOf(found).includes(text) && !elements.some((e) => e.parent === found.i && textOf(e).includes(text))) {
+                return `${JSON.stringify(target)} says ${JSON.stringify(textOf(found))}, not ${JSON.stringify(text)}`;
+            }
+        }
+        else if (text !== undefined && !elements.some((e) => textOf(e).includes(text)))
+            return `not on screen: ${JSON.stringify(text)}`;
+        if (typeof params.request === 'string') {
+            const status = typeof params.status === 'number' ? params.status : undefined;
+            if (!(await sinceMark()).some((e) => requestMatches(e, params.request, status)))
+                return `not requested since the mark: ${params.request}`;
+        }
+        if (typeof params.event === 'string') {
+            const wanted = (params.props ?? params.properties ?? {});
+            const events = normalizeEvents(await d.command('events'));
+            const hit = events.some((e) => e.name === params.event && Object.entries(wanted).every(([k, v]) => String(e.props?.[k]) === String(v)));
+            if (!hit)
+                return `no ${params.event} event${Object.keys(wanted).length ? ` with ${JSON.stringify(wanted)}` : ''}`;
+        }
+        return undefined;
+    };
+    const see = async (value) => {
+        const params = typeof value === 'string' ? { target: value } : (value ?? {});
+        const absent = params.absent === true;
+        const wait = typeof params.timeoutMs === 'number' ? params.timeoutMs : 3000;
+        const deadline = Date.now() + wait;
+        const hard = Date.now() + Math.max(wait, 12_000);
+        while (true) {
+            await interrupted(value);
+            const missing = await seen(params);
+            if (absent ? missing !== undefined : missing === undefined)
+                return;
+            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 } }).trim()}` : missing);
+            await sleep(150);
+        }
+    };
+    const waitForRequest = async (params) => {
+        const timeoutMs = typeof params.timeoutMs === 'number' ? params.timeoutMs : 10_000;
+        const deadline = Date.now() + timeoutMs;
+        const status = typeof params.status === 'number' ? params.status : undefined;
+        while (true) {
+            const events = await sinceMark();
+            const hit = events.some((e) => requestMatches(e, String(params.request), status) && (status !== undefined || (e.kind === 'request' && String(e.status).startsWith('2'))));
+            if (hit)
+                return;
+            if (Date.now() > deadline)
+                throw new Error(`no ${status ?? '2xx'} ${String(params.request)} within ${timeoutMs} ms`);
+            await sleep(300);
+        }
+    };
+    const press = async (value) => {
+        const params = typeof value === 'string' ? { target: value } : (value ?? {});
+        const target = targetIn(params);
+        if (!target)
+            throw new Error('app.press needs a target');
+        const d = await device();
+        if (params.optional === true) {
+            const there = await d.waitFor({ target, timeoutMs: 300 }).then(() => true, () => false);
+            if (!there)
+                return 'skipped';
+        }
+        // The control may still be arriving, or disabled while what it depends on loads.
+        const deadline = Date.now() + (typeof params.timeoutMs === 'number' ? params.timeoutMs : 3000);
+        const hard = Date.now() + 15_000;
+        while (Date.now() < hard && 'testId' in target) {
+            const found = (await d.server.call('find', target));
+            if (found?.enabled)
+                break;
+            if (Date.now() > deadline && !(await d.screen()).busy)
+                break;
+            await sleep(200);
+        }
+        const { optional: _optional, timeoutMs: _timeout, ...rest } = params;
+        await cli(argvFor(find('press'), rest));
+        return undefined;
+    };
+    const call = async (params) => {
+        if (!params?.command)
+            throw new Error('app.call needs a command');
+        const d = await device();
+        const deadline = Date.now() + (typeof params.timeoutMs === 'number' ? params.timeoutMs : 3000);
+        const expect = (params.expect ?? {});
+        for (;;) {
+            const answer = await d.command(String(params.command), params.params);
+            if (typeof params.as === 'string')
+                scope[params.as] = answer;
+            const miss = Object.entries(expect).find(([p, wanted]) => {
+                const got = dig(answer, p);
+                return wanted === null ? got !== undefined && got !== null : String(got) !== String(wanted);
+            });
+            if (!miss)
+                return;
+            if (Date.now() > deadline)
+                throw new Error(`${String(params.command)}: ${miss[0]} is ${JSON.stringify(dig(answer, miss[0]))}, expected ${JSON.stringify(miss[1])}`);
+            await sleep(250);
+        }
+    };
+    // Nobody acts on a screen that is still asking for what it shows: a press
+    // that lands before the data does is a different case from the one written.
+    const ready = async () => {
+        const d = await device();
+        const deadline = Date.now() + 5000;
+        while ((await d.screen()).busy && Date.now() < deadline)
+            await sleep(100);
+    };
+    let handling = false;
+    const interrupted = async (value) => {
+        if (handling || !config.interruptions?.length)
+            return;
+        const d = await device();
+        const about = JSON.stringify(value ?? '');
+        for (const one of config.interruptions) {
+            if (one.unless && new RegExp(one.unless, 'i').test(about))
+                continue;
+            const target = parseTarget(one.see);
+            const found = (await d.server.call('find', target).catch(() => null));
+            if (!found || found.hidden)
+                continue;
+            handling = true;
+            try {
+                for (const raw of one.do)
+                    await perform(stepOf(raw));
+            }
+            catch (error) {
+                const still = (await d.server.call('find', target).catch(() => null));
+                if (still && !still.hidden)
+                    throw error;
+            }
+            finally {
+                handling = false;
+            }
+        }
+    };
+    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;
+        switch (name) {
+            case 'press': {
+                await interrupted(value);
+                await ready();
+                const outcome = await press(value);
+                // One touch, one render: the next step reads what this one caused.
+                await d.idle({ quietMs: 50, timeoutMs: 400 }).catch(() => undefined);
+                return outcome;
+            }
+            case 'type':
+            case 'swipe':
+                await interrupted(value);
+                await ready();
+                await cli(argvFor(find(name), value));
+                // A pager on a device keeps moving after the finger lifts, and swallows a swipe sent into that momentum.
+                if (name === 'swipe' && d.server.hello?.native)
+                    await d.idle({ quietMs: 700, timeoutMs: 8000 }).catch(() => undefined);
+                return undefined;
+            case 'see':
+                await see(value);
+                return undefined;
+            case 'requests':
+                mark = (await d.trace()).last;
+                return undefined;
+            case 'wait': {
+                if (typeof value === 'number' || (typeof value === 'string' && /^\d+$/.test(value)))
+                    await sleep(Number(value));
+                else if (params?.request)
+                    await waitForRequest(params);
+                else {
+                    if (config.interruptions?.length) {
+                        const asked = typeof value === 'string' ? { what: value } : { ...(params ?? {}) };
+                        const deadline = Date.now() + (typeof asked.timeoutMs === 'number' ? asked.timeoutMs : 10_000);
+                        for (;;) {
+                            await interrupted(value);
+                            const left = deadline - Date.now();
+                            const outcome = await execute(argvFor(find('wait'), { ...asked, timeoutMs: Math.max(Math.min(left, 1000), 100) }), base);
+                            if (!outcome.error && outcome.code === 0)
+                                break;
+                            if (Date.now() >= deadline) {
+                                why = outcome.why;
+                                throw new Error(outcome.error ?? outcome.text ?? 'wait failed');
+                            }
+                        }
+                    }
+                    else
+                        await cli(argvFor(find('wait'), value));
+                    // A screen that just arrived on a device is still sliding in, which no render shows: a press then lands on the one it left.
+                    const what = typeof value === 'string' ? value : String(params?.what ?? '');
+                    if (d.server.hello?.native && isRoute(what))
+                        await d.idle({ quietMs: 700, timeoutMs: 8000 }).catch(() => undefined);
+                }
+                return undefined;
+            }
+            case 'nav': {
+                const route = typeof value === 'string' ? value : String(params?.route);
+                await cli(argvFor(find('nav'), value));
+                await d.waitFor({ route, timeoutMs: 8000 });
+                await d.idle({ quietMs: 300, timeoutMs: 8000 });
+                return undefined;
+            }
+            case 'call':
+                await call(params);
+                return undefined;
+            case 'run': {
+                const flow = typeof value === 'string' ? value : String(params?.flow);
+                const file = path.isAbsolute(flow) ? flow : path.resolve(config.base ?? base.root, config.flows ?? 'flows', flow);
+                const vars = Object.entries((params?.vars ?? {})).flatMap(([k, v]) => ['--var', `${k}=${String(v)}`]);
+                await cli(['run', file, ...vars]);
+                return undefined;
+            }
+            case 'events':
+                await collect(steps.length + 1);
+                await d.command('events', { clear: true });
+                buffer = [];
+                return undefined;
+            case 'event':
+                await see({ ...(params ?? {}), event: typeof value === 'string' ? value : params?.name, name: undefined });
+                return undefined;
+            default: {
+                const command = find(name) ?? find(`os ${name}`);
+                if (!command)
+                    throw new Error(`app.${name} is not a step: lynkeus has no command ${name}, and the project declares no macro for it`);
+                await cli(argvFor(command, value));
+                return undefined;
+            }
+        }
+    };
+    const shell = async (value) => {
+        const params = typeof value === 'string' ? { run: value } : (value ?? {});
+        const { stdout } = await run(String(params.run), { cwd: config.base ?? base.root, env: process.env, timeout: 120_000 });
+        if (typeof params.as !== 'string')
+            return;
+        const json = /\{[\s\S]*\}/.exec(stdout)?.[0];
+        scope[params.as] = json ? JSON.parse(json) : { out: stdout.trim() };
+    };
+    const macro = async (steps, value) => {
+        const given = value && typeof value === 'object' && !Array.isArray(value) ? value : { value };
+        // A parameter that names an alias is that alias: `as: u` makes `{{param.as.user_id}}` the user's.
+        const param = Object.fromEntries(Object.entries(given).map(([k, v]) => [k, typeof v === 'string' && v in scope ? scope[v] : v]));
+        const outer = scope.param;
+        scope.param = param;
+        try {
+            for (const raw of steps) {
+                const entry = raw;
+                if ('do' in entry) {
+                    const all = (v) => (Array.isArray(v) ? v : [v]).map(String);
+                    if ('when' in entry && !all(entry.when).every((c) => holds(c, param, ran)))
+                        continue;
+                    if ('unless' in entry && all(entry.unless).some((c) => holds(c, param, ran)))
+                        continue;
+                    if ('on' in entry && !(await runsHere(String(entry.on))))
+                        continue;
+                    await perform(stepOf(entry.do));
+                }
+                else
+                    await perform(stepOf(entry));
+            }
+        }
+        finally {
+            scope.param = outer;
+        }
+    };
+    const runsHere = async (on) => {
+        const hello = (await device()).server.hello;
+        const native = !!hello?.native;
+        if (on === 'device')
+            return native;
+        if (on === 'headless')
+            return !native;
+        return hello?.platform === on;
+    };
+    const perform = async (step) => {
+        if (step.on && !(await runsHere(step.on)))
+            return 'skipped';
+        ran.add(step.verb);
+        const value = interpolate(step.value, scope);
+        const custom = config.macros?.[step.verb];
+        if (custom) {
+            await macro(custom, value);
+            return undefined;
+        }
+        if (step.verb.startsWith('app.'))
+            return app(step.verb.slice(4), value);
+        if (step.verb === 'assert')
+            return void (await assert(value));
+        if (step.verb === 'exec')
+            return void (await shell(value));
+        return void (await fixture(step.verb, value));
+    };
+    if (options.events && !options.dry) {
+        const d = await base.device().catch(() => undefined);
+        if (d?.server.connected)
+            buffer = normalizeEvents(await d.command('events').catch(() => []));
+    }
+    let failed = false;
+    for (const step of [...c.setup, ...c.steps]) {
+        const text = label(step);
+        if (failed) {
+            steps.push({ step: text, status: 'skipped', ms: 0 });
+            continue;
+        }
+        if (options.dry) {
+            const unknown = unknownStep(step, config);
+            steps.push({ step: text, status: unknown ? 'failed' : 'passed', ms: 0, ...(unknown ? { error: unknown } : {}) });
+            if (unknown)
+                log(`  ❌ ${text}  — ${unknown}`);
+            continue;
+        }
+        const t0 = Date.now();
+        try {
+            const outcome = await perform(step);
+            if (step.verb.startsWith('app.') || config.macros?.[step.verb])
+                await collect(steps.length + 1);
+            steps.push({ step: text, status: outcome === 'skipped' ? 'skipped' : 'passed', ms: Date.now() - t0 });
+            log(`  ${outcome === 'skipped' ? '⏭️' : '✅'} ${text}  (${Date.now() - t0}ms)`);
+        }
+        catch (error) {
+            failed = true;
+            const message = error instanceof Error ? error.message : String(error);
+            steps.push({ step: text, status: 'failed', ms: Date.now() - t0, error: message });
+            log(`  ❌ ${text}  — ${message.split('\n')[0]}  (${Date.now() - t0}ms)`);
+        }
+    }
+    if (options.dry)
+        failed = steps.some((s) => s.status === 'failed');
+    const report = { id: c.id, title: c.title, file: c.file, result: failed ? 'failed' : 'passed', ms: Date.now() - started, steps };
+    if (options.events)
+        report.events = recorded;
+    if (failed && !options.dry) {
+        const d = await device().catch(() => undefined);
+        if (d?.server.connected) {
+            const screen = await d.screen().catch(() => undefined);
+            const events = await d.trace(mark).catch(() => undefined);
+            report.evidence = {
+                screen: screen ? describeScreen(screen, { limit: 40 }) : undefined,
+                requests: events?.events.flatMap((e) => (e.kind === 'request' ? [`${e.status ?? '…'} ${e.method} ${e.url}`] : [])).slice(-8),
+                why,
+            };
+        }
+    }
+    return report;
+};

package/lib/cases/templates.d.ts

@@ -0,0 +1,20 @@
+/**
+ * What `lynkeus case init` writes: one case to copy from, the reference of the
+ * 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? }` | Waits for the control to be there and enabled. `optional` presses only if it is on screen. |\n| `app.type` | `{ text, target?, submit?, clear? }` | `target` is tapped first; `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` | From here on, `request` only counts what the app asks for. |\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`, `\"text\"`, an index or `x,y`.\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\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  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;
+    flows: string;
+    fixtures: {
+        command: string;
+    };
+    inspect: string;
+    refs: {
+        user: string;
+    };
+    macros: {};
+};