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

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

--detach, -d · boolean · default: "false"

By default, pressing Ctrl+C during a recorded run cancels the test session. With --detach, Ctrl+C exits the CLI immediately instead, leaving the checks running in the cloud.

Usage:

Terminal

npx checkly test --detach

--env, -e · 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"

--env-file · 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"

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

--location, -l · string

The location to run the checks at.

Usage:

Terminal

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

--private-location · string

The private location to run checks at.

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"

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

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)

--list · boolean

List all checks to be run but don’t run them.

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"

--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 list (or ci in CI environments).

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

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

Terminal

npx checkly test --refresh-cache

--retries · number

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

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

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

--timeout · number · default: "600"

A timeout (in seconds) to wait for checks to complete.

Usage:

Terminal

npx checkly test --timeout=300

--update-snapshots, -u · 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.

--verbose, -v · boolean

Always show the full logs of the checks.

Usage:

Terminal

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:

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. 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 Ctrl+C to report the cancelled results. Press Ctrl+C again to exit immediately without waiting.

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

See Cancellation for the full flow.

Related Commands

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