Run headless browser tests reliably in CI containers, handling display server, font, and codec requirements
domain: playwright.dev · 5 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
For Playwright in CI, use the official Docker image (`mcr.microsoft.com/playwright`) which bundles all required browser binaries, system fonts, and shared libraries — avoid building your own base image from scratch unless necessary.
If you must run Chromium or Firefox in a custom container without a display, install `xvfb` (`apt-get install -y xvfb`) and launch it before tests: `Xvfb :99 -screen 0 1280x1024x24 &` then set `DISPLAY=:99` — this is required for headed mode but not for truly headless.
Install system fonts (e.g., `fonts-liberation`, `fonts-noto-cjk`) to prevent font-fallback rendering that causes pixel-diff failures. In Alpine-based images, add `font-freefont` or equivalent.
For video or audio codec-dependent tests on Chromium, use a build that includes proprietary codecs (Chromium does not include them by default). Use `chromium-browser` from distribution packages where available, or consider switching to Chrome for Testing.
Set `CI=true` in the environment — Playwright and most test runners detect this and adjust parallelism, disable interactivity, and enable retries automatically.
Known gotchas
Font rendering in headless Chrome differs from a desktop session even with the same fonts installed — slight sub-pixel differences cause screenshot diffs to fail. Use a generous pixel-diff threshold or a dedicated font-consistent CI image and do not compare CI screenshots against locally generated baselines.
Some CI providers run containers with no `/dev/shm` or a very small one. Chromium uses shared memory for inter-process communication and crashes silently under memory pressure. Pass `--disable-dev-shm-usage` to the browser launch arguments as a workaround.
Playwright's `--headed` flag requires a display. Forgetting to start Xvfb or omitting `DISPLAY` in the environment causes headed tests to fail with an obscure display-related error rather than a clear message.
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?