@arjunkhera/atlas 0.3.7 → 0.3.9

package/tests/contract.mjs

@@ -0,0 +1,398 @@
+// The contract library (design section 8.1). It sits between the words of a
+// scenario and the test code, on `node:test`.
+//
+//   // in test/scenarios/week-conflict.test.mjs, with the kit copy in test/atlas/
+//   scenario('scenarios/week-conflict.md', async (run, way) => {
+//     const first = await run.persona('planner-1', way);
+//     // ... steps, through the actions of the area ...
+//     run.gate('week-conflict/e1#be9cf0', () => assert.equal(firstAnswer.revision, 1));
+//     run.check('week-conflict/e2#7f1d74', () => assert.equal(secondAnswer.revision, 2));
+//   }, { adapter });
+//
+// What `scenario(path, body, options)` does
+//   1. Reads the scenario and atlas/tests.yaml, and refuses to run when either
+//      has a fault.
+//   2. Registers one node:test test for each way in of `through:`. It runs the
+//      body with (run, way).
+//   3. Starts the environment once for the scenario (environment.mjs): the
+//      stand-ins, then the product. It stops them when the last way is done.
+//   4. Writes the evidence file (evidence.mjs): at the start, and after each
+//      assertion.
+//   5. A test fails (node:test red) when any assertion is not `pass`. That
+//      holds for `fail`, `not checked`, `not exercised` and `blocked`.
+//      When the scenario's `runs-in` excludes the environment, the result is
+//      `not here` and the test passes.
+//
+// Guard parts at run time: with ATLAS_GUARDS_FROM=<tests.yaml of the main
+// branch>, a branch whose guard parts differ ends `blocked` and starts nothing.
+// After the body and the results are settled, the run is closed: a late
+// run.check throws and changes nothing. After the product is ready, a lost
+// connection, a server exit or a time-out is `fail`, not `blocked`.
+//
+// The adapter binds the library to one product. Every part is optional:
+//   adapter.standIns  { name: async ({ name, runId, hosts }) => ({ url, stop, calls }) }
+//                     a stand-in made in this process, instead of a start command
+//   adapter.warmUp    async (env) => {}   make the product call its stand-ins once
+//   adapter.drivers   { wayOrDriver: async (ctx) => driver }  a driver the kit does not ship
+//   adapter.functions the module (or { way: module }) for the function driver
+//   adapter.loadModule async (file) => module   loads the `module` of a function way in; the
+//                     kit gives the path under the product root, so a fault run loads the copy
+//   adapter.makers    { name: async (ctx) => ({ credential, headers, cleanup }) } for `make:`
+//   adapter.signIns   { name: async (ctx) => ({ credential, headers, cleanup }) } for `sign-in:`
+//   adapter.data      { rule: ({ runId, count }) => value }  a data rule of the repo
+//   adapter.actions   an object, or (run) => object: the verbs of the area, on run.actions
+import { describe, it, after } from 'node:test';
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Blocked, GateFailed } from './errors.mjs';
+import { Redactor } from './redact.mjs';
+import { readTestsYaml, checkTestsYaml, compareGuardParts } from './tests-yaml.mjs';
+import { readScenario, addFingerprints, combinations, pairs } from './scenario.mjs';
+import { Evidence, clip } from './evidence.mjs';
+import { makeFresh, makeRunId } from './fresh.mjs';
+import { startEnvironment, provideSecrets } from './environment.mjs';
+import { makeDriver } from './drivers/index.mjs';
+import { parseLimit, waitUntil } from './wait.mjs';
+
+export { waitUntil };
+export const defineAdapter = (adapter) => adapter;
+
+const FULL_ID = /^(.+)\/(e\d+)#([0-9a-f]{6})$/;
+const isThenable = (x) => x && typeof x.then === 'function';
+
+export const RUN_ID = makeRunId();
+
+function locate(path) {
+  if (path instanceof URL) return fileURLToPath(path);
+  if (typeof path === 'string' && path.startsWith('file:')) return fileURLToPath(path);
+  return resolve(String(path));
+}
+
+function findRoot(file) {
+  let dir = dirname(file);
+  for (;;) {
+    if (existsSync(join(dir, 'atlas', 'tests.yaml'))) return dir;
+    const up = dirname(dir);
+    if (up === dir) throw new Error(`no atlas/tests.yaml above ${file}`);
+    dir = up;
+  }
+}
+
+function load(path, options) {
+  const file = locate(path);
+  const root = findRoot(file);
+  const yaml = readTestsYaml(join(root, 'atlas', 'tests.yaml'));
+  const findings = checkTestsYaml(yaml);
+  if (findings.length) throw new Error(`atlas/tests.yaml: ${findings.map((f) => `line ${f.line}: ${f.message}`).join('; ')}`);
+  const sc = readScenario(file);
+  if (sc.problems.length) throw new Error(`${path}: ${sc.problems.map((p) => `line ${p.line}: ${p.message}`).join('; ')}`);
+  const tests = yaml.value;
+  addFingerprints(sc, tests);
+  // ATLAS_GUARDS_FROM names tests.yaml of the main branch. The guard parts of this
+  // run come from that file, and a branch whose guard parts differ is refused
+  // (`blocked`). CI sets it. A local run without it uses the branch file.
+  let guardRefusal = null;
+  const guardsFrom = options.guardsFrom ?? process.env.ATLAS_GUARDS_FROM;
+  if (guardsFrom) {
+    try {
+      const changes = compareGuardParts(readFileSync(guardsFrom, 'utf8'), yaml.value);
+      if (changes.length) guardRefusal = `the guard parts of atlas/tests.yaml differ from the main branch copy (${changes.map((c) => c.part).join(', ')}); the run is refused. A change to a guard part comes to the owner`;
+    } catch (error) {
+      guardRefusal = `ATLAS_GUARDS_FROM names a file that cannot be read as tests.yaml (${error.code ?? error.message}); the run is refused`;
+    }
+  }
+  const environment = options.environment ?? process.env.ATLAS_ENV ?? (process.env.CI ? 'ci' : 'local');
+  const evidenceDir = options.evidenceDir ?? process.env.ATLAS_EVIDENCE_DIR ?? join(root, 'test', 'evidence');
+  return { file, root, tests, sc, environment, evidenceDir, guardRefusal };
+}
+
+const listOf = (x) => (Array.isArray(x) ? x.map(String) : x === undefined ? [] : [String(x)]);
+
+export function scenario(path, body, options = {}) {
+  const ctx = load(path, options);
+  const { sc, tests, root, environment } = ctx;
+  const adapter = options.adapter ?? {};
+  const runsHere = listOf(sc.fields['runs-in']).includes(environment);
+  const limitMs = parseLimit(sc.fields.limit);
+
+  describe(`${sc.id}: ${sc.title}`, () => {
+    const state = {
+      redactor: new Redactor(), evidence: null, envPromise: null, env: null,
+      drivers: new Map(), personas: new Map(), cleanups: [], fresh: null,
+    };
+    const evidence = () => {
+      state.evidence ??= new Evidence({
+        evidenceDir: ctx.evidenceDir, runId: RUN_ID, environment, scenario: sc, root,
+        redactor: state.redactor, providedSecrets: [],
+      });
+      return state.evidence;
+    };
+    const getEnv = () => {
+      state.envPromise ??= (async () => {
+        if (ctx.guardRefusal) throw new Blocked(ctx.guardRefusal);
+        const named = [...new Set([...sc.start, ...sc.steps, ...sc.assertions].flatMap((x) => x.names))]
+          .filter((n) => Object.hasOwn(tests.secrets ?? {}, n));
+        const provided = provideSecrets(named, { root, tests });
+        const env = await startEnvironment({ root, tests, name: environment, runId: RUN_ID, redactor: state.redactor, adapter, provided });
+        evidence().record.provided_secrets = named;
+        state.env = env;
+        return env;
+      })();
+      return state.envPromise;
+    };
+
+    if (!runsHere) {
+      it(`${sc.id} [not here: runs-in excludes ${environment}]`, () => {
+        const ev = evidence();
+        for (const way of sc.through) {
+          for (const a of sc.assertions) ev.setResult(a.fullId, way, 'not here', { why: `runs-in does not list ${environment}` });
+          ev.setWay(way, { verdict: 'not here', started: new Date().toISOString(), ended: new Date().toISOString() });
+        }
+      });
+      return;
+    }
+
+    for (const way of sc.through) {
+      it(`${sc.id} [${way}]`, async () => {
+        const ev = evidence();
+        ev.setWay(way, { started: new Date().toISOString() });
+        let run = null;
+        let error = null;
+        try {
+          const env = await getEnv();
+          run = makeRun({ ctx, state, way, env, ev, adapter });
+          await withLimit(Promise.resolve().then(() => body(run, way)), limitMs, sc.fields.limit);
+        } catch (thrown) {
+          error = thrown;
+        }
+        const outcome = settle({ sc, way, ev, error });
+        // The run is closed: a late call (after a time limit, say) changes nothing.
+        run?.close();
+        await cleanUp(state, run, ev);
+        // The problem list goes to node:test and then to the CI log: redact it first.
+        if (outcome.problems.length) throw new Error(state.redactor.text(outcome.problems.join('\n')));
+      });
+    }
+
+    after(async () => {
+      for (const driver of state.drivers.values()) { try { await (await driver).close(); } catch { /* the stop goes on */ } }
+      try { await (await state.envPromise)?.stop(); } catch { /* it did not start */ }
+    });
+  });
+}
+
+function withLimit(promise, ms, text) {
+  let timer;
+  const limit = new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(`the scenario ran out of time: its limit is ${text}`)), ms); timer.unref?.(); });
+  return Promise.race([promise, limit]).finally(() => clearTimeout(timer));
+}
+
+async function cleanUp(state, run, ev) {
+  const list = run ? run.cleanups.splice(0).reverse() : [];
+  for (const fn of list) { try { await fn(); } catch (error) { ev.note(`clean-up failed: ${error.message}`); } }
+}
+
+// Turns the end of a body into results, a verdict and a list of problems.
+function settle({ sc, way, ev, error }) {
+  const mine = ev.record.assertions.filter((a) => a.way === way);
+  const problems = [];
+  let verdict = 'pass';
+  let reason = null;
+  // `blocked` is for a guard refusal, a start-up fault and the first-call check. After
+  // the product is ready, a lost connection, a server exit or a timeout is a `fail`.
+  if (error instanceof Blocked) {
+    verdict = 'blocked';
+    reason = error.message;
+    for (const a of mine) if (a.result === 'not checked') { a.result = 'blocked'; a.proof = { why: reason }; }
+  } else if (error && !(error instanceof GateFailed)) {
+    verdict = 'fail';
+    reason = error.message;
+  } else if (error instanceof GateFailed) {
+    verdict = 'fail';
+    reason = 'a gate assertion failed, so the run stopped';
+  }
+  for (const a of mine) {
+    if (a.result === 'pass' || a.result === 'not here') continue;
+    if (verdict === 'pass') verdict = 'fail';
+    problems.push(`[${a.id}] ${a.result}${a.proof?.error ? `: ${a.proof.error}` : a.proof?.why ? `: ${a.proof.why}` : ''}`);
+  }
+  if (verdict === 'blocked') problems.unshift(`BLOCKED: ${reason}`);
+  else if (reason && !(error instanceof GateFailed)) problems.push(`the run stopped: ${reason}`);
+  ev.setWay(way, { verdict, reason, ended: new Date().toISOString() });
+  return { verdict, problems };
+}
+
+// ---------------------------------------------------------------- the run object
+
+function makeRun({ ctx, state, way, env, ev, adapter }) {
+  const { sc, tests, root } = ctx;
+  state.fresh ??= makeFresh(RUN_ID, tests.data, adapter.data);
+  const cleanups = [];
+  let mark = ev.record.calls.length;
+  const callsSince = () => { const from = mark; mark = ev.record.calls.length; return ev.record.calls.slice(from).map((c) => c.n); };
+
+  let closed = false;
+  const open = (what) => { if (closed) throw new Error(`the run is closed: ${what} came after the scenario ended, so it changed nothing`); };
+  const record = (call) => (closed ? undefined : ev.addCall(call));
+
+  const driver = (wayName = way) => {
+    if (!state.drivers.has(wayName)) {
+      const spec = tests['ways-in'][wayName];
+      if (!spec) throw new Error(`there is no way in "${wayName}" in tests.yaml`);
+      state.drivers.set(wayName, makeDriver({ way: wayName, spec, env, root, hosts: env.hosts, redactor: state.redactor, record, adapter, runId: RUN_ID }));
+    }
+    return state.drivers.get(wayName);
+  };
+
+  const find = (full) => {
+    const m = FULL_ID.exec(String(full));
+    if (!m) throw new Error(`"${full}" is not a full assertion id like ${sc.id}/e1#abc123`);
+    if (m[1] !== sc.id) throw new Error(`"${full}" names the scenario "${m[1]}"; this is "${sc.id}"`);
+    const a = sc.assertions.find((x) => x.id === m[2]);
+    if (!a) throw new Error(`the scenario has no assertion ${m[2]}`);
+    return { a, fp: m[3] };
+  };
+
+  const settleOne = (full, fn, opts = {}, mode) => {
+    open(`run.${mode}`);
+    const { a, fp } = find(full);
+    const target = opts.way ?? way;
+    if (!sc.through.includes(target)) throw new Error(`"${target}" is not a way in of this scenario`);
+    const entry = ev.entry(a.fullId, target);
+    const calls = callsSince();
+    let failure = null;
+    let value;
+    if (fp !== a.fp) failure = `the fingerprint ${fp} is old: the words of ${a.id} now print ${a.fp}; convert the test again`;
+    else if (mode === 'exercise') {
+      if (entry.result === 'pass' || entry.result === 'fail') return a;
+      ev.setResult(a.fullId, target, 'not exercised', { why: String(fn), calls });
+      return a;
+    } else {
+      try {
+        value = fn();
+        if (isThenable(value)) { failure = 'a check must not be async: wait first, then check'; value = undefined; }
+      } catch (e) { failure = e?.message ?? String(e); }
+    }
+    if (failure) ev.setResult(a.fullId, target, 'fail', { error: failure, calls });
+    else if (entry.result !== 'fail') ev.setResult(a.fullId, target, 'pass', { value: value === undefined ? undefined : clip(value, state.redactor), calls });
+    if (failure && mode === 'gate') throw new GateFailed(`[${a.id}] ${failure}`);
+    return a;
+  };
+
+  const tableOf = (name) => {
+    const t = sc.tables.get(name);
+    if (!t) throw new Error(`the scenario has no case table ${name}`);
+    return t;
+  };
+  const checkTable = (t, expected) => {
+    ev.record.tables[t.name] = t.fingerprint;
+    if (expected && expected !== t.fingerprint) throw new Error(`the table ${t.name} now prints ${t.fingerprint}, not ${expected}; its rows changed`);
+  };
+
+  const run = {
+    id: sc.id, title: sc.title, runId: RUN_ID, way, env, scenario: sc, tests, root, cleanups,
+    redact: (text) => state.redactor.text(text),
+    driver,
+
+    // One assertion. `fn` runs at once, must not be async, and must hold an
+    // assert statement. A failure is recorded and the run goes on.
+    check: (full, fn, opts) => { settleOne(full, fn, opts, 'check'); },
+    // The same, and a failure stops the run. Later assertions read `not checked`.
+    gate: (full, fn, opts) => { settleOne(full, fn, opts, 'gate'); },
+    // A "when" assertion whose situation never happened in this run.
+    notExercised: (full, why) => { settleOne(full, why, {}, 'exercise'); },
+    // The test could not run. Never use it for a product result.
+    blocked: (why) => { throw new Blocked(why); },
+
+    // The rows of a rule table, as objects keyed by the header. A test that
+    // reads a table gets every row of the file at run time.
+    table(name, { fingerprint } = {}) {
+      const t = tableOf(name);
+      checkTable(t, fingerprint);
+      return t.rows.map((row) => ({ ...row }));
+    },
+    // The cells of a rule table: one case each, with a label that names the cell.
+    cells(name, { fingerprint } = {}) {
+      const t = tableOf(name);
+      if (t.kind !== 'rule') throw new Error(`${name} is a combination table; use run.cases`);
+      checkTable(t, fingerprint);
+      const [first, ...rest] = t.header;
+      return t.rows.flatMap((row, rowIndex) => rest.map((column) => ({ row: row[first], column, value: row[column], rowIndex, label: `${name}: ${row[first]} / ${column}` })));
+    },
+    // Every case of a combination table: every combination, or a set that holds every pair.
+    cases(name, { fingerprint } = {}) {
+      const t = tableOf(name);
+      if (t.kind !== 'combination') throw new Error(`${name} is a rule table; use run.table or run.cells`);
+      checkTable(t, fingerprint);
+      return (t.cover === 'pair' ? pairs(t.dimensions) : combinations(t.dimensions)).map((one, i) => ({ ...one, label: `${name} case ${i + 1}` }));
+    },
+
+    // A test user from tests.yaml, made or loaded for this run.
+    async persona(name, wayName = way) {
+      const key = `${name}\u0000${wayName}`;
+      if (state.personas.has(key)) return state.personas.get(key);
+      const def = tests.personas?.[name];
+      if (!def) throw new Error(`there is no persona "${name}" in tests.yaml`);
+      const made = (async () => {
+        const drv = await driver(wayName);
+        let extra = {};
+        const maker = def.make ? adapter.makers?.[def.make] : def['sign-in'] ? adapter.signIns?.[def['sign-in']] : null;
+        if ((def.make || def['sign-in']) && !maker) throw new Blocked(`persona "${name}" needs the ${def.make ? 'maker' : 'sign-in'} "${def.make ?? def['sign-in']}" and the adapter does not give it`);
+        if (maker) {
+          extra = (await maker({ run, name, def, way: wayName, env, driver: drv, fresh: run.fresh, persona: (n) => run.persona(n, wayName) })) ?? {};
+          if (extra.cleanup) cleanups.push(extra.cleanup);
+        }
+        const credential = extra.credential ?? (def.secret ? (env.vars[def.secret] ?? null) : null);
+        state.redactor.add(credential);
+        for (const value of Object.values(extra.headers ?? {})) state.redactor.add(String(value));
+        const persona = {
+          ...extra, name, role: def.role ?? null, way: wayName, credential,
+          call: (request, opts = {}) => drv.call(request, { credential, headers: extra.headers ?? {}, persona: name, ...opts }),
+        };
+        return persona;
+      })();
+      state.personas.set(key, made);
+      return made;
+    },
+
+    // A fresh value from a data rule. It carries the run id; a date is picked from it.
+    fresh: (rule) => {
+      open('run.fresh');
+      const value = state.fresh(rule);
+      ev.record.fresh = state.fresh.made.slice();
+      ev.write();
+      return value;
+    },
+
+    // The wait of a scenario step: wait for a state, never for a fixed time.
+    wait: waitUntil,
+    // The same, and a wait that fails or runs out marks the assertion it
+    // serves as failed, with the last state as proof. The run stops.
+    async waitFor(full, read, opts) {
+      open('run.waitFor');
+      const { a } = find(full);
+      try { return await waitUntil(read, opts); } catch (e) {
+        if (e.name !== 'WaitFailed' && e.name !== 'WaitTimeout') throw e;
+        ev.setResult(a.fullId, way, 'fail', { error: e.message, last: clip(e.last?.body ?? e.last, state.redactor) });
+        throw new GateFailed(`[${a.id}] ${e.message}`);
+      }
+    },
+
+    note: (text) => { open('run.note'); ev.note(state.redactor.text(String(text))); },
+    // Keep a file, such as a screenshot, as evidence. Returns the path to write to.
+    attach(fileName) {
+      open('run.attach');
+      const dir = join(ev.dir, sc.id);
+      mkdirSync(dir, { recursive: true });
+      const path = join(dir, fileName);
+      ev.addFile(path);
+      return path;
+    },
+    onCleanup: (fn) => { cleanups.push(fn); },
+    // Called by the library after the body and the results are settled.
+    close: () => { closed = true; },
+  };
+  run.actions = typeof adapter.actions === 'function' ? adapter.actions(run) : (adapter.actions ?? {});
+  return run;
+}

package/tests/drivers/function.mjs

@@ -0,0 +1,30 @@
+// The function driver. It calls a function or a module directly, for a rule
+// that holds below every way in. It has no address and no credential, so
+// duties 1 and 2 of the driver contract do not apply. It records the inputs
+// and the return or the error, and it opens nothing.
+//
+// The shipped kit cannot load a module by name. The repo loads the module
+// itself and gives it to the driver through the adapter, as the value of
+// adapter.functions (one module, or one module for each way in).
+export function createFunctionDriver({ way, target, record: rawRecord, redactor }) {
+  const record = rawRecord && ((call) => rawRecord(redactor ? redactor.deep(call) : call));
+  if (!target) throw new Error(`the way in "${way}" has no target: give the module in adapter.functions`);
+
+  // request: { fn, args } - or { args } when the target is itself a function.
+  async function call(request = {}, { persona = null } = {}) {
+    const args = request.args ?? [];
+    const fn = request.fn === undefined ? target : target[request.fn];
+    if (typeof fn !== 'function') throw new Error(`the target of "${way}" has no function "${request.fn}"`);
+    let answer;
+    try {
+      const value = await fn.apply(request.fn === undefined ? undefined : target, args);
+      answer = { status: 'ok', body: value, isError: false, raw: value };
+    } catch (error) {
+      answer = { status: 'threw', body: { name: error?.name ?? 'Error', message: String(error?.message ?? error) }, isError: true, raw: error };
+    }
+    record?.({ way, persona, request: { fn: request.fn ?? '(target)', args }, response: { status: answer.status, body: answer.body } });
+    return answer;
+  }
+
+  return { name: 'function', way, call, async close() {} };
+}

package/tests/drivers/http.mjs

@@ -0,0 +1,68 @@
+// The http driver. It calls a REST or plain HTTP route with `fetch`.
+//
+// The seven duties of a driver (design section 7.2):
+//   1. It refuses an address that guards.hosts does not allow (`blocked`).
+//   2. It sends a credential only to the origin it belongs to.
+//   3. It records each call and each answer.
+//   4. It removes run secrets and named secrets from what it records, by value.
+//   5. It returns the raw answer: { status, body, isError, headers, raw }.
+//   6. It signs in as a persona, never as the person who runs the test.
+//   7. It cleans up what it opened. This driver opens nothing.
+import { Unavailable } from '../errors.mjs';
+import { requireAllowed, sameOrigin } from '../guards.mjs';
+import { clip } from '../evidence.mjs';
+import { LIBRARY_HEADER } from '../stand-in.mjs';
+
+export function createHttpDriver({ way, base, hosts, record: rawRecord, redactor, timeoutMs = 30000 }) {
+  const record = rawRecord && ((call) => rawRecord(redactor ? redactor.deep(call) : call));
+  if (!base) throw new Error(`the way in "${way}" has no base address`);
+  const origin = new URL(base).origin;
+  requireAllowed(base, hosts, `the way in "${way}"`);
+
+  async function call(request = {}, { credential = null, headers: personaHeaders = {}, persona = null } = {}) {
+    const method = (request.method ?? 'GET').toUpperCase();
+    let target;
+    if (request.url) target = new URL(request.url);
+    else {
+      const path = String(request.path ?? '');
+      target = new URL(`${base.replace(/\/+$/, '')}${path.startsWith('/') || path === '' ? '' : '/'}${path}`);
+    }
+    for (const [k, v] of Object.entries(request.query ?? {})) target.searchParams.set(k, String(v));
+    requireAllowed(target.href, hosts, `${method} ${target.pathname}`);
+    const own = sameOrigin(target.href, origin);
+    // A call of the kit carries this header, so a stand-in does not count it as a call of the product.
+    const headers = { ...(request.headers ?? {}), [LIBRARY_HEADER]: '1' };
+    const sent = [];
+    // A credential goes only to the origin of this way in.
+    if (own) {
+      for (const [k, v] of Object.entries(personaHeaders)) { headers[k] = v; sent.push(k); }
+      if (credential) { headers['authorization'] = `Bearer ${credential}`; sent.push('authorization'); }
+    }
+    const init = { method, headers, redirect: 'manual', signal: AbortSignal.timeout(timeoutMs) };
+    if (request.body !== undefined) {
+      if (request.raw) init.body = request.body;
+      else { init.body = JSON.stringify(request.body); headers['content-type'] ??= 'application/json'; }
+    }
+    let response;
+    let text;
+    try {
+      response = await fetch(target, init);
+      text = await response.text();
+    } catch (error) {
+      throw new Unavailable(`${method} ${target.pathname}: ${error.cause?.code ?? error.name}`);
+    }
+    let body = text;
+    if (/json/.test(response.headers.get('content-type') ?? '') && text) {
+      try { body = JSON.parse(text); } catch { /* keep the text */ }
+    }
+    const answer = { status: response.status, body, isError: response.status >= 400, headers: Object.fromEntries(response.headers), raw: text };
+    record?.({
+      way, persona,
+      request: { method, url: target.href, credential_headers: sent, body: request.body === undefined ? undefined : clip(request.body, redactor) },
+      response: { status: answer.status, body: clip(body, redactor) },
+    });
+    return answer;
+  }
+
+  return { name: 'http', way, base, call, async close() {} };
+}

package/tests/drivers/index.mjs

@@ -0,0 +1,65 @@
+// Builds the driver for a way in from its entry in tests.yaml. A driver that
+// the kit does not ship (a browser, a command) comes from the adapter:
+//   adapter.drivers = { browser: async (ctx) => driver }
+// A driver has the shape { name, way, call(request, opts), close() }.
+import { isAbsolute, resolve } from 'node:path';
+import { Blocked } from '../errors.mjs';
+import { requireAddressesAllowed, substitute } from '../guards.mjs';
+import { createHttpDriver } from './http.mjs';
+import { createMcpStdioDriver } from './mcp-stdio.mjs';
+import { createFunctionDriver } from './function.mjs';
+
+export { createHttpDriver, createMcpStdioDriver, createFunctionDriver };
+
+// ctx: { way, spec, env, root, hosts, redactor, record, adapter, runId }
+// In a fault run, ATLAS_PRODUCT_ROOT names a throwaway copy. A process that a
+// way in starts (an MCP server) and the module of the function driver load from
+// that copy, so a planted fault is what runs. tests.yaml and the kit stay in the
+// real worktree. A `cwd` in the way in is a folder under that root.
+export function productRootOf(root) {
+  return process.env.ATLAS_PRODUCT_ROOT ? resolve(process.env.ATLAS_PRODUCT_ROOT) : root;
+}
+
+// Moves a path in a command from the worktree to the product root. The text
+// is changed only where it names the worktree root as a whole path part.
+export function commandFor(command, root, productRoot) {
+  if (!command || productRoot === root) return command;
+  return command.split(root).join(productRoot);
+}
+
+export async function makeDriver(ctx) {
+  const { way, spec, env, root, hosts, redactor, record, adapter = {}, runId } = ctx;
+  const productRoot = productRootOf(root);
+  const own = adapter.drivers?.[way] ?? adapter.drivers?.[spec.driver];
+  if (own) return own(ctx);
+  const template = { id: runId, varsFile: env.varsFile, url: env.url, vars: (n) => env.vars[n], standIn: (n) => env.standIns[n]?.url };
+  const fill = (text) => (text === undefined ? text : substitute(text, template));
+  // Every address in the env of a way in must be on the list, of any scheme and whatever its name.
+  if (spec.env && typeof spec.env === 'object') {
+    requireAddressesAllowed(Object.fromEntries(Object.entries(spec.env).map(([k, v]) => [k, fill(String(v))])), hosts, `the env of the way in "${way}"`);
+  }
+  switch (spec.driver) {
+    case 'http':
+      return createHttpDriver({ way, base: fill(spec.base), hosts, record, redactor });
+    case 'mcp-stdio':
+      return createMcpStdioDriver({
+        way, command: commandFor(fill(spec.command), root, productRoot), cwd: spec.cwd ? (isAbsolute(spec.cwd) ? spec.cwd : resolve(productRoot, spec.cwd)) : productRoot, hosts, redactor, record,
+        env: Object.fromEntries(Object.entries(spec.env ?? {}).map(([k, v]) => [k, fill(String(v))])),
+      });
+    case 'function': {
+      let target = adapter.functions?.[way] ?? adapter.functions?.function ?? adapter.functions;
+      // No module from the adapter: the `module` of the way in is a path under the
+      // product root. The adapter loads it (adapter.loadModule(file)), because the
+      // kit loads no module by a name it builds at run time.
+      if (!target && spec.module) {
+        const file = resolve(productRoot, fill(String(spec.module)));
+        if (typeof adapter.loadModule !== 'function') throw new Blocked(`the way in "${way}" names the module ${spec.module}; the adapter gives no loadModule(file) to load it from ${productRoot}`);
+        try { target = await adapter.loadModule(file, { way, root, productRoot }); } catch (error) { throw new Blocked(`the module of "${way}" could not be loaded from ${file}: ${error.message}`); }
+      }
+      if (!target) throw new Blocked(`the way in "${way}" uses the function driver and the adapter gives no module: set adapter.functions`);
+      return createFunctionDriver({ way, target, record, redactor });
+    }
+    default:
+      throw new Blocked(`the way in "${way}" uses the driver "${spec.driver}", which the kit does not ship; add it to adapter.drivers`);
+  }
+}