Browser Check Construct

Learn how to configure browser checks with the Checkly CLI.

Learn more about Browser Checks in the Browser Checks overview.

Use Browser Checks to run end-to-end tests with Playwright. The examples below show how to configure browser checks for different testing scenarios.

Prerequisites

Before creating Browser Checks, ensure you have:

• An initialized Checkly CLI project
• A public website you want to monitor
• Understanding of Playwright test syntax and structure

For additional setup information, see CLI overview.

Basic Example

import { BrowserCheck, Frequency } from "checkly/constructs"
import * as path from "path"

new BrowserCheck("browser-check-1", {
  name: "Browser check #1",
  description: "Loads the **home page** and asserts key elements are visible.",
  frequency: Frequency.EVERY_10M,
  locations: ["us-east-1", "eu-west-1"],
  code: {
    entrypoint: path.join(__dirname, "home.spec.ts"),
  },
})

Configuration

The Browser Check configuration consists of specific Browser Check options and inherited general check options.

Browser Check

Parameter	Type	Required	Default	Description
code	object	✅	-	The Playwright test code

General Check

Property	Type	Required	Default	Description
name	string	✅	-	Friendly name for your check
description	string	❌	null	A description of the check. Supports markdown. Max 500 characters
activated	boolean	❌	true	Whether the check is enabled
alertChannels	AlertChannel[]	❌	[]	Array of AlertChannel objects for notifications
alertEscalationPolicy	AlertEscalationPolicy	❌	-	Advanced alert settings
environmentVariables	object[]	❌	[]	Check-level environment variables
frequency	Frequency	❌	-	How often to run your check
group	CheckGroup	❌	-	The CheckGroup this check belongs to
locations	string[]	❌	[]	Public locations for this monitor/check
muted	boolean	❌	false	Whether alert notifications are muted
privateLocations	string[]	❌	[]	Private Location slugs
retryStrategy	RetryStrategy	❌	-	Strategy for configured retries
runtimeId	string	❌	-	The ID of the runtime to use
runParallel	boolean	❌	false	Whether to run checks in parallel across locations
tags	string[]	❌	[]	Tags to organize checks/monitors
testOnly	boolean	❌	false	Only run with test, not during deploy
triggerIncident	IncidentTrigger	❌	-	Create and resolve an incident based on the check’s alert configuration

Browser Check Options

code · object · required

The Playwright test code that defines how to execute your end-to-end browser monitor. This is the core component of any browser check.

Usage:

// Using file reference
code: {
  entrypoint: path.join(__dirname, "login-flow.spec.ts")
}

// Using inline content
code: {
  content: `
    import { test, expect } from '@playwright/test'

    test("homepage loads", async ({ page }) => {
      await page.goto("https://example.com");
      await expect(page).toHaveTitle(/Example/);
    });
  `
}

Parameters:

Parameter	Type	Required	Description
entrypoint	string	❌	Path to a .spec.js or .spec.ts file containing the Playwright test
content	string	❌	Inline JavaScript/TypeScript code as a string

You must provide either entrypoint or content, but not both.

Examples:

File Reference

new BrowserCheck("login-flow-check", {
  name: "User Login Flow",
  code: {
    entrypoint: path.join(__dirname, "tests/login.spec.ts"),
  },
})

Use cases: E2E testing, user journey validation, performance testing, visual regression testing.

General Check Options

name · string · required

Friendly name for your Browser Check that will be displayed in the Checkly dashboard and used in notifications.

Usage:

new BrowserCheck("my-check", {
  name: "User Login Flow Test",
  /* More options... */
})

frequency · Frequency

How often the Browser Check should run. Use the Frequency enum to set the check interval.

Usage:

import { Frequency } from 'checkly/constructs'

new BrowserCheck("my-check", {
  name: "My Browser Check",
  frequency: Frequency.EVERY_5M,
  /* More options... */
})

Examples:

High Frequency

// For critical user journeys
new BrowserCheck("critical-login", {
  name: "Critical Login Flow",
  frequency: Frequency.EVERY_1M, // Every minute
  tags: ["critical", "high-priority"],
  /* More options... */
})

Available frequencies: EVERY_1M, EVERY_2M, EVERY_5M, EVERY_10M, EVERY_15M, EVERY_30M, EVERY_1H, EVERY_2H, EVERY_6H, EVERY_12H, EVERY_24H

runtimeId · string

The Checkly runtime version used to execute the Browser Check. Runtimes are managed execution environments for Browser and Multistep Checks. They include fixed Checkly-provided dependencies, such as Playwright, browser binaries, and runtime libraries.

Use runtimeId for Browser Checks and Multistep Checks. For Playwright Check Suites, use engine instead to select the JavaScript engine version that runs your own Playwright project.

Usage:

new BrowserCheck("my-check", {
  name: "My Browser Check",
  runtimeId: "2025.04",
  /* More options... */
})

Learn more about Checkly runtimes in the general documentation.

locations · string[] · default: "[]"

Array of public location codes where the Browser Check should run. Multiple locations provide geographic coverage and redundancy.

Usage:

new BrowserCheck("my-check", {
  name: "My Browser Check",
  locations: ["us-east-1", "eu-west-1", "ap-southeast-1"],
  /* More options... */
})

Examples:

Global Coverage

// Comprehensive global monitoring
new BrowserCheck("global-check", {
  name: "Global User Experience",
  locations: [
    "us-east-1", // N. Virginia
    "us-west-1", // N. California
    "eu-west-1", // Ireland
    "ap-southeast-1", // Singapore
    "ap-northeast-1", // Tokyo
  ],
  /* More options... */
})

Use cases: Global user experience monitoring, regional performance testing, compliance requirements.

activated · boolean · default: "true"

Whether the browser check is enabled and will run according to its schedule.

Usage:

new BrowserCheck("my-check", {
  name: "My Browser Check",
  activated: false, // Disabled check
  /* More options... */
})

tags · string[] · default: "[]"

Array of tags to organize and categorize your Browser Checks in the Checkly infrastructure.

Usage:

new BrowserCheck("my-check", {
  name: "My Browser Check",
  tags: ["e2e", "critical-path", "user-journey"],
  /* More options... */
})

Examples:

Functional Tags

new BrowserCheck("login-test", {
  name: "User Authentication",
  tags: ["authentication", "login", "security"],
  code: { entrypoint: path.join(__dirname, "auth.spec.ts") },
  /* More options... */
})

Use cases: Organization, filtering, alerting rules, reporting.

environmentVariables · object[] · default: "[]"

Check-level environment variables that will be available during test execution. Useful for test configuration and sensitive data.

Usage:

new BrowserCheck("my-check", {
  name: "My Browser Check",
  environmentVariables: [
    { key: "TEST_USERNAME", value: "[e-mail]" },
    { key: "TEST_PASSWORD", value: "{{SECRET_PASSWORD}}", secret: true },
  ],
  /* More options... */
})

Parameters:

Parameter	Type	Required	Description
key	string	✅	Environment variable name
value	string	✅	Environment variable value
secret	boolean	❌	Whether the value should be encrypted and hidden

Examples:

Test Credentials

new BrowserCheck("user-flow", {
  name: "User Account Flow",
  environmentVariables: [
    { key: "TEST_EMAIL", value: "[e-mail]" },
    { key: "TEST_PASSWORD", value: "{{TEST_USER_PASSWORD}}", secret: true },
    { key: "BASE_URL", value: "https://staging.example.com" },
  ],
  code: { entrypoint: path.join(__dirname, "user-flow.spec.ts") },
})

Use cases: Test configuration, authentication, API keys, feature flags, environment-specific settings.

Examples

Login Flow

new BrowserCheck("login-flow-check", {
  name: "User Login Flow",
  frequency: Frequency.EVERY_15M,
  locations: ["us-east-1", "eu-west-1"],
  code: {
    entrypoint: path.join(__dirname, "login.spec.ts"),
  },
})

// login.spec.ts
import { expect, test } from "@playwright/test"

test("user can login successfully", async ({ page }) => {
  await page.goto("https://app.example.com/login")

  await page.getByLabel('email', { name: /email/i }).fill(process.env.TEST_USERNAME)
  await page.getByLabel('password', { name: /password/i }).fill(process.env.TEST_PASSWORD)
  await page.getByRole('button', { name: /login/i }).click()

  await expect(page).toHaveURL(/dashboard/)
  await expect(page.getByTestId('user-menu')).toBeVisible()
})

Browser checks require Playwright test files. Make sure your test files use the @playwright/test framework and follow Playwright’s testing conventions.