PWCS review

detect/synthetic-monitoring/playwright-checks/add-to-group.mdx

@@ -4,45 +4,45 @@ description: 'Organize your Playwright Check Suites with groups for better manag
 sidebarTitle: 'Add to Group'
 ---
 
-You can define a new group, or associate a Playwright Check Suite to an existing group.
+<Accordion title="Prerequisites">
+You need:
 
-## Steps
+- A repository using the Checkly CLI
+- At least one Playwright Check Suite defined in your repository.
 
-### 1. Create a group for your checks
+</Accordion>
 
-Create a new file to create and configure your new group.
+Groups organize checks and share configuration across them. See the [Groups overview](/platform/groups) for details on benefits and how groups work.
+
+## 1. Create a group
+
+Create a new file to define your group.
 
 ```typescript website-group.check.ts
-import { CheckGroup } from 'checkly/constructs'
+import { CheckGroupV2 } from 'checkly/constructs'
 
-export const myGroup = new CheckGroup('production-group', {
+export const myGroup = new CheckGroupV2('production-group', {
   name: 'Production group',
-  logicalID: 'production-group',
   activated: true,
   muted: false,
   locations: ['us-east-1', 'eu-west-1'],
-  tags: ['mac', 'group'],
+  tags: ['production', 'playwright'],
   environmentVariables: [],
-  apiCheckDefaults: {},
-  concurrency: 100,
-  runParallel: true,
-  retryStrategy: RetryStrategyBuilder.linearStrategy({
-    baseBackoffSeconds: 30,
-    maxRetries: 2,
-    sameRegion: false
-  }),
 })
 ```
 
 <Tip>
-Learn more about [using groups](/constructs/check-group-v2) to unify checks in Checkly.
+Learn more about [using groups](/constructs/check-group-v2).
 </Tip>
 
-### 2. Associate the group to the check
+## 2. Add a Playwright Check Suite to the group
 
-When specifying your Playwright Check Suite, you can reference the new or existing group, using its name:
+Import the group and reference it in your Playwright Check Suite configuration:
+
+```typescript checkly.config.ts highlight={2,14}
+import { defineConfig } from 'checkly'
+import { myGroup } from './website-group.check'
 
-```typescript checkly.config.ts highlight={13}
 export default defineConfig({
   logicalId: 'checkly-website',
   projectName: 'checkly-website',
@@ -55,20 +55,58 @@ export default defineConfig({
         pwTags:'critical',
         frequency: 10,
         locations: ['us-east-1',],
-        groupName: 'Production group', // use the name of the group you created
+        group: myGroup,
       },
     ],
   },
 })
-
-export default config
 ```
 
-### 3. Deploy to apply the changes
+## 3. Deploy your changes
 
 ```bash
-npx checkly deploy --preview # confirm what will be deployed
-npx checkly deploy           # deploy
+npx checkly deploy --preview # preview what will be deployed
+npx checkly deploy           # deploy the new scheduled Playwright Check Suites into the group
 ```
 
-You can now see your Playwright Check Suite assigned to your group.
+Your Playwright Check Suite now appears in the group in your [Checkly Home Dashboard](https://app.checklyhq.com/).
+
+## Add multiple check suites to one group
+
+Add multiple Playwright Check Suites to the same group while keeping individual test selection and frequency settings. Reference the group in each suite:
+
+```typescript checkly.config.ts highlight={2,13,20,27}
+import { defineConfig } from 'checkly'
+import { myGroup } from './website-group.check'
+
+export default defineConfig({
+  logicalId: 'checkly-website',
+  projectName: 'checkly-website',
+  checks: {
+    playwrightConfigPath: './playwright.config.ts',
+    playwrightChecks: [
+      {
+        name: 'Critical User Flows',
+        logicalId: 'critical-flows',
+        pwTags: 'critical',
+        frequency: 5,
+        group: myGroup,
+      },
+      {
+        name: 'Authentication Tests',
+        logicalId: 'auth-tests',
+        pwTags: 'auth',
+        frequency: 10,
+        group: myGroup,
+      },
+      {
+        name: 'Checkout Flow',
+        logicalId: 'checkout-flow',
+        pwTags: 'checkout',
+        frequency: 5,
+        group: myGroup,
+      },
+    ],
+  },
+})
+```

detect/synthetic-monitoring/playwright-checks/configuration.mdx

@@ -99,57 +99,143 @@ A Playwright Check Suite inherits multiple properties from [the abstract `Check`
 - `privateLocations`
 - `alertEscalationPolicy`
 
-Check [the reference documentation](/constructs/project#param-checks-playwright-checks) for more information on these settings.
+Check out [the reference documentation](/constructs/project#param-checks-playwright-checks) for more information on these settings.
 
 <Note>
 **Checks' Retry strategy is not applicable for Playwright checks.** Playwright includes its own retry features that can be set up directly in your `playwright.config.ts/js` file with the [`retries`](https://playwright.dev/docs/test-retries) option. This allows for more detailed management of test retries within Playwright, when your check runs.
 </Note>
 
 Additionally, Playwright Check Suites provide specific configuration for your Playwright monitoring.
 
-* `installCommand:` Override the command to install dependencies, by default it'll use `npm install --dev`.
+* `installCommand:` Override the command to install dependencies. `npm install --dev` is used by default.
 
-* `testCommand:` Override the command to test, by default it uses npx playwright test with the tags, projects, and config file options your check specifies.
+* `testCommand:` Override the command to test. `npx playwright test` is used by default with the tags, projects, and config file options your check specifies.
 
-* `groupName:` The group this check belongs to.
+* `group:` The group 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
+installCommand: 'yarn install --frozen-lockfile'
+```
+
+**Install dependencies from a specific directory:**
+
+```typescript
+installCommand: 'npm install --prefix ./e2e'
+```
+
+**Enable Playwright tracing to debug failures**
+
+```typescript
+testCommand: 'npx playwright test --trace=on'
+```
+
+**Set a specific test timeout:**
+
+```typescript
+testCommand: 'npx playwright test --timeout=60000'
+```
+
+**Combine multiple test flags:**
+
+```typescript
+testCommand: 'npx playwright test --trace=retain-on-failure --max-failures=5'
+```
+
+### Example Checkly config
 
 ```typescript checkly.config.ts
+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: {
-    // 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
+        group: productionGroup,
         frequency: Frequency.EVERY_5M,
-        // Define locations to monitor from
         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
+# 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.
+
+## 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.
+
+### Test execution issues
+
+**Tests exceed 20-minute limit**
+
+If your Playwright Check Suite times out after 20 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.