Skip to content
Vizzly Docs

Matching Screenshots Across Environments

If screenshots match in CI but not on your machine, the problem is usually the environment, not Vizzly.

Different operating systems, browser builds, fonts, and locales all change pixels.

The fix is simple: run your local tests inside a container that looks more like CI.

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 . .

If your CI image is custom, mirror that instead.

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
    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