pytest-xvfb

library3.1.1pypypi✓ verified 85d ago

pytest-xvfb is an active pytest plugin, currently at version 3.1.1, that automatically runs tests within a virtual X server like Xvfb, Xephyr, or Xvnc. This enables running graphical user interface (GUI) tests in headless environments, such as continuous integration (CI) servers, without the need for a physical display, preventing windows from unexpectedly popping up during testing.

testing

pip install pytest-xvfb

github ↗package ↗

INSTALL

IMPORT

SIG · PYTEST-XVFB

pytest-xvfb

testingpythonv3.1.1

Install

2.7s avg

Import

—

Disk

29MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.1.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.000s · 30.9MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.7s · import 0.000s · 31MB

29MB installed

● package 29MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Xvfb

✓ from pytest_xvfb import Xvfb

✗ import pytest; @pytest.mark.no_xvfb

xvfb

✓ from pytest_xvfb import xvfb

pytest_addhooks

✓ from pytest_xvfb import pytest_addhooks

To use `pytest-xvfb`, simply install it and `pytest`. For most use cases, tests that require a display will automatically run in a virtual framebuffer when `pytest-xvfb` is installed and a suitable backend (like `xvfb` or `xephyr`) is available on the system. You can access the `xvfb` fixture in your tests to get details about the virtual display, or use `@pytest.mark.no_xvfb` to explicitly disable the plugin for a specific test.

import pytest import os def test_gui_app_runs_headless(xvfb): # The test automatically runs with Xvfb started by pytest-xvfb # The 'xvfb' fixture provides details about the virtual display. print(f"\nRunning on virtual display: {xvfb.display}") print(f"Screen resolution: {xvfb.width}x{xvfb.height}x{xvfb.colordepth}") # Example: Run a simple command that needs a display # In a real scenario, you'd launch your GUI application here # and perform assertions. # For demonstration, we'll just check DISPLAY environment variable assert os.environ.get('DISPLAY') == f':{xvfb.display}', 'DISPLAY environment variable not set correctly.' @pytest.mark.no_xvfb def test_this_runs_without_xvfb(): # This test will explicitly not use Xvfb, even if enabled. assert 'DISPLAY' not in os.environ

Debug

Known issues

gotchaThe `xvnc` backend is currently experimental and may not be fully stable or tested on all CI environments, especially with newer Ubuntu versions and `PyVirtualDisplay` incompatibilities.

fix

Prefer `xvfb` or `xephyr` backends for production CI environments. Check GitHub issues for current status if `xvnc` is critical.

affects: All versions

gotchaWhen using `xvfb` or `xephyr`, ensure a window manager is running for UI events to function properly within your GUI applications being tested. Without a window manager, certain UI interactions (like clicks or keyboard inputs) might not be registered correctly.

fix

Install and start a lightweight window manager (e.g., `herbstluftwm`) in your CI setup before running tests, especially for complex GUI interactions. Refer to `pytest-qt` documentation for examples.

affects: All versions

gotchaIf the underlying `xvfb` system package is not installed on the testing environment, `pytest-xvfb` will issue an informational message. However, if you explicitly use the `--xvfb-backend xvfb` option without the `xvfb` system package, it will result in a hard error.

fix

Ensure `xvfb` (and optionally `xephyr` or `tightvncserver` for other backends) is installed on your system or CI runner via its package manager (e.g., `sudo apt-get install xvfb` on Debian/Ubuntu).

affects: All versions

gotchaUsing Python's Qt modules (PySide or PyQt) with other packages that also link against Qt (e.g., some `cv2` builds) can lead to conflicts in CI environments due to differing Qt versions or environment variables, which may cause tests to fail.

fix

Isolate your test environments as much as possible. Consider dedicated Docker images for CI with specific Qt/GUI library versions, or try to use `--xvfb-backend xephyr` if it helps isolate the display server.

affects: All versions

Upgrade

Version history

3.1.1latest on PyPI · released Mar 12, 2025

Audit

Dependencies

pytestrequiredCore testing framework that pytest-xvfb extends.

pyvirtualdisplayrequiredPython wrapper for Xvfb, Xephyr, and Xvnc, used by pytest-xvfb to manage virtual displays.

xvfboptionalSystem dependency (X virtual framebuffer) which provides the virtual display server. Must be installed separately via system package manager (e.g., apt, yum).

xephyroptionalSystem dependency for an alternative virtual display backend. Must be installed separately.

tightvncserveroptionalSystem dependency for the Xvnc virtual display backend. Must be installed separately for 'xvnc' backend.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/The-Compiler/pytest-xvfb ↗

packagehttps://pypi.org/project/pytest-xvfb/ ↗