Run tests
Run every test or a chosen few, pick the output, and read the exit code.
# every .retest.ts file under this foldernpx retest run# the test, test.for or test.describe declared on line 22npx retest run tests/tasks.retest.ts:22npx retest run --tag "smoke and not slow"npx retest run --grep "/^tasks > saves/i"npx retest run --target desktop=chromiumnpx retest run --last-failedWith no files named, run takes every .retest.ts file under the folder. It skips node_modules and folders whose names start with a dot.
Choose tests Link to Choose tests
| Choose by | How |
|---|---|
| A line | file:line keeps the test, test.for or test.describe declared on that line. Add #row for one row of a test.for, counted from 1. |
| Title | --grep text keeps tests whose full title holds the text. --grep /pattern/flags matches a pattern instead. |
| Tags | --tag "expression" keeps tests whose tags fit it. It reads and, or, not and parentheses. |
| Target | --target app=name keeps the runs on that target of the app. Repeat it for other apps. |
| Last run | --last-failed keeps the tests the last run did not pass, from .retest/last-run.json. |
A test runs when it fits every filter given. The setups the chosen tests need run too. A choice that keeps nothing exits with 2 and says why.
Flags Link to Flags
| Flag | What it does |
|---|---|
--config <path> | Loads another config. The default is retest.config.ts. |
--base-url <url> | Replaces the default app's base URL. --base-url app=url replaces one app's. Repeat it for other apps. |
--reporter <name> | human, jsonl, agent or html. With jsonl, the terminal gets only event lines. |
--output <dir> | Names a new folder for the run. The default is .retest/runs/<time>. |
--timeouts <list> | Replaces budgets for this run, such as action=500,test=3000. |
--workers <n> | How many test files run at once. The default is half the machine's cores. |
--browsers <n> | How many browsers each target's tests are spread over. |
--allow-only | Runs the tests marked only even when CI is set. |
--agent, --no-agent | Prints the short report for coding agents, or the report for people. |
--playwright | Runs Playwright test files. See Run Playwright tests. |
--browser <path> | Runs without a config, in this Chromium or Chrome. Not allowed when a config exists. |
Retest refuses to write into a folder that already holds files, so --output always names a new one. retest help run lists every flag.
List tests Link to List tests
npx retest listnpx retest list --tag smoke --jsonlist loads each file the way a run does and prints its tests with their lines, tags, locks, apps and variants. It takes the same filters as run and opens no browser.
Exit codes Link to Exit codes
| Code | Means |
|---|---|
| 0 | Every chosen test passed and cleaned up. Skipped tests do not count against it. |
| 1 | Tests ran, and at least one failed a check. |
| 2 | The run could not check everything. For example: a bad config, a missing secret, a lost browser, or a test that did not run. |
| 130 | Stopped with Ctrl+C. |
| 143 | Stopped by SIGTERM, as a CI runner does on cancel. |
When one test failed and others hit problems, the code is 1. A run that cannot be trusted as a whole, such as one whose result could not be written, gives 2 instead.
Ctrl+C stops the running test, writes the result, closes the browsers and deletes saved sign-in state. A second Ctrl+C quits at once.