Playwright in GitHub Actions: Run E2E Tests in CI (2026)

Playwright tests are failing in GitHub Actions because the xvfb service, which provides a virtual framebuffer for GUI applications in headless environments, is not running or not accessible by Playwright.

Common Causes and Fixes

xvfb Service Not Started or Crashed
- Diagnosis: Check the GitHub Actions logs for messages indicating xvfb failed to start or exited with an error. You can also try to manually start xvfb in a similar environment to see its output.
- Fix: Ensure xvfb is properly installed and started as a service in your GitHub Actions workflow. A common way to do this is by using a dedicated GitHub Action for xvfb.
```
- name: Start xvfb
  uses: cypress-io/github-action@v4 # This action can also start xvfb
  with:
    # ... other options
    xvfb: true
```
  This works because the cypress-io/github-action implicitly handles the installation and startup of xvfb on the runner, making it available for Playwright.
- Diagnosis: If you’re not using a dedicated action, check your run steps. You might have a command like xvfb-run --auto-servernum --server-num=99 ... but the xvfb server itself wasn’t initiated.
- Fix: Explicitly start xvfb before running your tests.
```
# In your workflow file's run step
sudo apt-get update && sudo apt-get install -y xvfb
Xvfb :99 -screen 0 1024x768x24 &
export DISPLAY=:99
# Now run your Playwright tests
npx playwright test
```
  This explicitly installs xvfb, starts a server on display 99, and sets the DISPLAY environment variable so Playwright can connect to it.
Incorrect DISPLAY Environment Variable
- Diagnosis: Playwright needs to know which X server to connect to. If the DISPLAY environment variable is not set or points to the wrong server, Playwright won’t be able to render its browser. Check your workflow logs for errors related to "cannot open display" or "no X server found."
- Fix: Ensure the DISPLAY environment variable is correctly set to the running xvfb instance.
```
- name: Run Playwright tests
  run: |
    echo "DISPLAY=:99" >> $GITHUB_ENV # Or use your xvfb server number
    npx playwright test
```
  Setting DISPLAY in $GITHUB_ENV makes the variable available to all subsequent steps in the job, ensuring Playwright can find the X server.
xvfb Not Installed on the Runner
- Diagnosis: The GitHub Actions runner might not have xvfb installed by default, especially if you’re using a custom Docker image or a minimal runner environment. Look for "command not found: xvfb" or similar errors.
- Fix: Install xvfb as part of your workflow setup.
```
- name: Install dependencies
  run: |
    sudo apt-get update
    sudo apt-get install -y xvfb
```
  This ensures that the xvfb executable is present on the runner’s filesystem before you attempt to use it.
Permissions Issues with xvfb
- Diagnosis: In some environments, xvfb might fail to start due to insufficient permissions, especially if it’s not run with sudo or if the user context doesn’t allow it.
- Fix: Run xvfb commands with sudo or ensure the user executing the tests has the necessary privileges.
```
# In your workflow file's run step
sudo xvfb-run --auto-servernum --server-num=99 -- npm run test:e2e
```
  Using sudo grants xvfb-run the elevated privileges it might need to create and manage the virtual display server.
Port Conflicts or xvfb Server Already Running
- Diagnosis: If multiple processes try to use the same xvfb server number, or if a previous xvfb instance didn’t shut down cleanly, you might encounter "Address already in use" errors.
- Fix: Use xvfb-run --auto-servernum which dynamically assigns an available server number, or explicitly kill any lingering xvfb processes before starting a new one.
```
# In your workflow file's run step
pkill -f Xvfb || true # Kill any existing Xvfb processes, ignore errors if none exist
xvfb-run --auto-servernum -- npm run test:e2e
```
  This pkill command ensures a clean slate by terminating any Xvfb processes that might be holding onto a port, then xvfb-run --auto-servernum finds a free display to use.
Playwright Browser Binary Issues
- Diagnosis: While less directly related to xvfb, if the Playwright browser binaries themselves are corrupted or not downloaded correctly, it can manifest as test failures that seem like display issues. Check Playwright’s own logs for errors during browser launch.
- Fix: Ensure Playwright browsers are installed correctly within your CI environment.
```
- name: Install Playwright browsers
  run: npx playwright install
```
  This command downloads the necessary browser binaries (Chromium, Firefox, WebKit) for Playwright to use, ensuring they are available on the runner.

The next error you’ll likely hit after resolving xvfb issues is related to network connectivity or timeouts if your tests are trying to access external resources that aren’t available in the CI environment.