# Run tests

> Run every test or a chosen few, pick the output, and read the exit code.

Source: https://rehearsal.dev/retest/essentials/run-tests

```sh
# every .retest.ts file under this folder
npx retest run
# the test, test.for or test.describe declared on line 22
npx retest run tests/tasks.retest.ts:22
npx retest run --tag "smoke and not slow"
npx retest run --grep "/^tasks > saves/i"
npx retest run --target desktop=chromium
npx retest run --last-failed
```

With 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

| 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

| 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](https://rehearsal.dev/retest/scaling-up/playwright-tests.md). |
| `--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

```sh
npx retest list
npx retest list --tag smoke --json
```

`list` 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

| 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.

> [!NOTE]
> 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.