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/docker.md

View on GitHub
# Container-Based Testing

## Table of Contents

1. [Patterns](#patterns)
2. [Decision Guide](#decision-guide)
3. [Anti-Patterns](#anti-patterns)
4. [Troubleshooting](#troubleshooting)

> **When to use**: Running tests in containers for reproducible environments, CI pipelines, or consistent browser versions across team machines.

## Patterns

### Official Image Usage

Run tests without building a custom image:

```bash
docker run --rm \
  -v $(pwd):/app \
  -w /app \
  -e CI=true \
  -e BASE_URL=http://host.docker.internal:3000 \
  mcr.microsoft.com/playwright:v1.48.0-noble \
  bash -c "npm ci && npx playwright test"
```

Extract reports with bind mounts:

```bash
docker run --rm \
  -v $(pwd):/app \
  -v $(pwd)/playwright-report:/app/playwright-report \
  -v $(pwd)/test-results:/app/test-results \
  -w /app \
  mcr.microsoft.com/playwright:v1.48.0-noble \
  bash -c "npm ci && npx playwright test"
```

### Custom Dockerfile

Build a custom image when you need additional dependencies or pre-installed packages:

```dockerfile
FROM mcr.microsoft.com/playwright:v1.48.0-noble

WORKDIR /app

COPY package.json package-lock.json ./
RUN npm ci

COPY . .

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

Chromium-only slim image:

```dockerfile
FROM node:latest-slim

RUN npx playwright install --with-deps chromium

WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .

CMD ["npx", "playwright", "test", "--project=chromium"]
```

### Docker Compose Stack

Full application stack with database, cache, and test runner:

```yaml
services:
    app:
        build: .
        ports:
            - '3000:3000'
        environment:
            - NODE_ENV=test
            - DATABASE_URL=postgresql://postgres:postgres@db:5432/test
        depends_on:
            db:
                condition: service_healthy

    db:
        image: postgres:latest-alpine
        environment:
            POSTGRES_USER: postgres
            POSTGRES_PASSWORD: postgres
            POSTGRES_DB: test
        healthcheck:
            test: ['CMD-SHELL', 'pg_isready -U postgres']
            interval: 5s
            timeout: 5s
            retries: 5
        tmpfs:
            - /var/lib/postgresql/data

    e2e:
        image: mcr.microsoft.com/playwright:v1.48.0-noble
        working_dir: /app
        volumes:
            - .:/app
            - /app/node_modules
        environment:
            - CI=true
            - BASE_URL=http://app:3000
        depends_on:
            - app
        command: bash -c "npm ci && npx playwright test"
        profiles:
            - test
```

Run commands:

```bash
docker compose --profile test up --abort-on-container-exit --exit-code-from e2e

docker compose --profile test down -v
```

### CI Container Jobs

**GitHub Actions:**

```yaml
jobs:
    test:
        runs-on: ubuntu-latest
        container:
            image: mcr.microsoft.com/playwright:v1.48.0-noble
        steps:
            - uses: actions/checkout@v4
            - run: npm ci
            - run: npx playwright test
              env:
                  HOME: /root
```

**GitLab CI:**

```yaml
test:
    image: mcr.microsoft.com/playwright:v1.48.0-noble
    script:
        - npm ci
        - npx playwright test
```

**Jenkins:**

```groovy
pipeline {
    agent {
        docker {
            image 'mcr.microsoft.com/playwright:v1.48.0-noble'
            args '-u root'
        }
    }
    stages {
        stage('Test') {
            steps {
                sh 'npm ci'
                sh 'npx playwright test'
            }
        }
    }
}
```

### Dev Container Setup

VS Code Dev Container or GitHub Codespaces configuration:

```json
{
	"name": "Playwright Dev",
	"image": "mcr.microsoft.com/playwright:v1.48.0-noble",
	"features": {
		"ghcr.io/devcontainers/features/node:latest": {
			"version": "20"
		}
	},
	"postCreateCommand": "npm ci",
	"customizations": {
		"vscode": {
			"extensions": ["ms-playwright.playwright"]
		}
	},
	"forwardPorts": [3000, 9323],
	"remoteUser": "root"
}
```

## Decision Guide

| Scenario                          | Approach                                       |
| --------------------------------- | ---------------------------------------------- |
| Simple CI pipeline                | Official image as CI container                 |
| Tests need database + cache       | Docker Compose with app, db, e2e services      |
| Team needs identical environments | Dev Container or custom Dockerfile             |
| Only testing Chromium             | Slim image with `install --with-deps chromium` |
| Cross-browser testing             | Official image (all browsers pre-installed)    |
| Local development                 | Run directly on host for faster iteration      |

## Anti-Patterns

| Anti-Pattern                                     | Problem                            | Solution                                                        |
| ------------------------------------------------ | ---------------------------------- | --------------------------------------------------------------- |
| Installing browsers at runtime                   | Wastes 60-90 seconds per run       | Use official image or bake browsers into custom image           |
| Running as non-root without sandbox config       | Chromium sandbox permission errors | Run as root or disable sandbox                                  |
| Bind-mounting `node_modules` from host           | Platform-specific binary crashes   | Use anonymous volume: `-v /app/node_modules`                    |
| No health checks on dependent services           | Tests start before database ready  | Add `healthcheck` with `depends_on: condition: service_healthy` |
| Building application inside Playwright container | Large image, slow builds           | Separate app and e2e containers                                 |

## Troubleshooting

### "browserType.launch: Executable doesn't exist"

Playwright version mismatch with Docker image. Ensure `@playwright/test` version matches image tag:

```bash
npm ls @playwright/test
docker pull mcr.microsoft.com/playwright:v<matching-version>-noble
```

### "net::ERR_CONNECTION_REFUSED" in docker-compose

Tests trying to reach `localhost` instead of service name. Configure `baseURL`:

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

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

```yaml
e2e:
    environment:
        - BASE_URL=http://app:3000
```

### Permission denied on mounted volumes

Match user IDs or run as root:

```bash
docker run --rm -u $(id -u):$(id -g) \
  -v $(pwd):/app -w /app \
  mcr.microsoft.com/playwright:v1.48.0-noble \
  npx playwright test
```

### Slow container tests on macOS/Windows

Docker Desktop I/O overhead. Copy files instead of mounting:

```dockerfile
FROM mcr.microsoft.com/playwright:v1.48.0-noble
WORKDIR /app
COPY . .
RUN npm ci
CMD ["npx", "playwright", "test"]
```

Or use delegated mount:

```bash
docker run --rm \
  -v $(pwd):/app:delegated \
  -w /app \
  mcr.microsoft.com/playwright:v1.48.0-noble \
  bash -c "npm ci && npx playwright test"
```
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: 471kUpdated 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: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated 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