Configuration
Set up the apps a test opens, the browsers it runs in, its base URL, its screen and its time limits.
A project's config is retest.config.ts in the folder Retest runs from. --config <path> names another file. Retest loads the config in its own process, and test files never load it.
import { app, chrome, chromium, defineConfig, env } from '@rehearsal-labs/retest'const baseUrl = process.env['TASK_APP_URL'] ?? 'http://127.0.0.1:4173'const config = defineConfig({ apps: { web: chrome({ baseUrl }), admin: chrome({ baseUrl }), desktop: app({ baseUrl, targets: { chrome: chrome(), chromium: chromium() } }), phone: app({ baseUrl, targets: { pixel: chrome({ emulate: 'Pixel 9' }), iphone: chrome({ emulate: 'iPhone 17' }) } }), }, defaultApp: 'web', runs: [ { desktop: 'chrome', phone: 'pixel' }, { desktop: 'chromium', phone: 'iphone' }, ], secrets: { password: env('TASK_APP_PASSWORD') }, tags: ['smoke', 'roles', 'browsers', 'phone'], states: ['signed-in'], locks: ['saves'], timeouts: { action: 5000, assertion: 5000, test: 30_000 },})export default configdeclare module '@rehearsal-labs/retest' { interface Register { config: typeof config }}Keys Link to Keys
| Key | What it holds |
|---|---|
apps | Each app the tests open, with its targets |
defaultApp | The app page is. With one app, that app. |
runs | Which targets run together, for tests that use two apps with several targets each |
secrets | Each secret's source: env(name), or a function |
secretOrigins | More origins where a secret may be typed |
testIds | The test ids getByTestId accepts. Only the type check reads it. |
tags | The tags tests may use. --tag refuses any other. |
states | The names of the sign-in states test.setup may save |
locks | The shared state tests may hold with locks |
timeouts | Budgets that replace the defaults |
evaluation | The judges for AI checks |
diagnostics | Console and network capture, and when it fails a test |
recording | Which apps are recorded as video, and whether a recording is required |
pixels | Whether screenshots and recordings may be taken, by app |
Names of apps, targets, secrets, tags, states and locks hold letters, digits, _ and -, and start with a letter. Paths in the config are relative to its folder.
An invalid config stops the run with exit code 2 before anything starts. The message names the file and every key at fault, such as apps.web.baseUrl: expected an http or https URL.
Apps and targets Link to Apps and targets
An app is what a test opens. A target is where it runs. An app is a target on its own, or app({ baseUrl, start, targets }) with several.
| Target | Runs |
|---|---|
chrome({ channel }) | Google Chrome. channel is stable, the default, or beta, dev or canary. |
edge({ channel }) | Microsoft Edge, with the same channels. |
chromium({ executablePath }) | The Chromium at executablePath, or at the path in RETEST_CHROMIUM. |
{ browser: 'firefox' } | Firefox, on macOS. See Browser support. |
{ browser: 'webkit' } | Playwright's WebKit build, on macOS. |
electron({ executablePath, appPath }) | An Electron app. See Desktop apps. |
{ platform: 'ios-simulator', ... } | An app on an iOS simulator. See Mobile apps. |
{ platform: 'macos', ... } | A macOS app. See Desktop apps. |
A test that uses an app with several targets runs once on each. With two such apps, runs lists the pairs to run, one entry each. Each run is a variant, named like desktop=chromium.
Base URL Link to Base URL
baseUrl is the address page.goto('/') opens a path on. The command line can replace it, which is how CI points the tests at a preview.
npx retest run --base-url https://preview.example.comnpx retest run --base-url web=https://preview.example.com --base-url admin=https://admin.preview.example.comScreen size Link to Screen size
viewport: { width, height }sizes the page and nothing else, as inchromium({ viewport: { width: 1280, height: 720 } }).emulatemakes a desktop browser pretend to be a device, by name or by its screen. Web apps lists the devices.- A target takes
viewportoremulate, not both.
Start the app Link to Start the app
An app with start: { command, ready, cwd, timeoutMs } gets its server started when a test first needs it.
web: chrome({ baseUrl: 'http://localhost:3000', start: { command: 'npm run dev', ready: 'http://localhost:3000' },}),- Retest asks
readywith an HTTP GET. If anything answers, it uses that server and never stops it. - Otherwise it runs
commandin a shell, with its output inlogs/app-<name>.log, and waits forreadyto answer. - When the run ends, it stops the server it started.
- A server that exits early or never answers fails every test that needs it, and the failure names the log.
Budgets Link to Budgets
Every wait answers to a budget, in milliseconds. timeouts in the config replaces some, and --timeouts action=500,test=3000 replaces them again for one run.
| Budget | Default | What it covers |
|---|---|---|
collection | 10000 | Loading each test file |
setup | 60000 | Launching a browser, opening a test's pages and starting an app server |
action | 10000 | One action |
navigation | 30000 | One goto, reload, goBack or goForward |
assertion | 5000 | One check |
test | 60000 | One test |
cleanup | 10000 | Closing pages and browsers, and failure screenshots |
How many files run at once is a flag, not a config key. Pass --workers <n> to retest run, as Run tests in parallel explains.