Matching screenshots across environments
Different operating systems, browser versions, fonts, and locales can change pixels. If local results differ from CI, run tests in a container that matches the CI environment.
What to match
Before you build anything, check what CI is actually using:
- base image or OS
- Node version
- browser version
- installed fonts
- locale settings
If CI uses Playwright, the easiest path is usually to start from the Playwright image that matches your test version.
Example Dockerfile
FROM mcr.microsoft.com/playwright:v1.57.0-noble
WORKDIR /appCOPY package*.json ./RUN npm ciCOPY . .Replace the image tag with the Playwright version from your lockfile. If CI uses a custom image, use that image locally too.
Example Compose setup
Mount .vizzly so local baselines and results persist between runs, and point the container at your local TDD server.
services: visual-tests: build: . volumes: - ./.vizzly:/app/.vizzly - ./src:/app/src:ro - ./tests:/app/tests:ro environment: - VIZZLY_SERVER_URL=http://host.docker.internal:47392 extra_hosts: - "host.docker.internal:host-gateway" shm_size: '2gb'Workflow
-
Start the TDD server
Terminal window npx vizzly tdd start --open -
Run tests in the container
Terminal window docker compose run visual-tests npm test -
Iterate normally
Update your app, rerun the container, and review the results in the local Vizzly dashboard.
When this helps most
This is especially useful when:
- CI runs Linux but you work on macOS
- fonts differ between local and CI
- browser updates changed rendering
- you want local iteration against CI-like baselines
Troubleshooting
The container cannot reach the TDD server
- make sure the TDD server is running
- confirm the container can reach
host.docker.internal - on Linux, keep the
host-gatewaymapping
Screenshots still do not match
- pin the browser and Playwright versions
- verify installed fonts
- verify locale settings like
LANG
The container runs out of memory
- increase Docker memory or swap
- give Chromium more shared memory with
shm_size - move heavy build steps out of image build time if needed