Skip to content
Latest

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 /app
COPY package*.json ./
RUN npm ci
COPY . .

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

  1. Start the TDD server

    Terminal window
    npx vizzly tdd start --open
  2. Run tests in the container

    Terminal window
    docker compose run visual-tests npm test
  3. 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-gateway mapping

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

See also