> ## Documentation Index > Fetch the complete documentation index at: https://checkly-422f444a-mda-troubleshooting-section.mintlify.site/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. Before using {command_0}, 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). ## 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 | Description | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | | `--config, -c` | The Checkly CLI configuration file. If not passed, uses the `checkly.config.ts\|js` file in the current directory. | | `--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. | | `--record` | Record test results in Checkly as a test session with full logs, traces and videos. | | `--reporter, -r` | A list of custom reporters for the test output. | | `--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 storing results in Checkly with `--record`. | | `--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 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" ``` [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" ``` 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" ``` 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-.*" ``` 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" ``` 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" ``` 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 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" ``` A list of custom reporters for the test output. Options: `list|dot|ci|github|json` **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 ``` Record test results in Checkly as [a test session](/detect/testing/overview) with full logs, traces and videos. **Usage:** ```bash Terminal theme={null} npx checkly test --record npx checkly test --record --test-session-name="CI Build #123" ``` 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 ``` A name to use when storing results in Checkly with `--record`. **Usage:** ```bash Terminal theme={null} npx checkly test --record --test-session-name="Release v1.2.3" npx checkly test --record -n="Nightly Test Run" ``` A timeout (in seconds) to wait for checks to complete. **Usage:** ```bash Terminal theme={null} npx checkly test --timeout=300 ``` 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 ``` Snapshots are essential for [visual regression testing in Browser Checks](/detect/synthetic-monitoring/browser-checks/visual-regressions). Always show the full logs of the checks. **Usage:** ```bash Terminal theme={null} npx checkly test --verbose npx checkly test -v ``` 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. You can provide custom dependencies in [Playwright Check Suites](/detect/synthetic-monitoring/playwright-checks/overview) 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 ``` Record a test session in Checkly with git branch info, full logging, videos and traces: ```bash Terminal theme={null} npx checkly test --record ``` 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 ``` ## 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