pytest-qt

https://pytest-qt.readthedocs.io/en/latest/
Admin
pytest-qt is a pytest plugin that provides tools and fixtures for testing Qt applications, including...
Tokens:38,776
Snippets:368
Trust Score:8.3
Update:2 months ago
Show doc for...
Tokens:
Raw
### Configure GitHub Actions for Qt CI

Source: https://pytest-qt.readthedocs.io/en/latest/troubleshooting.html

Example configuration for running Qt tests on ubuntu-latest, including dependency installation and Xvfb setup.

```yaml
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
```

--------------------------------

### Install Dependencies and Start Xvfb

Source: https://pytest-qt.readthedocs.io/en/latest/_sources/troubleshooting.rst.txt

Install necessary Xvfb and Qt dependencies on Linux and start the Xvfb server. This is crucial for running GUI tests in CI environments.

```bash
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
```

```bash
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
```

--------------------------------

### Configure Travis-CI for Xvfb

Source: https://pytest-qt.readthedocs.io/en/latest/troubleshooting.html

Includes the necessary steps to install Xvfb and a window manager, and start the display server before running tests.

```yaml
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
```

--------------------------------

### Install pytest-qt and Run Tests

Source: https://pytest-qt.readthedocs.io/en/latest/_sources/troubleshooting.rst.txt

Install pytest-qt and run your tests. Ensure all dependencies are met before execution.

```bash
python -m pip install pyqt6 pytest-qt
python -m pytest test.py
```

--------------------------------

### Basic Test Setup Without waitUntil

Source: https://pytest-qt.readthedocs.io/en/latest/_sources/wait_until.rst.txt

This example shows a test that might fail due to the asynchronous nature of GUI events. It sets text, focuses an edit widget, and asserts the status label's text, but the focus event might not be processed immediately.

```python
def test_validate(qtbot):
    window = MyWindow()
    window.edit.setText("not a number")
    # after focusing, should update status label
    window.edit.setFocus()
    assert window.status.text() == "Please input a number"
```

--------------------------------

### Configure Azure Pipelines for Qt6

Source: https://pytest-qt.readthedocs.io/en/latest/troubleshooting.html

Pipeline step for installing dependencies and starting Xvfb on Linux agents.

```yaml
# 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'))
```

--------------------------------

### GitHub Actions configuration for xvfb and Qt dependencies

Source: https://pytest-qt.readthedocs.io/en/latest/_sources/troubleshooting.rst.txt

This GitHub Actions workflow configures an Ubuntu environment for testing Qt applications. It installs necessary XCB libraries, sets the DISPLAY variable, and starts Xvfb for headless operation.

```yaml
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
```

--------------------------------

### Manage test setup exception capture

Source: https://pytest-qt.readthedocs.io/en/latest/_modules/pytestqt/plugin.html

Wraps the test setup phase to initialize exception capture and process events.

```python
@pytest.hookimpl(wrapper=True, tryfirst=True)
def pytest_runtest_setup(item):
    """
    Hook called after before test setup starts, to start capturing exceptions
    as early as possible.
    """
    capture_enabled = _is_exception_capture_enabled(item)
    if capture_enabled:
        item.qt_exception_capture_manager = _QtExceptionCaptureManager()
        item.qt_exception_capture_manager.start()
    result = yield
    _process_events()
    if capture_enabled:
        item.qt_exception_capture_manager.fail_if_exceptions_occurred("SETUP")
    return result
```

--------------------------------

### Run pytest command

Source: https://pytest-qt.readthedocs.io/en/latest/_sources/logging.rst.txt

Example of running pytest from the command line with specific options.

```bash
pytest test.py --color=no -q
```

--------------------------------

### Basic Find Files Test Setup

Source: https://pytest-qt.readthedocs.io/en/latest/_sources/tutorial.rst.txt

Sets up a test function using the qtbot fixture and pytest's tmp_path to create test files. The qtbot fixture automatically handles QApplication creation.

```python
def test_basic_search(qtbot, tmp_path):
    """
    test to ensure basic find files functionality is working.
    """
    tmp_path.joinpath("video1.avi").touch()
    tmp_path.joinpath("video1.srt").touch()

    tmp_path.joinpath("video2.avi").touch()
    tmp_path.joinpath("video2.srt").touch()
```

--------------------------------

### Configure GitLab CI/CD for Qt6

Source: https://pytest-qt.readthedocs.io/en/latest/troubleshooting.html

Pipeline configuration for Qt6 tests, ensuring all required XCB and GL libraries are installed.

```yaml
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
```

--------------------------------

### Travis CI configuration for xvfb

Source: https://pytest-qt.readthedocs.io/en/latest/_sources/troubleshooting.rst.txt

This configuration sets up Travis CI to use xvfb, a virtual framebuffer, and a window manager (herbstluftwm) to ensure UI events work correctly in a headless environment. It includes installing necessary packages and starting Xvfb.

```yaml
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
```

--------------------------------

### Manage exception capturing

Source: https://pytest-qt.readthedocs.io/en/latest/_modules/pytestqt/exceptions.html

The _QtExceptionCaptureManager class handles the installation and removal of sys.excepthook to intercept exceptions.

```python
class _QtExceptionCaptureManager:
    """
    Manages exception capture context.
    """

    def __init__(self):
        self.old_hook = None
        self.exceptions = []

    def start(self):
        """Start exception capturing by installing a hook into sys.excepthook
        that records exceptions received into ``self.exceptions``.
        """
        self.old_hook = sys.excepthook
        sys.excepthook = functools.partial(_except_hook, exceptions=self.exceptions)

    def finish(self):
        """Stop exception capturing, restoring the original hook.

        Can be called multiple times.
        """
        if self.old_hook is not None:
            sys.excepthook = self.old_hook
            self.old_hook = None

    def fail_if_exceptions_occurred(self, when):
        """calls pytest.fail() with an informative message if exceptions
        have been captured so far. Before pytest.fail() is called, also
        finish capturing.
        """
        if self.exceptions:
            self.finish()
            exceptions = self.exceptions
            self.exceptions = []
            prefix = "%s ERROR: " % when
            msg = prefix + format_captured_exceptions(exceptions)
            del exceptions[:]  # Don't keep exceptions alive longer.
            if hasattr(sys, "last_exc"):
                sys.last_exc = None
            pytest.fail(msg, pytrace=False)
```

--------------------------------

### View Qt exception failure output

Source: https://pytest-qt.readthedocs.io/en/latest/changelog.html

Example of the error output displayed when an exception occurs within a virtual method during testing.

```text
E           Failed: Qt exceptions in virtual methods:
E           ________________________________________________________________________________
E             File "x:\pytest-qt\pytestqt\_tests\test_exceptions.py", line 14, in event
E               raise ValueError('mistakes were made')
E
E           ValueError: mistakes were made
E           ________________________________________________________________________________
E             File "x:\pytest-qt\pytestqt\_tests\test_exceptions.py", line 14, in event
E               raise ValueError('mistakes were made')
E
E           ValueError: mistakes were made
E           ________________________________________________________________________________
```

--------------------------------

### Test a PyQt/PySide Widget with qtbot

Source: https://pytest-qt.readthedocs.io/en/latest/_sources/intro.rst.txt

Use the `qtbot` fixture to interact with and test Qt widgets. This example demonstrates clicking a button and asserting a text change.

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

    # Click the greet button and make sure the appropriate label is updated.
    widget.button_greet.click()

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

--------------------------------

### Initialize and manage Qt log capture

Source: https://pytest-qt.readthedocs.io/en/latest/_modules/pytestqt/logging.html

The class handles the installation of a custom message handler and provides context management to temporarily disable capture.

```python
    def __init__(self, ignore_regexes):
        self._records = []
        self._ignore_regexes = ignore_regexes or []
        self._previous_handler = None

    def _start(self):
        """
        Start receiving messages from Qt.
        """
        previous_handler = qt_api.QtCore.qInstallMessageHandler(
            self._handle_with_context
        )
        self._previous_handler = previous_handler

    def _stop(self):
        """
        Stop receiving messages from Qt, restoring the previously installed
        handler.
        """
        qt_api.QtCore.qInstallMessageHandler(self._previous_handler)

    @contextmanager
    def disabled(self):
        """
        Context manager that temporarily disables logging capture while
        inside it.
        """
        self._stop()
        try:
            yield
        finally:
            self._start()
```

--------------------------------

### Tox InvocationError example

Source: https://pytest-qt.readthedocs.io/en/latest/troubleshooting.html

Example of an abrupt tox failure output when running tests.

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

--------------------------------

### Capture Qt Warning Message in Test

Source: https://pytest-qt.readthedocs.io/en/latest/_sources/logging.rst.txt

This example demonstrates how to trigger a Qt warning message within a test function. The captured message will be displayed if the test fails.

```python
from pytestqt.qt_compat import qt_api


def do_something():
    qt_api.qWarning("this is a WARNING message")


def test_foo():
    do_something()
    assert 0
```

--------------------------------

### Using qtbot.waitUntil with Boolean Callback

Source: https://pytest-qt.readthedocs.io/en/latest/_sources/wait_until.rst.txt

This example shows an alternative way to use qtbot.waitUntil with a callback that returns a boolean. The method waits until the callback returns True. This approach is often terser but results in a generic failure message if it times out.

```python
def test_validate(qtbot):
    window = MyWindow()
    window.edit.setText("not a number")
    # after focusing, should update status label
    window.edit.setFocus()
    qtbot.waitUntil(lambda: window.edit.hasFocus())
    assert window.status.text() == "Please input a number"
```

--------------------------------

### Take a screenshot of a widget

Source: https://pytest-qt.readthedocs.io/en/latest/_sources/debugging.rst.txt

Use `qtbot.screenshot()` to capture an image of a widget. The screenshot is saved to a temporary directory. This example intentionally fails the test to display the screenshot path.

```python
from pytestqt.qt_compat import qt_api


def test_screenshot(qtbot):
    button = qt_api.QtWidgets.QPushButton()
    button.setText("Hello World!")
    qtbot.add_widget(button)
    path = qtbot.screenshot(button)
    assert False, path  # show the path and fail the test
```

--------------------------------

### GitLab CI/CD configuration for Qt6

Source: https://pytest-qt.readthedocs.io/en/latest/_sources/troubleshooting.rst.txt

This GitLab CI/CD configuration uses a Python 3.11 Docker image and sets the DISPLAY variable. It includes apt update commands, which would typically be followed by package installations for Qt6 requirements.

```yaml
variables:
  DISPLAY: ':99.0'

test:
  stage: test
  image: python:3.11
  script:
    - apt update
```

--------------------------------

### Example of Captured Qt Messages on Test Failure

Source: https://pytest-qt.readthedocs.io/en/latest/_sources/logging.rst.txt

This shows the output when a test fails and Qt messages are captured. The 'Captured Qt messages' section lists the emitted warnings.

```bash
$ pytest test.py -q
F
================================== FAILURES ===================================
_________________________________ test_types __________________________________

    def test_foo():
        do_something()
>       assert 0
E       assert 0

test.py:8: AssertionError
---------------------------- Captured Qt messages -----------------------------
QtWarningMsg: this is a WARNING message
1 failed in 0.01 seconds
```

--------------------------------

### Azure Pipelines CI/CD Configuration for Qt Tests

Source: https://pytest-qt.readthedocs.io/en/latest/_sources/troubleshooting.rst.txt

Configure Azure Pipelines to run Qt GUI tests on Linux. Sets the DISPLAY environment variable and installs necessary dependencies.

```yaml
variables:
  DISPLAY: ':99.0'
  PYTHONFAULTHANDLER: 'enabled'

# 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'))
```

--------------------------------

### Example Output of Test Failing on Critical Qt Message

Source: https://pytest-qt.readthedocs.io/en/latest/_sources/logging.rst.txt

This output demonstrates a test failure triggered by a critical Qt message. The failure report explicitly states that Qt messages with the configured level or above were emitted.

```bash
>pytest test.py --color=no -q
F
================================== FAILURES ===================================
__________________________________ test_foo ___________________________________
test.py:5: Failure: Qt messages with level CRITICAL or above emitted
---------------------------- Captured Qt messages -----------------------------
QtCriticalMsg: WM_PAINT failed
```

--------------------------------

### Implement QtLoggingPlugin for message capture

Source: https://pytest-qt.readthedocs.io/en/latest/_modules/pytestqt/logging.html

The QtLoggingPlugin installs a message handler before tests and appends captured logs to test reports if failures occur.

```python
from collections import namedtuple
from contextlib import contextmanager
import datetime
import re
from _pytest._code.code import TerminalRepr, ReprFileLocation
import pytest
from pytestqt.qt_compat import qt_api
from pytestqt.utils import get_marker


class QtLoggingPlugin:
    """
    Plugin responsible for installing a QtMessageHandler before each
    test and augment reporting if the test failed with the messages captured.
    """

    LOG_FAIL_OPTIONS = ["NO", "CRITICAL", "WARNING", "DEBUG", "INFO"]

    def __init__(self, config):
        self.config = config

    def pytest_runtest_setup(self, item):
        if get_marker(item, "no_qt_log"):
            return
        m = get_marker(item, "qt_log_ignore")
        if m:
            if not set(m.kwargs).issubset({"extend"}):
                raise ValueError(
                    "Invalid keyword arguments in {!r} for "
                    "qt_log_ignore mark.".format(m.kwargs)
                )
            if m.kwargs.get("extend", True):
                config_regexes = self.config.getini("qt_log_ignore")
                ignore_regexes = config_regexes + list(m.args)
            else:
                ignore_regexes = m.args
        else:
            ignore_regexes = self.config.getini("qt_log_ignore")
        item.qt_log_capture = _QtMessageCapture(ignore_regexes)
        item.qt_log_capture._start()

    @pytest.hookimpl(wrapper=True)
    def pytest_runtest_makereport(self, item, call):
        """Add captured Qt messages to test item report if the call failed."""
        report = yield
        if not hasattr(item, "qt_log_capture"):
            return report

        if call.when == "call":
            m = get_marker(item, "qt_log_level_fail")
            if m:
                log_fail_level = m.args[0]
            else:
                log_fail_level = self.config.getini("qt_log_level_fail")
            assert log_fail_level in QtLoggingPlugin.LOG_FAIL_OPTIONS

            # make test fail if any records were captured which match
            # log_fail_level
            if report.outcome != "failed":
                for rec in item.qt_log_capture.records:
                    is_modeltest_error = (
                        rec.context is not None
                        and rec.context.category == "qt.modeltest"
                        and rec.matches_level("WARNING")
                    )
                    if (
                        rec.matches_level(log_fail_level) and not rec.ignored
                    ) or is_modeltest_error:
                        report.outcome = "failed"
                        if report.longrepr is None:
                            report.longrepr = _QtLogLevelErrorRepr(
                                item, log_fail_level, is_modeltest_error
                            )
                        break

            # if test has failed, add recorded messages to its terminal
            # representation
            if not report.passed:
                long_repr = getattr(report, "longrepr", None)
                if hasattr(long_repr, "addsection"):  # pragma: no cover
                    log_format = self.config.getoption("qt_log_format")
                    context_format = None
                    if log_format is None:
                        context_format = "{rec.context.file}:{rec.context.function}:{rec.context.line}:\n"
                        log_format = "    {rec.type_name}: {rec.message}"

                    lines = []
                    for rec in item.qt_log_capture.records:
                        suffix = " (IGNORED)" if rec.ignored else ""

                        if (
                            rec.context is not None
                            and (
                                rec.context.file is not None
                                or rec.context.function is not None
                                or rec.context.line != 0
                            )
                            and context_format is not None
                        ):
                            context_line = context_format.format(rec=rec)
                            lines.append(context_line)
                        else:
                            log_format = log_format.lstrip()

                        line = log_format.format(rec=rec) + suffix
                        lines.append(line)
                    if lines:
                        long_repr.addsection("Captured Qt messages", "\n".join(lines))

            item.qt_log_capture._stop()
            del item.qt_log_capture
        return report


class _QtMessageCapture:
    """
    Captures Qt messages when its `handle` method is installed using
    qInstallMessageHandler, and stores them into `records` attribute.
    """
```

--------------------------------

### Using qtbot.waitUntil with Assertion Callback

Source: https://pytest-qt.readthedocs.io/en/latest/_sources/wait_until.rst.txt

This example demonstrates using qtbot.waitUntil with a callback function that contains an assertion. The callback is repeatedly called until the assertion passes or a timeout is reached. If a timeout occurs, a TimeoutError is raised.

```python
def test_validate(qtbot):
    window = MyWindow()
    window.edit.setText("not a number")
    # after focusing, should update status label
    window.edit.setFocus()

    def check_label():
        assert window.status.text() == "Please input a number"

    qtbot.waitUntil(check_label)
```

--------------------------------

### Use waitCallback for QtWebEngine JavaScript execution

Source: https://pytest-qt.readthedocs.io/en/latest/_sources/wait_callback.rst.txt

Use qtbot.waitCallback as a context manager to test Qt methods that take a callback. The code inside the 'with' block will execute, and the test will pause until the callback is invoked or a timeout occurs. This example demonstrates testing JavaScript execution in QWebEnginePage.

```python
def test_js(qtbot):
    page = QWebEnginePage()
    with qtbot.waitCallback() as cb:
        page.runJavaScript("1 + 1", cb)
    cb.assert_called_with(2)  # result of the last js statement
```

--------------------------------

### Widget Initialization and Registration

Source: https://pytest-qt.readthedocs.io/en/latest/_sources/tutorial.rst.txt

Initializes the widget under test, displays it, and registers it with qtbot. Registering widgets ensures they are properly closed after the test.

```python
window = Window()
window.show()
qtbot.addWidget(window)
```

--------------------------------

### qapp_args

Source: https://pytest-qt.readthedocs.io/en/latest/_modules/pytestqt/plugin.html

Fixture that provides the arguments used to initialize the QApplication.

```APIDOC
## fixture qapp_args

### Description
Provides the list of arguments passed to the QApplication constructor. This fixture can be overridden at the session scope to customize application arguments.

### Returns
- **list** - A list of strings representing command-line arguments.
```

--------------------------------

### Flaky test example without waitUntil

Source: https://pytest-qt.readthedocs.io/en/latest/wait_until.html

An example of a test that may fail due to asynchronous event loop processing.

```python
def test_validate(qtbot):
    window = MyWindow()
    window.edit.setText("not a number")
    # after focusing, should update status label
    window.edit.setFocus()
    assert window.status.text() == "Please input a number"
```

--------------------------------

### Define basic search test function

Source: https://pytest-qt.readthedocs.io/en/latest/tutorial.html

Initializes the test environment using the qtbot fixture and creates temporary files for testing.

```python
def test_basic_search(qtbot, tmp_path):
    """
    test to ensure basic find files functionality is working.
    """
    tmp_path.joinpath("video1.avi").touch()
    tmp_path.joinpath("video1.srt").touch()

    tmp_path.joinpath("video2.avi").touch()
    tmp_path.joinpath("video2.srt").touch()
```

--------------------------------

### QtTest interaction wrappers

Source: https://pytest-qt.readthedocs.io/en/latest/_modules/pytestqt/qtbot.html

Static methods wrapping QtTest functionality for key and mouse events.

```python
@staticmethod
def keyToAscii(key: Any) -> None:
    if not hasattr(qt_api.QtTest.QTest, "keyToAscii"):
        raise NotImplementedError("This method isn't available on PyQt5.")
    qt_api.QtTest.QTest.keyToAscii(key)
```

```python
@staticmethod
def mouseClick(*args, **kwargs):
    qt_api.QtTest.QTest.mouseClick(*args, **kwargs)
```

```python
@staticmethod
def mouseDClick(*args, **kwargs):
    qt_api.QtTest.QTest.mouseDClick(*args, **kwargs)
```

```python
@staticmethod
def mouseMove(*args, **kwargs):
    qt_api.QtTest.QTest.mouseMove(*args, **kwargs)
```

```python
@staticmethod
def mousePress(*args, **kwargs):
    qt_api.QtTest.QTest.mousePress(*args, **kwargs)
```

```python
@staticmethod
def mouseRelease(*args, **kwargs):
    qt_api.QtTest.QTest.mouseRelease(*args, **kwargs)
```

--------------------------------

### pytest-qt exception capture output

Source: https://pytest-qt.readthedocs.io/en/latest/virtual_methods.html

Example of the error report generated by pytest-qt when an exception occurs in a virtual method.

```text
E           Failed: Qt exceptions in virtual methods:
E           ________________________________________________________________________________
E             File "x:\pytest-qt\pytestqt\_tests\test_exceptions.py", line 14, in event
E               raise RuntimeError('unexpected error')
E
E           RuntimeError: unexpected error
```

--------------------------------

### Testing JavaScript execution with waitCallback

Source: https://pytest-qt.readthedocs.io/en/latest/wait_callback.html

Demonstrates using qtbot.waitCallback to handle a callback from QWebEnginePage.runJavaScript.

```python
def test_js(qtbot):
    page = QWebEnginePage()
    with qtbot.waitCallback() as cb:
        page.runJavaScript("1 + 1", cb)
    cb.assert_called_with(2)  # result of the last js statement
```

--------------------------------

### Timeout error output example

Source: https://pytest-qt.readthedocs.io/en/latest/wait_until.html

The error message displayed when a waitUntil condition fails to meet within the timeout period.

```text
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
    def check_label():
>       assert window.status.text() == "Please input a number"
E       AssertionError: assert 'OK' == 'Please input a number'
E         - OK
E         + Please input a number
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
>       qtbot.waitUntil(check_label)
E       pytestqt.exceptions.TimeoutError: waitUntil timed out in 1000 milliseconds
```

--------------------------------

### Using Custom Dialog Convenience Method

Source: https://pytest-qt.readthedocs.io/en/latest/_sources/note_dialogs.rst.txt

Demonstrates how clients can use the `ask` class method of a custom dialog to retrieve user input. This pattern simplifies the client code and prepares for testing.

```python
name, age = AskNameAndAgeDialog.ask("Enter name and age because of bananas:", parent)
if name is not None:
    # use name and age for bananas
    ...
```

--------------------------------

### qapp fixture

Source: https://pytest-qt.readthedocs.io/en/latest/_sources/reference.rst.txt

The `qapp` fixture provides an instance of `QApplication` or `QGuiApplication` for use in tests. It can also be configured using `qapp_args`.

```APIDOC
## qapp fixture

### Description
Provides an instance of `QApplication` or `QGuiApplication` for use in tests. This fixture is essential for any test that interacts with Qt's event loop or GUI elements.

### Usage
```python
def test_my_gui(qapp):
    # Use qapp here
    assert qapp is not None
```

## qapp_args fixture

### Description
Allows customization of the `QApplication` or `QGuiApplication` instance created by the `qapp` fixture. You can provide command-line arguments to the application.

### Usage
```python
@pytest.fixture
def qapp_args(request):
    return ['-no-xshm']

def test_with_custom_args(qapp):
    # qapp will be created with '-no-xshm' argument
    pass
```
```

--------------------------------

### Exception behavior in virtual methods

Source: https://pytest-qt.readthedocs.io/en/latest/virtual_methods.html

Example of an exception raised in a virtual method that results in a stack trace rather than a raised exception.

```python
class MyWidget(QWidget):
    def mouseReleaseEvent(self, ev):
        raise RuntimeError("unexpected error")


w = MyWidget()
QTest.mouseClick(w, QtCore.Qt.LeftButton)
```

--------------------------------

### qapp_cls

Source: https://pytest-qt.readthedocs.io/en/latest/_modules/pytestqt/plugin.html

Fixture that provides the QApplication subclass to be instantiated.

```APIDOC
## fixture qapp_cls

### Description
Provides the class used to instantiate the QApplication. Override this to use a custom QApplication subclass or QCoreApplication for non-GUI tests.

### Returns
- **class** - The class type to be used for the application instance.
```

--------------------------------

### Asserting signal non-emission with wait duration

Source: https://pytest-qt.readthedocs.io/en/latest/signals.html

Pass the wait parameter in milliseconds to account for asynchronous signals that might arrive after the block starts.

```python
def test_no_error(qtbot):
    ...
    with qtbot.assertNotEmitted(page.loadFinished, wait=100):
        page.runJavaScript("document.getElementById('not-a-link').click()")
```

--------------------------------

### QtBot Keyboard Simulation Methods

Source: https://pytest-qt.readthedocs.io/en/latest/_modules/pytestqt/qtbot.html

Methods for simulating keyboard input on Qt widgets, including key clicks, presses, and releases.

```APIDOC
## keyClick(widget, key, modifier=Qt.KeyboardModifier.NoModifier, delay=-1)
## keyClicks(widget, key_sequence, modifier=Qt.KeyboardModifier.NoModifier, delay=-1)
## keyEvent(action, widget, key, modifier=Qt.KeyboardModifier.NoModifier, delay=-1)
## keyPress(widget, key, modifier=Qt.KeyboardModifier.NoModifier, delay=-1)
## keyRelease(widget, key, modifier=Qt.KeyboardModifier.NoModifier, delay=-1)

### Description
Sends one or more keyboard events to a widget.

### Parameters
- **widget** (QWidget) - Required - The widget that will receive the event.
- **key** (str|int) - Required - Key to send, either a Qt.Key.Key_* constant or a single character string.
- **modifier** (Qt.KeyboardModifier) - Optional - Flags representing modifier keys (Shift, Ctrl, Alt, etc.).
- **delay** (int) - Optional - Delay in milliseconds after the event if > 0.
```

--------------------------------

### Override a Virtual Method in Python

Source: https://pytest-qt.readthedocs.io/en/latest/_sources/virtual_methods.rst.txt

Example of overriding a virtual C++ method (mouseReleaseEvent) in a Python QWidget subclass. This is a standard way to customize Qt widget behavior.

```python
class MyWidget(QWidget):
    # mouseReleaseEvent
    def mouseReleaseEvent(self, ev):
        print(f"mouse released at: {ev.pos()}")
```

--------------------------------

### Configure pytest-qt plugin

Source: https://pytest-qt.readthedocs.io/en/latest/_modules/pytestqt/plugin.html

Registers pytest markers and initializes the Qt API and logging plugin.

```python
def pytest_configure(config):
    config.addinivalue_line(
        "markers",
        "qt_no_exception_capture: Disables pytest-qt's automatic exception "
        "capture for just one test item.",
    )

    config.addinivalue_line(
        "markers", "qt_log_level_fail: overrides qt_log_level_fail ini option."
    )
    config.addinivalue_line(
        "markers", "qt_log_ignore: overrides qt_log_ignore ini option."
    )
    config.addinivalue_line("markers", "no_qt_log: Turn off Qt logging capture.")

    if config.getoption("qt_log") and config.getoption("capture") != "no":
        config.pluginmanager.register(QtLoggingPlugin(config), "_qt_logging")

    qt_api.set_qt_api(config.getini("qt_api"))
```

--------------------------------

### Define Custom QApplication Class

Source: https://pytest-qt.readthedocs.io/en/latest/_sources/qapplication.rst.txt

Define a custom QApplication subclass to add specific attributes or methods for testing. Ensure to import from pytestqt.qt_compat.

```python
from pytestqt.qt_compat import qt_api


class CustomQApplication(qt_api.QtWidgets.QApplication):
    def __init__(self, *argv):
        super().__init__(*argv)
        self.custom_attr = "xxx"

    def custom_function(self):
        pass
```

--------------------------------

### Keyboard interaction methods

Source: https://pytest-qt.readthedocs.io/en/latest/_modules/pytestqt/qtbot.html

Static methods for simulating keyboard events on widgets using the underlying QTest API.

```python
@staticmethod
def keyClick(*args, **kwargs):
    qt_api.QtTest.QTest.keyClick(*args, **kwargs)
```

```python
@staticmethod
def keyClicks(*args, **kwargs):
    qt_api.QtTest.QTest.keyClicks(*args, **kwargs)
```

```python
@staticmethod
def keyEvent(*args, **kwargs):
    qt_api.QtTest.QTest.keyEvent(*args, **kwargs)
```

```python
@staticmethod
def keyPress(*args, **kwargs):
    qt_api.QtTest.QTest.keyPress(*args, **kwargs)
```

```python
@staticmethod
def keyRelease(*args, **kwargs):
    qt_api.QtTest.QTest.keyRelease(*args, **kwargs)
```

--------------------------------

### Example of Test Failure with Qt Logging Disabled

Source: https://pytest-qt.readthedocs.io/en/latest/_sources/logging.rst.txt

This illustrates the output when Qt logging capture is disabled. The Qt warning message appears in the 'Captured stderr call' section instead of 'Captured Qt messages'.

```bash
F
================================== FAILURES ===================================
_________________________________ test_types __________________________________

    def test_foo():
        do_something()
>       assert 0
E       assert 0

test.py:8: AssertionError
---------------------------- Captured stderr call -----------------------------
this is a WARNING message
```

--------------------------------

### Keyboard Event Methods

Source: https://pytest-qt.readthedocs.io/en/latest/_modules/pytestqt/qtbot.html

Static methods for simulating keyboard interactions on widgets.

```APIDOC
## Keyboard Event Methods

### Methods
- **keyClick(*args, **kwargs)**: Simulates a key click.
- **keyClicks(*args, **kwargs)**: Simulates a sequence of key clicks.
- **keyEvent(*args, **kwargs)**: Simulates a raw key event.
- **keyPress(*args, **kwargs)**: Simulates a key press.
- **keyRelease(*args, **kwargs)**: Simulates a key release.
- **keySequence(widget, key_sequence)**: Simulates a QKeySequence on a widget (requires Qt 5.10+).
```

--------------------------------

### Disable Exception Capture with pytest Marker

Source: https://pytest-qt.readthedocs.io/en/latest/_sources/virtual_methods.rst.txt

Shows how to disable pytest-qt's automatic exception capture for a specific test using the @pytest.mark.qt_no_exception_capture marker. This is useful if you need to handle exceptions differently or install a custom hook.

```python
@pytest.mark.qt_no_exception_capture
def test_buttons(qtbot):
    ...
```

--------------------------------

### Wait for window exposure with waitExposed

Source: https://pytest-qt.readthedocs.io/en/latest/_modules/pytestqt/qtbot.html

Use this context manager to wait for a widget to be exposed on the screen, which is useful for asynchronous window systems like X11.

```python
with qtbot.waitExposed(splash, timeout=500):
    startup()
```

--------------------------------

### QtBot Source Implementation

Source: https://pytest-qt.readthedocs.io/en/latest/_modules/pytestqt/qtbot.html

The core implementation of the QtBot class and its supporting imports and type definitions.

```python
from collections.abc import Callable
import contextlib
from types import TracebackType
import weakref
import warnings
from typing import (
    TYPE_CHECKING,
    Generator,
    Iterator,
    Literal,
    Optional,
    Any,
    cast,
)
from pathlib import Path
import pytest
from typing_extensions import Self, TypeAlias

from pytestqt.exceptions import TimeoutError, ScreenshotError
from pytestqt.qt_compat import qt_api
from pytestqt.wait_signal import (
    SignalBlocker,
    MultiSignalBlocker,
    SignalEmittedSpy,
    SignalEmittedError,
    CallbackBlocker,
    CallbackCalledTwiceError,
    CheckParamsCb,
)

from pytest import FixtureRequest

# Type hint objects until figuring out how to import across qt
# versions possibly using 'qtpy' library.
QWidget: TypeAlias = Any
SignalInstance: TypeAlias = Any
QRect: TypeAlias = Any
QKeySequence: TypeAlias = Any

if TYPE_CHECKING:
    # Keep local import behavior the same.
    from pytestqt.exceptions import CapturedExceptions

BeforeCloseFunc = Callable[[QWidget], None]
WaitSignalsOrder = Literal["none", "simple", "strict"]


def _parse_ini_boolean(value: Any) -> bool:
    if value in (True, False):
        return cast("bool", value)
    try:
        return {"true": True, "false": False}[str(value).lower()]
    except KeyError:
        raise ValueError("unknown string for bool: %r" % value)




[docs]
class QtBot:
    """
    Instances of this class are responsible for sending events to `Qt` objects (usually widgets),
    simulating user input.

    .. important:: Instances of this class should be accessed only by using a ``qtbot`` fixture,
                    never instantiated directly.

    **Widgets**

    .. automethod:: addWidget
    .. automethod:: captureExceptions
    .. automethod:: waitActive
    .. automethod:: waitExposed
    .. automethod:: waitForWindowShown
    .. automethod:: stop
    .. automethod:: screenshot
    .. automethod:: wait

    **Signals and Events**

    .. automethod:: waitSignal
    .. automethod:: waitSignals
    .. automethod:: assertNotEmitted
    .. automethod:: waitUntil

    **Raw QTest API**

    Methods below provide very low level functions, as sending a single mouse click or a key event.
    Those methods are just forwarded directly to the `QTest API`_. Consult the documentation for more
    information.

    .. note::
        These methods should be rarely be used, in general prefer to interact with widgets
        using their own methods such as ``QComboBox.setCurrentText``, ``QLineEdit.setText``, etc.
        Doing so will have the same effect as users interacting with the widget, but are more reliable.

        See :ref:`this note in the tutorial <note-about-qtbot-methods>` for more information.

    ---

    Below are methods used to simulate sending key events to widgets:

    .. staticmethod:: keyClick (widget, key[, modifier=Qt.KeyboardModifier.NoModifier[, delay=-1]])
    .. staticmethod:: keyClicks (widget, key_sequence[, modifier=Qt.KeyboardModifier.NoModifier[, delay=-1]])
    .. staticmethod:: keyEvent (action, widget, key[, modifier=Qt.KeyboardModifier.NoModifier[, delay=-1]])
    .. staticmethod:: keyPress (widget, key[, modifier=Qt.KeyboardModifier.NoModifier[, delay=-1]])
    .. staticmethod:: keyRelease (widget, key[, modifier=Qt.KeyboardModifier.NoModifier[, delay=-1]])

        Sends one or more keyboard events to a widget.

        :param QWidget widget: the widget that will receive the event

        :param str|int key: key to send, it can be either a Qt.Key.Key_* constant or a single character string.

        .. _keyboard modifiers:

        :param Qt.KeyboardModifier modifier: flags OR'ed together representing other modifier keys
            also pressed. Possible flags are:

            * ``Qt.KeyboardModifier.NoModifier``: No modifier key is pressed.
            * ``Qt.KeyboardModifier.ShiftModifier``: A Shift key on the keyboard is pressed.
            * ``Qt.KeyboardModifier.ControlModifier``: A Ctrl key on the keyboard is pressed.
            * ``Qt.KeyboardModifier.AltModifier``: An Alt key on the keyboard is pressed.
            * ``Qt.KeyboardModifier.MetaModifier``: A Meta key on the keyboard is pressed.
            * ``Qt.KeyboardModifier.KeypadModifier``: A keypad button is pressed.
            * ``Qt.KeyboardModifier.GroupSwitchModifier``: X11 only. A Mode_switch key on the keyboard is pressed.

        :param int delay: after the event, delay the test for this milliseconds (if > 0).


    .. staticmethod:: keyToAscii (key)

        Auxiliary method that converts the given constant to its equivalent ascii.

        :param Qt.Key.Key_* key: one of the constants for keys in the Qt namespace.

        :return type: str
        :returns: the equivalent character string.

        .. note:: This method is not available in PyQt.

    ---
```

--------------------------------

### Test Failing Due to Critical Qt Message

Source: https://pytest-qt.readthedocs.io/en/latest/_sources/logging.rst.txt

This example shows a test that fails because it emits a critical Qt message, as configured by 'qt_log_level_fail'. The failure indicates that a critical message was detected, even without an explicit assert failure.

```python
from pytestqt.qt_compat import qCritical


def do_something():
    qCritical("WM_PAINT failed")


def test_foo(qtlog):
    do_something()
```

--------------------------------

### Signal Tracking Initialization

Source: https://pytest-qt.readthedocs.io/en/latest/_modules/pytestqt/wait_signal.html

Initializes the tracking state for emitted signals.

```python
def _create_signal_emitted_indices(self, signals):
        for signal in signals:
            self._signals_emitted.append(False)
```

--------------------------------

### qtbot

Source: https://pytest-qt.readthedocs.io/en/latest/_modules/pytestqt/plugin.html

Fixture used to create a QtBot instance for testing.

```APIDOC
## fixture qtbot

### Description
Provides a QtBot instance to simulate user interaction and control the event loop during tests. Use addWidget to register top-level widgets for automatic cleanup.
```

--------------------------------

### Wait for a signal with parameter checking

Source: https://pytest-qt.readthedocs.io/en/latest/_sources/signals.rst.txt

Use the `check_params_cb` parameter to provide a callable that validates the parameters emitted with a signal. The callback must match the signal's signature and return `True` if parameters match, `False` otherwise. This example checks if a status signal reaches 100%.

```python
def test_status_100(status):
    """Return true if status has reached 100%."""
    return status == 100


def test_status_complete(qtbot):
    app = Application()

    # the following raises if the worker's status signal (which has an int parameter) wasn't raised
    # with value=100 within the default timeout
    with qtbot.waitSignal(
        app.worker.status, raising=True, check_params_cb=test_status_100
    ) as blocker:
        app.worker.start()
```

--------------------------------

### Wait for multiple signals with qtbot

Source: https://pytest-qt.readthedocs.io/en/latest/_modules/pytestqt/qtbot.html

Demonstrates using waitSignals as a context manager or via the MultiSignalBlocker object to pause test execution until signals are emitted.

```python
with qtbot.waitSignals([signal1, signal2], timeout=1000):
    long_function_that_calls_signals()
```

```python
blocker = qtbot.waitSignals(signals, timeout=1000)
long_function_that_calls_signal()
blocker.wait()
```

--------------------------------

### Verifying callback arguments

Source: https://pytest-qt.readthedocs.io/en/latest/wait_callback.html

Shows how to inspect arguments passed to the callback using .args and .kwargs attributes.

```python
assert cb.args == [2]
assert cb.kwargs == {}
```

--------------------------------

### Mock QApplication.exit()

Source: https://pytest-qt.readthedocs.io/en/latest/_sources/qapplication.rst.txt

Use the mock package to patch QApplication.exit() and assert that it was called. This approach verifies the call without altering the application's exit behavior.

```python
def test_exit_button(qtbot):
    with mock.patch.object(QApplication, "exit"):
        button = get_app_exit_button()
        button.click()
        assert QApplication.exit.call_count == 1
```

--------------------------------

### keyToAscii(key)

Source: https://pytest-qt.readthedocs.io/en/latest/_modules/pytestqt/qtbot.html

Converts a Qt key constant to its equivalent ASCII character string.

```APIDOC
## keyToAscii(key)

### Description
Auxiliary method that converts the given constant to its equivalent ascii. Note: This method is not available in PyQt.

### Parameters
- **key** (Qt.Key.Key_*) - Required - One of the constants for keys in the Qt namespace.

### Returns
- **str** - The equivalent character string.
```

--------------------------------

### qtmodeltester

Source: https://pytest-qt.readthedocs.io/en/latest/_modules/pytestqt/plugin.html

Fixture to create a ModelTester instance.

```APIDOC
## fixture qtmodeltester

### Description
Provides a ModelTester instance used to validate Qt models. It automatically performs cleanup after the test.
```

--------------------------------

### waitExposed(widget, timeout=5000)

Source: https://pytest-qt.readthedocs.io/en/latest/reference.html

Context manager that waits for a window to be exposed.

```APIDOC
## waitExposed(widget, timeout=5000)

### Description
Context manager that waits for `timeout` milliseconds or until the window is exposed. Raises `qtbot.TimeoutError` if not exposed within the timeout.

### Parameters
- **widget** (QWidget) - Required - Widget to wait for.
- **timeout** (int) - Optional - How many milliseconds to wait.
```

--------------------------------

### Wait for a callback

Source: https://pytest-qt.readthedocs.io/en/latest/_modules/pytestqt/qtbot.html

Demonstrates how to use waitCallback as a context manager or directly with a blocker object to wait for a callback execution.

```python
with qtbot.waitCallback() as callback:
    function_taking_a_callback(callback)
assert callback.args == [True]
```

```python
blocker = qtbot.waitCallback(timeout=1000)
function_calling_a_callback(blocker)
blocker.wait()
```
Tokens:
Raw