Reference

QtBot

class pytestqt.qtbot.QtBot(request)[source]

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

addWidget(widget)[source]

Adds a widget to be tracked by this bot. This is not required, but will ensure that the widget gets closed by the end of the test, so it is highly recommended.

Parameters:widget (QWidget) – Widget to keep track of.
waitForWindowShown(widget)[source]

Waits until the window is shown in the screen. This is mainly useful for asynchronous systems like X11, where a window will be mapped to screen some time after being asked to show itself on the screen.

Parameters:widget (QWidget) – Widget to wait on.

Note

In Qt5, the actual method called is qWaitForWindowExposed, but this name is kept for backward compatibility

stopForInteraction()[source]

Stops the current test flow, letting the user interact with any visible widget.

This is mainly useful so that you can verify the current state of the program while writing tests.

Closing the windows should resume the test run, with qtbot attempting to restore visibility of the widgets as they were before this call.

Note

As a convenience, it is also aliased as stop.

wait(ms)[source]

New in version 1.9.

Waits for ms milliseconds.

While waiting, events will be processed and your test will stay responsive to user interface events or network communication.

Signals

waitSignal(signal=None, timeout=1000, raising=False)[source]

New in version 1.2.

Stops current test until a signal is triggered.

Used to stop the control flow of a test until a signal is emitted, or a number of milliseconds, specified by timeout, has elapsed.

Best used as a context manager:

with qtbot.waitSignal(signal, timeout=1000):
    long_function_that_calls_signal()

Also, you can use the SignalBlocker directly if the context manager form is not convenient:

blocker = qtbot.waitSignal(signal, timeout=1000)
blocker.connect(another_signal)
long_function_that_calls_signal()
blocker.wait()

Any additional signal, when triggered, will make wait() return.

New in version 1.4: The raising parameter.

Parameters:
  • signal (Signal) – A signal to wait for. Set to None to just use timeout.
  • timeout (int) – How many milliseconds to wait before resuming control flow.
  • raising (bool) – If QtBot.SignalTimeoutError should be raised if a timeout occurred.
Returns:

SignalBlocker object. Call SignalBlocker.wait() to wait.

Note

Cannot have both signals and timeout equal None, or else you will block indefinitely. We throw an error if this occurs.

waitSignals(signals=None, timeout=1000, raising=False)[source]

New in version 1.4.

Stops current test until all given signals are triggered.

Used to stop the control flow of a test until all (and only all) signals are emitted or the number of milliseconds specified by timeout has elapsed.

Best used as a context manager:

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

Also, you can use the MultiSignalBlocker directly if the context manager form is not convenient:

blocker = qtbot.waitSignals(signals, timeout=1000)
long_function_that_calls_signal()
blocker.wait()
Parameters:
  • signals (list) – A list of Signal`s to wait for. Set to ``None` to just use timeout.
  • timeout (int) – How many milliseconds to wait before resuming control flow.
  • raising (bool) – If QtBot.SignalTimeoutError should be raised if a timeout occurred.
Returns:

MultiSignalBlocker object. Call MultiSignalBlocker.wait() to wait.

Note

Cannot have both signals and timeout equal None, or else you will block indefinitely. We throw an error if this occurs.

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.

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

static keyPress(widget, key[, modifier=Qt.NoModifier[, delay=-1]])
static keyClick(widget, key[, modifier=Qt.NoModifier[, delay=-1]])
static keyClicks(widget, key sequence[, modifier=Qt.NoModifier[, delay=-1]])
static keyEvent(action, widget, key[, modifier=Qt.NoModifier[, delay=-1]])
static keyPress(widget, key[, modifier=Qt.NoModifier[, delay=-1]])
static keyRelease(widget, key[, modifier=Qt.NoModifier[, delay=-1]])

Sends one or more keyword events to a widget.

Parameters:
  • widget (QWidget) – the widget that will receive the event
  • key (str|int) – key to send, it can be either a Qt.Key_* constant or a single character string.
Parameters:
  • modifier (Qt.KeyboardModifier) –

    flags OR’ed together representing other modifier keys also pressed. Possible flags are:

    • Qt.NoModifier: No modifier key is pressed.
    • Qt.ShiftModifier: A Shift key on the keyboard is pressed.
    • Qt.ControlModifier: A Ctrl key on the keyboard is pressed.
    • Qt.AltModifier: An Alt key on the keyboard is pressed.
    • Qt.MetaModifier: A Meta key on the keyboard is pressed.
    • Qt.KeypadModifier: A keypad button is pressed.
    • Qt.GroupSwitchModifier: X11 only. A Mode_switch key on the keyboard is pressed.
  • delay (int) – after the event, delay the test for this miliseconds (if > 0).
static keyToAscii(key)

Auxilliary method that converts the given constant ot its equivalent ascii.

Parameters:key (Qt.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.

Below are methods used to simulate sending mouse events to widgets.

static mouseClick(widget, button[, stateKey=0[, pos=QPoint()[, delay=-1]]])
static mouseDClick(widget, button[, stateKey=0[, pos=QPoint()[, delay=-1]]])
static mouseEvent(action, widget, button, stateKey, pos[, delay=-1])
static mouseMove(widget[, pos=QPoint()[, delay=-1]])
static mousePress(widget, button[, stateKey=0[, pos=QPoint()[, delay=-1]]])
static mouseRelease(widget, button[, stateKey=0[, pos=QPoint()[, delay=-1]]])

Sends a mouse moves and clicks to a widget.

Parameters:
  • widget (QWidget) – the widget that will receive the event
  • button (Qt.MouseButton) –

    flags OR’ed together representing the button pressed. Possible flags are:

    • Qt.NoButton: The button state does not refer to any button (see QMouseEvent.button()).
    • Qt.LeftButton: The left button is pressed, or an event refers to the left button. (The left button may be the right button on left-handed mice.)
    • Qt.RightButton: The right button.
    • Qt.MidButton: The middle button.
    • Qt.MiddleButton: The middle button.
    • Qt.XButton1: The first X button.
    • Qt.XButton2: The second X button.
  • modifier (Qt.KeyboardModifier) – flags OR’ed together representing other modifier keys also pressed. See keyboard modifiers.
  • position (QPoint) – position of the mouse pointer.
  • delay (int) – after the event, delay the test for this miliseconds (if > 0).

SignalBlocker

class pytestqt.wait_signal.SignalBlocker(timeout=1000, raising=False)[source]

Returned by pytestqt.qtbot.QtBot.waitSignal() method.

Variables:
  • timeout (int) – maximum time to wait for a signal to be triggered. Can be changed before wait() is called.
  • signal_triggered (bool) – set to True if a signal (or all signals in case of MultipleSignalBlocker) was triggered, or False if timeout was reached instead. Until wait() is called, this is set to None.
  • raising (bool) – If SignalTimeoutError should be raised if a timeout occurred.
  • args (list) – The arguments which were emitted by the signal, or None if the signal wasn’t emitted at all.

New in version 1.10: The args attribute.

wait()

Waits until either a connected signal is triggered or timeout is reached.

Raises ValueError:
 if no signals are connected and timeout is None; in this case it would wait forever.
connect(signal)[source]

Connects to the given signal, making wait() return once this signal is emitted.

More than one signal can be connected, in which case any one of them will make wait() return.

Parameters:signal – QtCore.Signal

MultiSignalBlocker

class pytestqt.wait_signal.MultiSignalBlocker(timeout=1000, raising=False)[source]

Returned by pytestqt.qtbot.QtBot.waitSignals() method, blocks until all signals connected to it are triggered or the timeout is reached.

Variables identical to SignalBlocker:
  • timeout
  • signal_triggered
  • raising
wait()

Waits until either a connected signal is triggered or timeout is reached.

Raises ValueError:
 if no signals are connected and timeout is None; in this case it would wait forever.

SignalTimeoutError

class pytestqt.wait_signal.SignalTimeoutError[source]

New in version 1.4.

The exception thrown by pytestqt.qtbot.QtBot.waitSignal() if the raising parameter has been given and there was a timeout.

Record

class pytestqt.logging.Record(msg_type, message, ignored, context)[source]

Hold information about a message sent by one of Qt log functions.

Variables:
  • message (str) – message contents.
  • type (Qt.QtMsgType) – enum that identifies message type
  • type_name (str) – type as string: "QtDebugMsg", "QtWarningMsg" or "QtCriticalMsg".
  • log_type_name (str) – type name similar to the logging package: DEBUG, WARNING and CRITICAL.
  • when (datetime.datetime) – when the message was captured
  • ignored (bool) – If this record matches a regex from the “qt_log_ignore” option.
  • context – a namedtuple containing the attributes file, function, line. Only available in Qt5, otherwise is None.