For repeatable Playwright screenshots in Docker, pin the container image and match its Playwright version to the project, install the required browsers and system dependencies, provide the fonts your app needs, and create and compare baselines in the same environment. Docker reduces environmental variation; it does not make screenshots identical across operating systems, browser versions, hardware, power settings, or headless modes.
How to run Playwright screenshot tests in Docker
Choose either the official Playwright image or a custom Linux base image. In both cases, keep the Playwright package and browser binaries aligned: each Playwright release expects specific browser builds, and a mismatch can keep Playwright from locating its browser executables. Playwright’s Docker documentation says, “It is recommended to always pin your Docker image to a specific version if possible.”
Option 1: Use the official Playwright image
The official image includes Playwright browser binaries and browser system dependencies, but not the Playwright package for your project. Install the project dependencies separately. Pin the image tag and use the corresponding Playwright package version; do not assume that an unpinned or differently versioned image will match.
# Dockerfile
FROM mcr.microsoft.com/playwright:v1.63.0-noble
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
CMD ["npx", "playwright", "test"]The tag shown is an example, not a permanent recommendation. Playwright’s documentation listed v1.63.0-noble as an example on October 3, 2026. Check the current published image tags and select the tag that matches the Playwright version in your project. The documentation lists Ubuntu 24.04 (Noble), 22.04 (Jammy), and 26.04 (Resolute) variants; available tags can change.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitches#1 Best Overall
- CRISP CLARITY: This 23.8″ Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
- WORK SEAMLESSLY: This sleek monitor is virtually bezel-free on three sides, so the screen looks even bigger for the viewer. This minimalistic design also allows for seamless multi-monitor setups that enhance your workflow and boost productivity
- A BETTER READING EXPERIENCE: For busy office workers, EasyRead mode provides a more paper-like experience for when viewing lengthy documents
Option 2: Build on a custom Linux image
A custom image gives you control over the base image and installed software, but you must install Node.js for the JavaScript commands below, the matching Playwright package, browser binaries, and browser system dependencies. Playwright’s documented Node-based pattern is npx -y playwright@<matching-version> install --with-deps. Replace the version with the one used by your project rather than copying the example version blindly.
# Dockerfile
FROM node:22-bookworm
WORKDIR /app
COPY package*.json ./
RUN npm ci
RUN npx -y [email protected] install --with-deps
COPY . .
CMD ["npx", "playwright", "test"]In this example, set both the project dependency and CLI install version to the same Playwright release. The command installs the default browsers; specify browser names if you intentionally want to narrow the installed set. Firefox and WebKit builds target glibc, so Alpine and other musl-based distributions are unsupported for those browsers.
The version in the custom-image example is illustrative. Confirm the current Playwright release and supported base-image requirements when you build or update your image.
Configure Docker runtime and browser security
Playwright recommends running Docker with --init. For Chromium, it also recommends --ipc=host, because Chromium can run out of memory and crash when its shared-memory needs are constrained.
Rank #2
- CRISP CLARITY: This 22 inch class (21.5″ viewable) Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- 100HZ FAST REFRESH RATE: 100Hz brings your favorite movies and video games to life. Stream, binge, and play effortlessly
- SMOOTH ACTION WITH ADAPTIVE-SYNC: Adaptive-Sync technology ensures fluid action sequences and rapid response time. Every frame will be rendered smoothly with crystal clarity and without stutter
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
docker run --init --ipc=host --rm my-playwright-testsIf Chromium has unusual launch problems during local development, Playwright’s Docker guidance suggests trying --cap-add=SYS_ADMIN. Treat that as a troubleshooting measure, not a default flag.
The official image runs as root by default, which disables Chromium’s sandbox. Playwright says this can be acceptable for trusted end-to-end tests. For untrusted browsing or scraping, use a separate user and a seccomp profile instead; do not treat the trusted-test setup as a general-purpose secure browsing environment.
Install and verify fonts
Fonts affect layout, line wrapping, glyph shape, and therefore screenshot comparisons. Playwright’s screenshot documentation identifies fonts as a source of screenshot differences, but the reviewed official Docker documentation does not provide a definitive inventory of font families in current image tags. Do not assume the container has the same fonts as a developer workstation.
Make required fonts explicit
Identify the fonts your application actually uses, including any local or licensed font files. Add those fonts to your image through your normal Linux font-installation process, then verify that the browser can render the intended family. Browser system dependencies installed by Playwright are not a guarantee that your application’s specific fonts are present.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Rank #3
- Clear visuals. Fluid motion: A 144Hz refresh rate and 1ms MPRT deliver smooth, tear‑free motion across work, gaming, and streaming for clearer, more fluid viewing.
- Eye comfort: TÜV Rheinland 3‑star* certification reduces harmful blue light while preserving stunning color quality without compromise. *TÜV Rheinland 3-star eye comfort certification.
- Wide viewing angle: Get consistent views across a wide 178° /178° viewing angle.
- In-Plane Switching (IPS): See excellent color accuracy and consistency across wide viewing angles with In-plane Switching (IPS) technology.
- Ultra-thin bezels: Maximize your viewing experience with thin bezels.
For web-hosted fonts, ensure the page has finished loading them before capture. In a Playwright test, wait for the document’s font set before taking the screenshot:
await page.goto('http://localhost:3000');
await page.evaluate(() => document.fonts.ready);
await expect(page).toHaveScreenshot();For a page with asynchronous content or images, also wait for the application-specific ready state or relevant selector. A font-ready check alone does not guarantee that every other visual element has settled.
Create and maintain screenshot baselines
Playwright Test’s toHaveScreenshot() creates an expected image on the first run and compares later runs with that baseline. The assertion waits for two consecutive screenshots to match before saving the initial reference. PNG is the default snapshot format; the visual-comparisons documentation also supports lossless WebP.
Example test
import { test, expect } from '@playwright/test';
test('home page visual baseline', async ({ page }) => {
await page.goto('http://localhost:3000');
await page.evaluate(() => document.fonts.ready);
await expect(page).toHaveScreenshot('home-page.png');
});On its first execution, this test creates a reference screenshot. Later executions compare against it and report visual differences. Snapshot filenames incorporate test and snapshot identity along with browser and platform information; multi-project configurations can include the project name.
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #4
- CURVED FOR ENHANCED ENGAGEMENT: An immersive viewing experience with a curved monitor that wraps more closely around your field of vision; It creates a wider view, enhancing depth perception and minimizing peripheral distraction
- SMOOTH PERFORMANCE FOR SEAMLESS CONTENT: Stay in the action when playing games, watching videos, or working on creative projects; The 100Hz refresh rate reduces lag and motion blur so you don't miss a thing in fast-paced moments¹
- MORE GAMING POWER: Gain the edge with optimizable game settings; Color and image contrast can be adjusted to see scenes more vividly and spot enemies hiding in the dark; Game Mode adjusts any game to fill the screen so you can view every detail²
- KEEP IT EASY ON THE EYES: Care for your eyes and stay comfortable, even during long sessions; Advanced eye comfort technology certified by TÜV reduces eye strain by minimizing blue light and reducing irritating screen flicker²
- INCREASED VERSATILITY: Connect to more; Plug devices straight into your monitor for increased flexibility, making your computing environment even more convenient
Update references deliberately
- Run the test in the same pinned image, browser project, and relevant settings used for comparison.
- Review the reported image differences and decide whether they reflect an intended visual change or environment drift.
- When the change is expected, update snapshots with
npx playwright test --update-snapshots. - Commit the snapshot changes with the code and review them as part of the change.
Do not update baselines automatically just to make a failing comparison pass; that can turn an unintended rendering change into the new reference.
Choose browsers and platforms intentionally
Playwright supports Chromium, Firefox, and WebKit, along with branded Chrome and Edge and device emulation. Browser engines and platforms can render differently, so decide whether a test needs one stable target or broader coverage.
| Approach | What it gives you | Baseline implication |
|---|---|---|
| One browser and pinned image | A narrower, more controlled comparison environment. | Use the same browser, image, and relevant settings to create and compare snapshots. |
| Multiple browser projects | Coverage across Chromium, Firefox, or WebKit, and optionally branded browsers. | Expect browser-specific rendering and maintain distinct project baselines where needed. |
| Device emulation | Tests using Playwright’s emulated device configurations. | Keep the selected device and viewport settings consistent with the reference run. |
| Multiple operating-system environments | Broader platform coverage. | Expect platform differences and use environment-appropriate baselines rather than assuming one reference represents every OS. |
Why Playwright screenshots differ in CI
Containerization helps control the environment, but it cannot erase every rendering variable. Playwright identifies host operating system, browser version, settings, hardware, power source, and headless mode as sources of variation. Fonts are another documented factor.
- Browser or image version drift: an image update or mismatch between the package and browser binaries changes the rendering environment. Pin the image and align its Playwright version with the project.
- Font availability or timing: a missing font can change text metrics; a screenshot taken before web fonts load may capture a fallback. Install and verify required fonts and wait for page fonts before capture.
- Different browser projects: Chromium, Firefox, WebKit, and branded browsers may render differently. Compare each against its own intended baseline.
- Different settings or viewport: changes to viewport, device emulation, color scheme, scale, or other screenshot settings can alter pixels. Keep test configuration stable when comparing.
- Host and execution differences: hardware, operating system, power source, and headless mode can still affect output. Use a consistent CI image and runner where repeatability is the priority.
- Unsettled page content: asynchronous application rendering can produce a screenshot before the page is visually ready. Wait for the specific application state, not merely navigation completion.
Set up Playwright screenshot tests in CI
The basic CI sequence is to install project packages, install Playwright browsers and dependencies (or run a matching Playwright image), and execute the tests. The Playwright CI guide recommends one worker for stability and reproducibility. Stronger self-hosted runners may use parallel execution or sharding when throughput is more important and the environment is controlled.
Best Value
- 【INTEGRATED SPEAKERS】Whether you're at work or in the midst of an intense gaming session, our built-in speakers provide rich and seamless audio, all while keeping your desk clutter-free.
- 【EASY ON THE EYES】 Protect your eyes and enhance your comfort with Blue-Light Shift technology. This feature reduces harmful blue light emissions from your screen, helping to alleviate eye strain during long hours of use and promoting healthier viewing habits.
- 【WIDEN YOUR PERSPECTIVE】Our sleek minimal bezel design ensures undivided attention. The nearly bezel-free display seamlessly connects in a dual monitor arrangement, delivering an unobstructed view that lets you focus on more at once, completely distraction-free.
npm ci
npx playwright install --with-deps
npx playwright testIf using the official image, make sure its tag matches the Playwright package in the repository; the browser and system dependencies are already in the image, while the project package still needs to be installed.
Playwright’s CI documentation does not recommend caching browser binaries by default: restoring them can take about as long as downloading them, and Linux operating-system dependencies cannot be cached that way. If you do cache browser binaries, include the Playwright version in the cache key so a package update does not restore incompatible browser builds.
Troubleshooting common failures
| Symptom | Likely cause | What to do |
|---|---|---|
| Playwright cannot find or launch a browser executable. | The installed browser binaries do not match the Playwright package, or the required browser was not installed. | Align the Docker image, project package, and browser-install CLI versions; install the browser required by the test. |
| Browser launch reports missing shared libraries or system dependencies. | A custom image lacks browser dependencies. | For a Node-based Linux image, run npx -y playwright@<matching-version> install --with-deps and rebuild. |
| Chromium crashes or exits under Docker. | Shared-memory limits or container runtime configuration may be contributing. | Run with --init --ipc=host. If the problem occurs only in local development, Playwright suggests trying --cap-add=SYS_ADMIN. |
| Text wraps differently or glyphs look unlike the baseline. | The intended font is absent, unavailable to the browser, or not loaded before capture. | Install and verify the app’s required fonts in the image; wait for document.fonts.ready and application readiness. |
| A screenshot comparison fails after a seemingly small change. | The change may be real, or the browser, image, OS, settings, or page readiness may differ from the baseline run. | Compare the execution environment and inspect the diff before deciding whether to update snapshots. |
| Firefox or WebKit will not run on an Alpine image. | Those browser builds target glibc; Alpine uses musl. | Use a supported glibc-based image for Firefox or WebKit. |
Or skip the browser setup
If your task is to capture a website rather than run Playwright visual-regression tests against your own application, ScreenshotNeo offers a one-request screenshot API and an MCP server for AI agents. A screenshot API is not a replacement for Playwright Test baselines or test assertions, but it can avoid maintaining a browser container for standalone captures.
For example, this cURL request saves a WebP screenshot of Stripe; the ScreenshotNeo API documentation covers the API options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp- Cookie and consent banners are accepted before capture, and 60+ known consent platforms, newsletter popups, and chat widgets can be removed; each step can be turned off.
- Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed; response headers identify the page verdict and billing status.
- An MCP server provides
take_screenshot,get_page_info, andcapture_pdftools for AI agents and MCP clients. - The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.
See ScreenshotNeo for the service details, then sign up free for 1,000 screenshots a month with no card.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
