> ## Documentation Index
> Fetch the complete documentation index at: https://checklyhq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# checkly test

> Run checks in your project using the Checkly CLI.

export const command_0 = "checkly test"

The `checkly test` command executes all checks in your project on the Checkly cloud infrastructure. This command provides a dry-run capability for testing your monitoring setup before deployment, with support for different environments and configurations.

<Accordion title="Prerequisites">
  Before using <code>{command_0}</code>, ensure you have:

  * An initialized Checkly CLI project
  * At least one check or resource defined in your project
  * Valid Checkly account authentication (run `npx checkly login` if needed)
  * A `checkly.config.ts` or `checkly.config.js` configuration file

  For additional setup information, see [CLI overview](/cli/overview).
</Accordion>

## Basic Usage

The basic command runs all checks in your project as a test run without deploying them to your account as monitors.

```bash Terminal theme={null}
npx checkly test [arguments] [options]
```

| Option                               | Required | Description                                                                                                        |
| ------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `--config, -c`                       | -        | The Checkly CLI configuration file. If not passed, uses the `checkly.config.ts\|js` file in the current directory. |
| `--detach, -d`                       | -        | Keep checks running in the cloud when you stop the CLI with Ctrl+C, instead of cancelling the run.                 |
| `--env, -e`                          | -        | Env vars to be passed to the test run. Can be used multiple times.                                                 |
| `--env-file`                         | -        | dotenv file path to be passed. For example `--env-file="./.env"`                                                   |
| `--grep, -g`                         | -        | Only run checks where the check name matches a regular expression. Default: `.*`                                   |
| `--list`                             | -        | List all checks but don't run them.                                                                                |
| `--location, -l`                     | -        | The location to run the checks at.                                                                                 |
| `--private-location`                 | -        | The private location to run checks at.                                                                             |
| `--[no-]record`                      | -        | Record test session results in Checkly with full logs, traces and videos. Records by default since CLI v8.0.0.     |
| `--refresh-cache`                    | -        | Force a fresh install of dependencies and update the cached version.                                               |
| `--reporter, -r`                     | -        | One or more custom reporters for the test output. Supports comma-separated values and repeated flags.              |
| `--retries`                          | -        | How many times to retry a failing test run.                                                                        |
| `--tags, -t`                         | -        | Filter the checks to be run using a comma separated list of tags.                                                  |
| `--test-session-name, -n`            | -        | A name to use when recording results in Checkly.                                                                   |
| `--timeout`                          | -        | A timeout (in seconds) to wait for checks to complete.                                                             |
| `--update-snapshots, -u`             | -        | Update any snapshots using the actual result of this test run.                                                     |
| `--verbose, -v`                      | -        | Always show the full logs of the checks.                                                                           |
| `--[no-]verify-runtime-dependencies` | -        | Return an error if checks import dependencies that are not supported by the selected runtime.                      |

## Command Options

<ResponseField name="--config, -c" type="string">
  The Checkly CLI configuration file. If not passed, uses the `checkly.config.ts|js` file in the current directory.

  **Usage:**

  ```bash Terminal theme={null}
  npx checkly test --config="./checkly.staging.config.ts"
  npx checkly test -c="./checkly.staging.config.ts"
  ```
</ResponseField>

<ResponseField name="--detach, -d" type="boolean" default="false">
  By default, pressing <kbd>Ctrl</kbd>+<kbd>C</kbd> during a recorded run cancels the test session. With `--detach`, <kbd>Ctrl</kbd>+<kbd>C</kbd> exits the CLI immediately instead, leaving the checks running in the cloud.

  **Usage:**

  ```bash Terminal theme={null}
  npx checkly test --detach
  ```
</ResponseField>

<ResponseField name="--env, -e" type="string[]">
  [Environment variables](/cli/environment-variables) to be passed to the test run. Can be used multiple times.

  **Usage:**

  ```bash Terminal theme={null}
  npx checkly test --env KEY=value
  npx checkly test -e KEY=value
  ```

  **Examples:**

  ```bash Terminal theme={null}
  # Single environment variable
  npx checkly test --env "API_KEY=123456"

  # Multiple environment variables
  npx checkly test --env "API_KEY=123456" --env "BASE_URL=https://api.example.com"
  ```
</ResponseField>

<ResponseField name="--env-file" type="string">
  Path to a dotenv file containing environment variables.

  **Usage:**

  ```bash Terminal theme={null}
  npx checkly test --env-file="./.env"
  npx checkly test --env-file="./config/.env.production"
  ```
</ResponseField>

<ResponseField name="--grep, -g" type="string">
  Only run checks where the check name matches a regular expression. Default: `.*`

  **Usage:**

  ```bash Terminal theme={null}
  npx checkly test --grep="api-.*"
  npx checkly test -g="^production-.*"
  ```
</ResponseField>

<ResponseField name="--location, -l" type="string">
  The location to run the checks at.

  **Usage:**

  ```bash Terminal theme={null}
  npx checkly test --location="us-east-1"
  npx checkly test -l="eu-west-1"
  ```
</ResponseField>

<ResponseField name="--private-location" type="string">
  The private location to run checks at.

  **Usage:**

  ```bash Terminal theme={null}
  npx checkly test --private-location="my-private-location"
  ```

  **Examples:**

  ```bash Terminal theme={null}
  # Use private location
  npx checkly test --private-location="datacenter-1"

  # Combine with tags
  npx checkly test --private-location="office-network" --tags="internal"

  # With custom config
  npx checkly test --private-location="office-network" --config="./checkly.office.config.ts"
  ```
</ResponseField>

<ResponseField name="--tags, -t" type="string[]">
  Filter the checks to be run using a comma separated list of tags. Checks will only be run if they contain all of the specified tags. Multiple `--tags` flags can be passed, in which case checks will be run if they match any of the `--tags` filters.

  **Usage:**

  ```bash Terminal theme={null}
  npx checkly test --tags="tag1,tag2"
  npx checkly test -t="tag1,tag2"
  ```

  **Examples:**

  ```bash Terminal theme={null}
  # Single tag
  npx checkly test --tags="production"

  # Multiple tags (AND condition)
  npx checkly test --tags="production,webapp"

  # Multiple tag groups (OR condition)
  npx checkly test --tags="critical,api" --tags="critical,ui"
  # Runs checks with (critical AND api) OR (critical AND ui)
  ```
</ResponseField>

<ResponseField name="--list" type="boolean">
  List all checks to be run but don't run them.

  **Usage:**

  ```bash Terminal theme={null}
  # List checks
  npx checkly test --list

  # List checks with `api-` in the name
  npx checkly test --list --grep="api-.*"

  # List checks with the `production` tag
  npx checkly test --list --tags="production"
  ```
</ResponseField>

<ResponseField name="--reporter, -r" type="string[]">
  One or more custom reporters for the test output. Options: `list`, `dot`, `ci`, `github`, `json`.

  You can combine multiple reporters by passing multiple `--reporter` flags or using a comma-separated list. When no `--reporter` flag is provided, the CLI falls back to the `cli.reporters` array in `checkly.config.ts`, then defaults to `list` (or `ci` in CI environments).

  **Usage:**

  ```bash Terminal theme={null}
  npx checkly test --reporter=list
  npx checkly test -r=list
  ```

  **Examples:**

  ```bash Terminal theme={null}
  # List reporter (default)
  npx checkly test --reporter list

  # Dot reporter for minimal output
  npx checkly test --reporter dot

  # CI-optimized reporter
  npx checkly test --reporter ci

  # GitHub Actions reporter
  npx checkly test --reporter github

  # JSON output for programmatic use
  npx checkly test --reporter json > results.json

  # Multiple reporters using comma-separated values
  npx checkly test --reporter list,json

  # Multiple reporters using repeated flags
  npx checkly test --reporter list --reporter json

  # Short form with multiple reporters
  npx checkly test -r github -r json
  ```
</ResponseField>

<ResponseField name="--[no-]record" type="boolean" default="true">
  Record test results in Checkly as [a test session](/detect/testing/overview) with full logs, traces and videos. Recording is enabled by default; use `--no-record` to disable it.

  <Note>Recording defaults to enabled since CLI v8.0.0. In earlier versions, recording was opt-in via `--record`.</Note>

  **Usage:**

  ```bash Terminal theme={null}
  npx checkly test
  npx checkly test --no-record
  npx checkly test --test-session-name="CI Build #123"
  ```
</ResponseField>

<ResponseField name="--refresh-cache" type="boolean" default="false">
  Force a fresh install of dependencies and update the cached version. Use this when you've changed your project's dependencies and need Checkly to pick up the latest versions instead of using the cache from a previous run.

  **Usage:**

  ```bash Terminal theme={null}
  npx checkly test --refresh-cache
  ```
</ResponseField>

<ResponseField name="--retries" type="number">
  How many times to retry a failing test run. Default: 0, max: 3

  **Usage:**

  ```bash Terminal theme={null}
  npx checkly test --retries=2
  ```

  **Examples:**

  ```bash Terminal theme={null}
  # No retries (default)
  npx checkly test --retries 0

  # Retry twice on failure
  npx checkly test --retries 2

  # Maximum retries
  npx checkly test --retries 3
  ```
</ResponseField>

<ResponseField name="--test-session-name, -n" type="string">
  A name to use when recording results in Checkly.

  **Usage:**

  ```bash Terminal theme={null}
  npx checkly test --test-session-name="Release v1.2.3"
  npx checkly test -n="Nightly Test Run"
  ```
</ResponseField>

<ResponseField name="--timeout" type="number" default="600">
  A timeout (in seconds) to wait for checks to complete.

  **Usage:**

  ```bash Terminal theme={null}
  npx checkly test --timeout=300
  ```
</ResponseField>

<ResponseField name="--update-snapshots, -u" type="boolean">
  Update any snapshots using the actual result of this test run.

  **Usage:**

  ```bash Terminal theme={null}
  npx checkly test --update-snapshots
  npx checkly test -u
  ```

  <Note>Snapshots are essential for [visual regression testing in Browser Checks](/detect/synthetic-monitoring/browser-checks/visual-regressions).</Note>
</ResponseField>

<ResponseField name="--verbose, -v" type="boolean">
  Always show the full logs of the checks.

  **Usage:**

  ```bash Terminal theme={null}
  npx checkly test --verbose
  npx checkly test -v
  ```
</ResponseField>

<ResponseField name="--verify-runtime-dependencies" type="boolean">
  Return an error if checks import dependencies that are not supported by the selected runtime. Default: true

  **Usage:**

  ```bash Terminal theme={null}
  npx checkly test --verify-runtime-dependencies
  npx checkly test --no-verify-runtime-dependencies
  ```

  Runtime-dependent checks run in a specific runtime with a pre-defined set of dependencies. If you're using private locations and want to provide your own dependencies, disable the built-in dependency validation.

  <Tip>You can provide custom dependencies in [Playwright Check Suites](/detect/synthetic-monitoring/playwright-checks/overview) because they don't rely on a specific runtime.</Tip>
</ResponseField>

## Examples

Dry run all your project checks and monitors:

```bash Terminal theme={null}
npx checkly test
```

Dry run checks that have `product` and `api` in the file name:

```bash Terminal theme={null}
npx checkly test product api
```

Run a test session in Checkly with git branch info, full logging, videos and traces:

```bash Terminal theme={null}
npx checkly test
```

Dry run all checks against a specific location:

```bash Terminal theme={null}
npx checkly test --location eu-west-1
```

Specify [environment variables](/cli/environment-variables) to dry run checks with a specific URL and a password. These variables are available on `process.env`:

```bash Terminal theme={null}
npx checkly test --env ENVIRONMENT_URL="https://preview.acme.com" --env PASSWORD=doremiabc123
```

## Cancelling a run

<Note>Available in CLI v8.0.0+.</Note>

`checkly test` records a test session by default, so pressing <kbd>Ctrl</kbd>+<kbd>C</kbd> cancels it. Cancellation applies only to Playwright Check Suite runs inside the session; other check types finish normally. Runs started with `--no-record` cannot be cancelled.

The CLI keeps running after the first <kbd>Ctrl</kbd>+<kbd>C</kbd> to report the cancelled results. Press <kbd>Ctrl</kbd>+<kbd>C</kbd> again to exit immediately without waiting.

Pass the `--detach` flag to keep the checks running in the cloud instead — <kbd>Ctrl</kbd>+<kbd>C</kbd> then exits the CLI immediately without cancelling.

See [Cancellation](/concepts/cancellation) for the full flow.

## Related Commands

* [`checkly pw-test`](/cli/checkly-pw-test) - Run Playwright tests in the Checkly cloud
* [`checkly trigger`](/cli/checkly-trigger) - Run deployed checks on-demand
* [`checkly deploy`](/cli/checkly-deploy) - Deploy your application