Files

Jeremy 04aa3db883 chore(e2e): enable Playwright UI on headless Linux

Attempt to auto-start Xvfb when `--ui` is requested locally, add a stable `npm run e2e:ui:headless-server` wrapper, and document the headed/headless workflows. Improves developer DX when running Playwright UI on headless Linux and provides actionable guidance when Xvfb is unavailable.

2026-02-06 10:29:11 -05:00

2.7 KiB

Raw Blame History

Running Playwright E2E (headed and headless)

This document explains how to run Playwright tests using a real browser (headed) on Linux machines and in the project's Docker E2E environment.

Key points

Playwright's interactive Test UI (--ui) requires an X server (a display). On headless CI or servers, use Xvfb.
Prefer the project's E2E Docker image for integration-like runs; use the local --ui flow for manual debugging.

Quick commands (local Linux)

Headless (recommended for CI / fast runs):
```
npm run e2e
```

Headed UI on a headless machine (auto-starts Xvfb):

npm run e2e:ui:headless-server
# or, if you prefer manual control:
xvfb-run --auto-servernum --server-args='-screen 0 1280x720x24' npx playwright test --ui

Headed UI on a workstation with an X server already running:
```
npx playwright test --ui
```

Using the project's E2E Docker image (recommended for parity with CI)

Rebuild/start the E2E container (this sets up the full test environment):
```
.github/skills/scripts/skill-runner.sh docker-rebuild-e2e
```
Run the UI against the container (you still need an X server on your host):
```
PLAYWRIGHT_BASE_URL=http://localhost:8080 npm run e2e:ui:headless-server
```

CI guidance

Do not run Playwright --ui in CI. Use headless runs or the E2E Docker image and collect traces/videos for failures.
For coverage, use the provided skill: .github/skills/scripts/skill-runner.sh test-e2e-playwright-coverage

Troubleshooting

Playwright error: "Looks like you launched a headed browser without having a XServer running." → run npm run e2e:ui:headless-server or install Xvfb.
If npm run e2e:ui:headless-server fails with an exit code like 148:
- Inspect Xvfb logs: tail -n 200 /tmp/xvfb.playwright.log
- Ensure no permission issues on /tmp/.X11-unix: ls -la /tmp/.X11-unix
- Try starting Xvfb manually: Xvfb :99 -screen 0 1280x720x24 & then export DISPLAY=:99 and re-run npx playwright test --ui.
If running inside Docker, prefer the skill-runner which provisions the required services; the UI still needs host X (or use VNC).

Developer notes (what we changed)

Added scripts/run-e2e-ui.sh — wrapper that auto-starts Xvfb when DISPLAY is unset.
Added npm run e2e:ui:headless-server to run the Playwright UI on headless machines.
Playwright config now auto-starts Xvfb when --ui is requested locally and prints an actionable error if Xvfb is not available.

Security & hygiene

Playwright auth artifacts are ignored by git (playwright/.auth/). Do not commit credentials.

If you'd like, I can open a PR with these changes (scripts + config + docs) and add a short CI note to .github/ workflows.

2.7 KiB Raw Blame History