Skip to content

ever-co/ever-works / .agents/skills/playwright-best-practices

playwright-best-practices

Verified

Use when writing Playwright tests, fixing flaky tests, debugging failures, implementing Page Object Model, configuring CI/CD, optimizing performance, mocking APIs, handling authentication or OAuth, testing accessibility (axe-core), file uploads/downloads, date/time mocking, WebSockets, geolocation, permissions, multi-tab/popup flows, mobile/responsive layouts, touch gestures, GraphQL, error handling, offline mode, multi-user collaboration, third-party services (payments, email verification), console error monitoring, global setup/teardown, test annotations (skip, fixme, slow), test tags (@smoke, @fast, @critical, filtering with --grep), project dependencies, security testing (XSS, CSRF, auth), performance budgets (Web Vitals, Lighthouse), iframes, component testing, canvas/WebGL, service workers/PWA, test coverage, i18n/localization, Electron apps, or browser extension testing. Covers E2E, component, API, visual, accessibility, security, Electron, and extension testing.

FileKindSize
LICENSE.mdmarkdown1.0 KB
README.mdmarkdown9.9 KB
SKILL.mdskill md25.7 KB
advanced/authentication-flows.mdmarkdown10.4 KB
advanced/authentication.mdmarkdown29.4 KB
advanced/clock-mocking.mdmarkdown9.4 KB
advanced/mobile-testing.mdmarkdown10.3 KB
advanced/multi-context.mdmarkdown8.2 KB
advanced/multi-user.mdmarkdown10.9 KB
advanced/network-advanced.mdmarkdown10.1 KB
advanced/third-party.mdmarkdown11.1 KB
architecture/pom-vs-fixtures.mdmarkdown11.4 KB
architecture/test-architecture.mdmarkdown14.3 KB
architecture/when-to-mock.mdmarkdown11.9 KB
browser-apis/browser-apis.mdmarkdown10.1 KB
browser-apis/iframes.mdmarkdown11.1 KB
browser-apis/service-workers.mdmarkdown13.1 KB
browser-apis/websockets.mdmarkdown9.9 KB
core/annotations.mdmarkdown10.4 KB
core/assertions-waiting.mdmarkdown9.1 KB
core/configuration.mdmarkdown13.7 KB
core/fixtures-hooks.mdmarkdown11.2 KB
core/global-setup.mdmarkdown12.4 KB
core/locators.mdmarkdown6.4 KB
core/page-object-model.mdmarkdown7.7 KB
core/projects-dependencies.mdmarkdown8.1 KB
core/test-data.mdmarkdown11.3 KB
core/test-suite-structure.mdmarkdown9.1 KB
core/test-tags.mdmarkdown6.7 KB
debugging/console-errors.mdmarkdown9.3 KB
debugging/debugging.mdmarkdown14.7 KB
debugging/error-testing.mdmarkdown9.2 KB
debugging/flaky-tests.mdmarkdown14.5 KB
frameworks/angular.mdmarkdown18.9 KB
frameworks/nextjs.mdmarkdown13.4 KB
frameworks/react.mdmarkdown17.5 KB
frameworks/vue.mdmarkdown17.3 KB
infrastructure-ci-cd/ci-cd.mdmarkdown10.4 KB
infrastructure-ci-cd/docker.mdmarkdown7.0 KB
infrastructure-ci-cd/github-actions.mdmarkdown15.1 KB
infrastructure-ci-cd/gitlab.mdmarkdown10.9 KB
infrastructure-ci-cd/other-providers.mdmarkdown14.2 KB
infrastructure-ci-cd/parallel-sharding.mdmarkdown11.6 KB
infrastructure-ci-cd/performance.mdmarkdown11.3 KB
infrastructure-ci-cd/reporting.mdmarkdown11.4 KB
infrastructure-ci-cd/test-coverage.mdmarkdown12.0 KB
testing-patterns/accessibility.mdmarkdown8.7 KB
testing-patterns/api-testing.mdmarkdown23.5 KB
testing-patterns/browser-extensions.mdmarkdown13.0 KB
testing-patterns/canvas-webgl.mdmarkdown12.3 KB
testing-patterns/component-testing.mdmarkdown11.0 KB
testing-patterns/drag-drop.mdmarkdown17.4 KB
testing-patterns/electron.mdmarkdown12.8 KB
testing-patterns/file-operations.mdmarkdown10.0 KB
testing-patterns/file-upload-download.mdmarkdown16.5 KB
testing-patterns/forms-validation.mdmarkdown21.3 KB
testing-patterns/graphql-testing.mdmarkdown8.6 KB
testing-patterns/i18n.mdmarkdown12.3 KB
testing-patterns/performance-testing.mdmarkdown11.5 KB
testing-patterns/security-testing.mdmarkdown11.5 KB
testing-patterns/visual-regression.mdmarkdown18.4 KB

infrastructure-ci-cd/ci-cd.md

View on GitHub
# CI/CD Integration

## Table of Contents

1. [GitHub Actions](#github-actions)
2. [Docker](#docker)
3. [Reporting](#reporting)
4. [Sharding](#sharding)
5. [Environment Management](#environment-management)
6. [Caching](#caching)

## GitHub Actions

### Basic Workflow

```yaml
# .github/workflows/playwright.yml
name: Playwright Tests

on:
    push:
        branches: [main]
    pull_request:
        branches: [main]

jobs:
    test:
        timeout-minutes: 60
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v4

            - uses: actions/setup-node@v4
              with:
                  node-version: 22
                  cache: 'npm'

            - name: Install dependencies
              run: npm ci

            - name: Install Playwright browsers
              run: npx playwright install --with-deps

            - name: Run Playwright tests
              run: npx playwright test

            - uses: actions/upload-artifact@v4
              if: ${{ !cancelled() }}
              with:
                  name: playwright-report
                  path: playwright-report/
                  retention-days: 30
```

### With Sharding

```yaml
name: Playwright Tests

on:
    push:
        branches: [main]

jobs:
    test:
        timeout-minutes: 60
        runs-on: ubuntu-latest
        strategy:
            fail-fast: false
            matrix:
                shardIndex: [1, 2, 3, 4]
                shardTotal: [4]
        steps:
            - uses: actions/checkout@v4

            - uses: actions/setup-node@v4
              with:
                  node-version: 22
                  cache: 'npm'

            - name: Install dependencies
              run: npm ci

            - name: Install Playwright browsers
              run: npx playwright install --with-deps

            - name: Run Playwright tests
              run: npx playwright test --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}

            - name: Upload blob report
              if: ${{ !cancelled() }}
              uses: actions/upload-artifact@v4
              with:
                  name: blob-report-${{ matrix.shardIndex }}
                  path: blob-report
                  retention-days: 1

    merge-reports:
        if: ${{ !cancelled() }}
        needs: [test]
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v4

            - uses: actions/setup-node@v4
              with:
                  node-version: 22
                  cache: 'npm'

            - name: Install dependencies
              run: npm ci

            - name: Download blob reports
              uses: actions/download-artifact@v4
              with:
                  path: all-blob-reports
                  pattern: blob-report-*
                  merge-multiple: true

            - name: Merge reports
              run: npx playwright merge-reports --reporter html ./all-blob-reports

            - name: Upload HTML report
              uses: actions/upload-artifact@v4
              with:
                  name: html-report
                  path: playwright-report
                  retention-days: 14
```

### With Container

```yaml
jobs:
    test:
        timeout-minutes: 60
        runs-on: ubuntu-latest
        container:
            # Use latest or more appropriate playwright version (match package.json)
            image: mcr.microsoft.com/playwright:v1.40.0-jammy
        steps:
            - uses: actions/checkout@v4

            - uses: actions/setup-node@v4
              with:
                  node-version: 22
                  cache: 'npm'

            - name: Install dependencies
              run: npm ci

            - name: Run tests
              run: npx playwright test
              env:
                  HOME: /root
```

## Docker

### Dockerfile

```dockerfile
FROM mcr.microsoft.com/playwright:v1.40.0-jammy

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .

CMD ["npx", "playwright", "test"]
```

### Docker Compose

```yaml
# docker-compose.yml
version: '3.8'

services:
    playwright:
        build: .
        volumes:
            - ./playwright-report:/app/playwright-report
            - ./test-results:/app/test-results
        environment:
            - CI=true
            - BASE_URL=http://app:3000
        depends_on:
            - app

    app:
        build: ./app
        ports:
            - '3000:3000'
```

### Run with Docker

```bash
# Build and run
docker build -t playwright-tests .
docker run --rm -v $(pwd)/playwright-report:/app/playwright-report playwright-tests

# With docker-compose
docker-compose run --rm playwright
```

## Reporting

### Configuration

```typescript
// playwright.config.ts
export default defineConfig({
	reporter: [
		// Always generate
		['html', { outputFolder: 'playwright-report' }],

		// Console output
		['list'],

		// CI-friendly
		['github'], // GitHub Actions annotations

		// JUnit for CI integration
		['junit', { outputFile: 'results.xml' }],

		// JSON for custom processing
		['json', { outputFile: 'results.json' }],

		// Blob for merging shards
		['blob', { outputDir: 'blob-report' }]
	]
});
```

### CI-Specific Reporter

```typescript
export default defineConfig({
	reporter: process.env.CI ? [['github'], ['blob'], ['html']] : [['list'], ['html']]
});
```

## Sharding

### Command Line

```bash
# Split into 4 shards, run shard 1
npx playwright test --shard=1/4

# Run shard 2
npx playwright test --shard=2/4
```

### Configuration

```typescript
// playwright.config.ts
export default defineConfig({
	// Evenly distribute tests across shards
	fullyParallel: true,

	// For blob reporter to merge later
	reporter: process.env.CI ? [['blob']] : [['html']]
});
```

### Merge Sharded Reports

```bash
# After all shards complete, merge blob reports
npx playwright merge-reports --reporter html ./all-blob-reports
```

## Environment Management

### Environment Variables

```typescript
// playwright.config.ts
import { defineConfig } from '@playwright/test';
import dotenv from 'dotenv';

// Load env file based on environment
dotenv.config({ path: `.env.${process.env.NODE_ENV || 'development'}` });

export default defineConfig({
	use: {
		baseURL: process.env.BASE_URL || 'http://localhost:3000'
	}
});
```

### Multiple Environments

```yaml
# .github/workflows/playwright.yml
jobs:
    test:
        strategy:
            matrix:
                environment: [staging, production]
        steps:
            - name: Run tests
              run: npx playwright test
              env:
                  BASE_URL: ${{ matrix.environment == 'staging' && 'https://staging.example.com' || 'https://example.com' }}
                  TEST_USER: ${{ secrets[format('TEST_USER_{0}', matrix.environment)] }}
```

### Secrets Management

```yaml
# GitHub Actions secrets
- name: Run tests
  run: npx playwright test
  env:
      TEST_EMAIL: ${{ secrets.TEST_EMAIL }}
      TEST_PASSWORD: ${{ secrets.TEST_PASSWORD }}
```

```typescript
// tests use environment variables
test('login', async ({ page }) => {
	await page.getByLabel('Email').fill(process.env.TEST_EMAIL!);
	await page.getByLabel('Password').fill(process.env.TEST_PASSWORD!);
});
```

## Caching

### Cache Playwright Browsers

```yaml
- name: Cache Playwright browsers
  uses: actions/cache@v4
  id: playwright-cache
  with:
      path: ~/.cache/ms-playwright
      key: playwright-${{ runner.os }}-${{ hashFiles('package-lock.json') }}

- name: Install Playwright browsers
  if: steps.playwright-cache.outputs.cache-hit != 'true'
  run: npx playwright install --with-deps

- name: Install system deps only
  if: steps.playwright-cache.outputs.cache-hit == 'true'
  run: npx playwright install-deps
```

### Cache Node Modules

```yaml
- uses: actions/setup-node@v4
  with:
      node-version: 22
      cache: 'npm'

- name: Install dependencies
  run: npm ci
```

## Tag-Based Test Filtering

### Run Specific Tags in CI

```yaml
# Run smoke tests on PR
- name: Run smoke tests
  run: npx playwright test --grep @smoke

# Run full regression nightly
- name: Run regression
  run: npx playwright test --grep @regression

# Exclude flaky tests
- name: Run stable tests
  run: npx playwright test --grep-invert @flaky
```

### PR vs Nightly Strategy

```yaml
# .github/workflows/pr.yml - Fast feedback
- name: Run critical tests
  run: npx playwright test --grep "@smoke|@critical"

# .github/workflows/nightly.yml - Full coverage
- name: Run all tests
  run: npx playwright test --grep-invert @flaky
```

### Tag Filtering in Config

```typescript
// playwright.config.ts
export default defineConfig({
	grep: process.env.CI ? /@smoke|@critical/ : undefined,
	grepInvert: process.env.CI ? /@flaky/ : undefined
});
```

### Project-Based Tag Filtering

```typescript
// playwright.config.ts
export default defineConfig({
	projects: [
		{
			name: 'smoke',
			grep: /@smoke/
		},
		{
			name: 'regression',
			grepInvert: /@smoke/
		}
	]
});
```

## Best Practices

| Practice                      | Benefit                   |
| ----------------------------- | ------------------------- |
| Use `npm ci`                  | Deterministic installs    |
| Run headless in CI            | Faster, no display needed |
| Set retries in CI only        | Handle flakiness          |
| Upload artifacts on failure   | Debug failures            |
| Use sharding for large suites | Faster execution          |
| Cache browsers                | Faster setup              |
| Use blob reporter for shards  | Merge reports correctly   |
| Use tags for PR vs nightly    | Fast feedback + coverage  |
| Exclude @flaky in CI          | Stable pipeline           |

## CI Configuration Reference

```typescript
// playwright.config.ts - CI optimized
export default defineConfig({
	testDir: './tests',
	fullyParallel: true,
	forbidOnly: !!process.env.CI,
	retries: process.env.CI ? 2 : 0,
	workers: process.env.CI ? 1 : undefined,
	reporter: process.env.CI ? [['github'], ['blob'], ['html']] : [['list'], ['html']],
	use: {
		baseURL: process.env.BASE_URL || 'http://localhost:3000',
		trace: 'on-first-retry',
		screenshot: 'only-on-failure',
		video: 'on-first-retry'
	}
});
```

## Related References

- **Test tags**: See [test-tags.md](../core/test-tags.md) for tagging and filtering patterns
- **Performance optimization**: See [performance.md](performance.md) for sharding and parallelization
- **Debugging CI failures**: See [debugging.md](../debugging/debugging.md) for troubleshooting
- **Test reporting**: See [debugging.md](../debugging/debugging.md) for trace viewer usage
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall