Playwright Check Suite Environment Variables

To create and manage environment variables and secrets, including inheritance and where to set them, see the Environment Variables documentation.

Built-in variables in Playwright Check Suites

Checkly sets the following environment variables on every Playwright Check Suite run:

Variable	Description
`CHECKLY`	Checkly sets this to `1` for every Playwright Check Suite run. Use it to distinguish Checkly runs from local runs.
`CHECKLY_RUN_SOURCE`	Identifies what triggered the check run. Use it to adjust test behavior for schedules, manual triggers, deployments, or CLI runs. See `CHECKLY_RUN_SOURCE` values.
`CI`	Checkly sets this to `1` for CLI runs (`npx checkly test` or `npx checkly trigger`) and checks started by deployments.
`ACCOUNT_ID`	The UUID of the Checkly account.
`CHECK_NAME`	The name of the check.
`CHECKLY_CHECK_ID`	The UUID of the check.
`CHECKLY_REGION`	The region where Checkly ran the check.
`CHECKLY_TRACE_ID`	The OpenTelemetry trace ID of the check run. Only set when Traces is active for the check; unset otherwise.
`CHECKLY_TRACEPARENT`	The W3C `traceparent` header value of the check run’s trace. Only set when Traces is active.
`CHECKLY_TRACESTATE`	The W3C `tracestate` header value of the check run’s trace. Only set when Traces is active.

`CHECKLY_RUN_SOURCE` values

Value	Description
`CLI_DEPLOY`	The first run after `npx checkly deploy`.
`DEPLOYMENT`	A CI/CD deployment started the run.
`GROUP_RUN_ALL`	The “Run all checks” action on the group’s edit screen started the run.
`SCHEDULE_NOW`	The “Schedule now” action in the web app started the run.
`SCHEDULER`	The regular check schedule started the run.
`TEST_NO_RECORD`	`npx checkly test --no-record` started the run.
`TEST_RECORD`	`npx checkly test` or `npx checkly pw-test` started the run.
`TRIGGER_API`	The API started the run.
`TRIGGER_NO_RECORD`	`npx checkly trigger --no-record` started the run.
`TRIGGER_RECORD`	`npx checkly trigger` started the run.

Use built-in variables

Use Checkly’s built-in environment variables to tune test behavior for different run contexts.

Adjust behavior based on trigger type

Use different timeouts for scheduled runs and manual triggers:

import { test } from '@playwright/test';

test('API health check', async ({ request }) => {
  // Scheduled monitors should fail fast. Manual runs can wait longer for debugging.
  const isScheduledRun = process.env.CHECKLY_RUN_SOURCE === 'SCHEDULER';
  const timeout = isScheduledRun ? 5000 : 30000;

  const response = await request.get('https://api.example.com/health', {
    timeout,
  });

  // ... assertions
});

Configure Playwright by environment

Use the built-in CHECKLY environment variable in your playwright.config.ts to use different settings for Checkly runs and local development.

playwright.config.ts

import { defineConfig } from '@playwright/test';

export default defineConfig({
  // Run one worker in Checkly when tests share state or accounts.
  workers: process.env.CHECKLY === '1' ? 1 : undefined,
  use: {
    // Checkly runs against a public URL. Local runs use the dev server.
    baseURL: process.env.CHECKLY === '1'
      ? 'https://www.example.com'
      : 'http://localhost:3000',
  },
});

Playwright Check Suites record traces for successful and failed runs. Checkly uses these traces to show dedicated Network and Browser console sections, so you can compare requests, logs, and errors when you troubleshoot.

You can also adjust these settings for Checkly runs:

maxFailures: stop early during monitoring runs, for example after the first failure.
timeout: give tests more or less time in Checkly than during local development.
expect.timeout: tune assertion timeouts for production or staging environments.
retries: override Checkly’s default retry count if your suite needs a different policy.

Access region information

Use region information for debugging or region-specific behavior:

import { test } from '@playwright/test';

test('geo-specific content test', async ({ page }) => {
  await page.goto('https://example.com');

  // Include the region in logs to compare results across locations.
  console.log(`Running in region: ${process.env.CHECKLY_REGION}`);

  // Add assertions only for regions where the content should appear.
  if (process.env.CHECKLY_REGION?.startsWith('eu-')) {
    // Example: check for an EU-specific cookie banner.
  }
});

Correlate a run with its trace

When Traces is active, use CHECKLY_TRACE_ID to link a check run to the trace in your observability backend — for example by logging it, or by tagging telemetry your test emits itself:

import { test } from '@playwright/test';

test('checkout flow', async ({ page }) => {
  // Search for this ID in your tracing backend to find the run's full trace.
  console.log(`Trace ID: ${process.env.CHECKLY_TRACE_ID}`);

  await page.goto('https://example.com/checkout');
  // ... assertions
});

CHECKLY_TRACEPARENT and CHECKLY_TRACESTATE carry the same trace context as standard W3C Trace Context header values, ready to pass to your own tooling. All three variables are unset when Traces is not active, so if (process.env.CHECKLY_TRACE_ID) reliably tells you whether the run is traced.

Getting Started

Detect

Communicate

Resolve

AI

Integrations

Playwright Check Suite Environment Variables

Built-in variables in Playwright Check Suites

`CHECKLY_RUN_SOURCE` values

Use built-in variables

Adjust behavior based on trigger type

Configure Playwright by environment

Access region information

Correlate a run with its trace

​Built-in variables in Playwright Check Suites

​CHECKLY_RUN_SOURCE values

​Use built-in variables

​Adjust behavior based on trigger type

​Configure Playwright by environment

​Access region information

​Correlate a run with its trace

Built-in variables in Playwright Check Suites

`CHECKLY_RUN_SOURCE` values

Use built-in variables

Adjust behavior based on trigger type

Configure Playwright by environment

Access region information

Correlate a run with its trace