> ## Documentation Index
> Fetch the complete documentation index at: https://www.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.

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.

> **Prerequisites**
>
> Before using `checkly test`, 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](https://www.checklyhq.com/docs/cli/overview.md).

## 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"` |
| `--[no-]fail-on-no-matching` | - | Exit with a failing status code when there are no matching checks. Enabled by default. |
| `--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. |
| `--max-failures` | - | Stop waiting for the remaining checks once this many checks have failed, and exit with a failing status code. |
| `--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 each check to make progress once it starts running: report a retry attempt or its result. Checks that have not started yet get up to 900 additional seconds for server-side scheduling. |
| `--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

**--config, -c** `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"
```

**--detach, -d** `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
```

**--env, -e** `string[]`

[Environment variables](https://www.checklyhq.com/docs/cli/environment-variables.md) 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"
```

**--env-file** `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"
```

**--\[no-]fail-on-no-matching** `boolean` (default: true)

Exit with a failing status code (`1`) when there are no checks to run, for example because the file arguments, `--grep` or `--tags` filters match none. This keeps a typo in a filter from turning a CI job green without running anything.

**Usage:**

```bash Terminal theme={null}
npx checkly test --fail-on-no-matching
npx checkly test --no-fail-on-no-matching
```

**Examples:**

```bash Terminal theme={null}
# Default behavior (enabled)
npx checkly test --tags non-existent-tag
# Exits with status code 1 because no checks match

# Disable the behavior
npx checkly test --no-fail-on-no-matching --tags optional-tag
# Exits successfully even if no checks match
```

> [!NOTE]
>
> Available since CLI v10.0.0. Earlier versions always exit successfully when no checks match.

**--grep, -g** `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-.*"
```

**--location, -l** `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"
```

**--max-failures** `number`

Stop waiting for the remaining checks once this many checks have failed (a whole number of 1 or more), and exit with a failing status code. Use it in CI to see a broken change fail early instead of waiting for the whole run. Overrides `cli.maxFailures` in your Checkly config.

Only a check's final result counts toward the limit: a check that passes after a retry does not count, and neither does a degraded check. If the failure that reaches the limit is the last check to finish, the run completes normally.

When the limit is reached, the CLI writes its reports, marks the remaining checks as not finished, and asks Checkly to cancel the test session. Only some check types, such as Playwright Check Suites, can be cancelled once they are running, so other checks may still run to completion in Checkly. The `json` reporter gives those checks `"result": "Not finished"` and adds a top-level `"stoppedEarly": { "reason": "maxFailures", "maxFailures": <n> }` field.

Cannot be combined with `--detach` or `--update-snapshots`.

**Usage:**

```bash Terminal theme={null}
npx checkly test --max-failures=1
```

**Examples:**

```bash Terminal theme={null}
# Stop at the first failed check
npx checkly test --max-failures=1

# Retry failing checks, and stop once three checks still fail after their retries
npx checkly test --retries=2 --max-failures=3
```

**--private-location** `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"
```

**--tags, -t** `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)
```

**--list** `boolean`

List all checks to be run but don't run them. The command exits successfully even when no checks match.

**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"
```

**--reporter, -r** `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 `ci` when the CLI detects a CI environment or an AI agent, and to `list` otherwise. Set `CHECKLY_CLI_MODE` to `interactive`, `ci` or `agent` to override the detection.

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

**--\[no-]record** `boolean` (default: true)

Record test results in Checkly as [a test session](https://www.checklyhq.com/docs/detect/testing/overview.md) 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`.

**Usage:**

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

**--refresh-cache** `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
```

**--retries** `number`

How many times to retry a failing test run. Default: 0, max: 3

A check that passes after one or more retries still counts as passed, but the output shows how many retries it needed, for example `(2 retries)`, and the summary counts it as flaky.

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

**--test-session-name, -n** `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"
```

**--timeout** `number` (default: 600)

A timeout (in seconds) to wait for each check to make progress once it starts running: report a retry attempt or its result. Checks that have not started yet get up to 900 additional seconds for server-side scheduling.

The timer restarts whenever a check starts running and whenever it reports a failed attempt that will be retried, so a check that retries several times can take longer than this value in total. The timeout only ends the wait when a check stops reporting progress.

Checkly can stagger the start of checks in large test sessions by up to 900 seconds. If a check still has not started within this value plus that allowance, the CLI reports that the check did not start. That usually means a problem on Checkly's side: check [the status page](https://is.checkly.online) or contact support.

**Usage:**

```bash Terminal theme={null}
npx checkly test --timeout=300
```

**--update-snapshots, -u** `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](https://www.checklyhq.com/docs/detect/synthetic-monitoring/browser-checks/visual-regressions.md).

**--verbose, -v** `boolean`

Always show the full logs of the checks.

**Usage:**

```bash Terminal theme={null}
npx checkly test --verbose
npx checkly test -v
```

**--verify-runtime-dependencies** `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](https://www.checklyhq.com/docs/detect/synthetic-monitoring/playwright-checks/overview.md) because they don't rely on a specific runtime.

## 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](https://www.checklyhq.com/docs/cli/environment-variables.md) 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+.

`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](https://www.checklyhq.com/docs/concepts/cancellation.md) for the full flow.

## Related Commands

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.