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.

By implementing the pytest_xvfb_disable(config: pytest.Config) pytest hook,
you can dynamically decide whether pytest-xvfb should be disabled (by returning
True from such a hook).

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

Dependencies of pytest-xvfb (2).
Dependency	Optional
pytest	false
pyvirtualdisplay	false

Package profile

pytest-xvfb

Releases

Release table

PyPI Downloads

Dependencies

Details

Project URLs

Dependencies

Package description