> ## Documentation Index
> Fetch the complete documentation index at: https://checklyhq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Playwright Check Suites Configuration

> Complete configuration reference for Playwright Check Suites including all available options and examples.

Use the `checkly.config.ts/js` file to define your Playwright Check Suite. Each Playwright Check Suite can be connected to references in your `playwright.config.ts/js` file.

<Info>
  **The Playwright test execution stage can run for up to 30 minutes**. Use Playwright's `globalTimeout` to set a custom suite-level limit. [Contact us in the Checkly Web App](https://app.checklyhq.com/?support=true) or get in touch with your account executive if you need longer runs.
</Info>

## Playwright Check Suite definition

To add Playwright Check Suites to your Checkly monitoring setup, specify the path to your `playwright.config.ts/js` and add a new `playwrightChecks` property to the existing `checks` configuration in your `checkly.config.ts/js`.

```typescript checkly.config.ts highlight={8-14} theme={null}
import { defineConfig } from 'checkly'
import { Frequency } from 'checkly/constructs'

export default defineConfig({
  // ...

  checks: {
    playwrightConfigPath: './playwright.config.ts',
    playwrightChecks: [
      {
        name: 'all-pwt-tests',
        logicalId: 'all-tests',
      }
    ],
  },
})
```

A Playwright Check Suite requires the following properties:

* `name` - a human friendly name for your check suite.
* `logicalId` - a reference for your check suite.

Other available properties like `frequency`, `alertChannels` or `locations` are inherited from the general Checkly configuration if not specified otherwise.

## Playwright references

Without limiting and selecting specific tests or Playwright projects, the Checkly infrastructure will run and deploy **all your existing Playwright tests** (similar to what `npx playwright test` runs) as monitors.

Specify which tests should become part of global end-to-end monitoring by defining these properties:

* `pwProjects`: select an existing project by name from your Playwright configuration to create a Playwright Check Suite.

* `pwTags`: select tagged tests that will be grouped into a Playwright Check Suite.

You can combine `pwTags` and `pwProjects` to generate your check suite, too.

For example:

```typescript checkly.config.ts highlight={11, 20} theme={null}
export default defineConfig({
  // ...
  checks: {
    playwrightConfigPath: './playwright.config.ts',
    playwrightChecks: [
      {
        name: "Marketing Environment",
        logicalId: "environment-marketing-suite",
        // Run the `environment-marketing` Playwright project
        // in two locations every hour
        pwProjects: ["environment-marketing"],
        frequency: Frequency.EVERY_1H,
        locations: ["us-west-1", "eu-west-2"],
      },
      {
        name: "Critical production tests",
        logicalId: "critical-tests",
        // Run `@critical` tagged Playwright tests
        // in three locations every ten minutes
        pwTags: ["@critical"],
        frequency: Frequency.EVERY_10M,
        locations: ["us-west-1", "eu-west-2", "af-south-1"],
      },
    ],
  },
});
```

Learn more about [best practices to organize and structure your Playwright tests](/detect/synthetic-monitoring/playwright-checks/test-organization/) for synthetic monitoring.

## Monitoring customizations

A Playwright Check Suite inherits multiple properties from the abstract `Check` class:

* `name`
* `description`
* `activated`
* `muted`
* `locations`
* `tags`
* `frequency`
* `alertChannels`
* `privateLocations`
* `alertEscalationPolicy`

Check out [the reference documentation](/constructs/project#param-checks-playwright-checks) for more information on these settings.

<Note>
  **Checkly retry strategies do not apply to Playwright Check Suites.** Use Playwright's [`retries`](https://playwright.dev/docs/test-retries) option in your `playwright.config.ts/js` file or `testCommand` to control test retries.
</Note>

### Checkly-applied Playwright settings

When Checkly runs a Playwright Check Suite, it applies Playwright settings that produce useful monitoring results and artifacts.

Checkly applies these defaults only when you do not set the option yourself:

| Playwright option | Checkly default  |
| ----------------- | ---------------- |
| `workers`         | `4`              |
| `retries`         | `2`              |
| `use.video`       | `on-first-retry` |
| `use.screenshot`  | `on-first-retry` |

Your Playwright config or `testCommand` value takes precedence for these options.

Checkly enforces these options for every run. User configuration does not override them:

| Playwright setting | Checkly behavior                                                                                 |
| ------------------ | ------------------------------------------------------------------------------------------------ |
| `use.trace`        | `on` for every run                                                                               |
| User agent         | Checkly appends a [user-agent suffix](/platform/allowlisting-traffic#default-checkly-user-agent) |

Checkly supports Playwright's [`globalTimeout`](https://playwright.dev/docs/api/class-testconfig#test-config-global-timeout). Use it to control the maximum duration of the Playwright suite after `npx playwright test` starts.

Playwright Check Suites also provide specific configuration for your Playwright monitoring.

* `installCommand:` Override the command to install dependencies. `npm install --dev` is used by default.

* `testCommand:` Append to the command that runs tests. `npx playwright test` is used by default with the tags, projects, and config file options your check specifies.

* `engine:` Override the runtime engine for the check (Node.js or Bun). See [`engine`](/constructs/playwright-check#param-engine).

* `group:` The group id construct this check belongs to.

### Customize install and test commands

By default, Checkly runs `npm install --dev` to install dependencies and `npx playwright test` to run tests. The `testCommand` automatically includes your `pwProjects`, `pwTags`, and Playwright config file path.

You can override these commands to:

**Use a different package manager:**

```typescript theme={null}
installCommand: 'yarn install --frozen-lockfile'
```

**Install dependencies from a specific directory:**

```typescript theme={null}
installCommand: 'npm install --prefix ./e2e'
```

**Set a lower test timeout:**

```typescript theme={null}
testCommand: 'npx playwright test --timeout=60000'
```

**Set a global suite timeout:**

```typescript theme={null}
testCommand: 'npx playwright test --global-timeout=120000'
```

**Stop early after failures:**

```typescript theme={null}
testCommand: 'npx playwright test --max-failures=5'
```

**Combine multiple test flags:**

```typescript theme={null}
testCommand: 'npx playwright test --timeout=60000 --max-failures=5'
```

### Example Checkly config

```typescript checkly.config.ts theme={null}
import { defineConfig } from 'checkly'
import { Frequency } from 'checkly/constructs'
import { productionGroup } from './production-group.check'

export default defineConfig({
  // Shared Checkly configuration (scheduling, locations, etc.)
  // ...
  checks: {
    playwrightConfigPath: './playwright.config.ts',
    playwrightChecks: [
      {
        name: 'E2E test suite',
        logicalId: 'e2e-test-suite',
        pwProjects: ['chromium', 'firefox', 'webkit'],
        pwTags: '@e2e',
        installCommand: 'npm install --dev',
        testCommand: 'npx playwright test --max-failures=5',
        activated: true,
        muted: false,
        group: productionGroup,
        frequency: Frequency.EVERY_5M,
        locations: ['us-east-1', 'eu-west-1','eu-central-1', 'ap-south-1'],
      }
    ]
  },
})
```

## Testing configuration locally

Before deploying your Playwright Check Suites, validate your configuration locally:

```bash theme={null}
# Test your configuration without deploying
npx checkly test

# Test a specific check by logical ID
npx checkly test --grep=e2e-test-suite
```

The `npx checkly test` command runs your Playwright tests locally using the same configuration that Checkly will use in production. This helps catch configuration errors before deployment.

## Cancelling runs

You can cancel queued or in-progress Playwright Check Suite runs from the UI or CLI. Cancellation applies to runs from **Schedule Now** and from test sessions started with:

* `npx checkly test`
* `npx checkly pw-test`
* `npx checkly trigger`

Two ways to cancel:

* In the UI, click **Cancel Run** on the Check Suite Runs page or the Test Session Run page
* Press <kbd>Ctrl</kbd>+<kbd>C</kbd> in the CLI (v8.0.0+) to cancel a recorded test session

Cancelled runs show a **Cancelled** status in run history. See [Cancellation](/concepts/cancellation) for details on what happens after a run is cancelled.

## Common issues & troubleshooting

### Configuration errors

#### Invalid `logicalId`

```
Error: logicalId must be unique across all checks
```

Ensure each Playwright Check Suite has a unique `logicalId`. The `logicalId` is used as a stable reference across deployments.

#### Missing Playwright configuration

```
Error: Cannot find playwright.config.ts at path: ./playwright.config.ts
```

Verify that `playwrightConfigPath` points to the correct relative path from your `checkly.config.ts` file.

### Alert optimization

#### Alerts are triggered too late

Playwright Check Suites wait for `npx playwright test` to finish before triggering an alert on test failure. Use [Playwright's `maxFailures` option](https://playwright.dev/docs/api/class-testconfig#test-config-max-failures) to stop the test run and trigger alerts earlier. This setting halts the entire suite after reaching the specified number of failures, allowing you to receive alerts faster.

Specify this option in your `playwright.config` or the `testCommand` in your `checkly.config`.

<Tabs>
  <Tab title="playwright.config.ts">
    ```typescript playwright.config.ts highlight={5} theme={null}
    import { defineConfig } from '@playwright/test';

    export default defineConfig({
      // Setting to zero (default) disables max failures.
      maxFailures: process.env.CHECKLY === '1' ? 1 : 0,
    })
    ```
  </Tab>

  <Tab title="checkly.config.ts">
    ```typescript checkly.config.ts highlight={11} theme={null}
    import { defineConfig } from 'checkly'

    export default defineConfig({
      checks: {
        playwrightConfigPath: './playwright.config.ts',
        playwrightChecks: [
          {
            name: 'E2E test suite',
            logicalId: 'e2e-test-suite',
            pwTags: '@e2e',
            testCommand: 'npx playwright test --max-failures=1',
          }
        ]
      },
    })
    ```
  </Tab>
</Tabs>

#### Alerts are triggered too often

End-to-end testing for complex or flaky applications can be difficult. While it's best if your Playwright tests are not flaky, you can use the [`retries` option](https://playwright.dev/docs/test-retries#retries) to automatically rerun failed tests and prevent false alarms in your Playwright Check Suites monitoring.

Specify this option in your `playwright.config` or the `testCommand` in your `checkly.config`.

<Tabs>
  <Tab title="playwright.config.ts">
    ```typescript playwright.config.ts highlight={4} theme={null}
    import { defineConfig } from '@playwright/test';

    export default defineConfig({
      retries: process.env.CHECKLY === '1' ? 3 : 0,
    })
    ```
  </Tab>

  <Tab title="checkly.config.ts">
    ```typescript checkly.config.ts highlight={11} theme={null}
    import { defineConfig } from 'checkly'

    export default defineConfig({
      checks: {
        playwrightConfigPath: './playwright.config.ts',
        playwrightChecks: [
          {
            name: 'E2E test suite',
            logicalId: 'e2e-test-suite',
            pwTags: '@e2e',
            testCommand: 'npx playwright test --retries=3',
          }
        ]
      },
    })
    ```
  </Tab>
</Tabs>

### Test execution issues

#### Tests exceed 30-minute limit

If your Playwright Check Suite times out after 30 minutes:

* Split large test suites into multiple Playwright Check Suites using `pwTags` or `pwProjects`
* Use `.only` or `.skip` in your tests during development, then create separate check suites for different test priorities
* Optimize slow tests by reducing wait times and parallelizing where possible
* [Contact Checkly support](https://app.checklyhq.com/?support=true) if you need further help

#### Dependency installation failures

If dependencies fail to install:

* Check that your `package.json` and lock file (e.g., `package-lock.json`) are both included in your deployment.
* Verify that the private registry authentication is configured correctly. See the [custom dependencies guide](/detect/synthetic-monitoring/playwright-checks/custom-dependencies/) for more details.
* Adjust the `installCommand` to match your project's expectation.

#### Authentication failures in tests

If tests fail due to authentication issues:

* Verify environment variables are set correctly in Checkly. You can verify your environment variables using `npx checkly env ls`, or looking at your Global or Check's environment variables in the Checkly Webapp to ensure any `process.env.VARIABLE_NAME` call from your test is defined.
* For persistent authentication, use Playwright's [`storageState`](https://playwright.dev/docs/auth#reuse-authentication-state) feature.

#### webServer configuration requires additional files

When using `webServer` in your Playwright config, you need to include the server files in your check configuration:

* Add server files to the `include` parameter in your [Playwright check configuration](/constructs/playwright-check/#param-include)
* Include all files needed to start the server (e.g., server scripts, config files)
* Alternatively, skip `webServer` on Checkly and use your deployed URL: `...(process.env.CHECKLY ? {} : { webServer: { ... } })`

#### No tests found

If Playwright does not find any tests to run, this usually means a mismatch between your config and your test files:

* Verify your `--grep` pattern matches actual test tags or projects
* Verify the `testDir` path in `playwright.config.ts` matches the actual directory containing your test files
* Ensure path aliases (`~/`, `@/`) in imports are configured in your `tsconfig.json`, or replace them with relative paths