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.

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.

Basic Usage

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

Terminal

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`	-	Start the checks in the cloud and exit after printing the test session ID, without waiting for results.
`--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

string

The Checkly CLI configuration file. If not passed, uses the checkly.config.ts|js file in the current directory.Usage:

Terminal

npx checkly test --config="./checkly.staging.config.ts"
npx checkly test -c="./checkly.staging.config.ts"

boolean

default:"false"

Start the checks in the cloud and exit as soon as they’re scheduled. The CLI prints the test session ID and doesn’t wait for results. Get the results later with checkly test-sessions get <test-session-id>. --detach can’t be combined with the json or github reporters.Usage:

Terminal

npx checkly test --detach

string[]

Environment variables to be passed to the test run. Can be used multiple times.Usage:

Terminal

npx checkly test --env KEY=value
npx checkly test -e KEY=value

Examples:

Terminal

# 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"

string

Path to a dotenv file containing environment variables.Usage:

Terminal

npx checkly test --env-file="./.env"
npx checkly test --env-file="./config/.env.production"

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:

Terminal

npx checkly test --fail-on-no-matching
npx checkly test --no-fail-on-no-matching

Examples:

Terminal

# 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

Available since CLI v10.0.0. Earlier versions always exit successfully when no checks match.

string

Only run checks where the check name matches a regular expression. Default: .*Usage:

Terminal

npx checkly test --grep="api-.*"
npx checkly test -g="^production-.*"

string

The location to run the checks at. Defaults to the cli.runLocation in your config.Usage:

Terminal

npx checkly test --location="us-east-1"
npx checkly test -l="eu-west-1"

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. Queued API checks and uptime monitors are skipped and reported as cancelled, and running Playwright Check Suite runs are interrupted; other checks 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:

Terminal

npx checkly test --max-failures=1

Examples:

Terminal

# 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

string

The slug name of the private location to run checks at. Can’t be combined with --location.Usage:

Terminal

npx checkly test --private-location="my-private-location"

Examples:

Terminal

# 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"

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:

Terminal

npx checkly test --tags="tag1,tag2"
npx checkly test -t="tag1,tag2"

Examples:

Terminal

# 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)

boolean

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

Terminal

# 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"

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:

Terminal

npx checkly test --reporter=list
npx checkly test -r=list

Examples:

Terminal

# 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 report, written to checkly-json-report.json in the current directory
npx checkly test --reporter 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

boolean

default:"true"

Record test results in Checkly as a test session with full logs, traces and videos. Recording is enabled by default; use --no-record to disable it.

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

Usage:

Terminal

npx checkly test
npx checkly test --no-record
npx checkly test --test-session-name="CI Build #123"

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:

Terminal

npx checkly test --refresh-cache

number

How many times to retry a failing test run. Default: 0, max: 3A 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:

Terminal

npx checkly test --retries=2

Examples:

Terminal

# No retries (default)
npx checkly test --retries 0

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

# Maximum retries
npx checkly test --retries 3

string

A name to use when recording results in Checkly.Usage:

Terminal

npx checkly test --test-session-name="Release v1.2.3"
npx checkly test -n="Nightly Test Run"

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 or contact support.When the CLI stops waiting for a check, whether it stopped making progress or never started, it reports the check as timed out rather than failed: the CLI did not receive a result, and the check may still run and pass in Checkly. Reporters mark it with ⏱ (T in the dot reporter) and count it as timed out in the summary, and the json reporter gives it "result": "Timed out". The run still exits with code 1.Usage:

Terminal

npx checkly test --timeout=300

boolean

Update any snapshots using the actual result of this test run.Usage:

Terminal

npx checkly test --update-snapshots
npx checkly test -u

Snapshots are essential for visual regression testing in Browser checks.

boolean

Always show the full logs of the checks.Usage:

Terminal

npx checkly test --verbose
npx checkly test -v

boolean

Return an error if checks import dependencies that are not supported by the selected runtime. Default: trueUsage:

Terminal

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.

You can provide custom dependencies in Playwright Check Suites because they don’t rely on a specific runtime.

Examples

Dry run all your project checks and monitors:

Terminal

npx checkly test

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

Terminal

npx checkly test product api

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

Terminal

npx checkly test

Dry run all checks against a specific location:

Terminal

npx checkly test --location eu-west-1

Specify environment variables to dry run checks with a specific URL and a password. These variables are available on process.env:

Terminal

npx checkly test --env ENVIRONMENT_URL="https://preview.acme.com" --env PASSWORD=doremiabc123

Cancelling a run

Available in CLI v8.0.0+.

checkly test records a test session by default, so pressing Ctrl+C cancels it. Queued API checks and uptime monitors are skipped and reported as cancelled, and running Playwright Check Suite runs are interrupted; other checks finish normally. Runs started with --no-record cannot be cancelled. The CLI keeps running after the first Ctrl+C to report the cancelled results. Press Ctrl+C again to exit immediately without waiting. To start checks without waiting for them, use --detach. The CLI then exits as soon as the checks are scheduled, and the checks keep running in the cloud. See Cancellation for the full flow.

checkly pw-test - Run Playwright tests in the Checkly cloud
checkly trigger - Run deployed checks on-demand
checkly deploy - Deploy your application

Getting Started

CLI Commands

Basic Usage

Command Options

Examples

Cancelling a run

​Basic Usage

​Command Options

​Examples

​Cancelling a run

​Related Commands

Basic Usage

Command Options

Examples

Cancelling a run

Related Commands