diff --git a/detect/synthetic-monitoring/playwright-checks/add-to-group.mdx b/detect/synthetic-monitoring/playwright-checks/add-to-group.mdx index 9fdc954..7bbb725 100644 --- a/detect/synthetic-monitoring/playwright-checks/add-to-group.mdx +++ b/detect/synthetic-monitoring/playwright-checks/add-to-group.mdx @@ -14,9 +14,9 @@ You can define a new group, or associate a Playwright Check Suite to an existing ### 1. Create a group for your checks -To define a new group, create a group file, for example `website-group.check.ts`. +Create a new file to create and configure your new group. -```typescript +```typescript website-group.check.ts import { CheckGroup } from 'checkly/constructs' export const myGroup = new CheckGroup('production-group', { @@ -39,17 +39,15 @@ export const myGroup = new CheckGroup('production-group', { ``` -Learn more about [using groups](/cli/constructs-reference/#checkgroup) to unify checks in Checkly. +Learn more about [using groups](/constructs/check-group-v2) to unify checks in Checkly. ### 2. Associate the group to the check When specifying your Playwright Check Suite, you can reference the new or existing group, using its name: -```typescript -import { defineConfig } from 'checkly' - -const config = defineConfig({ +```typescript checkly.config.ts highlight={13} +export default defineConfig({ logicalId: 'checkly-website', projectName: 'checkly-website', checks: { @@ -65,9 +63,6 @@ const config = defineConfig({ }, ], }, - cli: { - runLocation: 'us-east-1', - }, }) export default config @@ -80,4 +75,4 @@ npx checkly deploy --preview # confirm what will be deployed npx checkly deploy # deploy ``` -You can now see your Playwright Check Suite in your group. +You can now see your Playwright Check Suite assigned to your group. diff --git a/detect/synthetic-monitoring/playwright-checks/configuration.mdx b/detect/synthetic-monitoring/playwright-checks/configuration.mdx index d0bbf0f..2b4333f 100644 --- a/detect/synthetic-monitoring/playwright-checks/configuration.mdx +++ b/detect/synthetic-monitoring/playwright-checks/configuration.mdx @@ -8,17 +8,17 @@ import PlaywrightCheckSuiteBetaNote from '/snippets/playwright-check-suite-beta- -Use the `checkly.config.ts/js` file to define your Playwright Check Suite. +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. -Each Playwright Check Suite can be connected to references in your `playwright.config.ts/js` file. - -During the Beta, **a Playwright Check Suite can run up to 20 minutes**. This limit can be adjusted based on feedback. + +**A Playwright Check Suite can run up to 15 minutes**. [Please contact us in the Checkly Web App](https://app.checklyhq.com/?support=true) or get in touch with your account executive if you're interested in longer runs. + ## 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 +```typescript checkly.config.ts highlight={8-14} import { defineConfig } from 'checkly' import { Frequency } from 'checkly/constructs' @@ -29,11 +29,8 @@ export default defineConfig({ playwrightConfigPath: './playwright.config.ts', playwrightChecks: [ { - name: 'critical-tagged', - pwTags: 'critical', - pwProjects: 'chromium', - frequency: Frequency.EVERY_1M, - locations: ['us-east-1', 'eu-west-1','eu-central-1', 'ap-south-1'], + name: 'all-pwt-tests', + logicalId: 'all-tests', } ], }, @@ -49,41 +46,48 @@ Other available properties like `frequency`, `alertChannels` or `locations` are ## Playwright references -The Checkly infrastructure will run and deploy all your existing Playwright tests (similar to what `npx playwright test` runs) as monitors if you don't reference Playwright projects or tags. +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 existing project names from your Playwright configuration to create a Playwright Check Suite. +* `pwProjects`: select an existing project by name from your Playwright configuration to create a Playwright Check Suite. -* `pwTags` --- select test tags that will be grouped into 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 +```typescript checkly.config.ts highlight={11, 20} export default defineConfig({ // ... checks: { playwrightConfigPath: './playwright.config.ts', playwrightChecks: [ { - /** - * Run critical tagged tests in Chromium - * every minute from 4 locations. - */ - name: 'critical-tagged', - pwTags: '@critical', - pwProjects: 'chromium', - frequency: Frequency.EVERY_1M, - locations: ['us-east-1', 'eu-west-1','eu-central-1', 'ap-south-1'], + 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"], }, ], }, }); ``` -> We recommend using `pwTags` and `pwProjects` to group your Playwright tests into different monitoring levels with different monitoring settings. For example, critical application functionality may be monitored best with short monitoring frequencies to lower the mean time to detect (MTTD). +Learn more about [best practices to organize and structure your Playwright tests](/detect/synthetic-monitoring/playwright-checks/test-organization/) for synthetic monitoring. ## Monitoring customizations @@ -100,7 +104,7 @@ A Playwright Check Suite inherits multiple properties from [the abstract `Check` - `retryStrategy` - `alertEscalationPolicy` -Check [the reference documentation](/cli/constructs-reference/#check) for more information on these settings. +Check [the reference documentation](/constructs/project#param-checks-playwright-checks) for more information on these settings. Additionally, Playwright Check Suites provide specific configuration for your Playwright monitoring. @@ -110,36 +114,43 @@ Additionally, Playwright Check Suites provide specific configuration for your Pl * `groupName:` The group this check belongs to. -```typescript -checks: { - playwrightConfigPath: './playwright.config.ts', // specify your config file - playwrightChecks: [ - { - /** - * Run `@e2e` tagged tests across browsers - * every 5 minute from 4 locations. - */ - // Human readable name - name: 'E2E test suite', - // Reference id - logicalId: 'e2e-test-suite', - // Playwright project references defined in `playwright.config` - pwProjects: ['chromium', 'firefox', 'webkit'], - // Playwright tags defined in `spec` files - pwTags: '@e2e', - // Override default dependencies install command - installCommand: 'npm install --dev', - // Override the default test command - testCommand: 'npx playwright test --grep@checkly --config=playwright.foo.config.ts', - // Activate the check so that it runs on a schedule, true by default - activated: true, - // Mute the check so that it doesn't send alerts - muted: false, - // Add a check to a group - groupName: 'production-group', - frequency: Frequency.EVERY_5M, - locations: ['us-east-1', 'eu-west-1','eu-central-1', 'ap-south-1'], - } - ] - }, +```typescript checkly.config.ts +export default defineConfig({ + // Shared Checkly configuration (scheduling, locations, etc.) + // ... + checks: { + // Specify the relative path to your config file + playwrightConfigPath: './playwright.config.ts', + playwrightChecks: [ + { + /** + * Run `@e2e` tagged tests across browsers + * every 5 minute from 4 locations. + */ + // Human readable name + name: 'E2E test suite', + // Reference id + logicalId: 'e2e-test-suite', + // Playwright project references defined in `playwright.config` + pwProjects: ['chromium', 'firefox', 'webkit'], + // Playwright tags defined in `spec` files + pwTags: '@e2e', + // Override default dependencies install command + installCommand: 'npm install --dev', + // Append to the resulting test command, respects your pwTags and pwProjects filters. + testCommand: 'npx playwright test --trace=on', + // Activate the check so that it runs on a schedule, true by default + activated: true, + // Mute the check so that it doesn't send alerts + muted: false, + // Add a check to a group + groupName: 'production-group', + // Specify a monitoring frequency + frequency: Frequency.EVERY_5M, + // Define locations to monitor from + locations: ['us-east-1', 'eu-west-1','eu-central-1', 'ap-south-1'], + } + ] + }, +} ``` diff --git a/detect/synthetic-monitoring/playwright-checks/custom-dependencies.mdx b/detect/synthetic-monitoring/playwright-checks/custom-dependencies.mdx index ed80f78..78446e3 100644 --- a/detect/synthetic-monitoring/playwright-checks/custom-dependencies.mdx +++ b/detect/synthetic-monitoring/playwright-checks/custom-dependencies.mdx @@ -22,7 +22,9 @@ Whether you use [npm](https://www.npmjs.com/), [yarn](https://yarnpkg.com/), or } ``` -**By default, the Checkly infrastructure installs dependencies via npm.** + +By default, the Checkly infrastructure installs dependencies via npm. + However, if an alternative lock file (`pnpm-lock.json` or `yarn.lock`) is discovered, Checkly uses the matching package manager to install the project dependencies. @@ -32,7 +34,9 @@ However, if an alternative lock file (`pnpm-lock.json` or `yarn.lock`) is discov | `pnpm-lock.json` | pnpm | | `yarn.lock` | yarn | -> **For `pnpm` users:** if you define the same dependency in `dependencies` and `devDependencies`, please use a custom `installCommand` in your `checkly.config.ts|js` to register your package as a development dependency: `pnpm install --dev additional-package` + +**For `pnpm` users:** if you define the same dependency in `dependencies` and `devDependencies`, please use a custom `installCommand` in your `checkly.config.ts|js` to ensure all required dependenies are installed: `pnpm install` + ## Using private dependencies @@ -87,11 +91,11 @@ registry=https://yourcompany.jfrog.io/artifactory/api/npm/yourcompany.jfrog.io/a ### Include custom configuration files -To make the Checkly CLI and infrastructure aware of a custom package manager configuration for private packages, specify the additional files in the `checks.include` property in your `checkly.config.ts|js`. +To make the Checkly CLI and infrastructure aware of your configuration for private packages, specify the additional files in the `checks.include` property in your `checkly.config.ts`. -Checkly CLI commands like `test` or `deploy` will then bundle and upload these files so they are available in the Checkly infrastructure when running essential commands like `install`. +Checkly CLI commands like `test` or `deploy` will bundle and upload these files so they are available in the Checkly infrastructure when running essential commands like `install`; making sure your private dependencies are installed. -```typescript +```typescript checkly.config.ts export default defineConfig({ checks: { playwrightConfigPath: './playwright.config.ts', diff --git a/detect/synthetic-monitoring/playwright-checks/overview.mdx b/detect/synthetic-monitoring/playwright-checks/overview.mdx index 31aa49c..678d720 100644 --- a/detect/synthetic-monitoring/playwright-checks/overview.mdx +++ b/detect/synthetic-monitoring/playwright-checks/overview.mdx @@ -14,13 +14,17 @@ import PlaywrightCheckSuiteBetaNote from '/snippets/playwright-check-suite-beta- ## What are Playwright Checks? -Playwright Checks enable you to run entire Playwright Suites or Projects as both pre-production tests and global production monitors, without rewriting your tests and configuration. +Playwright Check Suites enable you to run entire Playwright end-to-end test suites, Playwright projects or tagged tests as pre-production tests and global production monitors, without rewriting your tests and configuration. -Unlike [Browser Checks](detect/synthetic-monitoring/browser-checks/overview), Playwright Checks are not limited to a single test spec running in an async browser session and our preinstalled runtime dependencies. Playwright Checks enable you to run Playwright projects complete with all of your required dependencies, private packages, storage, data, and more. It's a complete native way to run Playwright in production, enabling you to detect issues with your applications or services even in the most complex scenarios. +Unlike [Browser Checks](detect/synthetic-monitoring/browser-checks/overview), Playwright Check Suites are not limited to a single test spec and our preinstalled runtime dependencies. Playwright Check Suites enable you to run Playwright projects complete with all of your required dependencies, private packages, storage, data, and more, and enable you to detect issues with your applications or services even in the most complex scenarios. -Playwright Checks support for the full Playwright API and ecosystem, meaning you can use your existing tests and `playwright.config.ts` files as is. + + ![Playwright Check Suites test result](/images/pwn-test-result.png) + -**Playwright Checks are perfect for:** +**Playwright Check Suites are the native way to run Playwright in production** and support the full Playwright API and ecosystem, meaning you can use your existing tests and `playwright.config.ts` files as is. + +**Playwright Check Suites are perfect for:** - Converting existing E2E tests into monitoring - Testing complex user workflows across multiple browsers - Monitoring critical business processes @@ -31,7 +35,7 @@ Playwright Checks support for the full Playwright API and ecosystem, meaning you -Playwright Checks analyze your Playwright configuration and test files to understand your existing test structure. +Playwright Check Suites analyze your Playwright configuration and test files to understand your existing test structure. @@ -59,21 +63,36 @@ Receive notifications when tests fail or performance degrades, keeping your team Control which tests become monitoring checks using: -- **Tags**: Select tests marked with specific tags (e.g., `@critical`, `@smoke`) - **Projects**: Choose browser configurations from your Playwright config +- **Tags**: Select tests marked with specific tags (e.g., `@critical`, `@smoke`) - **Combinations**: Mix tags and projects for precise test selection -```typescript -// Example: Monitor critical tests in Chromium -{ - name: 'Critical User Flows', - pwTags: '@critical', - pwProjects: 'chromium', - frequency: Frequency.EVERY_1M, - locations: ['us-east-1', 'eu-west-1'] -} +```typescript checkly.config.ts +export default defineConfig({ + checks: { + playwrightChecks: [ + { + name: "Marketing Environment", + logicalId: "environment-marketing-suite", + // Select the tests defined in + // the `environment-marketing` Playwright project + pwProjects: ["environment-marketing"], + }, + { + name: "@critical tests", + logicalId: "critical tests", + // Select tests tagged as `@critical` + pwTags: ["@critical"], + }, + ], + }, +}) ``` + +The Playwright Check Suite runner will use the `pwProjects` and `pwTags` values to configure [the native Playwright Test CLI run](https://playwright.dev/docs/test-cli). `pwProjects` reflects the `--project` and `pwTags` the `--grep` CLI options. + + ## Monitoring Configuration Customize monitoring behavior with: @@ -89,11 +108,11 @@ Customize monitoring behavior with: Ready to turn your Playwright tests into monitoring? Start with our quickstart guide to get running in 5 minutes. - + Get from zero to deployed monitoring in 5 minutes - + Complete configuration options and examples diff --git a/detect/synthetic-monitoring/playwright-checks/quickstart.mdx b/detect/synthetic-monitoring/playwright-checks/quickstart.mdx deleted file mode 100644 index 8014701..0000000 --- a/detect/synthetic-monitoring/playwright-checks/quickstart.mdx +++ /dev/null @@ -1,156 +0,0 @@ ---- -title: 'Playwright Checks Quickstart' -description: 'Get started with Playwright Check Suites in 5 minutes. Turn your existing Playwright tests into globally distributed monitoring.' -sidebarTitle: 'Quickstart' ---- - -import PlaywrightCheckSuiteBetaNote from '/snippets/playwright-check-suite-beta-note.mdx' - - - -Use your existing Playwright tests as live, scheduled monitoring checks. No rewrites required. Get from zero to deployed checks in 5 minutes. - - -Before you begin, you need: - -- A Checkly account -- A repository using Playwright for E2E tests and a Playwright configuration file - - -## Steps - -### 1. Install the Checkly CLI - -```bash -npm install --save-dev checkly -``` - -### 2. [Optional] If you're using TypeScript - -If you're using TypeScript, install the dev dependencies [`jiti`](https://www.npmjs.com/package/jiti) and [`typescript`](https://www.npmjs.com/package/typescript). These help the CLI bundle your typescript config and test files correctly. - -```bash -npm install --save-dev jiti typescript -``` - -### 3. Test with `pw-test` - -Run your Playwright test suite using `pw-test`. - -`pw-test` accepts both Checkly and Playwright command line arguments using the following syntax: - -`npx checkly pw-test --checkly-flag -- --playwright-flag`. Use `--` to separate Checkly and Playwright flags. - -The CLI command will then return a link to results, traces and more details: - -```bash -> npx checkly pw-test -- --project=chromium - -Parsing your Playwright project... ✅ - -Validating project resources... ✅ - -Bundling project resources... ✅ - -Running 1 checks in eu-west-1. - -playwright.config.ts - ✔ Playwright Test: --project=chromium (16s) - -Detailed session summary at: https://chkly.link/l/linkhere -``` - -### 4. Convert tests to checks - -Using `pw-test` with the `--create-check` flag will create a `checkly.config.ts` file if it doesn't exist, and will add the new check. Afterwards, you can tweak the monitoring configuration for your check. - -For example: - -```bash -> npx checkly pw-test --create-check -- --project=chromium -⚠ No Checkly config file found - -ℹ Creating a default checkly config file. - -Creating Checkly check from Playwright test... ✅ -``` - -Review the resulting check configuration in your `checkly.config.ts` file and make sure to tweak locations and schedule as needed. - -```typescript -import { defineConfig } from 'checkly' - -const config = defineConfig({ - logicalId: 'my-repo-name', - projectName: 'my-repo-name', - checks: { - playwrightConfigPath: './playwright.config.ts', - playwrightChecks: [ - { - logicalId: 'playwright-check-project-chromium', // tweak ID - name: 'Playwright Test: --project=chromium', // tweak name - testCommand: 'npx playwright test --project=chromium', // what we'll run as part of your check suite - locations: [ - 'eu-central-1', // add or change locations - ], - frequency: 10, // a custom per-check frequency - }, - ], - frequency: 10, // a global default frequency - locations: [ - 'us-east-1', // a global default location - ], - }, - cli: { - runLocation: 'us-east-1', // where test and pw-test will run - }, -}) - -export default config -``` - -### 5. Deploy your Playwright Check Suites - -Once you are ready to start monitoring your applications with these checks, deploy your Playwright Check Suite into global monitoring with `npx checkly deploy`. - -```bash -npx checkly deploy - -> You are about to deploy your project "playwright-check-suites" to account "Checkly E2E Prod". Do you want to continue? … yes - -Successfully deployed project "playwright-check-suite" to account "Checkly E2E Prod". -``` - -Once deployed, your checks will run on a schedule and results will appear in your [home dashboard](https://app.checklyhq.com/). - -### 6. Set up Alerts - -Configure alert channels and alert groups to get notified when checks fail. You can receive alerts via email, Slack, webhooks, and more. - -To set up alerts: - -1. Go to the Checkly dashboard. -2. Navigate to [**Alert Channels**](https://app.checklyhq.com/accounts/alerts/settings) to create a new channel. -3. Assign channels to your project or individual checks. - -Learn more in the [alerting guide](https://www.checklyhq.com/docs/alerts/). - -## Next Steps - - - -Complete CLI options and configuration reference - - - -Organize checks with groups for better management - - - -Use private packages and custom registries - - - -Run checks from your own infrastructure - - diff --git a/detect/synthetic-monitoring/playwright-checks/test-organization.mdx b/detect/synthetic-monitoring/playwright-checks/test-organization.mdx new file mode 100644 index 0000000..4ce74cc --- /dev/null +++ b/detect/synthetic-monitoring/playwright-checks/test-organization.mdx @@ -0,0 +1,434 @@ +--- +title: Organize your tests and monitors +sidebarTitle: Test organization +tags: ['synthetic-monitoring', 'playwright-checks'] +--- + +import PlaywrightCheckSuiteBetaNote from '/snippets/playwright-check-suite-beta-note.mdx' + + + +Playwright Check Suites enable you to reuse your existing Playwright end-to-end tests for global synthetic monitoring. + + + Playwright Check Suites should be a subset of the entire Playwright end-to-end test suite. + + +Run your entire Playwright end-to-end test suite, pick specific tests or group multiple tests together to run them as global synthetic monitoring and get alerted when your Playwright-based monitors fail. + +## How to include Playwright tests in your Playwright Check Suite + +The quickest way to reuse your existing Playwright end-to-end tests as Playwright Check Suites is to specify your Playwright config path and a single Playwright Check Suite in your `checkly.config.ts`. + +```typescript highlight={3-10} +export default defineConfig({ + checks: { + playwrightConfigPath: "./playwright.config.ts", + playwrightChecks: [ + // Playwright Check Suite without + // additional configuration or test selection + { + name: "Multiple Browser Suite", + logicalId: "browser-compat-e2e-suite", + }, + ], + }, +}) +``` + +Each Playwright Check Suite requires a `name` and `logicalId`. + +Without providing additional Playwright configuration (`pwProjects` or `pwTags`), the Playwright Check Suite will run all tests defined in the `playwright.config.ts`. It will include the tests that would also be run by `npx playwright test`. + +Without providing additional Checkly configuration (`frequency` or `locations`), the Playwright Check Suite will run **every 10 minutes** in **the three default locations** (North Carolina, Tokyo, London). + + +While it's possible to run **all** your Playwright tests as long as your suite runs in under 15 minutes, we recommend to group your tests into multiple Playwright Check Suites with different monitoring configuration. + +This approach leads to faster Mean Time to Detect (MTTD), overall transparency and more granular monitoring information. + + +## How to Organize your tests in Playwright Check Suites + +Use the `pwProjects` and `pwTags` properties to group and organize your Playwright Check Suites. + +### Group your Tests using Playwright Projects (recommended) + +Select existing Playwright tests and run them in a Playwright Check Suite by relying on [Playwright projects](https://playwright.dev/docs/test-projects). + +Use the `pwProjects` option to choose Playwright projects defined in the `playwright.config.ts` by name. + + +```typescript checkly.config.ts highlight={10} +export default defineConfig({ + checks: { + playwrightConfigPath: "./playwright.config.ts", + playwrightChecks: [ + { + name: "Multiple Browser Suite", + logicalId: "browser-compat-e2e-suite", + // Specify which projects should be + // included in the Playwright Check Suite + pwProjects: ["chromium", "firefox"], + frequency: Frequency.EVERY_10M, + }, + ], + }, +}) +``` + +```typescript playwright.config.ts +export default defineConfig({ + projects: [ + { + name: "chromium", + testMatch: /.*\/example-1\/.*\.spec\.ts/, + use: { + ...devices["Desktop Chrome"], + }, + }, + { + name: "firefox", + testMatch: /.*\/example-1\/.*\.spec\.ts/, + use: { + ...devices["Desktop Firefox"], + }, + }, + ], +}) +``` + + + +Playwright projects are most commonly used to configure different browser settings, but they can be used to configure different environments, authentication states, or any other Playwright configuration. + +Using `pwProjects` creates a custom `testCommand` that includes the exact same `npx playwright test --project` configuration. + +[Find more Playwright project examples below](#recommendations-and-examples). + + +### Group your Tests using Playwright tags + +Select existing Playwright tests and run them in a Playwright Check Suite by relying on [Playwright test annotations and tags](https://playwright.dev/docs/test-annotations#tag-tests). + + +```typescript checkly.config.ts highlight={9} +export default defineConfig({ + checks: { + playwrightChecks: [ + { + name: "Tagged Checkly Tests", + logicalId: "tagged-tests", + // Specify which tagged tests should be + // included in the Playwright Check Suite + pwTags: ["@checkly"], + frequency: Frequency.EVERY_1H, + }, + ], + }, +}) +``` + +```typescript example.spec.ts highlight={6} +import { expect, test } from "@playwright/test" + +test( + "Visit Checkly home page", + // Annotate a test to reuse is for synthetic monitoring + { tag: "@checkly" }, + async ({ page }) => { + await page.goto("/") + + // More test code ... + } +) +``` + + + +Playwright Check Suites let you filter existing tests using `pwTags`. However, we recommend to always start with a separated Playwright project and reuse it via `pwProjects` in your `checkly.config.ts`. + +This approach improves the maintainability and separates the Playwright test configuration (`playwright.config.ts`) from the Checkly monitoring configuration (`checkly.config.ts`). + +Using `pwTags` creates a custom `testCommand` that includes the exact same `npx playwright test --grep @tag` configuration for your check suite to run. + + +## Recommendations and Examples + +Synthetic monitoring with Playwright Check Suites is most effective when you organize your Playwright tests to match your monitoring needs. The best setup depends on your application and how quickly you want to receive alerts. + + +[The following examples are also available on GitHub](https://github.com/checkly/playwright-check-suite-examples/) if you want to see them in action. + + +### Group different environments + +If you want to use your Playwright tests to monitor different environments (e.g., `staging, production, ...` or `/de, /fr, ...`, ), create Playwright projects for each environment target. + + + ![Playwright Check Suites grouped by environment](/images/pwn-environment-grouping.png) + + +Specify a different `baseURL` options for each project. + +```typescript playwright.config.ts highlight={7,14} +export default defineConfig({ + projects: [ + { + name: "environment-staging", + use: { + ...devices["Desktop Chrome"], + baseURL: "https://staging.checklyhq.com" + }, + }, + { + name: "environment-production", + use: { + ...devices["Desktop Chrome"], + baseURL: "https://checklyhq.com", + }, + }, + ], +}) +``` + + +`baseURL` is one example of using advanced Playwright configuration. + +The Playwright test runner can always be configured at a global, project, or test level. If needed, set up your project: + +- to increase timeouts for a slow environment (e.g. `timeout` or `expect.timeout`) +- to run more retries for an unstable environment (e.g. `retries`) +- to use different authentication for each environment (e.g. `storageState`) + + +And configure different monitoring configuration for each Playwright project in your Playwright Check Suite. + +```typescript checkly.config.ts highlight={8-12, 17-21} +export default defineConfig({ + checks: { + playwrightConfigPath: "./playwright.config.ts", + playwrightChecks: [ + { + name: "Staging Environment", + logicalId: "environment-staging", + // Pick the Playwright project for the staging environment + pwProjects: ["environment-staging"], + // Run this Playwright Check Suite in one location every hour + frequency: Frequency.EVERY_1H, + locations: ["us-west-1", "eu-west-2", "af-south-1"], + }, + { + name: "Production Environment", + logicalId: "environment-production", + // Pick the Playwright project for the production environment + pwProjects: ["environment-production"], + // Run this Playwright check suite in three locations every ten minutes + frequency: Frequency.EVERY_10M, + locations: ["us-west-1", "eu-west-2", "af-south-1"], + }, + ], + }, +}) +``` + +### Group specific application areas + +If you want to use your Playwright tests to monitor different application areas (e.g. customer functionality, search, etc.), create [Playwright projects](https://playwright.dev/docs/test-projects) and select files via [Playwright annotations and tags](https://playwright.dev/docs/test-annotations#tag-tests). + + + ![Playwright Check Suites monitoring different application areas.](/images/pwn-use-case-grouping.png) + + +Select and group tests via Playwright projects. + +```typescript playwright.config.ts highlight={6,11} +export default defineConfig({ + projects: [ + { + name: "user-sign-up", + use: { ...devices["Desktop Chrome"] }, + grep: /@signup/, + }, + { + name: "search", + use: { ...devices["Desktop Chrome"] }, + grep: /@search/, + }, + ], +}) +``` + +And configure different monitoring configuration for each Playwright project in your Playwright Check Suite. + +```typescript checkly.config.ts highlight={8-12, 17-21} +export default defineConfig({ + checks: { + playwrightConfigPath: "./playwright.config.ts", + playwrightChecks: [ + { + name: "User Sign-up Suite", + logicalId: "user-sign-up", + // Pick the Playwright project covering user sign ups + pwProjects: ["user-sign-up"], + // Run this Playwright Check Suite in one location every hour + frequency: Frequency.EVERY_1H, + locations: ["us-west-1"], + }, + { + name: "Search Suite", + logicalId: "search", + // Pick the Playwright project covering search functionality + pwProjects: ["search"], + // Run this Playwright check suite in three locations every ten minutes + frequency: Frequency.EVERY_10M, + locations: ["us-west-1", "eu-west-2", "af-south-1"], + }, + ], + }, +}) +``` + +### Group tests depending on urgency or execution time + +If you want to use your Playwright tests to monitor both essential user flows, like login at a high frequency with critical alerts, and less critical ones, like profile updates at a lower frequency, create [Playwright projects](https://playwright.dev/docs/test-projects) and select tests via [Playwright annotations and tags](https://playwright.dev/docs/test-annotations#tag-tests). + + + ![Two Playwright Check Suites grouped by urgency](/images/pwn-urgency-grouping.png) + + +Select and group tests via Playwright projects. + +```typescript playwright.config.ts highlight={6,11} +export default defineConfig({ + projects: [ + { + name: "critical", + use: { ...devices["Desktop Chrome"] }, + grep: /@critical/, + }, + { + name: "important", + use: { ...devices["Desktop Chrome"] }, + grep: /@important/, + }, + ], +}) +``` + +And configure different monitoring configuration for each Playwright project in your Playwright Check Suite. + +```typescript checkly.config.ts highlight={8-14, 19-25} +export default defineConfig({ + checks: { + playwrightConfigPath: "./playwright.config.ts", + playwrightChecks: [ + { + name: "Critical Application Flows", + logicalId: "critical", + // Pick the `critical` project + pwProjects: ["critical"], + // Run this Playwright Check Suite in three locations every 5 minutes + frequency: Frequency.EVERY_5M, + locations: ["us-west-1", "eu-west-2", "af-south-1"], + // Assign critical alert channels + alertChannels: [criticalPagerDuty, criticalSlack], + }, + { + name: "Important Application Flows", + logicalId: "important", + // Pick the `important` project + pwProjects: ["important"], + // Run this Playwright check suite in two locations every thirty minutes + frequency: Frequency.EVERY_1H, + locations: ["us-west-1", "eu-west-2"], + // Assign important alert channels + alertChannels: [importantPagerDuty, importantSlack], + }, + ], + }, +}) +``` + + +Critical Playwright Check Suites running on high intervals should only include fast test cases to guarantee a short Mean Time to Detect (MTTD). + +**If a Check Suite run exceeds the specified interval frequency, subsequent runs will be skipped while it is running.** + + +### Group tests to reuse authentication states + +If your existing Playwright tests require authentication and a login step, use [Playwright project dependencies and storage state](https://playwright.dev/docs/test-global-setup-teardown#option-1-project-dependencies) to log in once and reuse the browser session information. + +Create a Playwright test that performs your login actions and calls [`context().storageState()`](https://playwright.dev/docs/api/class-browsercontext#browser-context-storage-state). + +```typescript login.setup.ts +const AUTH_FILE = ".auth/user.json" + +setup("Log into Checkly", async ({ page }) => { + await page.goto("/") + + // Perform your login actions + // ... + + // Use storage state to write the browser state to disk + await page.context().storageState({ path: AUTH_FILE }) +}) +``` + +Configure two new Playwright projects. The first one performs the login actions to persist the browser state, while the other one imports the browser state to avoid the login steps. + +```typescript playwright.config.ts highlight={15, 18} +export default defineConfig({ + projects: [ + { + name: "login-setup", + use: { + ...devices["Desktop Chrome"], + baseURL: "https://checklyhq.com" + }, + }, + { + name: "logged-in-tests", + use: { + ...devices["Desktop Chrome"], + // 2. Reuse the written browser state to avoid login steps + storageState: path.resolve(__dirname, AUTH_FILE), + }, + // 1. Set the project doing the login as a dependency + dependencies: ["login-setup"], + }, + ], +}) +``` + +This Playwright setup will always run the `login-setup` project before running `logged-in-tests` so that the authentication will be available and the browser state can be reused. + +Reuse the `logged-in-tests` project in your Checkly configuration. + +```typescript checkly.config.ts highlight={9} +export default defineConfig({ + checks: { + playwrightChecks: [ + { + name: "Logged-in tests", + logicalId: "logged-in-tests", + // Run the `logged-in-tests` project which will automatically run + // `login-setup` to write the authentication file to disk + pwProjects: ["logged-in-tests"], + frequency: Frequency.EVERY_1H, + }, + ], + }, +}) +``` + +Project dependencies and storage state work the same way as your standard Playwright project. + + +Check this video to learn more about [Playwright `storageState` and how to configure Playwright project dependencies](https://www.youtube.com/watch?v=nSHPCLUwwVk). + diff --git a/docs.json b/docs.json index f34ccbe..23e727d 100644 --- a/docs.json +++ b/docs.json @@ -224,6 +224,7 @@ "pages": [ "detect/synthetic-monitoring/playwright-checks/overview", "detect/synthetic-monitoring/playwright-checks/configuration", + "detect/synthetic-monitoring/playwright-checks/test-organization", "detect/synthetic-monitoring/playwright-checks/add-to-group", "detect/synthetic-monitoring/playwright-checks/custom-dependencies" ] diff --git a/images/playwright-tests-sub-set.jpg b/images/playwright-tests-sub-set.jpg new file mode 100644 index 0000000..d549b81 Binary files /dev/null and b/images/playwright-tests-sub-set.jpg differ diff --git a/images/pwn-environment-grouping.png b/images/pwn-environment-grouping.png new file mode 100644 index 0000000..4e4aeaa Binary files /dev/null and b/images/pwn-environment-grouping.png differ diff --git a/images/pwn-test-result.png b/images/pwn-test-result.png new file mode 100644 index 0000000..13065a5 Binary files /dev/null and b/images/pwn-test-result.png differ diff --git a/images/pwn-urgency-grouping.png b/images/pwn-urgency-grouping.png new file mode 100644 index 0000000..2760689 Binary files /dev/null and b/images/pwn-urgency-grouping.png differ diff --git a/images/pwn-use-case-grouping.png b/images/pwn-use-case-grouping.png new file mode 100644 index 0000000..3ad570b Binary files /dev/null and b/images/pwn-use-case-grouping.png differ