Docker with Playwright

Official Playwright Docker images bundle browsers and OS dependencies — the standard way to run consistent tests in CI and locally.

Official Images

Image: mcr.microsoft.com/playwright:v1.49.0-jammy (match your @playwright/test version). Includes Chromium, Firefox, WebKit, and Ubuntu deps.

Mount your project, run npm ci && npx playwright test inside container — identical to CI.

docker run --rm -v $(pwd):/work -w /work \
  mcr.microsoft.com/playwright:v1.49.0-jammy \
  npx playwright test

Update jammy tag when upgrading @playwright/test.

docker-compose Example

services:
  playwright:
    image: mcr.microsoft.com/playwright:v1.49.0-jammy
    volumes: ['.:/app']
    working_dir: /app
    command: npx playwright test

Pin image tag to Playwright npm version.
jammy = Ubuntu 22.04 base.
For custom deps, extend FROM playwright image.
Share network with app container via compose.

Docker Reference

Commands and patterns.

Task	Command
Run tests	docker run -v $(pwd):/work ... npx playwright test
Shell in image	docker run -it ... /bin/bash
Local CI parity	docker-compose run playwright
Custom Dockerfile	FROM mcr.microsoft.com/playwright:...
Version sync	Image tag = package.json version
Root user	Avoid — use node user in image

docker-compose with App Under Test

services:
  app:
    build: .
    ports: ['3000:3000']
  e2e:
    image: mcr.microsoft.com/playwright:v1.49.0-jammy
    depends_on: [app]
    environment:
      BASE_URL: http://app:3000

Shared Memory in Docker

Add --ipc=host or increase --shm-size when Chromium crashes with 'out of memory' in Docker containers.

Common Mistakes

Latest Docker tag drifting from npm lockfile version.
Running as root modifying file permissions on mounted volume.
Missing network link between app and test containers.
Building custom image without FROM official playwright base.

Key Takeaways

Official images include browsers and system deps.
Pin Docker tag to @playwright/test version.
Docker reproduces CI locally.
docker-compose coordinates app + test services.

Pro Tip

Add npm script "test:docker": "docker run ..." so entire team runs identical CI environment with one command.