# Configuration options

> Set every configuration option with its supported values and defaults.

Source: https://rehearsal.dev/retest/docs/reference/config

Use this reference when you need a config key's accepted values or default. For a first config and an explanation of apps and targets, start with [Configuration](https://rehearsal.dev/retest/docs/essentials/configuration.md).

## Config file

Export your config as the default export. The command line looks in the working directory, or loads the path you pass with `--config`. Relative paths inside the config resolve from its folder. Unknown keys are errors, and optional keys set to `undefined` count as absent.

```ts filename="retest.config.ts"
import { chrome, defineConfig, env } from '@rehearsal-labs/retest'

const config = defineConfig({
  apps: { web: chrome({ baseUrl: 'http://127.0.0.1:4173' }) },
  secrets: { password: env('TASK_APP_PASSWORD') },
  timeouts: { test: 30_000 },
})

export default config

declare module '@rehearsal-labs/retest' {
  interface Register {
    config: typeof config
  }
}
```

This config gives tests one web app and a password reference. Registering its type makes the declared names available to TypeScript in test files. Retest also validates the config when it loads; `defineConfig` itself preserves types without performing that validation.

## Top-level keys

| Key | Default | Meaning |
| --- | --- | --- |
| `apps` | Required | Non-empty map of app names to a target or an app with named targets. |
| `defaultApp` | The only app, when there is one | App a test receives as page when it declares no apps. |
| `runs` | No combinations declared | List of app-to-target maps for tests using several apps with several targets. |
| `secrets` | None | Secret sources by name, from env(name) or a function. |
| `secretOrigins` | App base URL origins for browser targets | Additional destinations per secret. Electron requires explicit http or https origins; native apps require exact bundle ids. |
| `inboxes` | None | Mailbox readers by name, optionally with extra allowed origins. |
| `testIds` | Any string type-checks | Array of test ids, or a named map whose values are test ids, for TypeScript checking. |
| `tags` | No catalogue | Allowed tag names. The words and, or and not are reserved. |
| `states` | No catalogue | Names for saved sign-in states. A test using one still needs a setup that saves it. |
| `locks` | None allowed | Names of shared resources a test may hold exclusively during a run. |
| `timeouts` | Built-in budgets | Partial map of budgets in milliseconds. |
| `evaluation` | No judges | Judges and limits for AI checks. |
| `diagnostics` | Capture on, no strict policy | Console and network capture, limits and failure policy. |
| `recording` | Off | Video capture and retention settings. |
| `pixels` | Allowed | Per-app rules for screenshots and recordings. |

App, target, secret, inbox, tag, state and lock names start with a letter and contain letters, digits, underscores or hyphens. An app's targets must all be one kind: web browsers, Electron apps, iOS simulator apps or macOS apps.

## Apps and target combinations

A standalone target can carry app settings directly. For several targets, put those settings on `app({ targets })`, outside the target map. A test using one app runs once per target. When two or more of its apps each have several targets, matching entries in `runs` must name them all.

| App key | Default | Meaning |
| --- | --- | --- |
| `targets` | Required for app() | Non-empty map of target names to target configurations. |
| `baseUrl` | None | Absolute http or https address used to resolve relative navigation. Web apps only. |
| `start.command` | No server started | Shell command that starts the app server. |
| `start.ready` | Required with start | http or https address that answers when the server is ready. |
| `start.cwd` | Config folder | Working directory for the command, relative to the config folder. |
| `start.timeoutMs` | Setup budget | Positive whole milliseconds to wait for readiness. |

Retest reuses a server that already answers at `start.ready`; otherwise it starts the command and stops that server after the run. `start` belongs to the app even when the app has several targets.

## Browser targets

| Target | Construction | Executable default |
| --- | --- | --- |
| Chromium | `chromium(options?)` | executablePath, then RETEST_CHROMIUM. |
| Chrome | `chrome(options?)` | Installed Chrome for the chosen channel. |
| Edge | `edge(options?)` | Installed Edge for the chosen channel. |
| Firefox | `{ browser: 'firefox', ... }` | executablePath, then the pinned cache build, then the macOS installation only at 133.0.3 build 20241209150345. Use retest install firefox for the pinned build. |
| WebKit | `{ browser: 'webkit', ... }` | executablePath, then RETEST_WEBKIT_BUILD. |

| Target key | Default | Meaning |
| --- | --- | --- |
| `browser` | Required in a plain object | chromium, chrome, edge, firefox or webkit. Helpers supply it. |
| `headless` | `true` | Request a headless browser. Visible-window mode remains unverified. |
| `executablePath` | See target table | Chromium, Firefox or WebKit path, relative to the config folder. WebKit also accepts its unpacked build folder. |
| `channel` | `stable` | Chrome and Edge only: stable, beta, dev or canary. |
| `viewport` | No explicit override | width and height in positive whole CSS pixels. Cannot accompany emulate. |
| `emulate` | None | Named device or custom emulation object. |
| `proxy.server` | No proxy | http, https, socks4 or socks5 proxy address without credentials. |
| `proxy.bypass` | None | Array of bypass rules; \<-loopback> sends loopback traffic through Chrome's proxy. |

Firefox accepts a viewport and pixel ratio but refuses proxies, touch, mobile layout and a custom user agent. WebKit accepts a viewport, pixel ratio and user agent, but refuses proxies, touch and mobile layout. See [Browsers](https://rehearsal.dev/retest/docs/platforms/browsers.md) before choosing a target.

### Emulation values

Named devices are Pixel 9, Galaxy S24, iPhone 17 and iPad Pro 11. These emulate screens in desktop browsers. A custom object has the following keys.

| Key | Default | Meaning |
| --- | --- | --- |
| `viewport.width`, `viewport.height` | Required | Positive whole CSS pixels. |
| `deviceScaleFactor` | Required | Positive pixel ratio. |
| `touch` | Required | Whether the page has a touch screen. |
| `isMobile` | `false` | Whether to use mobile layout behaviour. |
| `userAgent` | Browser's own | User agent string exposed to the app. |

## Native targets

Native targets use a plain object with `platform`. They take no `baseUrl` or browser emulation settings. [iOS simulator apps](https://rehearsal.dev/retest/docs/platforms/ios.md) and [macOS apps](https://rehearsal.dev/retest/docs/platforms/macos.md) cover executor and machine requirements.

| Key | Default | Meaning |
| --- | --- | --- |
| `platform` | Required | ios-simulator or macos. |
| `appPath` | Required | Path to the .app bundle, relative to the config folder. |
| `device` | Required on iOS | Simulator device type, such as iPhone 17. |
| `runtime` | Required on iOS | iOS runtime version. This release requires 26.5. |
| `arguments` | None | Array of launch arguments. |
| `environment` | None | Map of launch environment variables to strings. |
| `diagnostics.logs` | `stdout` | stdout captures the owned app's output; none leaves launch to the executor without an app log. |
| `diagnostics.network.path` | No network source | Metadata file written by the backend, relative to the config folder. |
| `diagnostics.network.client` | Required with network | ios or macos, matching the file's records for this app. |

## Electron targets

`electron(options)` supplies `browser: 'electron'`. Retest launches the app afresh for each test and uses its first window. Electron targets take no base URL, proxy or emulation settings.

| Key | Default | Meaning |
| --- | --- | --- |
| `executablePath` | Required | Electron executable, relative to the config folder. |
| `appPath` | Required | App folder or entry file, relative to the config folder. |
| `args` | None | Arguments following the app path. |
| `userDataDir` | Fresh temporary folder | Persistent app data folder. Each target needs a distinct folder. |

## Secrets and inboxes

`env(name)` returns `{ env: name }`; Retest reads that variable once when a run starts. A function source receives `{ signal }` and returns a string or promise each time a fill needs it. Judge credentials use the same source shape.

`inboxes.<name>` is a reader function, or `{ messages: reader, origins?: string[] }`. The reader receives `{ signal }` and returns messages newest first. A message has `subject`, `from`, plain `text`, `codes`, `links` containing `url` and `text`, and `receivedAt` as a Date, ISO string or epoch milliseconds.

Secret fills, inbox codes and inbox links are restricted to app origins plus their declared additional destinations. Read [Signing in and secrets](https://rehearsal.dev/retest/docs/guides/signing-in.md) and [Email codes and links](https://rehearsal.dev/retest/docs/guides/email-codes-and-links.md) for complete examples.

## Timeouts

Every budget is a whole number from 1 to 2147483647 milliseconds. Command-line overrides replace the configured budget. An action or matcher's `{ timeout }` can shorten its budget, while the test's remaining time still limits the call.

| Key | Default in milliseconds | Scope |
| --- | --- | --- |
| `collection` | 10000 | Loading one test file. |
| `setup` | 60000 | Starting a browser, opening pages and waiting for app readiness. |
| `action` | 10000 | One action. |
| `navigation` | 30000 | One navigation. |
| `assertion` | 5000 | One check that waits. |
| `test` | 60000 | One test, unless it declares its own timeout. |
| `cleanup` | 10000 | Finishing outstanding commands, failure capture and closing resources. |

## AI check configuration

| Key under evaluation | Default | Meaning |
| --- | --- | --- |
| `judges` | Required | Non-empty map of judges. |
| `defaultJudge` | The only judge, when there is one | Judge used when a check names none. |
| `timeoutMs` | 30000 | Check budget, also limited by the test's time left. |
| `judges.<name>.adapter` | Required | Module path, package name or evaluator factory. |
| `judges.<name>.credentials` | None | Named secret sources, resolved in Retest's process. |
| `judges.<name>.options` | Empty object | JSON options passed to the adapter. |
| `judges.<name>.accepts` | Required | Non-empty list drawn from text, images and frames. |

| Key under evaluation.limits | Default | Limit |
| --- | --- | --- |
| `callsPerTest` | 5 | Calls per attempt. |
| `callsPerRun` | 100 | Calls across the run. |
| `concurrentCalls` | 2 | Calls waiting on judges at once. |
| `maxOutputTokens` | 1000 | Output tokens per call. |
| `maxInputBytes` | 8000000 | Input bytes per call. |
| `maxImages` | 4 | Screenshots per call. |
| `maxImageWidth`, `maxImageHeight` | 4096 each | Image dimensions. |
| `maxFrames` | 16 | Recording frames per call, with a separate media cap of 64. |
| `maxDiagnosticRecords` | 200 | Diagnostic records per call. |

Evaluation limits are whole numbers from 1 to 2147483647. They bound requests across the run rather than guaranteeing that a provider accepts that much input or output.

The built-in adapter is `@rehearsal-labs/retest/evaluation/ai-sdk`. It needs the `ai` package, the selected provider package and an `apiKey` credential. Its options are below; [AI checks](https://rehearsal.dev/retest/docs/guides/ai-checks.md) shows a complete configuration.

| Adapter option | Default | Meaning |
| --- | --- | --- |
| `provider` | Required | anthropic, openai or azure. |
| `model` | Required | Model id, or Azure deployment name. |
| `baseURL` | Provider's public endpoint | https endpoint, or http to localhost, 127.x.x.x or ::1. Azure requires this or resourceName, never both. |
| `resourceName` | None | Azure resource name, as an alternative to baseURL. |
| `apiVersion` | SDK default | Azure API version, when supported by that endpoint. |
| `temperature`, `topP` | Not sent | Optional sampling settings; unsupported settings are recorded. |

## Console and network capture

| Key under diagnostics | Default | Meaning |
| --- | --- | --- |
| `capture` | `true` | Collect console and network records within the target's supported scope. |
| `requireComplete` | `false` | Prevent a pass when capture is incomplete. |
| `strict.runtimeErrors` | `false` | Fail for uncaught errors and unhandled rejections. |
| `strict.consoleErrors` | `false` | Fail for errors logged by app code. |
| `strict.transportFailures` | `false` | Fail for transport failures. |
| `strict.httpErrors` | `false` | Fail for responses with status 400 or above. |
| `strict.allow` | Empty list | Substrings in messages or addresses that exclude matching records from the policy. |

A `strict` block needs at least one enabled rule. Neither `strict` nor `requireComplete: true` can accompany `capture: false`. Without a strict policy, captured errors do not fail tests.

| Key under diagnostics.limits | Default | Limit per attempt |
| --- | --- | --- |
| `consoleEntries` | 1000 | Console messages and runtime errors. |
| `consoleBytes` | 1048576 | Bytes of console records. |
| `requests` | 1000 | Request hops. |
| `networkBytes` | 2097152 | Bytes of network records. |
| `textLength` | 4096 | Length of each message. |
| `stackFrames` | 20 | Frames in each recorded stack. |

## Recording and pixel rules

| Key under recording | Default | Meaning |
| --- | --- | --- |
| `record` | `false` | Record every app whose pixel rules allow it. |
| `apps` | No overrides | App-to-boolean map overriding record for individual apps. |
| `required` | `false` | Require complete requested recordings for the run to pass. |
| `keep` | `all` | all or failures. Recordings used by AI checks remain kept. |
| `fps` | 10 | Whole frames per second from 1 to 30. |
| `size.width`, `size.height` | 1280 and 720 | Even whole pixels from 16 to 4096. |
| `nativeWithholding` | `false` | Withhold pixels around plain native secret entry until clearance is verified. |

`pixels.<app>.screenshots` and `pixels.<app>.recordings` each accept `allowed` or `never`, defaulting to `allowed`. Explicitly recording an app that forbids recordings is an error, as is requiring recordings when no app records. `RETEST_NATIVE_WITHHOLDING=true` or `false` overrides the native withholding setting.

Recording needs the media process and ffmpeg. Missing required evidence affects the run independently of what each test observed. See [Recordings and evidence](https://rehearsal.dev/retest/docs/guides/recordings-and-evidence.md) for setup, pixel withholding and retention.

## Next steps

- [Test API](https://rehearsal.dev/retest/docs/reference/test-api.md): Look up test options, actions and matchers.
- [Configuration](https://rehearsal.dev/retest/docs/essentials/configuration.md): Build a configuration for your test suite.
- [Recordings and evidence](https://rehearsal.dev/retest/docs/guides/recordings-and-evidence.md): Choose what a run captures and keeps.