Running tests

Run the whole suite when you want to check a change, or select one test while working on a failure. Retest uses your config for apps and browsers, and writes a new folder of results for each run.

Run the suite #Link to Run the suite

From the folder containing retest.config.ts, run Retest without naming a file. It discovers every .retest.ts file below that folder, skipping node_modules and folders whose names start with a dot.

$ npx retest run

$ pnpm exec retest run

$ yarn retest run

$ bunx retest run

These commands use the Retest installed in your project. A test runs on each target required by its configured apps, so one test can have several results. The terminal names each variant, such as web=chromium, and prints the run folder at the end.

If the browser, app server or a secret is not ready, run npx retest doctor to check the setup. Use Configuration to change where the app runs and which browsers it uses.

Run one file or test #Link to Run one file or test

Name a file to limit the run to its tests. Add the declaration's line number to run one test, or use --grep to select by its title.

$ npx retest run tests/task.retest.ts$ npx retest run tests/task.retest.ts:3$ npx retest run --grep "saves a task"

Line 3 is the test declaration in the example on Writing tests. Use your own declaration line when it differs. A line can also select a whole test.describe block or test.for declaration; add #2 after the line to select its second data row.

--grep searches the full title, which joins group names and the test name with > . For example, a test called saves a task inside tasks has the full title tasks > saves a task. Write a regular expression between slashes when a substring is not precise enough.

$ npx retest run --grep "/^tasks > saves/i"

Select tags and targets #Link to Select tags and targets

Tags let you choose a set of related tests without depending on their titles. Declare the tags in your config and on tests or groups, then select them with --tag.

$ npx retest run --tag "smoke and not slow"$ npx retest run --target web=chromium

The tag expression accepts and, or, not and parentheses. When your config lists tags, using another name is a usage error. --target web=chromium keeps only variants using the web app's chromium target, which must exist in the config. You can repeat --target for other apps.

Filters combine, so a test must satisfy every filter you pass. Setups needed by the selected tests still run, even when their declarations live in other test files under the root. A selection that finds nothing exits with code 2 and explains why.

List before running #Link to List before running

Use list to check which tests and targets your selection contains before opening browsers. It loads the test files and prints their declaration lines, tags, apps and variants.

$ npx retest list$ npx retest list --tag smoke --json

list accepts the same selection filters as run and can emit one JSON document for a tool. It labels declarations marked only but still lists unfocused tests, while run applies that focus before its filters.

Listing tests loads their files, as running them does. Keep server writes and other setup work inside tests or hooks because top-level code runs on each load.

Run the last failures #Link to Run the last failures

After fixing a failure, use --last-failed to rerun results marked failed, error or not_run in the last run. Retest reads .retest/last-run.json and selects those tests on the same variants. Select inconclusive tests explicitly, because this record leaves them out.

$ npx retest run --last-failed

This starts a new run with fresh results. Retest does not retry tests automatically; use the failure card's rerun command when you want to repeat only one failing test and target.

Change a run's settings #Link to Change a run's settings

Use command-line overrides when a choice belongs to one run rather than the project. For example, point the default app at a preview deployment, load another config, or reduce concurrency while investigating shared data.

$ npx retest run --base-url https://preview.example.test$ npx retest run --config retest.preview.config.ts$ npx retest run --workers 1$ npx retest run --timeouts assertion=10000,test=60000

--base-url web=https://preview.example.test replaces one named app's address instead. --workers limits how many files run at once; tests within a file run in sequence. Each test still gets its own contexts, but shared server data needs separate accounts or locks.

Choose the report #Link to Choose the report

The usual terminal report shows failures and a summary. Use the HTML reporter for a page you can open afterwards, or the JSON lines reporter for tools that need events as they happen.

$ npx retest run --reporter html$ npx retest run --reporter jsonl

html keeps the terminal report and adds report.html inside the run folder. jsonl prints event lines to standard output. With Yarn classic, use yarn -s retest run --reporter jsonl to keep Yarn's own output out of that stream. When a coding agent runs Retest, it can select a shorter report automatically; Coding agents explains that output and its next command.

By default the new folder is .retest/runs/<time>. Use --output to choose another folder, which must not already hold files. The Command line reference lists the remaining run flags.

Read the exit code #Link to Read the exit code

The exit code tells a shell or continuous integration job whether the run passed. A test failing a check and a test that could not be checked need different follow-up work.

A selection containing only skipped tests checked nothing, so it exits with 2. session_lost and outcome_unknown give a test status error, which exits with 2 unless another test failed. A failure affecting the whole run can take precedence with 2. See Results and exit codes for the complete rules.

Pressing Ctrl+C once stops the running work, writes a result and cleans up browsers, servers Retest started and saved sign-in state. A second signal exits at once and can leave the folder without result.json. When that file is missing, inspect rebuilds what it can from events and marks the run incomplete.

Next steps #Link to Next steps

• Debugging a failureRead the failure and inspect the steps it took.
• Parallel runsControl file concurrency and shared state.
• Continuous integrationRun the suite and keep its evidence in a job.