Playwright Check Suite

Learn how to configure Playwright check suites with the Checkly CLI.

Learn more about Playwright Check Suites in the Playwright Check Suites overview.

Use Playwright Check Suites to reuse your existing Playwright test suite to run it as end-to-end tests and synthetic monitoring. The examples below show how to configure Playwright Check Suites for different testing and monitoring scenarios.

Prerequisites

Before creating Playwright Check Suites, ensure you have:

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

For additional setup information, see CLI overview.

Basic Example

import { PlaywrightCheck } from "checkly/constructs"

new PlaywrightCheck("critical-e2e-monitor", {
  name: "Critical E2E Monitor",
  description: "Runs the **critical path** e2e suite against production.",
  playwrightConfigPath: "./playwright.config.ts",
})

import { Engine, PlaywrightCheck } from "checkly/constructs"

new PlaywrightCheck("critical-e2e-monitor", {
  name: "Critical E2E Monitor",
  description: "Runs the **critical path** e2e suite against production.",
  include: [".npmrc", "test-files/**"],
  playwrightConfigPath: "./playwright.config.ts",
  engine: Engine.node("24"), // Optional: override the auto-detected engine.
  installCommand: "npm ci",
  testCommand: "npx playwright test --max-failures=5",
  pwProjects: ["chromium"],
  pwTags: ["e2e"],
})

Configuration

The Playwright Check Suite configuration consists of specific Playwright Check Suite options and inherited general monitoring options.

Playwright Check Suite

Parameter	Type	Required	Default	Description
playwrightConfigPath	string	✅	-	Path to the Playwright configuration file (playwright.config.js/ts)
installCommand	string	❌	-	Command to install dependencies before running tests
testCommand	string	❌	npx playwright test	Command to execute Playwright tests
pwProjects	string string[]	❌	-	Specific Playwright projects to run from your configuration
pwTags	string string[]	❌	-	Tags to filter which tests to run using Playwright’s grep functionality
include	string string[]	❌	-	File patterns to include when bundling the test project
engine	Engine	❌	Auto-detected, then Node.js 22	JavaScript engine and version used to run the Playwright Check Suite

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[]	❌	[]	Array of public location codes
muted	boolean	❌	false	Whether alert notifications are muted
privateLocations	string[]	❌	[]	Array of Private Location slugs
runParallel	boolean	❌	false	Run checks in parallel or round-robin
tags	string[]	❌	[]	Array of tags to organize checks
testOnly	boolean	❌	false	Only run with test, not during deploy
triggerIncident	IncidentTrigger	❌	-	Create and resolve an incident based on the check’s alert configuration

Playwright Check Suite Options

playwrightConfigPath · string · required

The path to the Playwright configuration file (playwright.config.js/ts) which defines test settings, browser configurations, and project structure.

Usage:

new PlaywrightCheck("critical-e2e-monitor", {
  name: "Critical E2E Monitor",
  playwrightConfigPath: "../playwright.config.ts",
})

installCommand · string

The command to install dependencies before running tests. This configuration is useful for ensuring test dependencies are available in the runtime environment.

Checkly defaults to using npm, but automatically detects other package managers if lock files are present.

Usage:

new PlaywrightCheck("critical-e2e-monitor", {
  name: "Critical E2E Monitor",
  playwrightConfigPath: "../playwright.config.ts",
  installCommand: "npm ci",
})

testCommand · string · default: "npx playwright test"

The command to execute Playwright tests when running npx checkly test or running your Playwright Check Suite as monitor.

Usage:

new PlaywrightCheck("critical-e2e-monitor", {
  name: "Critical E2E Monitor",
  playwrightConfigPath: "../playwright.config.ts",
  testCommand: "npx playwright test --grep@checkly --config=playwright.foo.config.ts",
})

If you configure the testCommand property and pwTags or pwProjects the options will be merged and all configurations applied to npx playwright test.

Checkly applies these Playwright defaults when you do not set them yourself: workers: 4, retries: 2, use.video: "on-first-retry", and use.screenshot: "on-first-retry". Checkly also records traces on every run, uses the Checkly reporter, and appends a Checkly user-agent suffix. Checkly supports Playwright’s globalTimeout; the timer starts when npx playwright test begins.

pwProjects · string

The defined projects to run from your Playwright configuration.

Usage:

Single project

new PlaywrightCheck("critical-e2e-monitor", {
  name: "Critical E2E Monitor",
  playwrightConfigPath: "../playwright.config.ts",
  pwProjects: "chromium",
})

new PlaywrightCheck("critical-e2e-monitor", {
  name: "Critical E2E Monitor",
  playwrightConfigPath: "../playwright.config.ts",
  pwProjects: ["chromium", "firefox"],
})

Playwright Test Projects let you run different test files in different browsers and with different settings. They’re the recommended way to group and bundle test functionality.

pwTags · string

The tags to filter which tests to run using Playwright’s grep functionality.

Tests matching any of these tags will be executed.

Usage:

Single project

new PlaywrightCheck("critical-e2e-monitor", {
  name: "Critical E2E Monitor",
  playwrightConfigPath: "../playwright.config.ts",
  pwTags: "@smoke",
})

new PlaywrightCheck("critical-e2e-monitor", {
  name: "Critical E2E Monitor",
  playwrightConfigPath: "../playwright.config.ts",
  pwTags: ["@smoke", "@critical"],
})

Learn more about test tags and annotations in the Playwright annotation docs.

include · string

Defines the glob patterns for files and directories that should be included when bundling the Playwright Check Suite. Use this option to manually include additional test files, helper utilities, or other resources that might be outside of the tests directory that your playwright config file points to.

Usage:

new PlaywrightCheck("critical-e2e-monitor", {
  name: "Critical E2E Monitor",
  playwrightConfigPath: "../playwright.config.ts",
  include: [".npmrc", "test-files/**"],
})

The Playwright Check Suite bundling process uses a breadth-first search algorithm starting from the entrypoint to recursively find all local file dependencies. It parses import/require statements and follows the dependency graph to include all necessary files.

Use include to bundle files that are not directly imported/required.

engine · Engine

The JavaScript engine and version used to run the Playwright Check Suite. Use the Engine helpers to select Node.js or Bun explicitly.

Usage:

Node.js

import { Engine, PlaywrightCheck } from "checkly/constructs"

new PlaywrightCheck("critical-e2e-monitor", {
  name: "Critical E2E Monitor",
  playwrightConfigPath: "../playwright.config.ts",
  engine: Engine.node("24"),
})

import { Engine, PlaywrightCheck } from "checkly/constructs"

new PlaywrightCheck("critical-e2e-monitor", {
  name: "Critical E2E Monitor",
  playwrightConfigPath: "../playwright.config.ts",
  engine: Engine.bun("1.3"),
})

If you omit engine, the Checkly CLI tries to detect it from project version files. It checks .node-version, .nvmrc, .tool-versions (nodejs or bun), .bun-version, and package.json engines.node or engines.bun.

When both Node.js and Bun candidates are found, Node.js takes precedence. .nvmrc aliases such as lts, lts/*, node, stable, and latest are skipped.

For package.json engine ranges, the CLI uses the minimum version from the semver range. For example, >=22 resolves to Node.js 22, and >=1.3 resolves to Bun 1.3.

Detected and explicit versions are checked against Checkly’s engine rules:

Engine	Supported versions	Resolution behavior
Node.js	22, 24, 26	Older, EOL, non-LTS, or future major versions are remapped to the nearest supported LTS version with a warning
Bun	1.3	Older or future 1.x versions are remapped to 1.3 with a warning; 2.x and newer are rejected

If no engine is set and the CLI cannot auto-detect one, Checkly uses the default Node.js 22 engine.

General Check Options

name · string · required

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

Usage:

new PlaywrightCheck("critical-e2e-monitor", {
  name: "Critical E2E Monitor",
  playwrightConfigPath: "../playwright.config.ts",
})

frequency · Frequency

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

Usage:

new PlaywrightCheck("my-pwt-check-suite", {
  name: "My Playwright Check Suite",
  playwrightConfigPath: "../playwright.config.ts",
  frequency: Frequency.EVERY_5M,
})

Examples:

High Frequency

// For critical user journeys
new PlaywrightCheck("my-pwt-check-suite", {
  name: "My Playwright Check Suite",
  playwrightConfigPath: "../playwright.config.ts",
  frequency: Frequency.EVERY_2M,
  pwTags: ["@critical"],
})

// For regular monitoring
new PlaywrightCheck("my-pwt-check-suite", {
  name: "My Playwright Check Suite",
  playwrightConfigPath: "../playwright.config.ts",
  frequency: Frequency.EVERY_2M,
  pwTags: ["@monitoring"],
})

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

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

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

Usage:

new PlaywrightCheck("my-pwt-check-suite", {
  name: "My Playwright Check Suite",
  playwrightConfigPath: "../playwright.config.ts",
  locations: ["us-east-1", "eu-west-1", "ap-southeast-1"],
})

Examples:

Global Coverage

// Comprehensive global monitoring
new PlaywrightCheck("global-pwt-check-suite", {
  name: "Global Playwright Check Suite",
  playwrightConfigPath: "../playwright.config.ts",
  locations: [
    "us-east-1", // N. Virginia
    "us-west-1", // N. California
    "eu-west-1", // Ireland
    "ap-southeast-1", // Singapore
    "ap-northeast-1", // Tokyo
  ],
})

// Focus on specific regions
new PlaywrightCheck("europe-pwt-check-suite", {
  name: "Europe Playwright Check Suite",
  playwrightConfigPath: "../playwright.config.ts",
  locations: ["eu-west-1", "eu-central-1"],
})

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

activated · boolean · default: "true"

Whether the Playwright Check Suite is enabled and will run according to its schedule.

Usage:

new PlaywrightCheck("disabled-pwt-check-suite", {
  name: "Disabled Playwright Check Suite",
  playwrightConfigPath: "../playwright.config.ts",
  activated: false,
})

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

Array of Checkly tags to organize and categorize your Playwright Check Suite in the Checkly infrastructure.

Usage:

new PlaywrightCheck("my-check-suite", {
  name: "My Playwright Check Suite",
  playwrightConfigPath: "../playwright.config.ts",
  tags: ["pwt", "critical"],
})

Examples:

Priority Tags

new PlaywrightCheck("my-check-suite", {
  name: "My Playwright Check Suite",
  playwrightConfigPath: "../playwright.config.ts",
  tags: ["critical", "revenue", "high-priority"],
})

new PlaywrightCheck("staging-check-suite", {
  name: "Staging Playwright Check Suite",
  playwrightConfigPath: "../playwright.config.ts",
  tags: ["staging"],
  /* More options... */
})

new PlaywrightCheck("prod-check-suite", {
  name: "Production Playwright Check Suite",
  playwrightConfigPath: "../playwright.config.ts",
  tags: ["production"],
  /* 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 PlaywrightCheck("user-flow-pwt-check-suite", {
  name: "User Flow Playwright Check Suite",
  playwrightConfigPath: "../playwright.config.ts",
  environmentVariables: [
    { key: "TEST_USERNAME", value: "[e-mail]" },
    { key: "TEST_PASSWORD", value: "{{SECRET_PASSWORD}}", secret: true },
  ],
})

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 PlaywrightCheck("user-flow-pwt-check-suite", {
  name: "User Flow Playwright Check Suite",
  playwrightConfigPath: "../playwright.config.ts",
  environmentVariables: [
    { key: "TEST_USERNAME", value: "[e-mail]" },
    { key: "TEST_PASSWORD", value: "{{SECRET_PASSWORD}}", secret: true },
  ],
})

new PlaywrightCheck("feature-test", {
  name: "Feature Flag Test",
  playwrightConfigPath: "../playwright.config.ts",
  environmentVariables: [
    {
      key: "BASE_URL",
      value: "https://example.com",
    },
  ],
})

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

Examples

Multi-browser Support

const playwrightChecks = new PlaywrightCheck("multi-browser-check", {
  name: "Multi-browser check suite",
  playwrightConfigPath: "./playwright.config.ts",
  // Playwright Check Suites support all browsers
  // defined in your `playwight.config`
  pwProjects: ["chromium", "firefox", "webkit"],
})

// Often, it makes sense to define different Playwright projects
// in your `playwright.config` and make them depend on each other
// to perform setup tasks:
//
// projects: [
//   {
//     name: "setup",
//     use: { ...devices["Desktop Chrome"] },
//     testMatch: /.*\.setup\.ts/,
//   },
//   {
//     name: "e2e",
//     use: { ...devices["Desktop Chrome"] },
//     dependencies: ["setup"],
//     testMatch: /.*\.spec\.ts/,
//   },
// ]

// Playwright Check Suites support, detect and run your
// Playwright project dependencies.
//
// Learn more in the Playwright docs:
const playwrightChecks = new PlaywrightCheck("multi-browser-check", {
  name: "Multi-browser check suite",
  playwrightConfigPath: "./playwright.config.ts",
  // https://playwright.dev/docs/test-projects#dependencies
  pwProjects: ["e2e"], // this will run `setup` and then `e2e`
})