@arjunkhera/atlas 0.3.11 → 0.3.13

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas",
-  "version": "0.3.11",
+  "version": "0.3.13",
   "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, for any repository.",
   "author": {
     "name": "Arjun Khera"

package/door/kit-releases.json

@@ -1,4 +1,9 @@
 {
   "note": "Every kit of the folder tests/ that a release of Atlas shipped, as the kit hash of its manifest (the sha256 of the sorted lines of path and file hash). The kit of this package is always accepted and need not be listed. When a release changes anything in tests/, add the kit hash of the release before it here. atlas tests check reads this list; git history is never read.",
-  "releases": []
+  "releases": [
+    {
+      "kit_sha256": "ae0f32b8c6694fbffb8bdacd8bd919d27c1c1da6281a46779e521dfea2341565",
+      "first_package": "0.3.8"
+    }
+  ]
 }

package/door/lib/proof.mjs

@@ -8,6 +8,9 @@
 // { "<scenario>/e1": { "result": "pass", "proof": "revision 1" } }; a full id
 // (with its #fingerprint) works as a key too. A way that is blocked or failed
 // shows its reason in the proof column. Evidence of a fault run is left out.
+// A scenario that kept files (screenshots of the browser driver) gets a list under the table:
+// each file with its run folder, and the count of console errors and failed requests of its page.
+// The pictures stay in the CI run (design section 8.3); the table holds their names only.
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { newestRunPerScenario } from '../../tests/link-check.mjs';
@@ -64,10 +67,21 @@ export function buildProof({ evidenceDir, runId = null, own = {} }) {
   const ways = [...new Set(scenarios.flatMap((s) => Object.keys(s.ways ?? {})))];
   const rows = [];
   const blocked = [];
+  const screenshots = [];
+  const pageEvents = [];
   for (const s of scenarios) {
     for (const [way, w] of Object.entries(s.ways ?? {})) {
       if (w.verdict === 'blocked' || w.verdict === 'fail') blocked.push(`${s.scenario} through ${way} is ${w.verdict}${w.reason ? `: ${clip(w.reason, 200)}` : ''}`);
     }
+    for (const file of s.files ?? []) {
+      if (/\.(png|jpe?g|webp)$/i.test(file)) screenshots.push({ scenario: s.scenario, file, run: s.run_id });
+    }
+    const events = (s.calls ?? []).map((c) => c.request?.event).filter(Boolean);
+    // A scenario that kept a picture used a page, so a count of 0 is news too.
+    if (events.length || (s.files ?? []).some((f) => /\.(png|jpe?g|webp)$/i.test(f))) {
+      const count = (kind) => events.filter((e) => e === kind).length;
+      pageEvents.push({ scenario: s.scenario, consoleErrors: count('console-error') + count('page-error'), failedRequests: count('request-failed'), httpErrors: count('http-error'), stopped: count('request-stopped') });
+    }
     const ids = [...new Set((s.assertions ?? []).map((a) => a.id))];
     for (const full of ids) {
       const short = full.replace(/#[0-9a-f]+$/, '');
@@ -92,7 +106,7 @@ export function buildProof({ evidenceDir, runId = null, own = {} }) {
       });
     }
   }
-  return { runId: id, environment: scenarios[0].environment, ways, rows, blocked, faultRuns, scenarios: scenarios.map((s) => s.scenario) };
+  return { runId: id, environment: scenarios[0].environment, ways, rows, blocked, faultRuns, screenshots, pageEvents, scenarios: scenarios.map((s) => s.scenario) };
 }
 
 export function renderProof(proof) {
@@ -107,6 +121,16 @@ export function renderProof(proof) {
     out.push('Blocked or failed ways in:');
     for (const b of proof.blocked) out.push(`- ${clean(b)}`);
   }
+  if (proof.screenshots.length) {
+    out.push('');
+    out.push('Screenshots (kept in test/evidence of the run; the CI run holds them for 14 days):');
+    for (const shot of proof.screenshots) out.push(`- ${clean(shot.scenario)}: test/evidence/${clean(shot.run)}/${clean(shot.file)}`);
+  }
+  if (proof.pageEvents.length) {
+    out.push('');
+    out.push('Page events:');
+    for (const e of proof.pageEvents) out.push(`- ${clean(e.scenario)}: ${e.consoleErrors} console error(s), ${e.failedRequests} failed request(s), ${e.httpErrors} HTTP error answer(s), ${e.stopped} request(s) stopped by the guards`);
+  }
   if (proof.faultRuns) {
     out.push('');
     out.push(`${proof.faultRuns} evidence file(s) of fault runs were left out.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arjunkhera/atlas",
-  "version": "0.3.11",
+  "version": "0.3.13",
   "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, as a Claude Code plugin for any repository.",
   "type": "module",
   "license": "UNLICENSED",
@@ -25,5 +25,13 @@
     "agents/",
     ".claude-plugin/",
     ".mcp.json"
-  ]
+  ],
+  "peerDependencies": {
+    "playwright": ">=1.40.0"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    }
+  }
 }

package/skills/sdlc-task/SKILL.md

@@ -34,6 +34,7 @@ checks and the transition log; each verb's own description says what it needs.
 | Keep its next step, its wait or its title true | `item_edit` |
 | Split it, or link it to other work | `item_split`, `item_link` |
 | Mark that it waits on another item, or clear that | `item_block`, `item_unblock` |
+| Keep a note on it, or read what happened on it | `item_comment`, `item_activity` |
 | Ask the owner something, or record the answer | `question_ask`, `question_answer` |
 | Record a decision in the owner's words | `decision_record` |
 | Mark it delivered, or reopen it | `item_done`, `item_reopen` |

package/tests/contract.mjs

@@ -34,6 +34,7 @@
 //                     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.playwright the Playwright module, for a test of the browser driver that has none installed
 //   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
@@ -145,10 +146,10 @@ export function scenario(path, body, options = {}) {
     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() });
+        for (const a of sc.assertions) {
+          for (const way of a.ways) ev.setResult(a.fullId, way, 'not here', { why: `runs-in does not list ${environment}` });
         }
+        for (const way of sc.ways) ev.setWay(way, { verdict: 'not here', started: new Date().toISOString(), ended: new Date().toISOString() });
       });
       return;
     }
@@ -167,6 +168,8 @@ export function scenario(path, body, options = {}) {
           error = thrown;
         }
         const outcome = settle({ sc, way, ev, error });
+        // A failed run keeps a picture of each open page (a driver that has one), before the run closes.
+        if (run && outcome.verdict === 'fail') await keepOnFail(state, sc.id);
         // The run is closed: a late call (after a time limit, say) changes nothing.
         run?.close();
         await cleanUp(state, run, ev);
@@ -182,6 +185,12 @@ export function scenario(path, body, options = {}) {
   });
 }
 
+async function keepOnFail(state, label) {
+  for (const pending of state.drivers.values()) {
+    try { await (await pending).keepOnFail?.(`fail-${label}`); } catch { /* a missing picture is not the news */ }
+  }
+}
+
 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?.(); });
@@ -195,7 +204,9 @@ async function cleanUp(state, run, ev) {
 
 // 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);
+  // The entries of this way in, and the entries of a way in that only a step names (the page).
+  // A run through `mcp` checks the page assertions too, so it settles them.
+  const mine = ev.record.assertions.filter((a) => a.way === way || !sc.through.includes(a.way));
   const problems = [];
   let verdict = 'pass';
   let reason = null;
@@ -220,6 +231,21 @@ function settle({ sc, way, ev, error }) {
   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() });
+  // A way in that only a step names has no run of its own. Its verdict is the verdict of its assertions.
+  for (const extra of sc.ways.filter((w) => !sc.through.includes(w))) {
+    const own = ev.record.assertions.filter((a) => a.way === extra).map((a) => a.result);
+    // A gate that failed, or a block, leaves the later assertions `not checked`. That is no `fail` of the page.
+    const stopped = own.every((r) => r === 'pass' || r === 'not here' || r === 'not checked' || r === 'blocked') && own.some((r) => r === 'not checked' || r === 'blocked');
+    let extraVerdict;
+    let extraReason = null;
+    if (own.includes('fail')) { extraVerdict = 'fail'; extraReason = `an assertion through ${extra} failed`; }
+    else if (stopped) {
+      extraVerdict = 'blocked';
+      extraReason = error instanceof GateFailed ? 'the gate stopped the run' : verdict === 'blocked' ? reason : 'the run stopped before every assertion through this way in was checked';
+    } else if (own.every((r) => r === 'pass' || r === 'not here')) extraVerdict = own.every((r) => r === 'not here') ? 'not here' : 'pass';
+    else { extraVerdict = 'fail'; extraReason = `an assertion through ${extra} is not a pass`; }
+    ev.setWay(extra, { verdict: extraVerdict, reason: extraReason, started: ev.record.ways[way].started, ended: new Date().toISOString() });
+  }
   return { verdict, problems };
 }
 
@@ -240,7 +266,12 @@ function makeRun({ ctx, state, way, env, ev, adapter }) {
     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 }));
+      // A driver is shared by the runs of the scenario (the page way in has no run of its own), so it reaches
+      // the record and the attach of the run that is live now, and not those of the run that made it.
+      // A driver is shared by the runs of a scenario (the page way in has no run of its own), so it reaches the
+      // record and the attach of the run that is live now (state.live), not those of the run that made it.
+      // attach: where a driver keeps a file (a screenshot) as evidence, in the folder of this scenario.
+      state.drivers.set(wayName, makeDriver({ way: wayName, spec, env, root, hosts: env.hosts, redactor: state.redactor, record: (call) => state.live?.record(call), adapter, runId: RUN_ID, attach: (name) => state.live.attach(name) }));
     }
     return state.drivers.get(wayName);
   };
@@ -257,8 +288,9 @@ function makeRun({ ctx, state, way, env, ev, adapter }) {
   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`);
+    // An assertion that reads a result of a step with its own way in (the page) belongs to that way.
+    const target = opts.way ?? (a.ways.includes(way) ? way : a.ways[0]);
+    if (!a.ways.includes(target)) throw new Error(`"${target}" is not a way in of ${a.id}: its ways are ${a.ways.join(', ')}`);
     const entry = ev.entry(a.fullId, target);
     const calls = callsSince();
     let failure = null;
@@ -274,8 +306,14 @@ function makeRun({ ctx, state, way, env, ev, adapter }) {
         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 });
+    // `settled_by` names the run (the way in of `through:`) that settled the assertion. A page assertion of a
+    // scenario with two `through` ways is settled twice. A fail stands over a later pass. The result of the other
+    // run is listed under `also`, so no result is overwritten without a trace.
+    const earlier = entry.proof?.settled_by && entry.proof.settled_by !== way ? entry : null;
+    const also = earlier ? [...(earlier.proof.also ?? []), { run: earlier.proof.settled_by, result: earlier.result }] : (entry.proof?.also ?? undefined);
+    if (failure) ev.setResult(a.fullId, target, 'fail', { error: failure, calls, settled_by: way, also });
+    else if (entry.result !== 'fail') ev.setResult(a.fullId, target, 'pass', { value: value === undefined ? undefined : clip(value, state.redactor), calls, settled_by: way, also });
+    else if (earlier || entry.proof) { entry.proof = { ...entry.proof, also: [...(entry.proof.also ?? []), { run: way, result: 'pass' }] }; ev.write(); }
     if (failure && mode === 'gate') throw new GateFailed(`[${a.id}] ${failure}`);
     return a;
   };
@@ -393,6 +431,7 @@ function makeRun({ ctx, state, way, env, ev, adapter }) {
     // Called by the library after the body and the results are settled.
     close: () => { closed = true; },
   };
+  state.live = { record, attach: (name) => run.attach(name) };
   run.actions = typeof adapter.actions === 'function' ? adapter.actions(run) : (adapter.actions ?? {});
   return run;
 }

package/tests/drivers/browser.mjs

@@ -0,0 +1,364 @@
+// The browser driver. It opens a web page in Chromium and reads it as a person
+// sees it. It is built on Playwright, which is an optional peer: the kit loads
+// and every other driver works when Playwright is not installed. Only a scenario
+// that uses a `browser` way in needs it. Without it the result is `blocked`, and
+// the reason names the cause.
+//
+// The seven duties of a driver (design section 7.2):
+//   1. It refuses an address that guards.hosts does not allow (`blocked`). It checks
+//      the address it opens, the address the page ends on after a redirect, and each
+//      request the page makes: a request to another host is stopped and recorded.
+//   2. It sends a credential only to the origin it belongs to. A cookie is set for
+//      the origin of the way in. A header goes only with requests to that origin.
+//   3. It records each call and each answer. It also records the console errors,
+//      the page errors and the failed requests of the page, as evidence.
+//   4. It removes run secrets and named secrets from what it records, by value. A
+//      screenshot is a picture, so the driver masks each part of the page that
+//      shows a secret before it takes the picture.
+//   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. Each persona
+//      has its own browser context, so no cookie moves from one persona to another.
+//   7. It closes what it opened: every context and the browser.
+//
+// A request has one of these forms:
+//   { open: '/week?x=1' }                     open a path of the base address (or a full address)
+//   { read: finder, timeout?, optional? }     read the parts that match the finder
+//   { click: finder }                         click the first part that matches
+//   { fill: finder, value }                   type into the first part that matches
+//   { screenshot: 'view' }                    keep a picture of the page as evidence
+//   { method, url, headers?, body? }          a plain HTTP call in the context of the persona,
+//                                             for a dev sign-in. The cookie it gets stays in that context.
+//
+// A finder names a page part the way a person would, from the map:
+//   { role, name?, exact? }  { text, exact? }  { label }  { css }  { hasText, has: finder, within: finder, nth }
+// `css` is the last resort, for a part with no role and no text of its own.
+//
+// `read` waits up to `timeout` (10 seconds) for the first part to show. When none
+// shows, it does not throw: it answers { count: 0, texts: [], found: false }, so an
+// assertion fails and the run reads `fail`, not `blocked`.
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { Blocked } from '../errors.mjs';
+import { hostAllowed, requireAllowed, sameOrigin } from '../guards.mjs';
+import { clip } from '../evidence.mjs';
+
+const DEFAULT_TIMEOUT = 10000;
+const NAVIGATION_TIMEOUT = 30000;
+const INTERNAL = /^(?:about:|data:|blob:|chrome-error:)/;
+
+// The reason to give when the import of the optional peer fails.
+export function explainMissing(error) {
+  const missing = error?.code === 'ERR_MODULE_NOT_FOUND' || error?.code === 'MODULE_NOT_FOUND';
+  if (missing && /playwright/.test(String(error.message))) {
+    return new Blocked('the browser driver needs the package "playwright" and it is not installed here. Install it in the repo (npm install --save-dev playwright), then install the browser (npx playwright install chromium)');
+  }
+  return new Blocked(`the package "playwright" could not be loaded: ${error?.message ?? error}`);
+}
+
+// Loads the optional peer. The import runs here, in the kit copy of the repo, so it finds the
+// "playwright" of that repo.
+export async function loadPlaywright() {
+  try {
+    return await import('playwright');
+  } catch (error) {
+    throw explainMissing(error);
+  }
+}
+
+// A finder can hold a regular expression. The record shows it as text, because JSON drops it.
+const show = (finder) => JSON.parse(JSON.stringify(finder, (key, value) => (value instanceof RegExp ? value.toString() : value)));
+
+const normal = (text) => String(text ?? '').replace(/\s+/g, ' ').trim();
+
+// Builds a Playwright locator from a finder.
+export function locate(scope, finder) {
+  if (!finder || typeof finder !== 'object') throw new Error('a finder must be an object such as { role: "listitem" }');
+  let one = finder.within ? locate(scope, finder.within) : scope;
+  const exact = finder.exact === true;
+  if (finder.role) one = one.getByRole(finder.role, finder.name === undefined ? {} : { name: finder.name, exact });
+  else if (finder.text !== undefined) one = one.getByText(finder.text, { exact });
+  else if (finder.label !== undefined) one = one.getByLabel(finder.label, { exact });
+  else if (finder.css) one = one.locator(finder.css);
+  else throw new Error('a finder needs a role, a text, a label or a css');
+  const filter = {};
+  if (finder.hasText !== undefined) filter.hasText = finder.hasText;
+  if (finder.has) filter.has = locate(scope.page ? scope.page() : scope, finder.has);
+  if (Object.keys(filter).length) one = one.filter(filter);
+  if (finder.nth !== undefined) one = one.nth(Number(finder.nth));
+  return one;
+}
+
+// `playwright` is for a test: { chromium } with the same calls. `load` replaces the import, for a test of the missing peer. `executablePath` can come from
+// the environment (ATLAS_BROWSER_EXECUTABLE) when the machine keeps its browser in an odd place.
+export async function createBrowserDriver({ way, base, hosts, record: rawRecord, redactor, attach, playwright, load = loadPlaywright, timeoutMs = DEFAULT_TIMEOUT }) {
+  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}"`);
+  const record = rawRecord && ((call) => rawRecord(redactor ? redactor.deep(call) : call));
+  const lib = playwright ?? await load();
+  const engine = lib.chromium ?? lib.default?.chromium;
+  if (!engine) throw new Blocked('the package "playwright" has no chromium engine');
+
+  let browser = null;
+  let closed = false;
+  const contexts = new Map(); // persona name -> { context, page, persona }
+
+  async function launch() {
+    if (browser) return browser;
+    const executablePath = process.env.ATLAS_BROWSER_EXECUTABLE || undefined;
+    try {
+      browser = await engine.launch({ headless: true, executablePath });
+    } catch (error) {
+      throw new Blocked(`the browser could not start: ${String(error?.message ?? error).split('\n')[0]}. Install it with "npx playwright install chromium", or set ATLAS_BROWSER_EXECUTABLE`);
+    }
+    return browser;
+  }
+
+  // Addresses that the guards stopped. A stopped request counts once, as stopped: it is no failed request.
+  const stopped = new Set();
+  const event = (persona, kind, data) => record?.({ way, persona, request: { event: kind }, response: data });
+
+  // The credential of a persona: cookies go into the context for the base origin; other headers (a bearer
+  // token) go only with a request to the base origin. Returns { cookies, extra }.
+  function credentialOf({ headers = {}, credential = null }) {
+    const extra = {};
+    const cookies = [];
+    for (const [name, value] of Object.entries(headers)) {
+      if (name.toLowerCase() === 'cookie') {
+        for (const part of String(value).split(';').map((x) => x.trim()).filter(Boolean)) {
+          const at = part.indexOf('=');
+          cookies.push({ name: part.slice(0, at), value: part.slice(at + 1), url: origin });
+        }
+      } else extra[name.toLowerCase()] = String(value);
+    }
+    if (credential) extra.authorization = `Bearer ${credential}`;
+    return { cookies, extra };
+  }
+
+  async function contextOf(persona, given = {}) {
+    const key = persona ?? '-';
+    const { cookies, extra } = credentialOf(given);
+    if (contexts.has(key)) {
+      // A credential that comes after the context was made must not be dropped without a word.
+      const entry = contexts.get(key);
+      for (const [name, value] of Object.entries(extra)) {
+        if (entry.extra[name] !== value) throw new Blocked(`the browser context of "${persona ?? 'no persona'}" was made before its credential (${name}) came, so the credential would be dropped. Give the credential on the first call of the persona`);
+      }
+      if (cookies.length) await entry.context.addCookies(cookies);
+      return entry;
+    }
+    // Service workers could answer a request with no route, so they are blocked.
+    const context = await (await launch()).newContext({ viewport: { width: 1280, height: 900 }, serviceWorkers: 'block' });
+    const entry = { context, page: null, persona, key, extra };
+    if (cookies.length) await context.addCookies(cookies);
+    const stop = (url, why, kind = 'request-stopped') => { if (kind === 'request-stopped') stopped.add(url); event(persona, kind, { url: redactUrl(url), why }); };
+    const refusal = `guards.hosts allows only ${hosts.join(', ')}`;
+    const allowedUrl = (url) => { try { return hostAllowed(new URL(url).hostname, hosts); } catch { return false; } };
+
+    // Each request goes through here, and so does each hop of a redirect. The route sees the first URL
+    // of a chain only, so the driver does not let the browser follow a redirect: it fetches the request
+    // with no redirect, checks the Location, and hands the browser the answer. The browser then follows
+    // the hop as a new request, and that request comes back here to be checked again. The credential goes
+    // only with a request whose own origin is the base origin, so it never follows a hop to another host.
+    await context.route('**/*', async (route) => {
+      const request = route.request();
+      const url = request.url();
+      if (INTERNAL.test(url)) return route.continue();
+      if (!allowedUrl(url)) { stop(url, refusal); return route.abort('blockedbyclient'); }
+      const headers = { ...request.headers() };
+      if (sameOrigin(url, origin)) Object.assign(headers, entry.extra);
+      else for (const name of Object.keys(entry.extra)) delete headers[name];
+      let response;
+      try {
+        response = await route.fetch({ headers, maxRedirects: 0 });
+      } catch (error) {
+        stop(url, `the request failed: ${String(error?.message ?? error).split('\n')[0]}`, 'request-failed');
+        return route.abort('failed');
+      }
+      const status = response.status();
+      const location = status >= 300 && status < 400 ? response.headers()['location'] : null;
+      if (location) {
+        let next = null;
+        try { next = new URL(location, url).href; } catch { /* a bad Location is refused below */ }
+        if (!next || !allowedUrl(next)) { stopped.add(url); stop(next ?? location, `a redirect from ${new URL(url).pathname} leads to an address that ${refusal}`); return route.abort('blockedbyclient'); }
+      }
+      return route.fulfill({ response });
+    });
+    // A WebSocket is not a request of the route above. It is checked here, and a host that is not allowed is closed.
+    if (typeof context.routeWebSocket === 'function') {
+      await context.routeWebSocket(/.*/, (ws) => {
+        const url = ws.url();
+        if (!allowedUrl(url.replace(/^ws/, 'http'))) { stop(url, refusal); ws.close({ code: 1008, reason: 'refused by guards.hosts' }); return; }
+        ws.connectToServer();
+      });
+    }
+    contexts.set(key, entry);
+    return entry;
+  }
+
+  const redactUrl = (url) => (redactor ? redactor.text(url) : url);
+
+  async function pageOf(entry) {
+    if (entry.page && !entry.page.isClosed()) return entry.page;
+    const page = await entry.context.newPage();
+    page.setDefaultTimeout(timeoutMs);
+    page.on('console', (message) => { if (message.type() === 'error' && !stopped.has(message.location()?.url)) event(entry.persona, 'console-error', { text: normal(message.text()).slice(0, 500), at: redactUrl(message.location()?.url ?? '') }); });
+    page.on('pageerror', (error) => event(entry.persona, 'page-error', { text: normal(error?.message ?? error).slice(0, 500) }));
+    // A request failed at the network. A request that the guards stopped is not counted here.
+    page.on('requestfailed', (request) => { if (!stopped.has(request.url())) event(entry.persona, 'request-failed', { url: redactUrl(request.url()), why: request.failure()?.errorText ?? 'failed' }); });
+    // An HTTP error answer (4xx, 5xx) is listed apart. It is no network failure.
+    page.on('response', (response) => { if (response.status() >= 400) event(entry.persona, 'http-error', { url: redactUrl(response.url()), status: response.status() }); });
+    entry.page = page;
+    return page;
+  }
+
+  const answer = (status, body, headers = {}) => ({ status, body, isError: typeof status === 'number' && status >= 400, headers, raw: typeof body === 'string' ? body : JSON.stringify(body) });
+
+  // A picture cannot be redacted by value, so each part of the page that shows a secret is masked.
+  async function shoot(entry, name, { full = true } = {}) {
+    const page = entry.page;
+    if (!page || page.isClosed()) throw new Error(`there is no open page to take a screenshot of "${name}"`);
+    if (typeof attach !== 'function') throw new Error('this driver was made with no place to keep screenshots');
+    const safe = String(name).replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'screenshot';
+    const path = attach(`${safe}.png`);
+    const secrets = redactor ? [...redactor.values] : [];
+    const mask = secrets.map((value) => page.getByText(value));
+    // An input shows its value, which is no text node. Mark each input whose value holds a secret, and mask it.
+    if (secrets.length) {
+      await page.evaluate((values) => { for (const el of document.querySelectorAll('input, textarea, select')) if (values.some((v) => String(el.value ?? '').includes(v))) el.setAttribute('data-atlas-mask', '1'); }, secrets);
+      mask.push(page.locator('[data-atlas-mask]'));
+    }
+    let matched = 0;
+    for (const one of mask) matched += await one.count();
+    await page.screenshot({ path, fullPage: full, mask });
+    const bytes = readFileSync(path);
+    return { name: `${safe}.png`, bytes: bytes.length, sha256: createHash('sha256').update(bytes).digest('hex'), masked: matched };
+  }
+
+  async function call(request = {}, { credential = null, headers = {}, persona = null } = {}) {
+    if (closed) throw new Error(`the browser of "${way}" is closed`);
+    // The address is checked before any browser starts.
+    let target = null;
+    if (request.open !== undefined) {
+      target = /^[a-z][a-z0-9+.-]*:/i.test(String(request.open)) ? new URL(request.open) : new URL(`${base.replace(/\/+$/, '')}/${String(request.open).replace(/^\/+/, '')}`);
+      requireAllowed(target.href, hosts, `open ${target.pathname}`);
+    } else if (request.method) {
+      target = request.url ? new URL(request.url) : new URL(`${base.replace(/\/+$/, '')}/${String(request.path ?? '').replace(/^\/+/, '')}`);
+      requireAllowed(target.href, hosts, `${request.method} ${target.pathname}`);
+    }
+    const entry = await contextOf(persona, { headers, credential });
+    const log = (shape, response) => record?.({ way, persona, request: shape, response });
+
+    if (request.open !== undefined) {
+      const page = await pageOf(entry);
+      let response;
+      try {
+        response = await page.goto(target.href, { waitUntil: 'load', timeout: NAVIGATION_TIMEOUT });
+      } catch (error) {
+        const first = String(error?.message ?? error).split('\n')[0];
+        // The route stopped the address or a redirect of it. That is a guard refusal, so the result is `blocked`.
+        // The page is left in an error state, so it is closed and the next open makes a new one.
+        if (/ERR_BLOCKED_BY_CLIENT/.test(first)) {
+          try { await page.close(); } catch { /* it is gone */ }
+          entry.page = null;
+          throw new Blocked(`open ${target.pathname}: a request of the page, or a redirect, led to an address that guards.hosts does not allow, so the guards stopped it`);
+        }
+        throw new Error(`open ${target.pathname}: ${first}`);
+      }
+      const landed = page.url();
+      if (!INTERNAL.test(landed)) requireAllowed(landed, hosts, `the page ${target.pathname} ended on`);
+      const status = response?.status() ?? 0;
+      const out = answer(status, { url: redactUrl(landed), title: await page.title() }, response?.headers() ?? {});
+      log({ open: redactUrl(target.href) }, { status, body: out.body });
+      return out;
+    }
+
+    if (request.read !== undefined) {
+      const page = entry.page;
+      if (!page || page.isClosed()) throw new Error('read: there is no open page; open one first');
+      const wait = request.optional ? 0 : (request.timeout ?? timeoutMs);
+      const locator = locate(page, request.read);
+      let found = true;
+      if (wait > 0) {
+        try { await locator.first().waitFor({ state: 'visible', timeout: wait }); } catch { found = false; }
+      }
+      const texts = (await locator.allTextContents()).map(normal);
+      const count = texts.length;
+      found = count > 0 && (await locator.first().isVisible());
+      const body = { found, count, texts };
+      log({ read: show(request.read) }, { status: 200, body: clip(body, redactor) });
+      return answer(200, body);
+    }
+
+    if (request.click !== undefined || request.fill !== undefined) {
+      const page = entry.page;
+      if (!page || page.isClosed()) throw new Error('there is no open page; open one first');
+      const finder = request.click ?? request.fill;
+      if (request.fill !== undefined && redactor && [...redactor.values].some((v) => String(request.value ?? '').includes(v))) {
+        throw new Blocked('a fill with the value of a run secret was refused: a secret must not be typed into a page, because the page could show it or send it on');
+      }
+      const locator = locate(page, finder).first();
+      if (request.fill !== undefined) await locator.fill(String(request.value ?? ''));
+      else await locator.click();
+      // The value that was typed can be a secret: the record holds a redacted copy.
+      log(request.fill !== undefined ? { fill: show(finder), value: '[typed]' } : { click: show(finder) }, { status: 200 });
+      return answer(200, { done: true });
+    }
+
+    if (request.screenshot !== undefined) {
+      const info = await shoot(entry, request.screenshot);
+      log({ screenshot: request.screenshot }, { status: 200, body: info });
+      return answer(200, info);
+    }
+
+    if (request.method) {
+      const sendHeaders = { ...(request.headers ?? {}) };
+      const response = await entry.context.request.fetch(target.href, {
+        method: request.method.toUpperCase(), headers: sendHeaders, data: request.body, maxRedirects: 0, failOnStatusCode: false,
+      });
+      const text = await response.text();
+      let body = text;
+      if (/json/.test(response.headers()['content-type'] ?? '') && text) { try { body = JSON.parse(text); } catch { /* keep the text */ } }
+      const out = answer(response.status(), body, headersOf(response));
+      out.raw = text;
+      log({ method: request.method.toUpperCase(), url: redactUrl(target.href) }, { status: out.status, body: clip(body, redactor) });
+      return out;
+    }
+
+    throw new Error('the browser driver was called with no open, read, click, fill, screenshot or method');
+  }
+
+  // Playwright joins the values of a repeated header with a newline. A cookie reader wants the first.
+  function headersOf(response) {
+    const out = {};
+    for (const { name, value } of response.headersArray()) {
+      const key = name.toLowerCase();
+      out[key] = out[key] === undefined ? value : `${out[key]}, ${value}`;
+    }
+    return out;
+  }
+
+  // A picture of every open page, for a run that failed. It never throws.
+  async function keepOnFail(label = 'fail') {
+    const kept = [];
+    for (const entry of contexts.values()) {
+      try {
+        if (!entry.page || entry.page.isClosed()) continue;
+        const info = await shoot(entry, `${label}-${way}-${entry.persona ?? 'page'}`);
+        record?.({ way, persona: entry.persona, request: { event: 'screenshot-on-fail' }, response: info });
+        kept.push(info);
+      } catch { /* the failed run is the news; a missing picture is not */ }
+    }
+    return kept;
+  }
+
+  async function close() {
+    if (closed) return;
+    closed = true;
+    for (const entry of contexts.values()) { try { await entry.context.close(); } catch { /* the stop goes on */ } }
+    contexts.clear();
+    if (browser) { try { await browser.close(); } catch { /* the stop goes on */ } browser = null; }
+  }
+
+  return { name: 'browser', way, base, call, keepOnFail, close };
+}

package/tests/drivers/index.mjs

@@ -1,6 +1,8 @@
 // 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 }
+// the kit does not ship (a command, a queue) comes from the adapter:
+//   adapter.drivers = { command: async (ctx) => driver }
+// The `browser` driver ships. It needs the package "playwright", which is an optional
+// peer: without it a scenario that uses a browser way in reads `blocked`.
 // A driver has the shape { name, way, call(request, opts), close() }.
 import { isAbsolute, resolve } from 'node:path';
 import { Blocked } from '../errors.mjs';
@@ -8,10 +10,13 @@ import { requireAddressesAllowed, substitute } from '../guards.mjs';
 import { createHttpDriver } from './http.mjs';
 import { createMcpStdioDriver } from './mcp-stdio.mjs';
 import { createFunctionDriver } from './function.mjs';
+import { createBrowserDriver } from './browser.mjs';
 
-export { createHttpDriver, createMcpStdioDriver, createFunctionDriver };
+export { createHttpDriver, createMcpStdioDriver, createFunctionDriver, createBrowserDriver };
 
-// ctx: { way, spec, env, root, hosts, redactor, record, adapter, runId }
+// ctx: { way, spec, env, root, hosts, redactor, record, adapter, runId, attach }
+// `attach(fileName)` gives the path of a file to keep as evidence (a screenshot).
+// `adapter.playwright` is the Playwright module, for a test that has none installed.
 // 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
@@ -41,6 +46,8 @@ export async function makeDriver(ctx) {
   switch (spec.driver) {
     case 'http':
       return createHttpDriver({ way, base: fill(spec.base), hosts, record, redactor });
+    case 'browser':
+      return createBrowserDriver({ way, base: fill(spec.base), hosts, record, redactor, attach: ctx.attach, playwright: adapter.playwright });
     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,