Checkly Test

checkly test

Test Checkly checks locally with npx checkly test.

Quick start

# Test all checks
npx checkly test

# Test specific check
npx checkly test __checks__/api.check.ts

# Test with verbose output
npx checkly test --verbose

# Test in specific location
npx checkly test --location=eu-west-1

# List recorded test sessions after CI or cloud runs
npx checkly test-sessions list --status failed --limit 10

# Drill into a failed session and a specific result/error group
npx checkly test-sessions get <session-id> --result <result-id>
npx checkly test-sessions get <session-id> --error-group <error-group-id> --full-error

How it works

npx checkly test executes your checks in Checkly's runtime environment (same as production) but does NOT deploy or schedule them. Perfect for:

• ✅ Pre-deployment validation
• ✅ CI/CD integration
• ✅ Local development iteration
• ✅ Debugging check failures

The CLI dispatches test sessions through Checkly's asynchronous scheduling API and watches scheduling before collecting results. Scheduling failures now fail fast with the server error instead of waiting for the per-check timeout. With --detach, the CLI confirms scheduling reached a terminal state before exiting, so dispatch failures still return non-zero.

Command reference

npx checkly test [file-pattern] [options]

Options

Recorded test sessions

Use test-sessions drilldown commands for recorded sessions after npx checkly test, npx checkly trigger, CI runs, or Playwright Reporter uploads when you need failure details, result IDs, or error-group context for RCA.

For cancelled or timed-out runs started by checkly test, checkly trigger, or checkly pw-test, inspect the recorded session with the existing commands below; cancellation handling is backend/runner wiring rather than a separate public test-sessions command or flag.

# List recent sessions
npx checkly test-sessions list

# List failed sessions from a branch as JSON
npx checkly test-sessions list --status failed --branch main --limit 20 --output json

# Filter sessions by provider or error group
npx checkly test-sessions list --provider github --error-group <error-group-id>

# Inspect a session summary and error-group IDs
npx checkly test-sessions get <session-id>

# Wait for a running session to finish before rendering
npx checkly test-sessions get <session-id> --watch

# Drill into one result or one error group
npx checkly test-sessions get <session-id> --result <result-id>
npx checkly test-sessions get <session-id> --error-group <error-group-id> --full-error

test-sessions list flags

test-sessions get flags

Workflows

Basic testing

# Test everything
npx checkly test

# Output:
# Parsing your project... done
# Running 3 checks in us-east-1.
# 
# __checks__/api.check.ts
#  ✔ API Status Check (234ms)
# __checks__/homepage.spec.ts  
#  ✔ Homepage Check (2.1s)
# __checks__/login.spec.ts
#  ✔ Login Flow (3.4s)
#
# 3 passed, 3 total

Test specific checks

# Single file
npx checkly test __checks__/api.check.ts

# Multiple files
npx checkly test __checks__/api.check.ts __checks__/homepage.spec.ts

# Pattern matching
npx checkly test __checks__/api-*.check.ts

# By name (grep)
npx checkly test --grep="Homepage"

Verbose debugging

npx checkly test --verbose

# Shows:
# - Request/response details (API checks)
# - Console logs (browser checks)
# - Screenshots (on failure)
# - Full stack traces
# - Environment variables used

Testing in different locations

# Test from EU datacenter
npx checkly test --location=eu-west-1

# Test from multiple locations (requires configuration)
# Set in checkly.config.ts:
checks: {
  locations: ['us-east-1', 'eu-west-1'],
}

CI/CD integration

# GitHub Actions
name: Test Checks
on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: '22.13.0'
      
      - run: npm ci
      - run: npx checkly test
        env:
          CHECKLY_API_KEY: ${{ secrets.CHECKLY_API_KEY }}
          CHECKLY_ACCOUNT_ID: ${{ secrets.CHECKLY_ACCOUNT_ID }}

Test with retries

# Retry failed checks once
npx checkly test --retries=1

# Useful for flaky tests or network issues

Environment variables

# Inline
API_BASE_URL=https://staging.example.com npx checkly test

# From .env file
npx checkly test --env-file=.env.test

# .env.test
API_BASE_URL=https://staging.example.com
API_KEY=test-key-123

Reporters

List reporter (default)

npx checkly test --reporter=list

# Detailed output with timings

Dot reporter

npx checkly test --reporter=dot

# Compact: . = pass, F = fail

CI reporter

npx checkly test --reporter=ci

# Optimized for CI logs

GitHub reporter

npx checkly test --reporter=github

# Generates GitHub Actions annotations

JSON reporter

npx checkly test --reporter=json > results.json

# Machine-readable output

For failed gRPC, SSL, and traceroute monitors, terminal and JSON reporters include type-specific diagnostics when available. Inspect gRPC status/health/metadata, TLS certificate and handshake details, or traceroute hops/latency/packet loss before falling back to generic network troubleshooting.

Testing strategies

Local-first workflow

# 1. Write Playwright test
cat > __checks__/new-feature.spec.ts

# 2. Test locally with Playwright (fastest)
npx playwright test __checks__/new-feature.spec.ts

# 3. Validate in Checkly runtime
npx checkly test __checks__/new-feature.spec.ts

# 4. Deploy when passing
npx checkly deploy

Pre-deployment validation

# Run full test suite before deploy
npx checkly test && npx checkly deploy --force

Debugging failures

# 1. Run with verbose output
npx checkly test __checks__/failing.spec.ts --verbose

# 2. Check for common issues:
#    - API endpoint changed?
#    - Auth token expired?
#    - Selector changed (browser checks)?
#    - Environment variable missing?

# 3. Test locally first (browser checks)
npx playwright test __checks__/failing.spec.ts --headed

# 4. Compare environments
#    - Local vs Checkly runtime
#    - Check Node.js version
#    - Check npm package versions

Troubleshooting

"No checks found to test"

Solution:

# Check configuration
npx checkly validate

# Verify files exist
ls -la __checks__/

# Check checkMatch pattern in checkly.config.ts

"Check failed: Connection timeout"

Causes:

• Endpoint not accessible from Checkly locations
• Firewall blocking Checkly IPs
• Endpoint genuinely down

Solution:

# Test from different location
npx checkly test --location=eu-west-1

# For private endpoints, use private locations

"Module not found" errors

Cause: npm package not available in Checkly runtime

Solution:

# Validate dependencies
npx checkly test --verify-runtime-dependencies

# See supported packages:
# https://www.checklyhq.com/docs/runtimes/

Flaky tests

Solution:

# Enable retries
npx checkly test --retries=2

# Or configure in checkly.config.ts:
checks: {
  retryStrategy: RetryStrategyBuilder.fixedStrategy({
    maxAttempts: 2,
    baseBackoffSeconds: 60,
  }),
}

Testing vs Deploying

*Test runs count towards your account's test run limit but are not billed separately.

Related Skills

• See checkly-deploy for deploying checks after testing
• See checkly-checks for creating checks to test
• See checkly-playwright for Playwright-specific testing
• See checkly-advanced for retry strategies and reporters