Coding agents

Claude Code, Codex and Cursor can write and run Retest tests through the command line. Retest gives them a short report, source locations and saved evidence, so they can investigate a failure before editing the app or test.

For a new project, use the prompt in Quick start. In an existing project, ask the agent to read your config and a test first, then run only the file it is working on:

$ npx retest run tests/task.retest.ts --agent

--agent selects the short report explicitly. Retest also selects it automatically when a recognised agent environment variable is set. The tests and checks run the same way with either report.

Read the agent report #Link to Read the agent report

At the end of a run, the report prints counts and an exit code. A text mismatch includes the source line, failure class and compared values. This shortened example shows a task title that lost its last letter:

retest: 1 failed (1) in 6.1s, exit 1fail tests/task.retest.ts:7 saves a task  check_failed toHaveText getByTestId('saved-task')  expected "Release checklist" received "Release checklis" waited 5002ms for toHaveText, looked 14 times, limit 5000ms  compared whole text, ends trimmed, each run of spaces or line breaks read as one spacenext: npx retest inspect .retest/runs/<time> --test "tests/task.retest.ts > saves a task" --json

The next: line is a command, usually an inspection of the first failed test. Copy the actual line from your run, which contains its folder name. Inspection reads the existing evidence without rerunning the test or opening a browser.

Retest checks CLAUDECODE, CODEX_THREAD_ID, CODEX_SANDBOX, CURSOR_AGENT, GEMINI_CLI, AGENT and AI_AGENT. Empty values, 0 and false do not enable detection. Use --no-agent for human output or --reporter jsonl for events as they happen.

Inspect before editing #Link to Inspect before editing

Use inspect --json to read the whole result, or add --test to get one test's result, ordered events and diagnostics. A test id combines its file, any group names and its title. list --json shows ids and source locations before a run.

$ npx retest list --json$ npx retest inspect .retest/runs/<time> --json$ npx retest inspect .retest/runs/<time> --test "tests/task.retest.ts > saves a task" --json

If the test ran on several targets, add the --target app=name pair from the report to select one variant. For tools that read saved runs, Run folder and events lists the event and result schemas.

The agent should compare the failed check with the app's intended behaviour, then fix the cause and run the test again. An incomplete run is not a pass. The exit code helps distinguish a failed expectation from a setup problem:

A run with several problems combines them according to the exit-code rules. For example, a failed check can give exit 1 even when another test could not run, so read the counts as well as the code.

Give the agent project instructions #Link to Give the agent project instructions

Keep the app address, start command and testing rules in your project's AGENTS.md or equivalent instructions. The following text gives the agent a repeatable workflow. Add the commands and account setup specific to your project:

End-to-end tests use @rehearsal-labs/retest.Read retest.config.ts and an existing test before writing a test.Docs: https://rehearsal.dev/retest/docs/quick-start.mdRun npx retest doctor when setup changes.Run retest commands from this project, where @rehearsal-labs/retest is installed.Run one file while editing: npx retest run tests/task.retest.ts --agentFollow the report's next command to inspect a failure before changing code.Run npm run typecheck:e2e to check test types.Await every action and asynchronous assertion.Check the outcome after an action with expect; do not add fixed sleeps.Declare credentials in the config and use secret handles in tests.Keep the expected behaviour when fixing a failure.Report any test that could not run or whose result was inconclusive.

These commands use npm; replace them with your project's package manager commands where needed. init creates the typecheck:e2e script shown here.

Build an agent that explores an app #Link to Build an agent that explores an app

If you are building your own browser agent, use AgentHost from @rehearsal-labs/retest/agent to open a session without a test file. Your program can navigate, send actions and read elements through that session.

The example opens Chrome, navigates to the task app and reads the title field. Set RETEST_CHROMIUM to your Chrome or Chromium executable before running it:

import { resolve } from 'node:path'import { AgentHost } from '@rehearsal-labs/retest/agent'import { SessionBudget } from '@rehearsal-labs/retest/runner'const executablePath = process.env['RETEST_CHROMIUM']if (!executablePath) throw new Error('Set RETEST_CHROMIUM to the browser executable')const host = new AgentHost({  targets: { chrome: { engine: 'chromium', executablePath } },  budget: new SessionBudget({ perOwner: 1, host: 1 }),  logFolder: resolve('.retest/agent-logs'),})try {  const opened = await host.open({    owner: 'local-agent',    app: 'web',    purpose: 'discovery',    target: 'chrome',    engine: 'chromium',    baseUrl: 'http://localhost:3000',  })  if (!opened.ok) throw new Error(opened.failure.message)  const { session } = opened  try {    const navigated = await session.act({ kind: 'goto', url: '/' })    if (!navigated.result.ok) throw new Error(navigated.result.failure.message)    const observed = await session.observe({ by: 'testId', value: 'task-title' })    if (!observed.ok) throw new Error(observed.failure.message)  } finally {    await session.end()  }} finally {  await host.close()}

A successful observation's look.elements lists matching elements with references your agent can use for an action. Retest refuses a stale reference. Before saving a test, use session.recipe(ref, locator) to verify that a locator finds that same element (on Firefox and WebKit it accepts only the look's own locator); saved tests keep locators because references belong to a session.

Every call renews the session's lease, which lasts one minute by default. If your agent waits for a person between calls, renew it with session.renew(); a session still ends after ten minutes in all, so open a new one for a longer wait. Agent sessions write no events or run folder, so run a saved test when you need the reports described above. Use Retest from code covers host integration.

Next steps #Link to Next steps

• Debugging a failureRead the evidence and find the cause of a failed check.
• Command lineFind the available commands and selection flags.
• Use Retest from codeRun tests and required host checks from your program.