Skip to content

testdino-hq/playwright-skill / ci

playwright-ci

Verified

Production-ready CI/CD configurations for Playwright — GitHub Actions, GitLab CI, CircleCI, Azure DevOps, Jenkins, Docker, parallel sharding, reporting, code coverage, and global setup/teardown.

FileKindSize
SKILL.mdskill md2.1 KB
ci-github-actions.mdmarkdown18.0 KB
ci-gitlab.mdmarkdown10.8 KB
ci-other.mdmarkdown15.1 KB
docker-and-containers.mdmarkdown14.3 KB
global-setup-teardown.mdmarkdown17.7 KB
parallel-and-sharding.mdmarkdown16.1 KB
projects-and-dependencies.mdmarkdown19.1 KB
reporting-and-artifacts.mdmarkdown20.1 KB
test-coverage.mdmarkdown13.8 KB

docker-and-containers.md

View on GitHub
# Docker and Containers

> **When to use**: Running Playwright tests in containers for reproducible environments, CI pipelines, or local development with consistent browser versions. Essential when your team needs identical test environments across machines.

## Quick Reference

```bash
# Official Playwright Docker images
docker pull mcr.microsoft.com/playwright:v1.64.0-noble     # Ubuntu 24.04, all browsers
docker pull mcr.microsoft.com/playwright:v1.64.0-jammy      # Ubuntu 22.04, all browsers
docker pull mcr.microsoft.com/playwright:v1.64.0-resolute   # Ubuntu 26.04, all browsers

# Run tests in container
docker run --rm --init --ipc=host -v $(pwd):/app -w /app mcr.microsoft.com/playwright:v1.64.0-noble \
  npx playwright test

# Check your Playwright version (must match image tag)
npx playwright --version
```

## Patterns

### Pattern 1: Running Tests in the Official Image

**Use when**: Quick, reproducible test runs without building a custom image.
**Avoid when**: You need application services (database, API) running alongside -- use docker-compose instead.

```bash
# Run all tests
docker run --rm --init --ipc=host \
  -v $(pwd):/app \
  -w /app \
  mcr.microsoft.com/playwright:v1.64.0-noble \
  bash -c "npm ci && npx playwright test"

# Run with environment variables
docker run --rm --init --ipc=host \
  -v $(pwd):/app \
  -w /app \
  -e CI=true \
  -e BASE_URL=http://host.docker.internal:3000 \
  mcr.microsoft.com/playwright:v1.64.0-noble \
  bash -c "npm ci && npx playwright test"

# Run and extract report
docker run --rm --init --ipc=host \
  -v $(pwd):/app \
  -w /app \
  -v $(pwd)/playwright-report:/app/playwright-report \
  mcr.microsoft.com/playwright:v1.64.0-noble \
  bash -c "npm ci && npx playwright test"
```

### Pattern 2: Custom Dockerfile

**Use when**: You need additional system dependencies, pre-installed npm packages, or a smaller image with only certain browsers.
**Avoid when**: The official image works as-is.

```dockerfile
# Dockerfile.playwright
FROM mcr.microsoft.com/playwright:v1.64.0-noble

WORKDIR /app

# Copy package files first for better layer caching
COPY package.json package-lock.json ./
RUN npm ci

# Copy the rest of the project
COPY . .

# Default command
CMD ["npx", "playwright", "test"]
```

```bash
# Build and run
docker build -f Dockerfile.playwright -t my-e2e-tests .
docker run --rm --init --ipc=host my-e2e-tests

# Run with specific options
docker run --rm --init --ipc=host my-e2e-tests npx playwright test --project=chromium

# Extract report
docker run --rm --init --ipc=host -v $(pwd)/reports:/app/playwright-report my-e2e-tests
```

**Slim image with only Chromium:**

```dockerfile
# Dockerfile.playwright-chromium
FROM node:24-slim

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

# Install only Chromium + deps, using the project's pinned Playwright version
RUN npx playwright install --with-deps chromium
COPY . .

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

### Pattern 3: Docker Compose with Application Stack

**Use when**: Tests need the full application stack: web server, database, cache, and Playwright running together.
**Avoid when**: Tests run against a remote environment (staging/prod) -- no local services needed.

```yaml
# docker-compose.yml
services:
  # Application under test
  app:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=test
      - DATABASE_URL=postgresql://postgres:postgres@db:5432/test
      - REDIS_URL=redis://cache:6379
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started

  # Database
  db:
    image: postgres:16-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  # RAM disk for speed

  # Cache
  cache:
    image: redis:7-alpine

  # Playwright test runner
  e2e:
    image: mcr.microsoft.com/playwright:v1.64.0-noble
    init: true
    ipc: host
    working_dir: /app
    volumes:
      - .:/app
      - /app/node_modules  # prevent host node_modules from overriding
    environment:
      - CI=true
      - BASE_URL=http://app:3000
    depends_on:
      - app
    command: bash -c "npm ci && npx playwright test"
    profiles:
      - test  # only start with: docker compose --profile test up
```

```bash
# Run the full stack with tests
docker compose --profile test up --abort-on-container-exit --exit-code-from e2e

# Run just the app (for local dev)
docker compose up app

# Run tests against already-running stack
docker compose --profile test run --rm e2e npx playwright test

# Tear down everything
docker compose --profile test down -v
```

### Pattern 4: Extracting Reports and Traces from Containers

**Use when**: You need test artifacts (HTML reports, traces, screenshots) accessible on the host after container tests complete.
**Avoid when**: CI handles artifact collection natively (GitHub Actions, GitLab artifacts).

```bash
# Method 1: Bind mount the output directories
docker run --rm --init --ipc=host \
  -v $(pwd):/app \
  -v $(pwd)/playwright-report:/app/playwright-report \
  -v $(pwd)/test-results:/app/test-results \
  -w /app \
  mcr.microsoft.com/playwright:v1.64.0-noble \
  bash -c "npm ci && npx playwright test"

# Method 2: Copy artifacts from a stopped container
docker run --name e2e-run --init --ipc=host \
  -v $(pwd):/app \
  -w /app \
  mcr.microsoft.com/playwright:v1.64.0-noble \
  bash -c "npm ci && npx playwright test" || true

docker cp e2e-run:/app/playwright-report ./playwright-report
docker cp e2e-run:/app/test-results ./test-results
docker rm e2e-run

# View the report
npx playwright show-report ./playwright-report
```

**Docker Compose for report extraction:**

```yaml
# docker-compose.yml (add to e2e service)
services:
  e2e:
    image: mcr.microsoft.com/playwright:v1.64.0-noble
    working_dir: /app
    volumes:
      - .:/app
      - ./playwright-report:/app/playwright-report
      - ./test-results:/app/test-results
    # ... rest of config
```

### Pattern 5: CI Container Strategies

**Use when**: Your CI environment benefits from containerized test execution.

**GitHub Actions -- container job:**

```yaml
# .github/workflows/playwright.yml
jobs:
  test:
    runs-on: ubuntu-latest
    container:
      image: mcr.microsoft.com/playwright:v1.64.0-noble
      options: --ipc=host
    steps:
      - uses: actions/checkout@v7
      - run: npm ci
      - run: npx playwright test
        env:
          HOME: /root
```

**GitLab CI -- image directive:**

```yaml
# .gitlab-ci.yml
test:
  image: mcr.microsoft.com/playwright:v1.64.0-noble
  script:
    - npm ci
    - npx playwright test
```

**Jenkins -- Docker agent:**

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

### Pattern 6: Development Container (devcontainer)

**Use when**: Your team uses VS Code Dev Containers or GitHub Codespaces and needs Playwright available in the development environment.
**Avoid when**: Everyone installs Playwright locally and version differences don't cause issues.

```json
// .devcontainer/devcontainer.json
{
  "name": "Playwright Dev",
  "image": "mcr.microsoft.com/playwright:v1.64.0-noble",
  "postCreateCommand": "npm ci",
  "customizations": {
    "vscode": {
      "extensions": [
        "ms-playwright.playwright"
      ]
    }
  },
  "forwardPorts": [3000, 9323],
  "remoteUser": "root"
}
```

## Decision Guide

| Scenario | Approach | Why |
|---|---|---|
| Simple CI pipeline | Official Playwright image as CI image | Browsers pre-installed; zero browser install time |
| Tests need database + cache | Docker Compose with app, db, cache, e2e services | Full stack in isolated containers |
| Team needs identical environments | Dev Container or custom Dockerfile | Eliminate "works on my machine" |
| Only testing Chromium | Slim image: `node:24-slim` + `install --with-deps chromium` | Smaller image, faster pulls |
| Cross-browser testing | Official Playwright image (has all browsers) | All three engines pre-installed |
| Local development | Run directly on host, not in container | Faster iteration, easier debugging |
| CI with artifact extraction | Bind mount report/results dirs or use CI artifact upload | Reports accessible after container exits |

| Image | Size | Browsers | Base OS |
|---|---|---|---|
| `mcr.microsoft.com/playwright:v1.64.0-noble` | ~2 GB | Chromium, Firefox, WebKit | Ubuntu 24.04 |
| `mcr.microsoft.com/playwright:v1.64.0-jammy` | ~2 GB | Chromium, Firefox, WebKit | Ubuntu 22.04 |
| `mcr.microsoft.com/playwright:v1.64.0-resolute` | ~2 GB | Chromium, Firefox, WebKit | Ubuntu 26.04 |
| Custom slim (Chromium only) | ~800 MB | Chromium | Depends on base |

## Security: Pinning Docker Images to Digest

Version tags like `mcr.microsoft.com/playwright:v1.64.0-noble` are mutable — the tag can be updated to point to a different image layer without changing the tag name. This is a supply-chain risk (W012): you may pull different code than you tested against.

**Best practice**: pin images to their immutable content digest.

```bash
# Get the digest for a specific tag
docker pull mcr.microsoft.com/playwright:v1.64.0-noble
docker inspect --format='{{index .RepoDigests 0}}' mcr.microsoft.com/playwright:v1.64.0-noble
# e.g. mcr.microsoft.com/playwright@sha256:abc123...

# Or use skopeo (no pull required):
skopeo inspect docker://mcr.microsoft.com/playwright:v1.64.0-noble | jq '.Digest'
```

**Use digest-pinned references in CI:**

```yaml
# Instead of:
image: mcr.microsoft.com/playwright:v1.64.0-noble

# Pin to digest (example — verify the actual digest for your version):
image: mcr.microsoft.com/playwright:v1.64.0-noble@sha256:<digest-from-inspect>
```

```dockerfile
# Dockerfile
FROM mcr.microsoft.com/playwright:v1.64.0-noble@sha256:<digest-from-inspect>
```

> Digest values are specific to the exact image build. Verify the digest from the official Microsoft Artifact Registry (mcr.microsoft.com) before pinning.

## Anti-Patterns

| Anti-Pattern | Problem | Do This Instead |
|---|---|---|
| Image tag doesn't match `@playwright/test` version | Browser binaries incompatible with Playwright library | Always match: `v1.64.0` image for `@playwright/test@1.64.0` |
| Using `latest` tag | Unpredictable; image updates can break tests | Pin to exact version: `v1.64.0-noble` |
| Using only a version tag without digest | Tag is mutable; supply-chain risk if image is silently updated | Pin to digest: `playwright:v1.64.0-noble@sha256:<digest>` |
| Installing browsers inside container at runtime | Wastes 60-90 seconds on every run | Use official image (browsers pre-installed) or build custom image with browsers baked in |
| Running as non-root without configuring sandbox | Chromium sandbox fails with permission errors | Run as root (`-u root`) or disable sandbox (`--no-sandbox` in launch args) |
| `docker run` without `--ipc=host` | Chromium can run out of shared memory and crash | Add `--ipc=host` (and `--init` to avoid zombie processes), per the official Docker guide |
| Bind-mounting `node_modules` from host | Platform-specific binaries (macOS vs Linux) cause crashes | Use anonymous volume: `-v /app/node_modules` |
| No health checks on dependent services | Tests start before database is ready | Add `healthcheck` to db service; use `depends_on: condition: service_healthy` |
| Building application inside the Playwright container | Large image, slow builds, wrong base for your app | Separate app and e2e containers in docker-compose |

## Troubleshooting

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

**Cause**: Playwright version in `package.json` doesn't match the Docker image version.

**Fix**: Ensure exact version match:

```bash
# Check your version
npm ls @playwright/test
# @playwright/test@1.64.0

# Use matching image
docker pull mcr.microsoft.com/playwright:v1.64.0-noble
```

### Tests fail with "net::ERR_CONNECTION_REFUSED" in docker-compose

**Cause**: Tests are trying to reach `localhost:3000` but the app is in a different container.

**Fix**: Use the service name as hostname and configure `baseURL`:

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

export default defineConfig({
  use: {
    baseURL: process.env.BASE_URL || 'http://localhost:3000',
  },
  // Disable webServer in Docker -- app is managed by docker-compose
  ...(process.env.CI ? {} : {
    webServer: {
      command: 'npm run dev',
      url: 'http://localhost:3000',
      reuseExistingServer: true,
    },
  }),
});
```

```yaml
# docker-compose.yml
e2e:
  environment:
    - BASE_URL=http://app:3000  # "app" is the service name
```

### Permission denied on mounted volumes

**Cause**: Container runs as root but host files are owned by your user, or vice versa.

**Fix**: Match user IDs or run as root:

```bash
# Run as your host user
docker run --rm --init --ipc=host -u $(id -u):$(id -g) \
  -v $(pwd):/app -w /app \
  mcr.microsoft.com/playwright:v1.64.0-noble \
  npx playwright test

# Or run as root (simpler, fine for CI)
docker run --rm --init --ipc=host \
  -v $(pwd):/app -w /app \
  mcr.microsoft.com/playwright:v1.64.0-noble \
  npx playwright test
```

### Container tests are much slower than local

**Cause**: Docker Desktop on macOS/Windows has I/O overhead for bind-mounted volumes.

**Fix**: Copy files into the container instead of mounting:

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

Or use delegated mount on macOS:

```bash
docker run --rm --init --ipc=host \
  -v $(pwd):/app:delegated \
  -w /app \
  mcr.microsoft.com/playwright:v1.64.0-noble \
  bash -c "npm ci && npx playwright test"
```

## Related

- [ci/ci-github-actions.md](ci-github-actions.md) -- container jobs in GitHub Actions
- [ci/ci-gitlab.md](ci-gitlab.md) -- Docker images in GitLab CI
- [ci/ci-other.md](ci-other.md) -- Docker agents in Jenkins, CircleCI
- [ci/parallel-and-sharding.md](parallel-and-sharding.md) -- sharding within containers
- [ci/reporting-and-artifacts.md](reporting-and-artifacts.md) -- extracting reports from containers
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall