Learning center

Run the reproduction in a pinned browser container

A reproduction script still depends on the browser and the machine running it. A maintainer on macOS with a newer Playwright and a reporter on Linux with an older one are not running the same test. A container image with the browser, its version and its fonts pinned makes the script a portable artifact: anyone who runs the image runs the same browser.

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 imageNot pinned
Browser builds and versionsThe server the script talks to, unless it runs in the container too
System libraries the browsers needThe 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 imageThe host's CPU speed and core count
The OS distributionGPU: browsers in the container usually render without one
Node.js version in the imageYour 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.

One month of free code review.

New organizations get one calendar month of hosted code review for private and public GitHub repositories. No card or cloud connection required. Eligibility and fair-use terms.

Start free with GitHub

Related reading