How to Run Electron App Tests in CI (Xvfb)

Electron is a real desktop GUI app, so on a headless Linux runner it has no screen to draw on. A virtual display plus the right libraries makes it testable.

Unlike a headless browser, Electron always wants a display server. CI runners have none, so you run Electron under Xvfb (a virtual framebuffer) and install the GUI shared libraries Chromium needs underneath.

Why it fails in CI

Electron exits with Missing X server or $DISPLAY or The futex facility returned an unexpected error code on a headless runner because there is no display. On slim images it also fails to load the GTK/NSS libraries, the same family of libnss3/libgbm1 errors that hit Chrome.

Install & run it reliably

Install Xvfb plus Electron’s libraries and run the test command under a virtual display. xvfb-run allocates and tears down the display for you:

electron tests under Xvfb

apt-get update && apt-get install -y \
  xvfb libnss3 libgbm1 libasound2 \
  libgtk-3-0 libxss1 libxtst6

xvfb-run --auto-servernum --server-args='-screen 0 1280x1024x24' \
  npm test

Sandbox & launch flags

Inside a container as root, Electron’s Chromium sandbox fails like any Chrome process. Pass --no-sandbox to the app (e.g. through your test runner’s launch args) or run the container with the proper sandbox privileges. Tools like Playwright’s Electron support and electron-mocha accept these flags. Cache the Electron binary (~/.cache/electron) and any prebuilt native modules keyed on the Electron version to skip the per-run download and addon rebuild, and reuse one Xvfb display for the whole suite.

Common errors

Missing X server or $DISPLAY → run under xvfb-run.
No usable sandbox! → pass --no-sandbox to the Electron app.
error while loading shared libraries: libnss3.so → install the GUI lib list.
Hangs with no output → the display never came up; check Xvfb started.

Key takeaways

Electron needs a virtual display - wrap the test command in xvfb-run.
Install Electron’s Chromium GUI libraries on slim runners.
Pass --no-sandbox in root containers and cache ~/.cache/electron.