pytest-xvfb

A pytest plugin to run Xvfb_ (or Xephyr/Xvnc) for tests.

Installation

You can install "pytest-xvfb" via pip from PyPI_::

$ pip install pytest-xvfb

Usage

With Xvfb and the plugin installed, your testsuite automatically runs with Xvfb_. This allows tests to be run without windows popping up during GUI tests or on systems without a display (like a CI).

The plugin sees Xvfb being installed as "optional", since the tests can still run without it installed. If it's unavailable, it will show an informational message, if on Linux and a DISPLAY is available. When using --xvfb-backend xvfb, this message will turn into a hard error instead.

If you're currently using xvfb-run in something like a GitHub Actions YAML file simply remove the wrapper and install this plugin instead - then you'll also have the benefits of Xvfb locally.

Features

You can pass --no-xvfb to explicitly turn off Xvfb (e.g. to visually inspect a failure).

With --xvfb-backend xephyr or --xvfb-backend xvnc, you can use Xephyr or Xvnc in place of Xvfb, e.g. to visually inspect failures.

NOTE: Support for xvnc is currently experimental and not tested on CI, due to incompatibilities with PyVirtualDisplay and Ubuntu 22.04's tightvncserver.

You can mark tests with @pytest.mark.no_xvfb to skip them when they're running with Xvfb.

A xvfb fixture is available with the following attributes:

• width: The configured width of the screen.
• height: The configured height of the screen.
• colordepth: The configured colordepth of the screen.
• args: The arguments to be passed to Xvfb.
• display: The display number (as int) which is used.
• backend: Either None (Xvfb), "xvfb", "xephyr", or "xvnc".

In a pytest.ini, xvfb_width, xvfb_height, xvfb_colordepth and xvfb_args can be used to configure the respective values. In addition, xvfb_xauth can be set to true to generate an Xauthority token.

Contributing

Contributions are very welcome. Tests can be run with tox_, please ensure the coverage at least stays the same before you submit a pull request.

License

Distributed under the terms of the MIT_ license, "pytest-xvfb" is free and open source software

Thanks

This pytest_ plugin was generated with Cookiecutter_ along with @hackebrot's Cookiecutter-pytest-plugin template.

Thanks to @cgoldberg_ for xvfbwrapper_ which was the inspiration for this project.

Issues

If you encounter any problems, please file an issue_ along with a detailed description.

.. _pytest-xvfb: https://pypi.python.org/pypi/pytest-xvfb/ .. _Cookiecutter: https://github.com/audreyr/cookiecutter .. _@hackebrot: https://github.com/hackebrot .. _@cgoldberg: https://github.com/cgoldberg .. _xvfbwrapper: https://github.com/cgoldberg/xvfbwrapper .. _MIT: http://opensource.org/licenses/MIT .. _cookiecutter-pytest-plugin: https://github.com/pytest-dev/cookiecutter-pytest-plugin .. _file an issue: https://github.com/The-Compiler/pytest-xvfb/issues .. _pytest: https://github.com/pytest-dev/pytest .. _tox: https://tox.readthedocs.org/en/latest/ .. _pip: https://pypi.python.org/pypi/pip/ .. _PyPI: https://pypi.python.org/pypi .. _Xvfb: https://en.wikipedia.org/wiki/Xvfb .. _Xephyr: https://www.freedesktop.org/wiki/Software/Xephyr/ .. _Xvnc: https://tigervnc.org/doc/Xvnc.html