How to fix Playwright CI failures from missing OS dependencies and fonts?

Playwright browser launches fail in CI when the container image is missing the Linux shared libraries that Chromium requires, such as libnss3, libatk1.0-0, libgbm1, and various others. The symptom is a launch error mentioning a missing library or a browser exit immediately after starting. For visual regression tests, missing fonts cause text to render with fallback glyphs that differ from the reference screenshots, producing pixel-diff failures on pages that haven't visually changed.

Common mistake

# Minimal Node image — has Node but not Chromium's OS dependencies
FROM node:20-alpine

WORKDIR /app
COPY . .
RUN npm ci
# Missing: Playwright browser dependency installation
CMD ["npx", "playwright", "test"]

Alpine-based images in particular are missing many glibc-dependent libraries that Chromium requires.

The fix

Use Playwright's official Docker image — the most reliable approach:

FROM mcr.microsoft.com/playwright:v1.44.0-jammy

WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .

CMD ["npx", "playwright", "test"]

Or install dependencies on a Debian/Ubuntu base:

FROM node:20-bookworm-slim

WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci

# Install Chromium and all OS-level dependencies
RUN npx playwright install --with-deps chromium

COPY . .
CMD ["npx", "playwright", "test"]

For GitHub Actions with font consistency:

steps:
  - uses: actions/checkout@v4

  - uses: actions/setup-node@v4
    with:
      node-version: '20'

  - name: Install dependencies
    run: npm ci

  - name: Install Playwright with system deps
    run: npx playwright install --with-deps

  # Optional: pin fonts for visual regression tests
  - name: Install consistent fonts
    run: |
      sudo apt-get install -y fonts-noto fonts-noto-color-emoji
      fc-cache -f -v

For visual regression tests, lock font rendering:

// playwright.config.ts
export default defineConfig({
  use: {
    // Consistent viewport prevents platform-specific layout differences
    viewport: { width: 1280, height: 720 },
    deviceScaleFactor: 1,
    // Set locale for consistent date/number formatting
    locale: 'en-US',
    timezoneId: 'America/New_York',
  },
});

Why it works

Chromium on Linux dynamically links against system libraries — it is not a fully static binary. When those libraries are absent, the browser process exits immediately with a "shared library not found" error. npx playwright install --with-deps runs Playwright's own dependency installer that adds the exact packages each supported browser version requires. The official Playwright Docker images are built from a Debian base with all dependencies pre-installed and tested against the corresponding Playwright version, eliminating version mismatch issues.

Tips

Alpine-based images (node:20-alpine) are not supported by Playwright's --with-deps because they use musl libc instead of glibc — use Debian or Ubuntu base images for Playwright CI.
For visual regression tests, run screenshot generation and comparison on the same OS and font stack — screenshot baselines generated on macOS will differ from comparisons run on Linux even on the same page.
Pin your Playwright Docker image tag to a specific version (e.g., v1.44.0-jammy) rather than latest to ensure reproducible test environments across CI runs.
After a Playwright version upgrade, regenerate all visual regression baselines on the new image — even minor Chromium updates can alter font rendering subtly.