Troubleshooting

tox: InvocationError without further information

It might happen that your tox run finishes abruptly without any useful information, e.g.:

ERROR: InvocationError:
'/path/to/project/.tox/py36/bin/python setup.py test --addopts --doctest-modules'
___ summary _____
ERROR: py36: commands failed

pytest-qt needs a DISPLAY to run, otherwise Qt calls abort() and the process crashes immediately.

One solution is to use the pytest-xvfb plugin which takes care of the grifty details automatically, starting up a virtual framebuffer service, initializing variables, etc. This is the recommended solution if you are running in CI servers without a GUI, for example in Travis or CircleCI.

Alternatively, tox users may edit tox.ini to allow the relevant variables to be passed to the underlying pytest invocation:

[testenv]
passenv = DISPLAY XAUTHORITY

Note that this solution will only work in boxes with a GUI.

More details can be found in issue #170.

xvfb: AssertionError, TimeoutError when using waitUntil, waitExposed and UI events.

When using xvfb or equivalent make sure to have a window manager running otherwise UI events will not work properly.

If you are running your code on Travis-CI make sure that your .travis.yml has the following content:

sudo: required

before_install:
  - sudo apt-get update
  - sudo apt-get install -y xvfb herbstluftwm

install:
  - "export DISPLAY=:99.0"
  - "/sbin/start-stop-daemon --start --quiet --pidfile /tmp/custom_xvfb_99.pid --make-pidfile --background --exec /usr/bin/Xvfb -- :99 -screen 0 1920x1200x24 -ac +extension GLX +render -noreset"
  - sleep 3

before_script:
  - "herbstluftwm &"
  - sleep 1

More details can be found in issue #206.

GitHub Actions

When using ubuntu-latest on Github Actions, the package libxkbcommon-x11-0 has to be installed, DISPLAY should be set and xvfb run. More details can be found in issue #293.

Since Qt in version 5.15 xcb libraries are not distributed with Qt so this library in version at least 1.11 on runner. See more in https://codereview.qt-project.org/c/qt/qtbase/+/253905

For Github Actions, Azure pipelines and Travis-CI you will need to install libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-xinerama0 libxcb-xfixes0 x11-utils

As an example, here is a working config :

name: my qt ci in github actions
on: [push, pull_request]
jobs:
  Linux:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os : [ubuntu-latest]
        python: ["3.10"]
    env:
      DISPLAY: ':99.0'
    steps:
    - name: get repo
      uses: actions/checkout@v3
    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: ${{ matrix.python }}
    - name: setup ${{ matrix.os }}
      run: |
        sudo apt install libxkbcommon-x11-0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-xinerama0 libxcb-xfixes0 x11-utils
        /sbin/start-stop-daemon --start --quiet --pidfile /tmp/custom_xvfb_99.pid --make-pidfile --background --exec /usr/bin/Xvfb -- :99 -screen 0 1920x1200x24 -ac +extension GLX

tlambert03/setup-qt-libs

Instead manually curate list of used packages you may use tlambert03/setup-qt-libs github action: https://github.com/tlambert03/setup-qt-libs

pytest-xvfb

Instead of running Xvfb manually it is possible to use pytest-xvfb plugin.