Creating Your First Test

Checkly enables you to transform your existing Playwright tests into powerful synthetic monitors that run continuously across global locations. This guide will walk you through creating your first test, from setup to deployment.

Prerequisites

Node.js 22.13+ installed
A Checkly account (sign up at checklyhq.com)
Basic familiarity with JavaScript/TypeScript

Step 1: Initialize Your Project

In your project folder, set up Checkly using the CLI:

Terminal

npx checkly init

This command will:

Set up Checkly in your current folder, and offer to create a package.json if there isn’t one
Install the Checkly CLI and dependencies
Create a checkly.config.ts file
Optionally add example checks to get you started

You’ll first be asked whether your AI agent should set up Checkly. Answer yes to install the Checkly skill for your AI coding agent, or no to set up the project yourself and add the demo checks.

Step 2: Project Structure

After initialization, your project will have the following structure:

my-checkly-project/
├── __checks__/              # Your test files go here
│   ├── api.check.ts         # Example API check
│   ├── heartbeat.check.ts   # Example heartbeat check
│   ├── homepage.spec.ts     # Example Playwright test
│   └── url.check.ts         # Example URL monitor
├── checkly.config.ts        # Checkly configuration
├── package.json             # Node.js dependencies
└── README.md

Step 3: Configure Your Project

Open checkly.config.ts to configure your monitoring setup:

checkly.config.ts

import { defineConfig } from 'checkly'
import { Frequency } from 'checkly/constructs'

export default defineConfig({
  projectName: 'My First Checkly Project',
  logicalId: 'my-first-project',
  repoUrl: 'https://github.com/yourusername/your-repo',
  checks: {
    // Global check settings
    activated: true,
    muted: false,
    runtimeId: '2025.04',
    frequency: Frequency.EVERY_5M,
    locations: ['us-east-1', 'eu-west-1'], // Global locations
    tags: ['production', 'critical'],
    
    // Browser check specific settings
    browserChecks: {
      frequency: Frequency.EVERY_10M,
      testMatch: '**/__checks__/*.spec.ts',
    },
  },
  cli: {
    runLocation: 'eu-west-1', // Location for local testing
  },
})

Step 4: Write Your First Test

Create a new Playwright test file in the __checks__ directory:

Playwright.test.ts

// __checks__/my-first-test.spec.ts
import { test, expect } from '@playwright/test'

test('Homepage loads successfully', async ({ page }) => {
  // Navigate to your application
  const response = await page.goto('https://www.checklyhq.com')
  
  // Verify the page loaded successfully
  expect(response?.status()).toBeLessThan(400)
  
  // Check the page title
  const title = await page.title()
  expect(title).toContain('Checkly')
  
  // Verify key elements are present
  await expect(page.getByRole('heading', { level: 1 })).toBeVisible()
  
  // Take a screenshot for debugging
  await page.screenshot({ path: 'homepage.jpg' })
})

Step 5: Test Your Checks

Before deploying, run your checks on Checkly to make sure they pass:

Terminal

# Test all checks (records a test session with videos and traces)
npx checkly test

# Test specific checks
npx checkly test homepage

# Pass environment variables
npx checkly test --env ENVIRONMENT_URL="https://staging.example.com"

npx checkly test runs your checks from Checkly’s infrastructure, not on your machine. It will:

Execute your Playwright tests
Run API checks
Generate screenshots, videos, and traces
Provide detailed output and debugging information

Step 6: Deploy Your Checks

Deploy your checks so Checkly runs them on a schedule:

Terminal

npx checkly deploy

Step 7: View Results

After deployment, you can:

View check results in the Checkly dashboard
Set up alert channels to get notified of failures
Access detailed traces and screenshots
Monitor performance trends over time

Advanced Check Configuration

For more control over your Browser checks:

__checks__/advanced-browser.check.ts

import { BrowserCheck, Frequency, RetryStrategyBuilder } from 'checkly/constructs'

new BrowserCheck('advanced-check', {
  name: 'Advanced Browser Check',
  activated: true,
  frequency: Frequency.EVERY_5M,
  locations: ['us-east-1', 'eu-west-1', 'ap-southeast-1'],
  tags: ['critical', 'user-journey'],
  code: {
    entrypoint: './advanced-test.spec.ts',
  },
  retryStrategy: RetryStrategyBuilder.linearStrategy({
    baseBackoffSeconds: 60,
    maxRetries: 2,
  }),
})

Best Practices

Start Simple: Begin with basic page load tests before adding complex interactions
Use Page Object Model: Organize your tests with reusable page objects
Test Critical User Journeys: Focus on the most important user flows
Set Appropriate Frequencies: Don’t over-monitor; balance coverage with costs
Use Environment Variables: Keep sensitive data and URLs configurable
Add Meaningful Assertions: Test both functionality and performance
Take Screenshots: Helpful for debugging when tests fail
Monitor APIs and UI: Combine browser and API checks for comprehensive coverage

Troubleshooting

Common Issues

Check fails locally but works in browser:

Verify selectors are stable
Add proper waits for dynamic content
Check for timing issues

Environment variable not found:

Terminal

npx checkly test --env VARIABLE_NAME="value"

Login required for testing:

Playwright.test.ts

// Use Playwright's built-in authentication
test.use({ storageState: 'auth.json' })

Getting help:

Check the Checkly documentation
Join the Checkly community
Review example projects on GitHub

Next Steps

Once you have your first test running:

Add More Tests: Cover additional user journeys and API endpoints
Set Up CI/CD: Integrate Checkly into your deployment pipeline
Configure Alerts: Set up notifications for your team
Explore Traces: Use OpenTelemetry integration for deeper insights
Scale Your Monitoring: Add checks for different environments and regions

Congratulations! You’ve successfully created your first Checkly test. Your application is now being monitored continuously across global locations, helping you catch issues before your users do.

Getting Started

Detect

Communicate

Resolve

AI

Integrations

Creating Your First Test

Step 1: Initialize Your Project

Step 2: Project Structure

Step 3: Configure Your Project

Step 4: Write Your First Test

Step 5: Test Your Checks

Step 6: Deploy Your Checks

Step 7: View Results

Advanced Check Configuration

Best Practices

Troubleshooting

Common Issues

Next Steps

​Step 1: Initialize Your Project

​Step 2: Project Structure

​Step 3: Configure Your Project

​Step 4: Write Your First Test

​Step 5: Test Your Checks

​Step 6: Deploy Your Checks

​Step 7: View Results

​Advanced Check Configuration

​Best Practices

​Troubleshooting

​Common Issues

​Next Steps

Step 1: Initialize Your Project

Step 2: Project Structure

Step 3: Configure Your Project

Step 4: Write Your First Test

Step 5: Test Your Checks

Step 6: Deploy Your Checks

Step 7: View Results

Advanced Check Configuration

Best Practices

Troubleshooting

Common Issues

Next Steps