Playwright in Docker - base images, run, compose

01Why Docker for Playwright DevOps - docker/01

Running Playwright on a laptop is easy. Running it on twenty laptops, three CI providers, and a Mac M1 that has no Chromium binary becomes a parade of "works on my machine" tickets. Docker solves the same problem here that it solved everywhere else.

• Reproducible browser stack - the official Playwright image already has Chromium, Firefox, and WebKit + every shared library Chromium needs (libnss, libxshmfence, libgbm). One docker pull instead of forty-five apt-get installs.
• No host flake - dev laptop has Chrome 142, CI runner has Chrome 124, suite passes on one and not the other. Docker forces both to use the same Chromium ship inside the image.
• CI parity - the same image that runs in CI runs on the developer's machine. Bug repro is a literal docker run away.
• Network isolation - your tests + the system under test live in one compose network. No localhost-vs-127.0.0.1 confusion, no surprise port collisions.

Counter-point: Docker adds 700-1500 MB to the cold-start cost of a CI runner. If your suite is 15 tests and the image is pulled fresh every time, you may be slower in Docker than out. Pin the image, use registry caching, and sharding (next chapter) to amortise the pull.

02Official Playwright images registry

Microsoft publishes them at mcr.microsoft.com/playwright and tags every Playwright release against three Ubuntu LTS bases:

Pin to a specific version, never :latest. A test that passes today on v1.49.0-jammy may fail tomorrow when the tag rolls forward to v1.51.0-jammy because a default selector strategy changed. Version pinning gives you a stable contract.

03Image layer cake - size trade-offs svg 1/3

The Playwright image is layered: base OS, system libs Chromium needs, Node.js, then the browsers themselves. -slim drops Firefox and WebKit binaries - if you only ship Chromium tests, you save ~750 MB on every pull.

The CI hot path numbers tell the story: a fresh GitHub Actions runner pulling v1.49.0-jammy over its default network spends ~40 seconds on the pull. With -noble-slim the same pull is ~22 seconds. Multiply by 4-way shard, four parallel jobs per workflow, ten workflows per day - the minutes add up.

04Custom Dockerfile - the simplest viable file mermaid 1/3

You can run Playwright tests with no Dockerfile at all - just docker run the official image and bind-mount your repo. But once you have CI in the mix, a Dockerfile gives you a stable, taggable artefact.

FROM mcr.microsoft.com/playwright:v1.49.0-noble

WORKDIR /work

# Copy package files first for cache-friendly builds
COPY package.json package-lock.json ./

RUN npm ci

# Copy everything else
COPY . .

CMD ["npx", "playwright", "test"]

flowchart LR
  A[FROM playwright:v1.49.0-noble] --> B[WORKDIR /work]
  B --> C[COPY package*.json]
  C --> D[RUN npm ci]
  D --> E[COPY . .]
  E --> F[CMD playwright test]
  classDef pin fill:#fef3c7,stroke:#d97706
  classDef install fill:#dbeafe,stroke:#3b82f6
  classDef run fill:#dcfce7,stroke:#22c55e
  class A pin
  class D install
  class F run
              

The build order trick: copy package.json and package-lock.json first, run npm ci, then copy the rest. Docker layers are content-addressed - if the package files do not change, the npm ci layer reuses its cache. Changing a single line of test code does not reinstall a single package.

05Multi-stage build - cache efficiency advanced

Multi-stage adds a "deps" stage so the final image carries no node_modules bloat from build tools. For Playwright this is less dramatic than for a Node prod image - we are not trying to ship a tiny prod artefact - but it still helps because it separates two cache axes: dependency install vs test source.

# Stage 1: install dependencies
FROM mcr.microsoft.com/playwright:v1.49.0-noble AS deps
WORKDIR /work
COPY package.json package-lock.json ./
RUN npm ci

# Stage 2: copy app, reuse node_modules from deps
FROM mcr.microsoft.com/playwright:v1.49.0-noble AS runner
WORKDIR /work
COPY --from=deps /work/node_modules ./node_modules
COPY . .

ENV CI=true
CMD ["npx", "playwright", "test", "--reporter=blob"]

Why two stages help in practice: when you have a monorepo with five Playwright projects sharing one deps lockfile, the deps stage builds once and the runner stage re-runs per project. You can also push the deps image separately and use it as a cache source for faster CI.

06docker run flags that matter svg 2/3

Four flags do most of the work. Memorise them.

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

07docker-compose - app + tests on a shared network mermaid 2/3

The interesting case is not running tests in a container - it is running the system under test plus the tests in two coordinated containers. Compose makes that a single file.

flowchart LR
  subgraph compose[docker-compose network: tta-net]
    APP[ttacart-app:3000]
    TESTS[playwright-tests]
  end
  TESTS -->|HTTP http://ttacart-app:3000| APP
  APP -->|API calls inside| APP_BE[Internal API]
  TESTS -->|writes| ART[/host artifacts/]
  classDef app fill:#dbeafe,stroke:#3b82f6
  classDef tests fill:#dcfce7,stroke:#22c55e
  classDef out fill:#fef3c7,stroke:#d97706
  class APP app
  class TESTS tests
  class ART out
              

services:
  ttacart-app:
    image: ttacart:local
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: production
    healthcheck:
      test: ["CMD", "wget", "-q", "-O-", "http://localhost:3000/health"]
      interval: 5s
      retries: 10
    networks: [tta-net]

  playwright-tests:
    build: .
    depends_on:
      ttacart-app:
        condition: service_healthy
    environment:
      BASE_URL: http://ttacart-app:3000
    ipc: host
    volumes:
      - ./playwright-report:/work/playwright-report
      - ./test-results:/work/test-results
    networks: [tta-net]

networks:
  tta-net:
    driver: bridge

Three things to notice. (1) Tests reach the app at http://ttacart-app:3000 - the service name is the DNS name on the network. (2) depends_on with service_healthy waits for the app's healthcheck before tests boot. (3) ipc: host is the compose equivalent of --ipc=host.

08Headless vs headed in a container Xvfb

In CI you want headless. On a debugging session you sometimes want headed - to see a flaky test fail live. Inside a container, "headed" means we need a virtual display because there is no real screen. Xvfb is the classic answer.

docker run --rm --ipc=host \
  -v $(pwd):/work -w /work \
  mcr.microsoft.com/playwright:v1.49.0-noble \
  bash -c "xvfb-run -- npx playwright test --headed --project=chromium"

In most teaching settings you do not need headed-in-container. Use --debug on the host outside Docker if you want the Playwright Inspector.

09Trace + screenshot extraction svg 3/3

When a test fails inside Docker, you need the trace, video, and screenshot files out. They are written inside the container at /work/test-results/ and /work/playwright-report/. With the bind-mount they appear on the host as soon as the run completes - or fails.

In CI, upload the playwright-report directory as a workflow artifact. We cover that in the sharding chapter where blob reports merge across shards.

10TTACart dockerized example mermaid 3/3

Putting it together. The TTACart demo at https://app.thetestingacademy.com/playwright/ttacart/ is a static SPA - we can either point our Docker tests at the public URL (read-only smoke) or boot a local copy and run isolated.

sequenceDiagram
  autonumber
  participant ME as Developer
  participant DK as docker compose
  participant APP as ttacart-app
  participant T as playwright-tests
  participant HOST as Host filesystem
  ME->>DK: 1. docker compose up --abort-on-container-exit
  DK->>APP: 2. start ttacart-app:3000
  APP-->>DK: 3. healthcheck OK
  DK->>T: 4. start playwright-tests
  T->>APP: 5. GET / and run specs
  APP-->>T: 6. responses
  T->>HOST: 7. write test-results + playwright-report
  T-->>DK: 8. exit 0 (or 1 on failure)
  DK-->>ME: 9. surfaces both exit codes
              

import { test, expect } from "@playwright/test";

const BASE = process.env.BASE_URL ?? "https://app.thetestingacademy.com/playwright/ttacart/";

test("home page renders three feature cards", async ({ page }) => {
  await page.goto(BASE);
  await expect(page.getByRole("heading", { name: /ttacart/i })).toBeVisible();
  await expect(page.locator("[data-testid='feature-card']")).toHaveCount(3);
});

test("product list shows at least one item", async ({ page }) => {
  await page.goto(BASE + "products");
  const rows = page.locator("[data-testid='product-row']");
  await expect(rows.first()).toBeVisible();
});

D1Drill 1 - Pull and run the official image

No Dockerfile. Just docker run the official image, bind-mount a tiny Playwright project, run one test against https://app.thetestingacademy.com/playwright/ttacart/. Confirm the test passes and a report appears in your local playwright-report directory.

D2Drill 2 - Forget --ipc=host and observe the crash

Run the same command without --ipc=host. Run a test that opens many tabs or loads a heavy page. Note the Chromium crash error in the trace - something about /dev/shm. Add the flag back, observe stability.

D3Drill 3 - Write a single-stage Dockerfile

Build a Docker image that has your tests baked in. docker build -t my-tta-tests . then docker run --rm --ipc=host my-tta-tests. Verify the image is around 1.5 GB.

D4Drill 4 - Make it multi-stage

Refactor your Dockerfile to the two-stage version in section 5. Time both builds (time docker build ...). Touch one test file and rebuild - the second build should reuse the deps stage.

D5Drill 5 - Switch to the slim image

Change FROM to mcr.microsoft.com/playwright:v1.49.0-noble-slim. Run the same suite. Confirm Chromium-only tests still pass. Run a WebKit test - it fails. Document the trade-off in your team's README.

D6Drill 6 - docker-compose with an app + tests

Spin up a simple static server (nginx serving a folder) as ttacart-app. Set BASE_URL=http://ttacart-app:80. Run the test container against the service name. Verify both containers come up and tests pass.

D7Drill 7 - Extract a trace from a failing test

Force a failure by asserting a heading that does not exist. Run inside Docker. Confirm test-results/trace.zip appears on your host. Open it with npx playwright show-trace test-results/trace.zip.

D8Drill 8 - Headed run in container

Wrap the test command in xvfb-run --. Run --headed. The test should pass even though there is no host display. Record a video and confirm the page is visible in playback.

SSolution snippets

docker run --rm --ipc=host \
  -v $(pwd):/work -w /work \
  mcr.microsoft.com/playwright:v1.49.0-noble \
  bash -c "npm ci && npx playwright test"

# Single-stage
docker build -t ttacart-tests:1.0.0 .

# Multi-stage with build cache
DOCKER_BUILDKIT=1 docker build \
  --target runner \
  --cache-from ttacart-tests:deps \
  -t ttacart-tests:1.0.0 .

docker compose up --build --abort-on-container-exit \
  --exit-code-from playwright-tests

# exit code 0 if tests pass, 1 if tests fail, app exit ignored

# If not using a bind-mount, copy on container exit:
CID=$(docker create --ipc=host ttacart-tests:1.0.0)
docker start -a $CID || true
docker cp $CID:/work/playwright-report ./playwright-report
docker cp $CID:/work/test-results ./test-results
docker rm $CID

docker run --rm --ipc=host \
  -v $(pwd):/work -w /work \
  mcr.microsoft.com/playwright:v1.49.0-noble \
  xvfb-run -- npx playwright test --headed --project=chromium

import { defineConfig, devices } from "@playwright/test";

export default defineConfig({
  testDir: "./tests",
  fullyParallel: true,
  retries: process.env.CI ? 2 : 0,
  reporter: [["html", { open: "never" }], ["list"]],
  use: {
    baseURL: process.env.BASE_URL ?? "https://app.thetestingacademy.com/playwright/ttacart/",
    trace: "retain-on-failure",
    screenshot: "only-on-failure",
    video: "retain-on-failure",
  },
  projects: [
    { name: "chromium", use: { ...devices["Desktop Chrome"] } },
  ],
});

import { test, expect } from "@playwright/test";

test.describe("TTACart smoke", () => {
  test("home renders", async ({ page }) => {
    await page.goto("/");
    await expect(page).toHaveTitle(/ttacart/i);
  });

  test("product list has rows", async ({ page }) => {
    await page.goto("/products");
    await expect(page.getByTestId("product-row").first()).toBeVisible();
  });

  test("add to cart updates badge", async ({ page }) => {
    await page.goto("/products");
    await page.getByRole("button", { name: "Add to cart" }).first().click();
    await expect(page.getByTestId("cart-count")).toHaveText("1");
  });
});

FROM mcr.microsoft.com/playwright/java:v1.49.0-noble
WORKDIR /work
COPY pom.xml .
RUN mvn -B -q dependency:go-offline
COPY src ./src
CMD ["mvn", "-B", "test"]