Reticle Docs: verification for AI coding agents

@reticlehq/test is Reticle’s spec runner for CI. It turns an interactive session into a suite that runs on every pull request, without an agent and without paying model tokens to re-derive the same checks. Install it when you want unattended verification; skip it if you only ever drive Reticle interactively through MCP. Licensed under Apache-2.0. Depends on @reticlehq/core and @reticlehq/server. Optional peer dependency: vitest ^3.2.6 || ^4.0.0.

npm i -D @reticlehq/test

Why it exists

Driving interactively is reconnaissance. At some point you want the same checks to run unattended. This package invokes the tool layer directly, so a spec is the same evidence an agent would have gathered, minus the model.

Booting a session

import { bootSession, createTestContext, runSpecs, printSummary } from '@reticlehq/test';

const run = await bootSession({ driveUrl: 'http://localhost:5173' });
const { results, summary } = await runSpecs({
  invoke: run.invoke,
  buildContext: (invoke) => createTestContext(invoke),
  now: () => Date.now(),
});
printSummary(summary, results, (line) => process.stdout.write(`${line}\n`));
await run.close();

`BootOptions`

Option	Type	Default
`driveUrl`	`string`	required
`headless`	`boolean`	`true`
`port`	`number`	the default bridge port
`reticleRoot`	`string`	`cwd()/.reticle`
`now`	`() => number`	`Date.now`
`buildDeps`	`(server: RunningServer) => ToolDeps`	built in

bootSession resolves to BootedRun: { invoke: ToolInvoker; close: () => Promise<void> }.

Writing specs

import { reticleTest } from '@reticlehq/test';

reticleTest('login grants a session', async (t) => {
  await t.fill('email', 'user@example.com');
  await t.fill('password', 'hunter2');
  await t.actAndWait('login-submit', 'click', { kind: 'signal', name: 'auth:granted' });
  await t.expectNet('POST', '/api/session', 200);
  await t.expectNoConsoleErrors();
});

reticleTest(name: string, fn: SpecFn): void registers into a module-level registry. register, getRegistered and clearRegistry are exported for anyone driving it themselves. SpecFn types its argument as SpecContext, which is TestContext, so the methods below are typed without a cast.

The test context

createTestContext(invoke: ToolInvoker, options?: TestContextOptions): TestContext, where TestContextOptions is { sessionId?: string; defaultTimeoutMs?: number } and the timeout defaults to DEFAULT_ASSERT_TIMEOUT_MS.

Method	Signature
`act`	`(testid: string, action: ActionType, args?: Record<string, unknown>) => Promise<void>`
`fill`	`(testid: string, value: string) => Promise<void>`
`actAndWait`	`(testid: string, action: ActionType, until: Predicate) => Promise<void>`
`expectSignal`	`(name: string, dataMatches?: Record<string, unknown>) => Promise<void>`
`expectNet`	`(method: string, urlContains: string, status?: number) => Promise<void>`
`expectElement`	`(query: ElementQuery, state?: ElementState) => Promise<void>`
`expectText`	`(contains: string) => Promise<void>`
`expectAbsent`	`(query: ElementQuery) => Promise<void>`
`expectNoConsoleErrors`	`() => Promise<void>`
`state`	`(storeOrRef: string) => Promise<unknown>`
`expectInputModeReal`	`() => Promise<void>`
`invoke`	The raw `ToolInvoker`
`clock`	`TestClock`

Running and reporting

Export	Signature
`runOne`	`(spec: ReticleSpec, opts: RunnerOptions) => Promise<SpecResult>`
`runSpecs`	`(opts: RunnerOptions) => Promise<{ results: SpecResult[]; summary: RunSummary }>`
`summarize`	`(results: readonly SpecResult[]) => RunSummary`
`printSummary`	`(summary: RunSummary, results: readonly SpecResult[], print: (line: string) => void) => void`. The sink is injected, never `console`
`toJUnitXml` / `writeJUnit`	JUnit output for CI

RunnerOptions is { invoke; buildContext; now; print?; specs? }. RunSummary is { total, passed, failed, skipped, ok }.

Saved flows as specs

A recorded flow becomes a spec without being rewritten: flowToSpec, flowsAsSpecs, registerFlowSpecs, with assertSuccess, successToPredicate, and the FlowSpec, FlowSpecOptions and FlowsAsSpecsOptions types. Malformed flows raise FlowMalformedError.

Errors and control flow

ReticleSkip and isSkip for skipping, ReticleAssertionError with an AssertionDetail, ReticleQueryEmptyError when a query matched nothing. Constants: TestStatus, SpecKind, SpecOutcome, SpecMessage, PredicateKind, STATUS_GLYPH, SUMMARY_FOOTER_PREFIX, JUnit, DEFAULT_JUNIT_SUITE_NAME, SKIP_REASON_REAL_INPUT, PROBE_TESTID, FLOW_LOAD_ERROR_PREFIX, DEFAULT_ASSERT_TIMEOUT_MS. Also exported: resolveTestid, and the standalone expectInputModeReal, InputModeTracker and readInputMode.

Turning a session into a suite

Writing specs that bind to signals rather than DOM structure.

Tools

Beyond the loop

CLI commands

Packages

Grammar

Long form

@reticlehq/test

Why it exists

Booting a session

`BootOptions`

Writing specs

The test context

Running and reporting

Saved flows as specs

Errors and control flow

Turning a session into a suite

​Why it exists

​Booting a session

​BootOptions

​Writing specs

​The test context

​Running and reporting

​Saved flows as specs

​Errors and control flow

Turning a session into a suite

Why it exists

Booting a session

`BootOptions`

Writing specs

The test context

Running and reporting

Saved flows as specs

Errors and control flow