pytest-qt

What it is and what it does

pytest-qt bridges pytest and Qt application testing by providing the qtbot fixture, which manages Qt application lifecycle and exposes methods to simulate user interactions like mouse clicks and key presses. It also captures Qt debug/warning/critical messages automatically and provides waitSignal/waitSignals functions to block tests until specific signals are emitted, plus automatic exception handling in virtual methods and slots.

The plugin auto-detects which Qt library (PySide6, PyQt6, or PyQt5) is available or already imported, or lets you force a choice via pytest.ini or environment variable. It's designed for developers who need to verify that the view layer of a Qt application behaves correctly after code changes, without requiring manual GUI interaction.

Use it for:

• Test button clicks and user input on PyQt5/PyQt6/PySide6 widgets to verify UI state changes.
• Verify that Qt signals are emitted at the right time using waitSignal/waitSignals in your test suite.
• Capture and assert on qDebug, qWarning, and qCritical messages emitted during widget operations.
• Validate exception handling in Qt virtual methods and slots by letting pytest-qt catch and report them.
• Automate GUI regression testing in CI pipelines by simulating user interactions programmatically.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

pytest-qt is a pytest plugin that provides fixtures and utilities to test PyQt5, PyQt6, and PySide6 applications, including widget interaction simulation and signal handling.

Yes. pytest-qt is production-stable (since 2013), actively maintained, has no known vulnerabilities, and installs with low friction. Install it if you're testing PyQt or PySide applications and want pytest-native fixtures for widget interaction and signal handling. The only prerequisite is having one of PyQt5, PyQt6, or PySide6 already available.

Install

pytest-qt on PyPI

pip install pytest-qt

uv add pytest-qt

poetry add pytest-qt

Installing pytest-qt

Before you install

Low friction install with stable maintenance: the package is actively maintained (last commit 2026-08-03), has been in production since 2013, and depends only on pytest, pluggy, and typing_extensions—all widely available.

License in practice

MIT license is permissive; you can use this package in commercial or proprietary projects with minimal restrictions, provided you include the license notice.

Quickstart

pip install pytest-qt

# In your test file:
def test_widget(qtbot):
    widget = MyWidget()
    qtbot.addWidget(widget)
    qtbot.mouseClick(widget.button, qt_api.QtCore.Qt.MouseButton.LeftButton)

Requires PyQt5, PyQt6, or PySide6 to be installed separately; pytest-qt will auto-detect or you can set qt_api in pytest.ini or PYTEST_QT_API environment variable.

Verify before relying

• Whether the package handles headless/CI environments without additional configuration beyond pytest-xvfb.
• Performance characteristics when testing large widget hierarchies or many signals.
• Compatibility guarantees across PyQt5/PyQt6/PySide6 API differences in test code.

Package facts

Evidence: pytest_qt-4.5.0-py3-none-any.whl

Keywords: pytest, qt, test, unittest

Tags

More Testing packages