=========
pytest-qt
=========

pytest-qt is a `pytest`_ plugin that allows programmers to write tests
for `PyQt5`_, `PyQt6`_, `PySide2`_ and `PySide6`_ applications.

The main usage is to use the ``qtbot`` fixture, responsible for handling ``qApp``
creation as needed and provides methods to simulate user interaction,
like key presses and mouse clicks:


.. code-block:: python

    def test_hello(qtbot):
        widget = HelloWidget()
        qtbot.addWidget(widget)

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

        assert widget.greet_label.text() == "Hello!"


.. _PySide2: https://pypi.org/project/PySide2/
.. _PySide6: https://pypi.org/project/PySide6/
.. _PyQt5: https://pypi.org/project/PyQt5/
.. _PyQt6: https://pypi.org/project/PyQt6/
.. _pytest: http://pytest.org

This allows you to test and make sure your view layer is behaving the way you expect after each code change.

`Supported Python versions <https://pypi.python.org/pypi/pytest-qt/>`_
`conda-forge <https://anaconda.org/conda-forge/pytest-qt>`_
`ci <https://github.com/pytest-dev/pytest-qt/actions>`_
`test coverage<https://coveralls.io/r/pytest-dev/pytest-qt>`_
`docs <https://pytest-qt.readthedocs.io>`_


Features
========

- `qtbot`_ fixture to simulate user interaction with ``Qt`` widgets.
- `Automatic capture`_ of ``qDebug``, ``qWarning`` and ``qCritical`` messages;
- waitSignal_ and waitSignals_ functions to block test execution until specific
  signals are emitted.
- `Exceptions in virtual methods and slots`_ are automatically captured and
  fail tests accordingly.

.. _qtbot: https://pytest-qt.readthedocs.io/en/latest/reference.html#module-pytestqt.qtbot
.. _Automatic capture: https://pytest-qt.readthedocs.io/en/latest/logging.html
.. _waitSignal: https://pytest-qt.readthedocs.io/en/latest/signals.html
.. _waitSignals: https://pytest-qt.readthedocs.io/en/latest/signals.html
.. _Exceptions in virtual methods and slots: https://pytest-qt.readthedocs.io/en/latest/virtual_methods.html

Requirements
============

Since version 4.0.0, ``pytest-qt`` requires Python 3.6+.

Works with either PySide6_, PySide2_, PyQt6_ or PyQt5_, picking whichever
is available on the system, giving preference to the first one installed in
this order:

- ``PySide6``
- ``PySide2``
- ``PyQt6``
- ``PyQt5``

To force a particular API, set the configuration variable ``qt_api`` in your ``pytest.ini`` file to
``pyqt6``, ``pyside2``, ``pyqt6`` or ```pyqt5``:

.. code-block:: ini

    [pytest]
    qt_api=pyqt5


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).
