Configuration options
Set every configuration option with its supported values and defaults.
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.
Config file Link to 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.
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 configdeclare 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 Link to 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 Link to 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 Link to 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 before choosing a target.
Emulation values Link to 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 Link to Native targets
Native targets use a plain object with platform. They take no baseUrl or browser emulation settings. iOS simulator apps and macOS apps 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 Link to 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 Link to 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 and Email codes and links for complete examples.
Timeouts Link to 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 Link to 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 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 Link to 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 Link to 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 for setup, pixel withholding and retention.