# 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"