Use the Playwright image for your Playwright version#
Playwright publishes Docker images with its browsers and their system dependencies installed, tagged by Playwright version and base OS. The image and the playwright package in your project must be the same version, because each Playwright release supports specific browser builds. Playwright: Docker
docker run --rm --ipc=host -v "$PWD":/work -w /work \
mcr.microsoft.com/playwright:v1.63.0-noble \
/bin/sh -c "npm ci && npx playwright test repro.spec.ts --trace on"
Pin the tag to an exact version, never latest. Playwright's documentation recommends --ipc=host for Chromium, which otherwise can run out of shared memory and crash.
Put the tag in the report and in the reproduction's README: "Runs with mcr.microsoft.com/playwright:v1.63.0-noble, Playwright 1.63.0."
What the container pins, and what it does not#
| Pinned by the image | Not pinned |
|---|---|
| Browser builds and versions | The server the script talks to, unless it runs in the container too |
| System libraries the browsers need | The time zone, unless you set it with TZ or the context's timezoneId |
| The date and time, unless you fix them with the clock API | |
| Fonts installed in the image | The host's CPU speed and core count |
| The OS distribution | GPU: browsers in the container usually render without one |
| Node.js version in the image | Your own dependencies, unless the lockfile is used with npm ci |
Fonts deserve a note. A layout bug that depends on text width can pass in the container and fail on a laptop, or the reverse, because the container's fonts differ from macOS or Windows fonts. If the bug is about text layout, the container is the wrong place to reproduce it. If the bug is about logic, the container's consistency is what you want.
Run the app in the same place#
For a reproduction against a local build, run the app and the browser in containers on one network, such as with Docker Compose. Point the script at the app's service name, not localhost, which inside the browser's container means the container itself. Remember that a non-localhost address over plain http is not a secure context; the origin guide explains what that changes.
Make CI and the maintainer run the same thing#
When the reproduction becomes a regression test, run CI with the same image tag. A bug that reproduced in the image on a laptop and in CI is unlikely to depend on either machine. A bug that reproduces on one and not the other tells you to compare them: headless and headed differences is the usual first suspect.
Worked example: a test that only failed on one laptop#
This example is fictional. A developer's reproduction script for a broken export fails on their laptop and passes for the reviewer. The reviewer suspects the developer's machine.
Both run the script in mcr.microsoft.com/playwright:v1.63.0-noble. It fails in both containers. The reviewer's local run had used an older Playwright with a browser one major version behind, where a now-removed fallback hid the bug. Pinning the image ended the disagreement in one run, and the team added the image tag to their reproduction template.
Questions#
Can I pin branded Chrome instead of Playwright's Chromium?
Install Chrome for Testing at a fixed version in your own image, or use channel: 'chrome' with a fixed Chrome package in a custom image. Installing an exact Chrome version covers the versions.
Does the container run headed browsers?
It can, under a virtual display such as Xvfb, which the Playwright images support. Headless is simpler and is the default.
How large are the images?
Large, because they hold three browsers. If you only need Chromium, a custom image that installs only Chromium with npx playwright install --with-deps chromium is smaller.
Return to reproducing what someone else saw for the other layers a replay needs.