Playwright Docker: Stop Chasing Missing Browser Libraries in CI

You've seen the error. Something like error while loading shared libraries: libgbm.so.1: cannot open shared object file. Or the WebKit variant. Or the Firefox one. You search the error, find a GitHub issue from 2021, add the suggested apt-get line, push again, and get a different missing library. Repeat for 40 minutes until the pipeline is green. Two sprints later, the CI runner image updates and you do it again.

This is the dependency treadmill, and it's the default experience for teams running Playwright in CI without a proper container strategy. The browsers Playwright uses are not simple binaries. They carry deep system-level dependencies that vary by OS version, by distribution, and by the specific Playwright release you're on. If you are new to containerized test environments, Docker Compose Testing for Startups covers the broader philosophy of why containers beat shared staging for integration tests.

The exit is a Playwright Docker image that owns the full dependency tree. Build it once, pin it, and the treadmill stops. This guide shows you how to build that image, optimize it for production, wire it into GitHub Actions and GitLab CI, and debug tests when they fail inside a container.

Why Playwright's Browser Dependencies Make Docker Non-Optional

Playwright controls three browser engines: Chromium, Firefox, and WebKit. Each one links against a different set of native system libraries. Chromium needs roughly 20 shared libraries including libgbm, libasound2, and libxss1. WebKit needs another set. Firefox has its own requirements. On a developer machine that has had a browser installed for years, all of these are already present and nobody notices. On a fresh Linux container they are missing, and Playwright fails before it loads a single page.

The naive fix is to run npx playwright install-deps at the top of every CI job. This works, but it adds 90-180 seconds to every pipeline run, and those seconds compound. A team running 20 CI jobs per day burns roughly 25 engineer-hours of idle wait time per month just on browser dependency installation — and that is before you count the runs that fail midway and have to be retried.

Microsoft ships an official Docker image, mcr.microsoft.com/playwright, that solves this completely. The image is built with every system library pre-installed, alongside the browser binaries themselves. Pull the image, copy your test files, run your tests. No installation, no library hunting, no CI surprises.

One important caveat: Alpine Linux is not supported. The Playwright browser binaries depend on glibc, and Alpine uses musl. If your organization standardizes on Alpine-based images for size optimization, you will need to use the -noble (Ubuntu 24.04) or -jammy (Ubuntu 22.04) image tags instead. There is no workaround that the Playwright team officially supports.

This is why a Playwright Docker container is not just a nice-to-have for larger teams. It is the correct default for any team running Playwright in a CI environment. The comparison between Playwright and Selenium is heavily influenced by this infrastructure story: Playwright's official Docker image is one reason Playwright CI pipelines are significantly faster to set up and maintain.

The Basic Dockerfile

The starting point is simpler than most engineers expect. Pull the official image, copy your project, install npm dependencies (the browser binaries are already in the image), and run your tests. Here is the complete basic Dockerfile:

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 ./

# Install dependencies
RUN npm ci

# Copy the rest of the project
COPY . .

# Run Playwright tests
CMD ["npx", "playwright", "test"]

A few things worth noting. The FROM mcr.microsoft.com/playwright:v1.59.1-noble line pins a specific version. Never use latest in a test image. Playwright versions change browser binaries, and a silent update to latest that changes Chromium's rendering behavior can turn a passing test suite into a flaky one overnight. Pin the version, update intentionally.

The working directory is /app by convention. You copy package.json and package-lock.json before copying the rest of the project, which lets Docker cache the npm install layer. If your test files change but your dependencies do not, Docker skips the install step entirely. For a project with hundreds of packages, this shaves minutes off rebuild times.

Docker Runtime Flags That Prevent Silent Crashes

When you run this image, three flags matter. First, --ipc=host (or ipc: host in docker-compose): Chromium uses shared memory for inter-process communication, and Docker limits /dev/shm to 64MB by default. Without this flag, Chromium crashes silently on pages with heavy rendering. The alternative is --shm-size=2g if you cannot use host IPC. Second, --init (or init: true in compose): this prevents zombie processes from Chromium subprocesses that the default PID 1 does not reap. Third, if you are running as root (which you should not in production), --cap-add=SYS_ADMIN enables the Chromium sandbox. Running as a non-root user with --ipc=host is the cleaner path.

The Production Dockerfile

The basic Dockerfile works. The production Dockerfile is the one you should actually ship. The core difference is a multi-stage build that separates dependency installation from test execution, runs tests as a non-root user, and produces a smaller final image by not dragging build artifacts forward. Here is the production version:

# Stage 1: Install dependencies
FROM mcr.microsoft.com/playwright:v1.52.0-noble AS deps

WORKDIR /app

COPY package.json package-lock.json ./

RUN npm ci

# Stage 2: Run tests as non-root user
FROM mcr.microsoft.com/playwright:v1.52.0-noble AS runner

WORKDIR /app

# Copy installed dependencies from the deps stage
COPY --from=deps /app/node_modules ./node_modules

# Copy project files
COPY . .

# Switch to the built-in non-root user provided by the Playwright image
USER pwuser

# Run Playwright tests
CMD ["npx", "playwright", "test"]

The two-stage structure matters for a specific reason: the first stage installs everything including dev tools and build caches. The second stage copies only node_modules and your project files, leaving the build mess behind. Final image size is typically 40-60% smaller than a single-stage build with the same contents.

Running as a non-root user (pwuser is the user pre-created in the official Playwright image) is a security requirement for any production CI environment. Some container runtimes in CI reject root containers entirely. Building the habit into your Dockerfile from the start avoids a painful retrofit later.

Pair this with a .dockerignore file that excludes node_modules, .git, test-results, and any local .env files. Without it, your build context grows unbounded and the COPY . . step slows down on every change.

Docker Compose for Local Playwright Development

A Dockerfile runs your tests. Docker Compose orchestrates the full environment: your test runner, the application under test, a database, a mock service. When they all share a network and start in the right order with health checks, your local environment and your CI environment are identical. Here is the compose file:

services:
  webapp:
    build:
      context: .
      dockerfile: Dockerfile.webapp
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 5s
      timeout: 3s
      retries: 10
      start_period: 10s
    networks:
      - e2e-network

  playwright:
    build:
      context: .
      dockerfile: Dockerfile.production
    depends_on:
      webapp:
        condition: service_healthy
    environment:
      - BASE_URL=http://webapp:3000
    ipc: host
    init: true
    volumes:
      - ./tests:/app/tests
      - ./playwright.config.ts:/app/playwright.config.ts
      - ./test-results:/app/test-results
      - ./playwright-report:/app/playwright-report
    networks:
      - e2e-network

networks:
  e2e-network:
    driver: bridge

The health check on the webapp service is important. Without it, the playwright service can start before the app is ready to accept connections, and your tests fail with connection refused errors rather than actual test failures. These are among the most common flaky test sources in CI for containerized setups.

Volume mounts serve two purposes here. The ./playwright.config.ts and ./tests mounts let you edit test files locally and see results without rebuilding the image. The test-results and playwright-report mounts bring artifacts back to your host machine so you can open the HTML report in a browser after the run.

The shared network is straightforward: playwright talks to webapp using the service name as the hostname. Inside the playwright container, your baseURL is http://webapp:3000, not localhost. This is a common gotcha when first moving from a direct install to Docker Compose. For a deeper look at the broader patterns at play, Docker Compose Testing for Startups is the companion read.

Running Playwright Docker in GitHub Actions

GitHub Actions is where most teams first hit the "Playwright Docker or native runner" decision. The native runner approach (npx playwright install --with-deps) works, but it installs browsers on every run. The Docker approach caches the image between runs. For repos with active CI, the Docker approach wins on total pipeline time once the image is cached. Here is the complete workflow:

# Template workflow for running Playwright E2E tests in Docker.
# Copy this file into your own repo and adjust BASE_URL to point at your app.
#
# This workflow uses workflow_dispatch (manual trigger) in this companion repo
# because there is no live app to test against here. In your repo, replace the
# trigger with push/pull_request events as shown in the commented block below.

name: Playwright E2E Tests

on:
  workflow_dispatch:
  # Uncomment these triggers in your own repo:
  # push:
  #   branches: [main]
  # pull_request:
  #   branches: [main]

jobs:
  e2e:
    runs-on: ubuntu-latest
    timeout-minutes: 15

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Build Playwright Docker image
        uses: docker/build-push-action@v6
        with:
          context: .
          file: Dockerfile
          load: true
          tags: playwright-tests:latest
          cache-from: type=gha
          cache-to: type=gha,mode=max

      - name: Run Playwright tests
        run: |
          docker run --rm \
            --ipc=host \
            --init \
            -e CI=true \
            -e BASE_URL="${{ env.BASE_URL }}" \
            -v "${{ github.workspace }}/test-results:/app/test-results" \
            -v "${{ github.workspace }}/playwright-report:/app/playwright-report" \
            playwright-tests:latest
        env:
          BASE_URL: http://localhost:3000

      - name: Upload Playwright report
        uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 14

      - name: Upload test results
        uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: test-results
          path: test-results/
          retention-days: 14

The trace artifact upload on failure is critical. Playwright traces are binary files that the Playwright Trace Viewer can open to show a step-by-step replay of every action, every network request, and every DOM snapshot at the moment of failure. Without uploading them in CI, a test that fails only in GitHub Actions and passes locally is nearly undebuggable. With the trace, you can open it in 30 seconds and see exactly what happened.

The workflow uses docker build and docker run directly rather than a docker-compose step. For CI, this is the right call: compose introduces a daemon process and extra networking overhead that adds no value when you only need to run one container.

For teams who need to connect Playwright Docker with GitHub Actions to preview environments, the pattern extends cleanly. You pass the preview URL as a BASE_URL environment variable into the container, and the Playwright config reads it.

We built Autonoma specifically because maintaining CI workflows like this one is where teams lose time they should be spending on product. The GitHub Actions file above is not complicated, but it is one more file to maintain, one more place a dep update can break your pipeline, and one more thing to re-learn when you onboard a new engineer.

Playwright CI Docker Setup for GitLab

GitLab CI's runner model fits Playwright Docker naturally. The official Playwright image can be used directly as the job image, which means the browsers and system dependencies are present before your job script even begins. Here is a complete config:

stages:
  - e2e

e2e-tests:
  stage: e2e
  image: mcr.microsoft.com/playwright:v1.52.0-noble
  script:
    - npm ci
    - npx playwright test
  artifacts:
    paths:
      - playwright-report/
      - test-results/
    expire_in: 1 week
    when: always

The key structural difference from GitHub Actions is that GitLab CI runs each job inside the specified image, so you do not need a separate build step. The playwright image is the runtime. Your job script just installs npm deps and runs the tests. No docker build command inside the job.

Artifact collection follows GitLab's artifacts keyword. Storing the playwright-report/ directory with a one-week expiry gives your team time to investigate failures without filling up artifact storage. Mark them as when: always so reports are collected even on failed jobs, otherwise you lose the only evidence of what went wrong.

Debugging Playwright Tests in Docker Containers

This is the part of the Playwright Docker guide that nobody writes until someone spends an afternoon debugging a test that fails only in Docker. The problem is that Docker containers run headless by default. There is no display, no browser window, no way to watch what Playwright is doing. When a test fails for a visual reason (an element that renders differently in the container's Chromium versus your local Chrome), you need a way to see the browser.

VNC Live Debugging

VNC is the standard approach. You start the container with a virtual display via Xvfb, run Playwright in headed mode, and expose VNC on port 5900. From your host machine, you connect with any VNC viewer and watch the test run live. The script below automates this setup:

#!/usr/bin/env bash
#
# Debug Playwright tests visually using VNC.
#
# This script builds and runs the Playwright container in headed mode with a
# VNC server so you can watch the browser in real time from any VNC client.
#
# Usage:
#   ./examples/debug-with-vnc.sh
#
# Then connect a VNC viewer to localhost:5900 (no password by default).

set -euo pipefail

IMAGE_NAME="playwright-vnc-debug"
VNC_PORT="${VNC_PORT:-5900}"
DISPLAY_NUM="${DISPLAY_NUM:-99}"

echo "==> Building the Playwright Docker image..."
docker build -t "${IMAGE_NAME}" -f Dockerfile .

echo "==> Starting container with Xvfb + x11vnc on display :${DISPLAY_NUM}..."
echo "    Connect your VNC viewer to localhost:${VNC_PORT}"

docker run --rm -it \
  --ipc=host \
  --init \
  -p "${VNC_PORT}:${VNC_PORT}" \
  -e DISPLAY=":${DISPLAY_NUM}" \
  -v "$(pwd)/tests:/app/tests" \
  -v "$(pwd)/playwright.config.ts:/app/playwright.config.ts" \
  -v "$(pwd)/test-results:/app/test-results" \
  -v "$(pwd)/playwright-report:/app/playwright-report" \
  "${IMAGE_NAME}" \
  bash -c "
    # Start a virtual framebuffer
    Xvfb :${DISPLAY_NUM} -screen 0 1280x720x24 &
    sleep 1

    # Install x11vnc if not already present
    if ! command -v x11vnc &>/dev/null; then
      apt-get update -qq && apt-get install -y -qq x11vnc >/dev/null 2>&1
    fi

    # Start VNC server (no password for local debugging)
    x11vnc -display :${DISPLAY_NUM} -forever -nopw -rfbport ${VNC_PORT} &
    sleep 1

    echo '==> VNC server is running. Connect to localhost:${VNC_PORT}'
    echo '==> Running Playwright in headed mode...'

    # Run tests in headed mode
    npx playwright test --headed
  "

# -----------------------------------------------------------------
# Extracting a trace file after a test run (without VNC):
#
#   CONTAINER_ID=\$(docker run -d --ipc=host --init playwright-tests:latest)
#   docker wait "\${CONTAINER_ID}"
#   docker cp "\${CONTAINER_ID}:/app/test-results" ./test-results
#   docker rm "\${CONTAINER_ID}"
# -----------------------------------------------------------------

Trace-Based Debugging

For non-visual debugging, the Playwright trace is your primary tool. When a test fails, run it with --trace on (or set trace: 'on' in your config), then copy the trace file out of the container using docker cp. Open it with npx playwright show-trace trace.zip and you get a full step-by-step replay with screenshots, network requests, and console output at each action.

If you are dealing with flakiness that appears only in containers, the usual culprits are timing assumptions that hold on a fast developer machine but break under container resource limits, font rendering differences between the host OS and the Ubuntu container, and viewport size mismatches when no explicit viewport is set in the Playwright config. All three are solvable. The trace viewer will show you exactly which one you are dealing with. For a broader treatment of this category of problem, why E2E tests pass but the product is broken covers the failure modes in more depth.

When Docker Is the Wrong Answer

Playwright Docker solves the environment consistency problem. It is the right default for CI. But there are two situations where the overhead is not worth it.

If your team runs tests locally as the primary development loop and CI is just a gate, the image build time and compose startup add friction to a workflow that should be fast. Local development with a native Playwright install is faster. Use Docker for CI, native install for the inner development loop.

If you are running Playwright as part of a broader test infrastructure that includes API tests, unit tests, and integration tests, coordinating all of it through Docker adds orchestration complexity that compounds with team size. This is where E2E testing tools that abstract the infrastructure layer start to make economic sense.

The teams we see at Autonoma who spend the most engineering time on their Playwright Docker setup are not the ones who built it wrong. They built it correctly. But every Dockerfile, every compose config, every GitHub Actions YAML, and every GitLab CI config is infrastructure that someone owns. When Playwright releases a new version and the image tag changes, someone updates the Dockerfiles. When a new engineer joins, someone explains the VNC debug setup. When the compose file starts timing out under load, someone digs through the health check logic. That ownership cost never goes away.

For teams who want E2E coverage without carrying that infrastructure, we built Autonoma to run Playwright tests in managed cloud containers. You connect your codebase, agents generate tests from your code, and execution happens in our infrastructure. Autonoma is open source and free to self-host; a managed Cloud tier is also available. No Dockerfiles to maintain, no CI workflows to update, no browser dependency matrix to track.

Fixing Flaky Playwright Tests in Docker

Container-specific flakiness is real and distinct from regular test flakiness. The usual pattern: a test passes 90% of the time and fails 10% of the time, but only in Docker. The test passes every time locally. This is almost always one of three things.

First, resource contention. Containers share host CPU and memory. If your CI runner is also running 5 other jobs, Playwright's auto-waiting works against a slower DOM. Increase the global test timeout and add explicit waits for network-idle states on pages with heavy data loading. Second, font rendering. Playwright's visual comparison features (toHaveScreenshot) are pixel-sensitive. The Ubuntu fonts in the Playwright image render text at subtly different sizes than macOS. If you are using screenshot assertions, generate your baseline snapshots inside the same Docker image you use in CI. Third, the Xvfb display server. When running headed in a container without proper DISPLAY configuration, some browser operations silently fail. The VNC script above handles this correctly; if you are rolling your own headed setup, confirm the DISPLAY variable is set before Playwright launches.

Summary: Your Playwright Docker Container Checklist

Running Playwright in a Docker container comes down to three building blocks: the right base image, a multi-stage Dockerfile that optimizes for layer caching and image size, and a compose or CI config that wires the test container to the application under test. Get those three right and environment consistency stops being a problem you solve repeatedly. It becomes infrastructure you set up once.

The companion repo has all six configs ready to copy into your project. Pin your Playwright image version, add a .dockerignore, run as a non-root user, upload traces on failure. Those four habits handle 90% of the friction teams encounter when containerizing their E2E suite.

If the remaining 10% (maintaining the Dockerfiles, updating image tags, debugging container-specific flakiness) sounds like work you would rather spend on product instead, that is exactly what Autonoma handles for you. Connect your codebase, get E2E coverage, skip the infrastructure.