Turn your Playwright tests into monitors

By the end of this guide, two of your existing Playwright tests run against production every ten minutes from two regions, and you have seen what a failure looks like before a real one happens.

The Shop critical flows Playwright Check Suite in Checkly, passing from two locations

No Playwright project handy? Clone the sample project this guide is built on. It runs against the Danube demo shop.

Let your agent do it

To run this guide from your terminal or your coding agent, run npx checkly init in your project first. It installs the Checkly CLI and Checkly Skills for your agent. Then paste the prompt below into Claude Code, Cursor, Codex, or any agent that supports skills. It builds the same setup as this guide, proves it with npx checkly test --record, and stops for your confirmation before npx checkly deploy.

Prompt

Turn the Playwright tests in this repository into Checkly production monitors.

Goal: a Playwright Check Suite that runs only the tests worth alerting on, every 10 minutes, from us-east-1 and eu-west-1.

Success criteria:
1. Add a `monitoring` project to my existing `playwright.config.ts` that selects tests tagged `@monitor`. Do not change the other projects.
2. Use `process.env.CHECKLY === '1'` to point `baseURL` at production on Checkly and keep local runs on my dev server. Set `maxFailures: 1` and `retries: 2` for Checkly runs only.
3. Tag at most two critical user-flow tests with `@monitor`. Ask me which ones if it is not obvious. Never tag tests that create accounts or mutate data.
4. Create `checkly.config.ts` with one entry in `playwrightChecks` that selects the `monitoring` project.
5. Run `npx checkly test --record` and show me the session link.
6. Stop. Show me `npx checkly deploy --preview` and wait for my confirmation before `npx checkly deploy`.

Explain each file you changed and why.

Every step below is what the agent just did, in the open, so you can read the result or do it by hand.

Step 1: Pick the tests that become monitors

Not every test belongs in production monitoring. The sample has three: a search, a checkout, and a signup. Signup creates accounts, so it stays in CI. Search and checkout are what you want to know about within minutes, so they get a @monitor tag.

tests/checkout.spec.ts

import { test, expect } from '@playwright/test'

test('checkout completes', { tag: '@monitor' }, async ({ page }) => {
  await page.goto('/')

  // Add the first two books to the cart.
  for (const position of [1, 2]) {
    await page.locator(`.preview:nth-child(${position}) > .preview-author`).click()
    await page.getByRole('button', { name: 'Add to cart' }).click()
    await page.locator('#logo').click()
  }

  await page.locator('#cart').click()
  await page.getByRole('button', { name: 'Checkout' }).click()

  await page.getByPlaceholder('Name', { exact: true }).fill('Max')
  await page.getByPlaceholder('Surname', { exact: true }).fill('Mustermann')
  await page.getByPlaceholder('Address').fill('Charlottenstr. 57')
  await page.getByPlaceholder('Zipcode').fill('10117')
  await page.getByPlaceholder('City').fill('Berlin')
  await page.getByPlaceholder('Company (optional)').fill('Firma GmbH')
  await page.getByLabel('as soon as possible').check()
  await page.getByRole('button', { name: 'Buy' }).click()

  await expect(page.locator('#order-confirmation')).toContainText('Thank you')
})

Then give the tagged tests their own Playwright project. Checkly sets CHECKLY=1 on every run, which is the one switch you need to point monitoring at production while local runs keep using your dev server.

playwright.config.ts

import { defineConfig, devices } from '@playwright/test'

// Checkly sets CHECKLY=1 on every run. Use it to point monitoring at
// production while local runs keep hitting your dev server.
const onCheckly = process.env.CHECKLY === '1'

export default defineConfig({
  testDir: './tests',
  retries: onCheckly ? 2 : 0,
  // Stop after the first failure on Checkly so alerts fire sooner.
  maxFailures: onCheckly ? 1 : 0,
  use: {
    baseURL: onCheckly ? 'https://danube-web.shop' : 'http://localhost:3000',
    trace: 'retain-on-failure',
  },
  projects: [
    // Everything, for local runs and CI.
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
    // Only the flows worth waking someone up for.
    {
      name: 'monitoring',
      grep: /@monitor/,
      use: { ...devices['Desktop Chrome'] },
    },
  ],
})

Three settings matter for monitoring and not for testing. baseURL makes the same page.goto('/') hit production on Checkly. maxFailures: 1 stops the run at the first failure so the alert goes out sooner. retries absorbs a transient network blip before it becomes an alert. Checkly records a trace on every run regardless of your trace setting.

If your config starts a webServer, guard it the same way: webServer: onCheckly ? undefined : { ... }. On Checkly the deployed site is already running.

Step 2: Define the monitor

Install the CLI if this repository does not have it yet, then describe the monitor in a checkly.config.ts next to your Playwright config.

Terminal

npm install --save-dev checkly

A Playwright Check Suite reuses your Playwright config and runs a whole project. A Browser Check runs a single spec file with Checkly’s own Playwright setup. Pick one.

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

export default defineConfig({
  projectName: 'Docs guide: Playwright tests to monitors',
  logicalId: 'docs-guide-playwright-to-monitoring',
  checks: {
    // Reuse the Playwright config your tests already run with.
    playwrightConfigPath: './playwright.config.ts',
    playwrightChecks: [
      {
        name: 'Shop critical flows',
        logicalId: 'shop-critical-flows',
        // Run only the `monitoring` project: the @monitor-tagged tests.
        pwProjects: ['monitoring'],
        frequency: Frequency.EVERY_10M,
        locations: ['us-east-1', 'eu-west-1'],
      },
    ],
  },
  cli: {
    runLocation: 'eu-west-1',
  },
})

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

// The single-file alternative: one spec file becomes one Browser Check.
// Browser Checks run the file on its own, without playwright.config.ts,
// so the spec uses full URLs instead of baseURL.
new BrowserCheck('shop-checkout-browser-check', {
  name: 'Shop checkout (Browser Check)',
  frequency: Frequency.EVERY_10M,
  locations: ['us-east-1', 'eu-west-1'],
  code: {
    entrypoint: path.join(__dirname, 'checkout.spec.ts'),
  },
})

The Check Suite path needs nothing else: the pwProjects entry selects the monitoring project, and the suite runs every ten minutes from Virginia and Ireland. The Browser Check path needs a copy of the spec with page.goto('https://danube-web.shop/'), because there is no playwright.config.ts to supply baseURL. The sample keeps that copy in checks/checkout.spec.ts.

Prefer to have your coding agent write this file? The Playwright Check Suite quickstart has a prompt that inspects your Playwright config and generates the checkly.config.ts.

Step 3: Run it on Checkly before you deploy

npx checkly test bundles the project, runs it on Checkly’s infrastructure, and streams the result back. --record keeps the run so you can open it in the app.

Terminal

npx checkly test --record

Terminal

Parsing your project... ✅
Validating project resources... ✅
Bundling project resources... ✅
Uploading Playwright tests... ✅

Test session ID: 01a0ce89-ce0c-74e1-8ee7-e95a2430af87
Open session: https://app.checklyhq.com/accounts/<account-id>/test-sessions/01a0ce89-ce0c-74e1-8ee7-e95a2430af87

Running 2 checks in eu-west-1.

checks/checkout.check.ts
  ✔ Shop checkout (Browser Check) (7s)
playwright.config.ts
  ✔ Shop critical flows (12s)

2 passed, 2 total

Both variants from step 2 ran because the sample contains both. Open the session link. Each test in the suite shows its steps, timing, a trace, and a video, the same artifacts you get from a local run.

A passing Shop critical flows result in Checkly listing the checkout and search test cases with trace and video attachments

Step 4: Deploy

Terminal

npx checkly deploy

Terminal

Parsing your project... ✅
Validating project resources... ✅
Bundling project resources... ✅
Uploading Playwright tests... ✅
Deploying project... ✅

Successfully deployed project "Docs guide: Playwright tests to monitors" to account "Checkly Marketing".

The suite now runs on its schedule. The first run starts immediately with CHECKLY_RUN_SOURCE=CLI_DEPLOY, then every ten minutes from both locations. It appears in your check list as a Playwright check.

The Checkly check list showing the Shop critical flows Playwright check with its locations and pass rate

Every later npx checkly deploy updates the suite in place, so the monitor changes whenever the tests do. Wire that into CI and the tests and the monitors ship together.

Verify it works

Break the checkout on purpose before production does. Rename the Buy button in the spec to Purchase and run the suite again, without deploying.

Terminal

npx checkly test --record --grep "Shop critical flows"

Terminal

Running 1 checks in eu-west-1.

playwright.config.ts
  ✖ Shop critical flows (101s)

    09:53:59 ERROR Error: locator.click: Test timeout of 30000ms exceeded.
    Call log:
      - waiting for getByRole('button', { name: 'Purchase' })

        at tests/checkout.spec.ts:23:56
    09:55:04 INFO  1 ✘ [monitoring] checkout.spec.ts > checkout completes
    09:55:04 INFO  2 ✓ [monitoring] search.spec.ts > search finds a book
    09:55:04 ERROR Testing stopped early after 1 maximum allowed failures.

    View result: https://chkly.link/l/_rONl

1 failed, 1 total

Playwright retried the test twice, the search test still passed, and maxFailures stopped the run. The result page shows the failing step, the error, a screenshot at the moment of failure, and the trace. This is the page an alert links to.

The failed checkout test case in Checkly showing three failed attempts, the Playwright error with the failing line highlighted, and View Trace and Analyze root cause buttons

Put Buy back. The deployed monitor never saw the broken version, because npx checkly test runs the code in your working tree and npx checkly deploy is what changes the monitor.

--grep matches the check’s name, not its logicalId.

Cover every endpoint with uptime monitors: add URL, heartbeat, and SSL monitors around the flows you just covered, from a few lines of code.

Overview

AI and LLMs

Monitoring Guides

API Monitoring

Playwright Guides

Advanced Topics

Turn your Playwright tests into monitors

Step 1: Pick the tests that become monitors

Step 2: Define the monitor

Step 3: Run it on Checkly before you deploy

Step 4: Deploy

Verify it works

Next

Reference

​Step 1: Pick the tests that become monitors

​Step 2: Define the monitor

​Step 3: Run it on Checkly before you deploy

​Step 4: Deploy

​Verify it works

​Next

​Reference

Step 1: Pick the tests that become monitors

Step 2: Define the monitor

Step 3: Run it on Checkly before you deploy

Step 4: Deploy

Verify it works

Next

Reference