zebbern/claude-code-guide / skills/playwright/ci
playwright-ci
VerifiedProduction-ready CI/CD configurations for Playwright — GitHub Actions, GitLab CI, CircleCI, Azure DevOps, Jenkins, Docker, parallel sharding, reporting, code coverage, and global setup/teardown.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.7 KB |
| ci-github-actions.md | markdown | 17.1 KB |
| ci-gitlab.md | markdown | 12.3 KB |
| ci-other.md | markdown | 16.1 KB |
| docker-and-containers.md | markdown | 13.7 KB |
| global-setup-teardown.md | markdown | 17.8 KB |
| parallel-and-sharding.md | markdown | 15.8 KB |
| projects-and-dependencies.md | markdown | 18.8 KB |
| reporting-and-artifacts.md | markdown | 16.9 KB |
| test-coverage.md | markdown | 15.3 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.52.0-noble # Ubuntu 24.04, all browsers
docker pull mcr.microsoft.com/playwright:v1.52.0-jammy # Ubuntu 22.04, all browsers
# Run tests in container
docker run --rm -v $(pwd):/app -w /app mcr.microsoft.com/playwright:v1.52.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 \
-v $(pwd):/app \
-w /app \
mcr.microsoft.com/playwright:v1.52.0-noble \
bash -c "npm ci && npx playwright test"
# Run with environment variables
docker run --rm \
-v $(pwd):/app \
-w /app \
-e CI=true \
-e BASE_URL=http://host.docker.internal:3000 \
mcr.microsoft.com/playwright:v1.52.0-noble \
bash -c "npm ci && npx playwright test"
# Run and extract report
docker run --rm \
-v $(pwd):/app \
-w /app \
-v $(pwd)/playwright-report:/app/playwright-report \
mcr.microsoft.com/playwright:v1.52.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.52.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 my-e2e-tests
# Run with specific options
docker run --rm my-e2e-tests npx playwright test --project=chromium
# Extract report
docker run --rm -v $(pwd)/reports:/app/playwright-report my-e2e-tests
```
**Slim image with only Chromium:**
```dockerfile
# Dockerfile.playwright-chromium
FROM node:20-slim
# Install only Chromium dependencies
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"]
```
### 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.52.0-noble
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 \
-v $(pwd):/app \
-v $(pwd)/playwright-report:/app/playwright-report \
-v $(pwd)/test-results:/app/test-results \
-w /app \
mcr.microsoft.com/playwright:v1.52.0-noble \
bash -c "npm ci && npx playwright test"
# Method 2: Copy artifacts from a stopped container
docker run --name e2e-run \
-v $(pwd):/app \
-w /app \
mcr.microsoft.com/playwright:v1.52.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.52.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.52.0-noble
steps:
- uses: actions/checkout@v4
- 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.52.0-noble
script:
- npm ci
- npx playwright test
```
**Jenkins -- Docker agent:**
```groovy
// Jenkinsfile
pipeline {
agent {
docker {
image 'mcr.microsoft.com/playwright:v1.52.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.52.0-noble",
"features": {
"ghcr.io/devcontainers/features/node:1": {
"version": "20"
}
},
"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:20-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.52.0-noble` | ~2 GB | Chromium, Firefox, WebKit | Ubuntu 24.04 |
| `mcr.microsoft.com/playwright:v1.52.0-jammy` | ~2 GB | Chromium, Firefox, WebKit | Ubuntu 22.04 |
| Custom slim (Chromium only) | ~800 MB | Chromium | Depends on base |
## 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.52.0` image for `@playwright/test@1.52.0` |
| Using `latest` tag | Unpredictable; image updates can break tests | Pin to exact version: `v1.52.0-noble` |
| 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) |
| 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.52.0
# Use matching image
docker pull mcr.microsoft.com/playwright:v1.52.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 -u $(id -u):$(id -g) \
-v $(pwd):/app -w /app \
mcr.microsoft.com/playwright:v1.52.0-noble \
npx playwright test
# Or run as root (simpler, fine for CI)
docker run --rm \
-v $(pwd):/app -w /app \
mcr.microsoft.com/playwright:v1.52.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.52.0-noble
WORKDIR /app
COPY . .
RUN npm ci
CMD ["npx", "playwright", "test"]
```
Or use delegated mount on macOS:
```bash
docker run --rm \
-v $(pwd):/app:delegated \
-w /app \
mcr.microsoft.com/playwright:v1.52.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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 197k | Updated | Claude CodeCodex | Verified | Install |