Playwright is a fantastic tool for end-to-end testing of modern web apps. But if you’ve ever tried to run your Playwright test suite on a CI server (or a colleague’s machine), you’ve probably run into the classic: “But it works on my machine!”
The solution? Docker.
Containers give you a consistent, isolated, and reproducible environment for your tests. No more Chrome version mismatches or missing system dependencies.
Let’s walk through how to containerize your Playwright tests.
Why Docker for Playwright?
Consistency – Run tests exactly the same way locally, on staging, or in CI.
Speed – No need to set up browsers on the host machine. Docker images come with everything pre-installed.
Parallelism – Easily spin up multiple containers to shard your test suite.
Step 1: Your Project Structure
Assume a simple Node.js project with Playwright:
text
my-playwright-tests/
├── tests/
│ └── example.spec.js
├── package.json
├── playwright.config.js
└── Dockerfile
Step 2: The Dockerfile
Playwright maintains official Docker images. Here’s a minimal, production-ready Dockerfile:
dockerfile
Use the official Playwright image
FROM mcr.microsoft.com/playwright:latest
WORKDIR /app
Copy package files and install dependencies
COPY package*.json ./
RUN npm ci
Copy the rest of your test code
COPY . .
Run the tests
CMD ["npx", "playwright", "test"]
💡 The playwright:latest image already includes Chromium, Firefox, WebKit, and all system dependencies.
Step 3: Build & Run
Build the image:
bash
docker build -t playwright-tests .
Run once:
bash
docker run --rm playwright-tests
Run with mounted reports (to see HTML report locally):
bash
docker run --rm -v $(pwd)/test-results:/app/test-results playwright-tests
Step 4: Running specific browsers or headed mode
Want to see the browser window? Pass environment variables or override the command:
bash
docker run --rm -e BROWSER=firefox playwright-tests npx playwright test --headed
Note: Headed mode requires --ipc=host on Linux or special X11 handling. For CI, stick to headless.
Step 5: Using in CI (GitHub Actions example)
yaml
name: Playwright tests
on: push
jobs:
test:
runs-on: ubuntu-latest
container:
image: mcr.microsoft.com/playwright:latest
steps:
- uses: actions/checkout@v4
- run: npm ci
- run: npx playwright test
- uses: actions/upload-artifact@v4
if: always()
with:
name: playwright-report
path: playwright-report/
Common pitfalls & fixes
Problem Solution
Tests fail because of missing fonts Use mcr.microsoft.com/playwright:focal for better system fonts.
Docker cache bloats Use --mount=type=cache for ~/.cache/ms-playwright if you build frequently.
Slow test startup Pre-build the image and reuse layers.
To sum up
Containerizing your Playwright tests is a small upfront effort that pays off in reliability. You get:
✅ No more “works on my machine”
✅ Painless CI setup
✅ Easy scaling across multiple containers
Try it out. Your future self (and your teammates) will thank you.
Have you tried running Playwright in Docker? What was your biggest blocker? Let me know in the comments.
Top comments (0)