pytest-qt is a pytest plugin that provides fixtures to help programmers write tests for PySide and PyQt.

The main usage is to use the qtbot fixture, which provides methods to simulate user interaction, like key presses and mouse clicks:

def test_hello(qtbot):
    widget = HelloWidget()

    # click in the Greet button and make sure it updates the appropriate label
    qtbot.mouseClick(window.button_greet, QtCore.Qt.LeftButton)

    assert window.greet_label.text() == 'Hello!'


Python 2.7 or later, including Python 3.4+.

Requires pytest version 2.7 or later.

Works with either PyQt5, PyQt4, PySide or PySide2, picking whichever is available on the system giving preference to the first one installed in this order:

  • PySide2
  • PyQt5
  • PySide
  • PyQt4

To force a particular API, set the configuration variable qt_api in your pytest.ini file to pyqt5, pyside, pyside2, pyqt4 or pyqt4v2. pyqt4v2 sets the PyQt4 API to version 2.


Alternatively, you can set the PYTEST_QT_API environment variable to the same values described above (the environment variable wins over the configuration if both are set).

From pytest-qt version 2 the behaviour of pyqt4v2 has changed, as explained in A note about pyqt4v2.


The package may be installed by running:

pip install pytest-qt

Or alternatively, download the package from pypi, extract and execute:

python install

Both methods will automatically register it for usage in pytest.


If you intend to develop pytest-qt itself, use virtualenv to activate a new fresh environment and execute:

git clone
cd pytest-qt
pip install -e .  # or python develop
pip install pyside # or pyqt4/pyqt5

If you also intend to build the documentation locally, you can make sure to have all the needed dependences executing:

pip install -e .[doc]


This projects follows semantic versioning.