# Use Retest from an agent

> Give a coding agent short output, the next command to run, exit codes and JSON it can read.

Source: https://rehearsal.dev/retest/coding-agents

A coding agent can run Retest the way a person does. When it does, the output gets shorter, and every event and result can be read as JSON.

## The short report

When Retest detects a coding agent, `retest run` prints the agent report. It waits for the run to end, then prints the counts, one block per failure and the next command.

```text
retest: 1 failed, 1 passed (2) in 6.1s, exit 1
fail tests/tasks.retest.ts:7 saves a task
  check_failed toHaveText getByTestId('saved-task')
  expected "Release checklist" received "Saving…" waited 5003ms for toHaveText, looked 14 times, limit 5000ms
  compared whole text, ends trimmed, each run of spaces or line breaks read as one space
  screenshot .retest/runs/<time>/artifacts/…/screenshot-failure-1.png
next: npx retest inspect .retest/runs/<time> --test "tests/tasks.retest.ts > saves a task" --json
```

- The first line has the counts, the time and the exit code. A passing run is two lines.
- Each failure gives its line, its kind, the call, both values and the wait, each fact once.
- The `next:` line is the command that shows more, usually `retest inspect` on the first failure.
- Retest detects an agent from the variables agents set in their shells, such as `AGENT` or `AI_AGENT`. `--agent` turns the report on, and `--no-agent` turns it off.

## Exit codes

| Code | What an agent can do |
| --- | --- |
| 0 | Every chosen test passed. Move on. |
| 1 | A check failed. Read the failure, then fix the app or the test. |
| 2 | The run could not check everything. Read the message before changing any code. |
| 130, 143 | The run was stopped. Its result covers only what ran. |

## JSON to read

| Command | Prints |
| --- | --- |
| `retest run --reporter jsonl` | Every event as one JSON line, as it happens, and nothing else |
| `retest inspect <run-folder> --json` | The run's whole result |
| `retest inspect <run-folder> --test <id> --json` | Every step, look and check of one test |
| `retest list --json` | The tests in each file, with their lines, tags and variants |
| `retest install --list --json` | Each pinned build, its state and how to install it |

Events and results follow schema version 1 and have published JSON Schemas. The output of `list --json` has no published schema yet.

## Agent sessions

An agent that explores an app can drive a browser without a test file. An agent session uses the same drivers, commands and looks a test uses. Its API is `AgentHost`, from `@rehearsal-labs/retest/agent`.

```ts
import { AgentHost } from '@rehearsal-labs/retest/agent'

const host = new AgentHost({ targets: { chrome: { engine: 'chromium', executablePath } }, budget, logFolder, secrets: { values: { password: { value } } } })
const opened = await host.open({ owner: 'worker-1', app: 'owner', purpose: 'discovery', target: 'chrome', engine: 'chromium', baseUrl })
if (!opened.ok) throw new Error(opened.failure.message)
const { session } = opened
await session.act({ kind: 'goto', url: '/login' })
const field = await session.observe({ by: 'testId', value: 'user' })
const [first] = field.ok ? field.look.elements : []
if (first !== undefined) await session.act({ kind: 'fill', ref: first.ref, value: 'owner-a' })
const saved = await session.saveState()
await session.end()
await host.close()
```

- `act` sends one command a test's page takes, to a locator or to a reference from a look. The answer says how far the input got: not sent, sent or unknown.
- `observe` reads a locator's matches once and gives each a reference. A reference acts only on the element it names, and is refused once the page has changed.
- `recipe` turns a reference into a locator a saved test can keep, only when a read proves it finds that same element.
- The host holds the secrets. A fill of `{ secret: 'password' }` types only on origins the host allows.
- Every session holds a lease. A session nobody calls for a minute is ended, and its browser context is given back.
- An agent session writes no events and no run folder.

> [!NOTE]
> Retest has no MCP server and no installable skill for coding agents yet. [Coming soon](https://rehearsal.dev/retest/coming-soon.md) lists both.