How to Run Headed Browser Tests With Xvfb in GitHub Actions

A CI runner has no display, so xvfb-run creates a virtual one that lets a headed browser launch.

When a test only reproduces in headed mode (for example some extension or WebGL cases), wrap the command in xvfb-run so the browser gets a virtual display on the runner.

Steps

• Install xvfb (preinstalled on ubuntu-latest, but add it in slim containers).
• Wrap the test command in xvfb-run.
• Keep the run headed only where necessary; headless is faster.

Workflow

jobs:
  headed:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20, cache: npm }
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: xvfb-run --auto-servernum -- npx playwright test --headed

Gotchas

• --auto-servernum avoids display-number collisions when jobs share a host.
• Playwright and Cypress run headless fine in CI; only reach for xvfb when a bug is headed-only.

Related guides