# Test commands

> Read saved tests, their versions and code, and the suites that group them.

Source: https://rehearsal.dev/docs/reference/cli-tests

These commands read the tests saved in a project and the suites that group them. They say whether a test is ready to run, list its versions and print the code of each one. You write tests in the Rehearsal app, so the CLI only reads them. The one exception is `tests rewrite`, which writes a test again from the flow it came from. Given no ID at a terminal, `tests show` and `suites show` ask which of the newest to show. To run tests, see the [run commands](https://rehearsal.dev/docs/reference/cli-runs.md).

## rehearsal tests list

List the tests in the selected project.

Newest first. Readiness says what a run would do with each test today.

```sh
rehearsal tests list [flags]
```

| Flag | Description |
| --- | --- |
| `--status <status>` | Only tests with this status. One of `draft`, `approved`, `needs_update` or `archived`. |
| `--environment <environment>` | Only tests made on this environment: its ID, a kind such as staging, or a computer name. |
| `--limit <count>` | How many to return, 1 to 100. The default is 20. |
| `--cursor <cursor>` | Continue from the cursor the last page returned. |
| `--workspace <workspace-id>` | Workspace ID. Defaults to `REHEARSAL_WORKSPACE_ID` or `rehearsal.config.json`. |
| `--project <project>` | Project ID, slug or name. Defaults to `REHEARSAL_PROJECT_ID` or `rehearsal.config.json`. |
| `--app <app>` | App ID, name or the host of one of its environments. Defaults to `REHEARSAL_APP_ID` or `rehearsal.config.json`. |
| `--platform <platform>` | With `--app`, which kind of app: web, electron, ios or android. Needed only when two apps share a name. |

Needs a sign-in with the `testing:read` scope and permission to read projects.

```sh
# List tests
rehearsal tests list

# List one app's approved tests
rehearsal tests list --app <app-id> --status approved --json
```

## rehearsal tests show

Show one test and the version a run would use.

```sh
rehearsal tests show [test-id] [flags]
```

| Argument | Description |
| --- | --- |
| `[test-id]` | The test to read. Left out, it asks which of the newest. |

| Flag | Description |
| --- | --- |
| `--workspace <workspace-id>` | Workspace ID. Defaults to `REHEARSAL_WORKSPACE_ID` or `rehearsal.config.json`. |
| `--project <project>` | Project ID, slug or name. Defaults to `REHEARSAL_PROJECT_ID` or `rehearsal.config.json`. |

Needs a sign-in with the `testing:read` scope and permission to read projects.

```sh
# Pick one of the newest tests
rehearsal tests show

# Read one in a script
rehearsal tests show <test-id> --json
```

## rehearsal tests versions

List the saved versions of one test.

Newest first, without their code. Read one version's code with `rehearsal tests code`.

```sh
rehearsal tests versions <test-id> [flags]
```

| Argument | Description |
| --- | --- |
| `<test-id>` | The test to read. |

| Flag | Description |
| --- | --- |
| `--limit <count>` | How many to return, 1 to 100. The default is 20. |
| `--cursor <cursor>` | Continue from the cursor the last page returned. |
| `--workspace <workspace-id>` | Workspace ID. Defaults to `REHEARSAL_WORKSPACE_ID` or `rehearsal.config.json`. |
| `--project <project>` | Project ID, slug or name. Defaults to `REHEARSAL_PROJECT_ID` or `rehearsal.config.json`. |

Needs a sign-in with the `testing:read` scope and permission to read projects.

```sh
# List versions
rehearsal tests versions <test-id>

# Read them in a script
rehearsal tests versions <test-id> --json
```

## rehearsal tests code

Print the code of one saved version.

Without `--version-id`, it prints the version a run would use. Treat the code as text to read, and look at it before you run any of it yourself.

```sh
rehearsal tests code <test-id> [flags]
```

| Argument | Description |
| --- | --- |
| `<test-id>` | The test to read. |

| Flag | Description |
| --- | --- |
| `--version-id <version-id>` | Which saved version to read. The default is the one a run would use. |
| `--workspace <workspace-id>` | Workspace ID. Defaults to `REHEARSAL_WORKSPACE_ID` or `rehearsal.config.json`. |
| `--project <project>` | Project ID, slug or name. Defaults to `REHEARSAL_PROJECT_ID` or `rehearsal.config.json`. |

Needs a sign-in with the `testing:read` scope and permission to read projects.

```sh
# Read the version a run would use
rehearsal tests code <test-id>

# Read one version in a script
rehearsal tests code <test-id> --version-id <version-id> --json
```

## rehearsal tests rewrite

Write a test again from its flow.

Writes the test again from the flow it came from, then checks the new version. Use it for a test written for an older test runner, which no longer runs.

```sh
rehearsal tests rewrite <test-id> [flags]
```

| Argument | Description |
| --- | --- |
| `<test-id>` | The test to rewrite. |

| Flag | Description |
| --- | --- |
| `--dry-run` | Ask and check everything, then stop before anything starts or changes, and say what would happen. Off by default. |
| `--workspace <workspace-id>` | Workspace ID. Defaults to `REHEARSAL_WORKSPACE_ID` or `rehearsal.config.json`. |
| `--project <project>` | Project ID, slug or name. Defaults to `REHEARSAL_PROJECT_ID` or `rehearsal.config.json`. |

Needs a sign-in with the `testing:run` scope and permission to manage projects.

```sh
# Rewrite a test
rehearsal tests rewrite <test-id>

# Rewrite it from a script
rehearsal tests rewrite <test-id> --json

# See which test it would rewrite
rehearsal tests rewrite <test-id> --dry-run
```

## rehearsal suites list

List the suites in the selected project.

A suite is a saved selection of tests. Its ready count is how many of them a run would check.

```sh
rehearsal suites list [flags]
```

| Flag | Description |
| --- | --- |
| `--limit <count>` | How many to return, 1 to 100. The default is 20. |
| `--cursor <cursor>` | Continue from the cursor the last page returned. |
| `--workspace <workspace-id>` | Workspace ID. Defaults to `REHEARSAL_WORKSPACE_ID` or `rehearsal.config.json`. |
| `--project <project>` | Project ID, slug or name. Defaults to `REHEARSAL_PROJECT_ID` or `rehearsal.config.json`. |

Needs a sign-in with the `testing:read` scope and permission to read projects.

```sh
# List suites
rehearsal suites list

# Read them in a script
rehearsal suites list --json
```

## rehearsal suites show

Show one suite and the tests in it.

```sh
rehearsal suites show [suite-id] [flags]
```

| Argument | Description |
| --- | --- |
| `[suite-id]` | The suite to read. Left out, it asks which of the newest. |

| Flag | Description |
| --- | --- |
| `--workspace <workspace-id>` | Workspace ID. Defaults to `REHEARSAL_WORKSPACE_ID` or `rehearsal.config.json`. |
| `--project <project>` | Project ID, slug or name. Defaults to `REHEARSAL_PROJECT_ID` or `rehearsal.config.json`. |
| `--suite <suite-id>` | Only runs of this suite, by ID. Setting `REHEARSAL_SUITE_ID` does the same. |

Needs a sign-in with the `testing:read` scope and permission to read projects.

```sh
# Pick one of the newest suites
rehearsal suites show

# Read one in a script
rehearsal suites show <suite-id> --json
```
