{"id":8546,"library":"pytest-xvfb","title":"pytest-xvfb","description":"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.","status":"active","version":"3.1.1","language":"en","source_language":"en","source_url":"https://github.com/The-Compiler/pytest-xvfb","tags":["pytest","testing","headless","gui","xvfb","ci","plugin"],"install":[{"cmd":"pip install pytest-xvfb","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Core testing framework that pytest-xvfb extends.","package":"pytest","optional":false},{"reason":"Python wrapper for Xvfb, Xephyr, and Xvnc, used by pytest-xvfb to manage virtual displays.","package":"pyvirtualdisplay","optional":false},{"reason":"System dependency (X virtual framebuffer) which provides the virtual display server. Must be installed separately via system package manager (e.g., apt, yum).","package":"xvfb","optional":true},{"reason":"System dependency for an alternative virtual display backend. Must be installed separately.","package":"xephyr","optional":true},{"reason":"System dependency for the Xvnc virtual display backend. Must be installed separately for 'xvnc' backend.","package":"tightvncserver","optional":true}],"imports":[{"note":"Decorator to skip a test when running with pytest-xvfb enabled.","symbol":"pytest.mark.no_xvfb","correct":"import pytest; @pytest.mark.no_xvfb"},{"note":"The 'xvfb' fixture is automatically available in tests to provide information about the virtual display.","symbol":"xvfb fixture","correct":"def test_something(xvfb): ..."}],"quickstart":{"code":"import pytest\nimport os\n\ndef test_gui_app_runs_headless(xvfb):\n    # The test automatically runs with Xvfb started by pytest-xvfb\n    # The 'xvfb' fixture provides details about the virtual display.\n    print(f\"\\nRunning on virtual display: {xvfb.display}\")\n    print(f\"Screen resolution: {xvfb.width}x{xvfb.height}x{xvfb.colordepth}\")\n    # Example: Run a simple command that needs a display\n    # In a real scenario, you'd launch your GUI application here\n    # and perform assertions.\n    # For demonstration, we'll just check DISPLAY environment variable\n    assert os.environ.get('DISPLAY') == f':{xvfb.display}', 'DISPLAY environment variable not set correctly.'\n\n@pytest.mark.no_xvfb\ndef test_this_runs_without_xvfb():\n    # This test will explicitly not use Xvfb, even if enabled.\n    assert 'DISPLAY' not in os.environ\n","lang":"python","description":"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."},"warnings":[{"fix":"Prefer `xvfb` or `xephyr` backends for production CI environments. Check GitHub issues for current status if `xvnc` is critical.","message":"The `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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":"All versions"},{"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).","message":"If 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Using 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install `pytest-xvfb` and ensure `xvfb` (the system package) is installed. `pytest-xvfb` will automatically provide a virtual display for your tests. Command: `pip install pytest-xvfb` then `sudo apt-get install xvfb` (or equivalent for your OS).","cause":"GUI tests (e.g., using PyQt/PySide with pytest-qt) are being run in an environment without an active X display server, causing the Qt application to crash.","error":"pytest-qt needs a DISPLAY to run, otherwise Qt calls abort() and the process crashes immediately."},{"fix":"Integrate `pytest-xvfb` into your `tox` environment. Ensure `pytest-xvfb` is installed in the testenv and that `xvfb` is available on the system. You might need to add `passenv = DISPLAY XAUTHORITY` to your `tox.ini` if not automatically handled.","cause":"Similar to the 'DISPLAY' issue, `tox` runs often occur in headless environments. If the tests involve GUI components, the lack of a display server causes an unhandled error, leading to a generic `InvocationError`.","error":"ERROR: InvocationError: '/path/to/project/.tox/py36/bin/python setup.py test --addopts --doctest-modules' ___ summary _____ ERROR: py36: commands failed"},{"fix":"Start a lightweight window manager (e.g., `herbstluftwm`) within your CI environment before starting tests. For example, in a `.travis.yml` or similar CI config: `sudo apt-get install -y xvfb herbstluftwm` and then launch `herbstluftwm &` after Xvfb starts.","cause":"When running GUI tests with Xvfb, UI events (like button clicks, window exposures) may not propagate correctly if a window manager is not active within the virtual display.","error":"AssertionError: assert False + where False = hasattr('hello', 'check') (or similar for UI events). / TimeoutError when using waitUntil, waitExposed and UI events."},{"fix":"Investigate the logs of the GUI application itself for errors that might be causing the X server to terminate. Ensure system resources (memory, CPU) are sufficient for Xvfb and the application. If using `xvfb-run`, add `--error-file=` to capture Xvfb's stderr for more diagnostic information. Consider updating `pytest-xvfb` and `pyvirtualdisplay` as they manage Xvfb more robustly.","cause":"The application being tested crashed the Xvfb server itself, often due to an unhandled X error or resource issue, rather than the test framework failing. This can be masked if using an `xvfb-run` wrapper.","error":"Xvfb IO Error: client killed"}]}