Command line
Choose commands and flags to set up, run and inspect your tests.
Use the command line to prepare your project, choose tests and read a saved run. This page lists every command and flag; Running tests explains the usual workflow.
Commands Link to Commands
| Command | What it does |
|---|---|
retest init [options] | Write a config, example test and test tsconfig. |
retest doctor [options] | Check the configured targets, app servers and environment secrets. |
retest install <engine...> | Install the named pinned builds. |
retest install --list [options] | List pinned builds and their local cache state. |
retest licences [engine] | List builds with licence notices, or print one engine's notices. |
retest list [files...] [options] | Load test declarations without opening a browser. |
retest run [files...] [options] | Run selected tests and write a new run folder. |
retest inspect <run-folder> [options] | Read results and steps without running tests again. |
retest report <run-folder> | Write or replace the folder's HTML report. |
retest help [command] | Show general help or the named command's help. |
retest --help and retest -h show general help. Add either flag after a command for its help. retest --version and retest -v print the installed version. Calling retest without a command prints help and exits 2.
Value options accept --name value or --name=value. Flags take no value. Unknown options, missing values and repeated options are errors, except where a table explicitly allows repetition.
Create a project Link to Create a project
init writes the starter files, adds test scripts to package.json and adds .retest/ to .gitignore. It leaves existing starter files in place and prints an install command without installing packages.
npx retest init --app web=http://localhost:3000 --browser chrome --yesThis chooses the app and browser without questions. Without a terminal, or when a coding agent is detected, init needs --app or --yes; otherwise it exits 2 and writes nothing. An existing config skips the questions.
| Option | Meaning and default |
|---|---|
--app <name=url> | App name and base URL. The defaults are web and http://localhost:3000. |
--start <command> | App startup command. A detected dev or start script is offered interactively, or accepted with --yes. |
--browser <name> | chromium, chrome or edge. Otherwise use the first available Chrome, Edge or Chromium, falling back to Chrome. |
--ci github | Also write a GitHub Actions workflow. No workflow by default. |
--yes | Use defaults for unanswered questions. |
Check the setup Link to Check the setup
retest doctor loads the config, checks environment secrets and app readiness, and starts and stops configured app servers when needed. It launches and closes only Chromium-family browser targets. Firefox and WebKit are checked from their files; Electron's executable and app are checked without starting them. Native targets receive prerequisite checks. No test runs and nothing is downloaded.
| Option | Meaning and default |
|---|---|
--config <path> | Config file, defaulting to retest.config.ts in the working directory. |
Install pinned builds Link to Install pinned builds
install accepts chromium, firefox, webkit, electron, webdriveragent, mac2 and media. The native executor names are webdriveragent for iOS and mac2 for macOS. Available pins depend on the machine; use the list command before requesting a build.
npx retest install --listnpx retest install chromiumThe second command downloads Chromium. Native executors build from local checkouts at pinned commits. The media process builds from the shipped Rust crate and needs Rust 1.88 or later and ffmpeg. Browsers lists supported browser builds.
| Option | Meaning |
|---|---|
--list | Inspect pins and the cache without downloading. Takes no engine names. |
--verify | With --list, verify the files of installed builds. |
--json | With --list, print one JSON document. |
--media-binary <path> | For install media alone, use a prebuilt binary only if its exact build has a pinned checksum. |
--media-mirror <url> | For install media alone, fetch a pinned prebuilt binary from this mirror. Checksums still apply. |
--offline | For install media alone, build with cargo --offline using cached pinned crates. |
No prebuilt media binary has a pinned checksum in this release, so --media-binary and --media-mirror currently refuse the request. Use the source build with retest install media.
RETEST_DOWNLOAD_MIRROR chooses a mirror for pinned browser downloads. It preserves checksum checks and refuses credentials, queries or fragments in the mirror address. retest licences [engine] reads local or bundled licence notices and downloads nothing; it has no command-specific flags.
Choose tests Link to Choose tests
run and list share the following selection options. With a config and no files, they discover .retest.ts files under the working directory. Without a config, name the files explicitly.
| Option | What it selects |
|---|---|
--config <path> | Use this config instead of retest.config.ts in the working directory. |
--grep <text> | Full titles containing the text, or matching /pattern/flags. The g and y regular expression flags are refused. |
--tag <expression> | Tags combined with and, or, not and parentheses. |
--target <app=name> | Tests using this app target. Repeat for other apps. Requires a config. |
--last-failed | Variants the last run did not pass, read from .retest/last-run.json. |
file:line | The test, group or parameterised test declared on that line. |
file:line#row | One row of test.for, numbered from 1. |
npx retest list --tag "smoke and not slow"npx retest run tests/task.retest.ts --grep "saves a task"Filters combine, so a test must match each one. Required setups still run. test.only narrows the run before these filters; list shows both focused and unfocused declarations. run exits 2 when it selects nothing or only skipped tests. list can list skipped declarations successfully.
Run tests Link to Run tests
retest run uses the selected config and writes .retest/runs/<time> unless you choose an output folder. Its additional options control the runtime and report.
| Option | Meaning and default |
|---|---|
--browser <path> | Chromium or Chrome executable for a run without a config. Refused beside --config or an existing default config. |
--base-url <url> | A plain URL replaces the default app's base URL. With a config, app=url replaces a named app's URL; repeat for other apps. |
--reporter <name> | human, agent, jsonl or html. Defaults to human, or agent when a coding agent is detected. |
--output <dir> | New or empty run folder. Default: .retest/runs/<time>. A non-empty folder is refused. |
--timeouts <list> | Override budgets as name=milliseconds pairs separated by commas. |
--workers <n> | Files running at once. Default: half the available cores, rounded down, at least 1. |
--browsers <n> | Browser processes per target. Default: one per three active workers, rounded up, bounded by the target's work. |
--playwright | Resolve @playwright/test to Retest's compatibility API. Without files, discover .spec files. |
--allow-only | Allow focused tests when the CI environment would otherwise refuse them. |
--update-screenshots | Write each compared screenshot baseline and pass those comparisons. The report counts baselines written. |
--headed | Request visible browser windows. This mode has not been verified. |
--agent | Choose the coding-agent report. |
--no-agent | Disable automatic coding-agent reporting. |
human prints the terminal report; agent prints a shorter report with commands to investigate. jsonl writes only event lines to stdout. html prints the human report and writes report.html when the run ends. Conflicting reporter flags are refused.
Budget defaults in milliseconds are collection 10000, setup 60000, action 10000, navigation 30000, assertion 5000, test 60000 and cleanup 10000. Configuration options explains their scope. Recording is configured in the file; there is no recording flag.
List declarations Link to List declarations
retest list takes the shared selection options and --json. It prints source lines, tags, locks, apps and target variants without starting a browser. JSON output is one document with schemaVersion: 1 and files; it has no published JSON Schema.
Read a saved run Link to Read a saved run
inspect reads one run folder. When result.json is missing, it reconstructs an incomplete result from the events. Its exit code describes whether it could read the folder, rather than whether the recorded tests passed.
| Option | Meaning |
|---|---|
--json | Print the run result, or a test report when --test is present. |
--test <id> | Show one test's steps and evidence. Use its full id, including file and group names. |
--target <app=name> | With --test, choose one recorded variant. Repeat for other apps. |
npx retest inspect .retest/runs/<time> --test "tests/task.retest.ts > saves a task" --jsonnpx retest report .retest/runs/<time>The first command returns that test, its events and available diagnostics. The second writes a portable report.html from the saved run, replacing an earlier report. report has no command-specific flags.
Exit codes Link to Exit codes
For run, 0 means the selected work passed, 1 means a test failed, 2 means the run could not check everything, and 130 or 143 means interruption. See Results and exit codes for precedence and mixed results. Other commands return 0 on success and 2 when they cannot complete their task. init, doctor, install and list can also return 130 or 143 when interrupted.