waitUntil: Waiting for arbitrary conditions

Added in version 2.0.

Sometimes your tests need to wait a certain condition which does not trigger a signal, for example that a certain control gained focus or a QListView has been populated with all items.

For those situations you can use qtbot.waitUntil to wait until a certain condition has been met or a timeout is reached. This is specially important in X window systems due to their asynchronous nature, where you can’t rely on the fact that the result of an action will be immediately available.

For example:

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"

The window.edit.setFocus() may not be processed immediately, only in a future event loop, which might lead to this test to work sometimes and fail in others (a flaky test).

A better approach in situations like this is to use qtbot.waitUntil with a callback with your assertion:

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)

qtbot.waitUntil will periodically call check_label until it no longer raises AssertionError or a timeout is reached. If a timeout is reached, a qtbot.TimeoutError is raised from the last assertion error and the test will fail:

_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
    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

A second way to use qtbot.waitUntil is to pass a callback which returns True when the condition is met or False otherwise. It is usually terser than using a separate callback with assert statement, but it produces a generic message when it fails because it can’t make use of pytest’s assertion rewriting:

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"