lynkeus 0.2.0

package/src/__tests__/targets.test.ts

@@ -0,0 +1,132 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+import type { Screen } from 'lynkeus-protocol';
+
+import { describeScreen } from '../device/driver.js';
+import { parseTarget, scopedTarget } from '../targets.js';
+
+test('a #-prefixed string is a testId', () => {
+  assert.deepEqual(parseTarget('#next-button'), { testId: 'next-button' });
+});
+test('an x,y pair is a point', () => {
+  assert.deepEqual(parseTarget('100,200'), { x: 100, y: 200 });
+});
+test('a bare integer is an index', () => {
+  assert.deepEqual(parseTarget('12'), { i: 12 });
+});
+test('anything else is text', () => {
+  assert.deepEqual(parseTarget('Some label'), { text: 'Some label' });
+});
+test('a testId that contains a comma is still a testId, not a point', () => {
+  assert.deepEqual(parseTarget('#a,b'), { testId: 'a,b' });
+});
+
+test('describeScreen prints the value a QR image carries', () => {
+  const screen = {
+    route: 'X',
+    path: ['X'],
+    commit: 1,
+    busy: false,
+    window: { w: 390, h: 844 },
+    costMs: 1,
+    elements: [{ i: 0, kind: 'image', frame: { x: 0, y: 0, w: 168, h: 169 }, enabled: true, depth: 0, accessibilityLabel: 'qr', value: 'QR-TEST-0001' }],
+  } as unknown as Screen;
+  assert.match(describeScreen(screen), /image .*value="QR-TEST-0001"/);
+});
+test('describeScreen lists a view with a testID and leaves plain layout out', () => {
+  const screen = {
+    route: 'X',
+    path: ['X'],
+    commit: 1,
+    busy: false,
+    window: { w: 390, h: 844 },
+    costMs: 1,
+    elements: [
+      { i: 0, kind: 'view', frame: { x: 0, y: 0, w: 390, h: 844 }, enabled: true, depth: 0 },
+      { i: 1, kind: 'view', frame: { x: 0, y: 0, w: 390, h: 400 }, enabled: true, depth: 1, testId: 'intro-page-advances' },
+    ],
+  } as unknown as Screen;
+  const text = describeScreen(screen);
+  assert.match(text, /view +#intro-page-advances/);
+  assert.doesNotMatch(text, /^0? ?view$/m);
+});
+test('describeScreen leaves out what is not presented, counts it, and lists it with --all', () => {
+  const el = (i: number, over: object) => ({ i, kind: 'button', frame: { x: 0, y: 0, w: 100, h: 40 }, enabled: true, depth: 0, ...over });
+  const screen = {
+    route: 'X',
+    path: ['X'],
+    commit: 7,
+    busy: false,
+    window: { w: 390, h: 844 },
+    costMs: 3,
+    elements: [
+      el(0, { testId: 'tab-a', hidden: 'a11y' }),
+      el(1, { testId: 'behind', hidden: 'behind-overlay' }),
+      el(2, { testId: 'slide', hidden: 'inert' }),
+      el(3, { testId: 'close', enabled: false }),
+    ],
+  } as unknown as Screen;
+  const text = describeScreen(screen);
+  assert.equal(text.split('\n')[0] ?? '', 'X · 2 hidden: 1 a11y, 1 behind-overlay');
+  assert.doesNotMatch(text, /#tab-a|#behind/);
+  assert.match(text, /^button #slide ~inert$/m);
+  assert.match(text, /^button #close !disabled$/m);
+  assert.match(describeScreen(screen, { all: true }), /#behind ~behind-overlay/);
+  assert.match(describeScreen(screen, { frames: true }), /#slide ~inert @50,20$/m);
+  assert.match(describeScreen(screen, { verbose: true }).split('\n')[0] ?? '', /commit=7 3ms/);
+});
+test("describeScreen leaves a button's icon out", () => {
+  const screen = {
+    route: 'X',
+    path: ['X'],
+    commit: 1,
+    busy: false,
+    window: { w: 390, h: 844 },
+    costMs: 1,
+    elements: [
+      { i: 0, kind: 'button', frame: { x: 0, y: 0, w: 100, h: 40 }, enabled: true, depth: 0, testId: 'open' },
+      { i: 1, kind: 'view', frame: { x: 0, y: 0, w: 20, h: 20 }, enabled: true, depth: 1, testId: 'SvgArrow', parent: 0 },
+      { i: 2, kind: 'view', frame: { x: 0, y: 50, w: 20, h: 20 }, enabled: true, depth: 0, testId: 'page-marker' },
+    ],
+  } as unknown as Screen;
+  assert.doesNotMatch(describeScreen(screen), /SvgArrow/);
+  assert.match(describeScreen(screen), /#page-marker/);
+  assert.match(describeScreen(screen, { all: true }), /SvgArrow/);
+});
+test('describeScreen gives an index only to what cannot be named apart', () => {
+  const el = (i: number, over: object) => ({ i, kind: 'button', frame: { x: 0, y: 0, w: 100, h: 40 }, enabled: true, depth: 0, ...over });
+  const screen = {
+    route: 'X',
+    path: ['X'],
+    commit: 1,
+    busy: false,
+    window: { w: 390, h: 844 },
+    costMs: 1,
+    elements: [
+      el(0, { testId: 'save' }),
+      el(1, { testId: 'like' }),
+      el(2, { testId: 'like' }),
+      el(3, { kind: 'text', text: 'Hello' }),
+      el(4, { kind: 'view', testId: 'marker', accessibilityLabel: 'marker' }),
+      el(5, {}),
+    ],
+  } as unknown as Screen;
+  assert.deepEqual(describeScreen(screen).split('\n').slice(1), [
+    'button #save',
+    '1 button #like',
+    '2 button #like',
+    'text "Hello"',
+    'view #marker',
+    '5 button',
+  ]);
+});
+test('a [n] suffix picks the nth match of a testId or text', () => {
+  assert.deepEqual(parseTarget('#field[2]'), { testId: 'field', nth: 2 });
+  assert.deepEqual(parseTarget('Ciudad[0]'), { text: 'Ciudad', nth: 0 });
+});
+test('--in and --nth narrow a target', () => {
+  assert.deepEqual(scopedTarget('#like-message-button', { in: 'hi from Ana' }), { testId: 'like-message-button', within: { text: 'hi from Ana' } });
+  assert.deepEqual(scopedTarget('#like-message-button', { in: '#feed', nth: 2 }), { testId: 'like-message-button', within: { testId: 'feed' }, nth: 2 });
+  assert.deepEqual(scopedTarget('100,200', { in: '#feed' }), { x: 100, y: 200 });
+});

package/src/args.ts

@@ -0,0 +1,111 @@
+/**
+ * Booleans never consume the next token (`--direct a.ts` keeps `a.ts`),
+ * `--no-<flag>` clears one, and a repeated list flag collects.
+ */
+export type FlagSpec = {
+  type: 'string' | 'number' | 'boolean' | 'list';
+  help: string;
+  default?: string | number | boolean;
+  /** The placeholder in usage: `--timeout <ms>`. */
+  value?: string;
+};
+
+export type PositionalSpec = {
+  name: string;
+  help: string;
+  required?: boolean;
+  /** Takes every argument left. */
+  rest?: boolean;
+};
+
+export type FlagValues = Record<string, string | number | boolean | string[] | undefined>;
+
+export class UsageError extends Error {}
+
+export const GLOBAL_FLAGS: Record<string, FlagSpec> = {
+  root: { type: 'string', help: "the app's folder (default: the current one)", value: 'dir' },
+  device: { type: 'string', help: 'simulator udid or name', value: 'udid|name' },
+  app: { type: 'string', help: 'bundle id, for launching and simulator commands', value: 'bundleId' },
+  launch: { type: 'boolean', help: 'relaunch the app before attaching (needs --app)' },
+  'attach-timeout': { type: 'number', help: 'how long to wait for the app to attach', default: 15000, value: 'ms' },
+  json: { type: 'boolean', help: 'machine-readable output when the command has one' },
+  help: { type: 'boolean', help: 'this text' },
+};
+
+export const parseArgs = (
+  argv: string[],
+  positionals: PositionalSpec[] = [],
+  flags: Record<string, FlagSpec> = {},
+): { args: string[]; flags: FlagValues; passthrough: string[] } => {
+  const specs = { ...GLOBAL_FLAGS, ...flags };
+  const out: FlagValues = {};
+  const args: string[] = [];
+  let passthrough: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i]!;
+    if (token === '--') {
+      passthrough = argv.slice(i + 1);
+      break;
+    }
+    if (token.startsWith('--') && token.length > 2) {
+      const eq = token.indexOf('=');
+      let name = eq === -1 ? token.slice(2) : token.slice(2, eq);
+      let inline = eq === -1 ? undefined : token.slice(eq + 1);
+      let negated = false;
+      if (!specs[name] && name.startsWith('no-') && specs[name.slice(3)]?.type === 'boolean') {
+        name = name.slice(3);
+        negated = true;
+      }
+      const spec = specs[name];
+      if (!spec)
+        throw new UsageError(
+          `unknown flag --${name}; flags: ${Object.keys(specs)
+            .map((f) => `--${f}`)
+            .join(' ')}`,
+        );
+      if (spec.type === 'boolean') {
+        out[name] = !negated && (inline === undefined ? true : inline !== 'false');
+        continue;
+      }
+      if (inline === undefined) {
+        inline = argv[i + 1];
+        if (inline === undefined || (inline.startsWith('--') && inline.length > 2))
+          throw new UsageError(`--${name} needs a value${spec.value ? ` <${spec.value}>` : ''}`);
+        i++;
+      }
+      if (spec.type === 'number') {
+        const n = Number(inline);
+        if (Number.isNaN(n)) throw new UsageError(`--${name} expects a number, got "${inline}"`);
+        out[name] = n;
+      } else if (spec.type === 'list') {
+        out[name] = [...((out[name] as string[] | undefined) ?? []), inline];
+      } else out[name] = inline;
+      continue;
+    }
+    args.push(token);
+  }
+  for (const [name, spec] of Object.entries(specs)) if (out[name] === undefined && spec.default !== undefined) out[name] = spec.default;
+  const required = positionals.filter((p) => p.required);
+  if (args.length < required.length)
+    throw new UsageError(
+      `missing ${required
+        .slice(args.length)
+        .map((p) => `<${p.name}>`)
+        .join(' ')}`,
+    );
+  const last = positionals[positionals.length - 1];
+  if (!last?.rest && args.length > positionals.length) throw new UsageError(`unexpected argument "${args[positionals.length]}"`);
+  return { args, flags: out, passthrough };
+};
+
+export const pairs = (list: string[] | undefined): Record<string, string> => {
+  const out: Record<string, string> = {};
+  for (const item of list ?? []) {
+    const eq = item.indexOf('=');
+    if (eq > 0) out[item.slice(0, eq)] = item.slice(eq + 1);
+  }
+  return out;
+};
+
+/** Double quotes group; everything else splits on spaces. */
+export const splitLine = (line: string): string[] => (line.match(/"[^"]*"|\S+/g) ?? []).map((a) => a.replace(/^"|"$/g, ''));

package/src/cases/__tests__/format.test.ts

@@ -0,0 +1,76 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { dig, interpolate, matcherOf, matches, parseCase, readCases } from '../format.js';
+
+const CASE = `---
+id: gift
+title: "A gift shows up"
+---
+setup:
+  - create_user: { as: u, name: "Ana" }
+steps:
+  - app.press: "#open"
+  - app.back
+  - assert: { user: u, path: score, equals: 25 }
+expected: |
+  The score is 25.
+`;
+
+test('a case is its frontmatter, its setup, its steps and what it expects', () => {
+  const c = parseCase(CASE, 'cases/gift.md');
+  assert.equal(c.id, 'gift');
+  assert.deepEqual(c.setup, [{ verb: 'create_user', value: { as: 'u', name: 'Ana' } }]);
+  assert.deepEqual(
+    c.steps.map((s) => s.verb),
+    ['app.press', 'app.back', 'assert'],
+  );
+  assert.equal(c.expected, 'The score is 25.');
+});
+
+test('a file without frontmatter, or a step with two verbs, is refused with its place', () => {
+  assert.throws(() => parseCase('steps: []', 'x.md'), /x\.md: no frontmatter/);
+  assert.throws(() => parseCase('---\nid: x\n---\nsteps:\n  - { a: 1, b: 2 }\n', 'x.md'), /steps\[0\] must be one step/);
+});
+
+test('a path reads into lists, and a star collects from every element', () => {
+  const json = { accounts: [{ code: 'usd' }, { code: 'eur' }], user: { id: 7 } };
+  assert.equal(dig(json, 'accounts.1.code'), 'eur');
+  assert.deepEqual(dig(json, 'accounts.*.code'), ['usd', 'eur']);
+  assert.equal(dig(json, 'user.name.first'), undefined);
+});
+
+test('a reference alone keeps its type; inside text it is text; a missing one says which', () => {
+  const scope = { u: { user_id: 7, name: 'Ana' } };
+  assert.deepEqual(interpolate({ id: '{{u.user_id}}', hi: 'hi {{u.name}}', n: 3 }, scope), { id: 7, hi: 'hi Ana', n: 3 });
+  assert.match(interpolate('x{{random.letters}}', scope), /^x[a-z]{6}$/);
+  assert.throws(() => interpolate('{{v.user_id}}', scope), /no alias 'v'/);
+  assert.throws(() => interpolate('{{u.phone}}', scope), /\{\{u\.phone\}\} is empty/);
+});
+
+test('matchers compare numbers as numbers and lists by any element', () => {
+  assert.equal(matches('25.0', { equals: 25 }), true);
+  assert.equal(matches('abc', { equals: 'abc' }), true);
+  assert.equal(matches(['usd', 'bridge_usd'], { includes: 'bridge' }), true);
+  assert.equal(matches(9, { gte: 10 }), false);
+  assert.equal(matches(null, { absent: true }), true);
+  assert.equal(matches('AUTORIZADO', { matches: '^AUT' }), true);
+  assert.deepEqual(matcherOf({ path: 'a', equals: 1, user: 'u' }), { equals: 1 });
+  assert.equal(matcherOf({ path: 'a' }), undefined);
+});
+
+test('a case with a matrix runs once per combination, named after it', () => {
+  const file = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'lynkeus-matrix-')), 'm.md');
+  fs.writeFileSync(file, '---\nid: m\nmatrix: { locale: [en, fr], login: [phone] }\n---\nsteps:\n  - create_user: { locale: "{{matrix.locale}}" }\n');
+  const cases = readCases(file);
+  assert.deepEqual(
+    cases.map((c) => c.id),
+    ['m[locale=en,login=phone]', 'm[locale=fr,login=phone]'],
+  );
+  assert.deepEqual(cases[1]!.setup, []);
+  assert.deepEqual(cases[1]!.steps[0]!.value, { locale: 'fr' });
+});

package/src/cases/__tests__/runner.test.ts

@@ -0,0 +1,230 @@
+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 type { Device } from '../../device/driver.js';
+import { type Base, 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());
+
+type Call = { method: string; params: unknown };
+
+// An app with one button that, pressed, shows the points the fixtures hold.
+const fakeApp = () => {
+  const calls: Call[] = [];
+  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: string, params: { testId?: string }) => {
+      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: unknown) => {
+      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: string) => (name === 'events' ? [{ name: 'points_viewed', properties: { points: 25 } }] : {}),
+  } as unknown as Device;
+  const base: 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 as unknown as { waitFor: () => Promise<never> }).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: object[] = [];
+  (device as unknown as { command: (n: string) => Promise<unknown> }).command = async () => buffer;
+  const press = device.press.bind(device);
+  (device as unknown as { press: typeof device.press }).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/src/cases/fixtures.ts

@@ -0,0 +1,104 @@
+/**
+ * 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 { type ChildProcessWithoutNullStreams, spawn } from 'node:child_process';
+import path from 'node:path';
+import readline from 'node:readline';
+
+export type FixturesConfig = { command: string; cwd?: string; env?: Record<string, string>; timeoutMs?: number };
+
+export type Answer = Record<string, unknown>;
+
+const envOf = (params: Record<string, unknown>): Record<string, string> =>
+  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: FixturesConfig;
+  #root: string;
+  #child: ChildProcessWithoutNullStreams | null = null;
+  #lines: string[] = [];
+  #waiting: ((line: string | null) => void) | null = null;
+  #stderr = '';
+
+  constructor(config: FixturesConfig, root: string) {
+    this.#config = config;
+    this.#root = root;
+  }
+
+  #start(): ChildProcessWithoutNullStreams {
+    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: Buffer) => {
+      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: string, params: Record<string, unknown>): Promise<Answer> {
+    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<string | null>((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) as Answer;
+    if (answer.ok === false) throw new Error(`${command}: ${String(answer.error ?? answer.message ?? 'ok=false')}`);
+    return answer;
+  }
+
+  close(): void {
+    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
+    }
+  }
+}