1# Container-Based Testing
2 
3## Table of Contents
4 
51. [Patterns](#patterns)
62. [Decision Guide](#decision-guide)
73. [Anti-Patterns](#anti-patterns)
84. [Troubleshooting](#troubleshooting)
9 
10> **When to use**: Running tests in containers for reproducible environments, CI pipelines, or consistent browser versions across team machines.
11 
12## Patterns
13 
14### Official Image Usage
15 
16Run tests without building a custom image:
17 
18```bash
19docker run --rm \
20  -v $(pwd):/app \
21  -w /app \
22  -e CI=true \
23  -e BASE_URL=http://host.docker.internal:3000 \
24  mcr.microsoft.com/playwright:v1.48.0-noble \
25  bash -c "npm ci && npx playwright test"
26```
27 
28Extract reports with bind mounts:
29 
30```bash
31docker run --rm \
32  -v $(pwd):/app \
33  -v $(pwd)/playwright-report:/app/playwright-report \
34  -v $(pwd)/test-results:/app/test-results \
35  -w /app \
36  mcr.microsoft.com/playwright:v1.48.0-noble \
37  bash -c "npm ci && npx playwright test"
38```
39 
40### Custom Dockerfile
41 
42Build a custom image when you need additional dependencies or pre-installed packages:
43 
44```dockerfile
45FROM mcr.microsoft.com/playwright:v1.48.0-noble
46 
47WORKDIR /app
48 
49COPY package.json package-lock.json ./
50RUN npm ci
51 
52COPY . .
53 
54CMD ["npx", "playwright", "test"]
55```
56 
57Chromium-only slim image:
58 
59```dockerfile
60FROM node:latest-slim
61 
62RUN npx playwright install --with-deps chromium
63 
64WORKDIR /app
65COPY package.json package-lock.json ./
66RUN npm ci
67COPY . .
68 
69CMD ["npx", "playwright", "test", "--project=chromium"]
70```
71 
72### Docker Compose Stack
73 
74Full application stack with database, cache, and test runner:
75 
76```yaml
77services:
78  app:
79    build: .
80    ports:
81      - "3000:3000"
82    environment:
83      - NODE_ENV=test
84      - DATABASE_URL=postgresql://postgres:postgres@db:5432/test
85    depends_on:
86      db:
87        condition: service_healthy
88 
89  db:
90    image: postgres:latest-alpine
91    environment:
92      POSTGRES_USER: postgres
93      POSTGRES_PASSWORD: postgres
94      POSTGRES_DB: test
95    healthcheck:
96      test: ["CMD-SHELL", "pg_isready -U postgres"]
97      interval: 5s
98      timeout: 5s
99      retries: 5
100    tmpfs:
101      - /var/lib/postgresql/data
102 
103  e2e:
104    image: mcr.microsoft.com/playwright:v1.48.0-noble
105    working_dir: /app
106    volumes:
107      - .:/app
108      - /app/node_modules
109    environment:
110      - CI=true
111      - BASE_URL=http://app:3000
112    depends_on:
113      - app
114    command: bash -c "npm ci && npx playwright test"
115    profiles:
116      - test
117```
118 
119Run commands:
120 
121```bash
122docker compose --profile test up --abort-on-container-exit --exit-code-from e2e
123 
124docker compose --profile test down -v
125```
126 
127### CI Container Jobs
128 
129**GitHub Actions:**
130 
131```yaml
132jobs:
133  test:
134    runs-on: ubuntu-latest
135    container:
136      image: mcr.microsoft.com/playwright:v1.48.0-noble
137    steps:
138      - uses: actions/checkout@v4
139      - run: npm ci
140      - run: npx playwright test
141        env:
142          HOME: /root
143```
144 
145**GitLab CI:**
146 
147```yaml
148test:
149  image: mcr.microsoft.com/playwright:v1.48.0-noble
150  script:
151    - npm ci
152    - npx playwright test
153```
154 
155**Jenkins:**
156 
157```groovy
158pipeline {
159    agent {
160        docker {
161            image 'mcr.microsoft.com/playwright:v1.48.0-noble'
162            args '-u root'
163        }
164    }
165    stages {
166        stage('Test') {
167            steps {
168                sh 'npm ci'
169                sh 'npx playwright test'
170            }
171        }
172    }
173}
174```
175 
176### Dev Container Setup
177 
178VS Code Dev Container or GitHub Codespaces configuration:
179 
180```json
181{
182  "name": "Playwright Dev",
183  "image": "mcr.microsoft.com/playwright:v1.48.0-noble",
184  "features": {
185    "ghcr.io/devcontainers/features/node:latest": {
186      "version": "20"
187    }
188  },
189  "postCreateCommand": "npm ci",
190  "customizations": {
191    "vscode": {
192      "extensions": ["ms-playwright.playwright"]
193    }
194  },
195  "forwardPorts": [3000, 9323],
196  "remoteUser": "root"
197}
198```
199 
200## Decision Guide
201 
202| Scenario | Approach |
203|---|---|
204| Simple CI pipeline | Official image as CI container |
205| Tests need database + cache | Docker Compose with app, db, e2e services |
206| Team needs identical environments | Dev Container or custom Dockerfile |
207| Only testing Chromium | Slim image with `install --with-deps chromium` |
208| Cross-browser testing | Official image (all browsers pre-installed) |
209| Local development | Run directly on host for faster iteration |
210 
211## Anti-Patterns
212 
213| Anti-Pattern | Problem | Solution |
214|---|---|---|
215| Installing browsers at runtime | Wastes 60-90 seconds per run | Use official image or bake browsers into custom image |
216| Running as non-root without sandbox config | Chromium sandbox permission errors | Run as root or disable sandbox |
217| Bind-mounting `node_modules` from host | Platform-specific binary crashes | Use anonymous volume: `-v /app/node_modules` |
218| No health checks on dependent services | Tests start before database ready | Add `healthcheck` with `depends_on: condition: service_healthy` |
219| Building application inside Playwright container | Large image, slow builds | Separate app and e2e containers |
220 
221## Troubleshooting
222 
223### "browserType.launch: Executable doesn't exist"
224 
225Playwright version mismatch with Docker image. Ensure `@playwright/test` version matches image tag:
226 
227```bash
228npm ls @playwright/test
229docker pull mcr.microsoft.com/playwright:v<matching-version>-noble
230```
231 
232### "net::ERR_CONNECTION_REFUSED" in docker-compose
233 
234Tests trying to reach `localhost` instead of service name. Configure `baseURL`:
235 
236```typescript
237import { defineConfig } from '@playwright/test';
238 
239export default defineConfig({
240  use: {
241    baseURL: process.env.BASE_URL || 'http://localhost:3000',
242  },
243});
244```
245 
246```yaml
247e2e:
248  environment:
249    - BASE_URL=http://app:3000
250```
251 
252### Permission denied on mounted volumes
253 
254Match user IDs or run as root:
255 
256```bash
257docker run --rm -u $(id -u):$(id -g) \
258  -v $(pwd):/app -w /app \
259  mcr.microsoft.com/playwright:v1.48.0-noble \
260  npx playwright test
261```
262 
263### Slow container tests on macOS/Windows
264 
265Docker Desktop I/O overhead. Copy files instead of mounting:
266 
267```dockerfile
268FROM mcr.microsoft.com/playwright:v1.48.0-noble
269WORKDIR /app
270COPY . .
271RUN npm ci
272CMD ["npx", "playwright", "test"]
273```
274 
275Or use delegated mount:
276 
277```bash
278docker run --rm \
279  -v $(pwd):/app:delegated \
280  -w /app \
281  mcr.microsoft.com/playwright:v1.48.0-noble \
282  bash -c "npm ci && npx playwright test"
283```
284