Saffronv1.3.4
Get started
Reference

Architecture and design principles

Architecture

src/
  parser/        .saffron and .feature → scenarios (outline expansion, step kinds, AST line lookup)
  cache/         schema, store, proposals, propagation
  replay/        the replayer: cache actions performed on Playwright's browser engine (locators, retries, tabs, capture vars)
  agent/         AgentProvider abstraction; Claude, Codex, Antigravity and Cursor providers, the tool gateway, recorder, prompts, MCP tools
  orchestrator/  per-scenario state machine: replay ⇄ agent, assertion guard, proposals
  report/        HTML + JSON generation
  trace/         trace capture and masking, the replay server and page, heal review from the replay
  cli/           run / accept / reject / report (report --merge for shards) / trace

Key boundaries:

  • AgentProvider is an interface with four providers behind it, and the orchestrator knows none of them. Claude runs in process through its SDK's hooks; Codex, Antigravity and Cursor are drivers behind one external provider that serves them the tools over a loopback MCP gateway. All four share one session (agent/session.ts): the recording, the trace bridge, the per-call hooks and the result.
  • The replayer knows nothing about AI; the agent knows nothing about caching. The orchestrator owns the escalation policy and the assertion guard: trust decisions live in exactly one place.
  • One browser, two drivers. The orchestrator launches Chromium with a CDP port; the replayer drives it via the Playwright library, the agent via Playwright MCP attached to the same endpoint (or, with trace on, running in process on the scenario's browser context, so the trace sees its calls).

Design principles

  1. A test tool that masks regressions is worse than none. Everything about assertions follows from this.
  2. Adaptation is a proposal, not a decision. Humans accept caches, like snapshot updates.
  3. Determinism is the product; AI is the maintenance crew. Tokens are spent only when reality changed.
  4. Exact identity over clever inference. Propagation matches identical queries; no entity-resolution heuristics rewrite your suite.

The full design rationale, competitor research, and decision log live in the design log. For hands-on usage, continue to How to Use; for pending work, milestones, and decision gates, see the Roadmap.