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, Azure pipelines, Travis-CI and GitLab CI/CD

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 issues #293 and #550.

To resolve any missing dll issue with docker-windows base gitlab runner it is recommanded to use an image based on mcr.microsoft.com/windows/server and not servercore (docker hub python official images are based on servercore). Setting QT_QPA_PLATFORM environment variable to offscreen may also be helpfull.

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

Since Qt in version 6.5 xcb-cursor0 is a requirement. See all Qt6 requirements in https://doc.qt.io/qt-6/linux-requirements.html

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

You might need to install libgl1 libegl1 libdbus-1-3 as well.

As an example, here is a working Github Actions 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

And here is a working Qt6 GitLab CI/CD config :

variables:
  DISPLAY: ':99.0'

test:
  stage: test
  image: python:3.11
  script:
    - apt update
    - apt install -y libgl1 libegl1 libdbus-1-3 libxcb-cursor0 libxkbcommon-x11-0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-xinerama0 libxcb-xfixes0 x11-utils xvfb
    - /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
    - python -m pip install pyqt6 pytest-qt

    - python -m pytest test.py

And here is a working Qt6 Azure Pipelines CI/CD config for ubuntu-latest :

# Set these environment variables for the job that runs tests

variables:
  DISPLAY: ':99.0'  # This is needed for pytest-qt not to crash as mentioned above
  # Python fault handler is enabled in case UI tests crash without meaningful error messages
  PYTHONFAULTHANDLER: 'enabled'  # https://docs.python.org/3/library/faulthandler.html

# Add this step to your CI pipeline before running your pytest-qt-based Qt6 tests with pytest

    # this was tested with ``ubuntu-latest`` image
    - script: |
        sudo apt update
        sudo apt-get install -y xvfb libxkbcommon-x11-0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-xinerama0 libxcb-xinput0 libxcb-xfixes0 libxcb-shape0 libglib2.0-0 libgl1-mesa-dev
        sudo apt-get install -y '^libxcb.*-dev' libx11-xcb-dev libglu1-mesa-dev libxrender-dev libxi-dev libxkbcommon-dev libxkbcommon-x11-dev
        sudo apt-get install -y 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
      displayName: 'Install and start xvfb and other dependencies on Linux for Qt GUI tests'
      condition: and(succeededOrFailed(), eq(variables['Agent.OS'], 'Linux'))

# After this step, assuming you have ``pytest-qt`` installed, just run ``pytest`` and your PyQt6 tests will work

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.

Using with other Qt-related packages

Using Python’s Qt modules (PySide or PyQt5) with other packages which use Qt (e.g. cv2) can result in conflicts. This is because the latter builds their own Qt and modify Qt-related environment variables. This may not raise errors in your local app, but running the tests on CI servers can fail.

In this case, try use the package without Qt dependency. For example, if your code does not rely on cv2’s Qt feature you can use opencv-python-headless instead of full opencv-python.

More details can be found in issue #396.