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. Note
This method is also available as
add_widget
(pep-8 alias)
-
captureExceptions
(**kwds)[source]¶ New in version 2.1.
Context manager that captures Qt virtual method exceptions that happen in block inside context.
with qtbot.capture_exceptions() as exceptions: qtbot.click(button) # exception is a list of sys.exc_info tuples assert len(exceptions) == 1
Note
This method is also available as
capture_exceptions
(pep-8 alias)
-
waitActive
(widget, timeout=1000)[source]¶ Context manager that waits for
timeout
milliseconds or until the window is active. If window is not exposed withintimeout
milliseconds, raiseTimeoutError
.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.
with qtbot.waitActive(widget, timeout=500): show_action()
Parameters: - widget (QWidget) – Widget to wait for.
- timeout (int|None) – How many milliseconds to wait for.
Note
This function is only available in PyQt5, raising a
RuntimeError
if called fromPyQt4
orPySide
.Note
This method is also available as
wait_active
(pep-8 alias)
-
waitExposed
(widget, timeout=1000)[source]¶ Context manager that waits for
timeout
milliseconds or until the window is exposed. If the window is not exposed withintimeout
milliseconds, raiseTimeoutError
.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.
with qtbot.waitExposed(splash, timeout=500): startup()
Parameters: - widget (QWidget) – Widget to wait for.
- timeout (int|None) – How many milliseconds to wait for.
Note
This function is only available in PyQt5, raising a
RuntimeError
if called fromPyQt4
orPySide
.Note
This method is also available as
wait_exposed
(pep-8 alias)
-
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
PyQt5
this function is considered deprecated in favor ofwaitExposed()
.Note
This method is also available as
wait_for_window_shown
(pep-8 alias)
-
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 and Events
-
waitSignal
(signal=None, timeout=1000, raising=None, check_params_cb=None)[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.
New in version 2.0: The check_params_cb parameter.
Parameters: - signal (Signal) – A signal to wait for, or a tuple
(signal, signal_name_as_str)
to improve the error message that is part ofTimeoutError
. Set toNone
to just use timeout. - timeout (int) – How many milliseconds to wait before resuming control flow.
- raising (bool) – If
QtBot.TimeoutError
should be raised if a timeout occurred. This defaults toTrue
unlessqt_wait_signal_raising = false
is set in the config. - check_params_cb (Callable) – Optional
callable
that compares the provided signal parameters to some expected parameters. It has to match the signature ofsignal
(just like a slot function would) and returnTrue
if parameters match,False
otherwise.
Returns: SignalBlocker
object. CallSignalBlocker.wait()
to wait.Note
Cannot have both
signals
andtimeout
equalNone
, or else you will block indefinitely. We throw an error if this occurs.Note
This method is also available as
wait_signal
(pep-8 alias)- signal (Signal) – A signal to wait for, or a tuple
-
waitSignals
(signals=None, timeout=1000, raising=None, check_params_cbs=None, order='none')[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
objects to wait for. Alternatively: a list of (Signal, str
) tuples of the form(signal, signal_name_as_str)
to improve the error message that is part ofTimeoutError
. Set toNone
to just use timeout. - timeout (int) – How many milliseconds to wait before resuming control flow.
- raising (bool) – If
QtBot.TimeoutError
should be raised if a timeout occurred. This defaults toTrue
unlessqt_wait_signal_raising = false
is set in the config. - check_params_cbs (list) – optional list of callables that compare the provided signal parameters to some expected parameters.
Each callable has to match the signature of the corresponding signal in
signals
(just like a slot function would) and returnTrue
if parameters match,False
otherwise. Instead of a specific callable,None
can be provided, to disable parameter checking for the corresponding signal. If the number of callbacks doesn’t match the number of signalsValueError
will be raised. - order (str) –
Determines the order in which to expect signals:
"none"
: no order is enforced"strict"
: signals have to be emitted strictly in the provided order (e.g. fails when expecting signals [a, b] and [a, a, b] is emitted)"simple"
: like “strict”, but signals may be emitted in-between the provided ones, e.g. expectedsignals == [a, b, c]
and actually emittedsignals = [a, a, b, a, c]
works (would fail with"strict"
).
Returns: MultiSignalBlocker
object. CallMultiSignalBlocker.wait()
to wait.Note
Cannot have both
signals
andtimeout
equalNone
, or else you will block indefinitely. We throw an error if this occurs.Note
This method is also available as
wait_signals
(pep-8 alias)- signals (list) – A list of
-
assertNotEmitted
(**kwds)[source]¶ New in version 1.11.
Make sure the given
signal
doesn’t get emitted.This is intended to be used as a context manager.
Note
This method is also available as
assert_not_emitted
(pep-8 alias)
-
waitUntil
(callback, timeout=1000)[source]¶ New in version 2.0.
Wait in a busy loop, calling the given callback periodically until timeout is reached.
callback()
should raiseAssertionError
to indicate that the desired condition has not yet been reached, or just returnNone
when it does. Useful toassert
until some condition is satisfied:def view_updated(): assert view_model.count() > 10 qtbot.waitUntil(view_updated)
Another possibility is for
callback()
to returnTrue
when the desired condition is met,False
otherwise. Useful specially withlambda
for terser code, but keep in mind that the error message in those cases is usually not very useful because it is not using anassert
expression.qtbot.waitUntil(lambda: view_model.count() > 10)
Note that this usage only accepts returning actual
True
andFalse
values, so returning an empty list to express “falseness” raises aValueError
.Parameters: - callback – callable that will be called periodically.
- timeout – timeout value in ms.
Raises: ValueError – if the return value from the callback is anything other than
None
,True
orFalse
.Note
This method is also available as
wait_until
(pep-8 alias)
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
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
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).
-
TimeoutError¶
-
class
pytestqt.qtbot.
TimeoutError
[source]¶ New in version 2.1.
Exception thrown by
pytestqt.qtbot.QtBot
methods.Note
In versions prior to
2.1
, this exception was calledSignalTimeoutError
. An alias is kept for backward compatibility.
SignalBlocker¶
-
class
pytestqt.wait_signal.
SignalBlocker
(timeout=1000, raising=True, check_params_cb=None)[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 ofMultipleSignalBlocker
) was triggered, orFalse
if timeout was reached instead. Untilwait()
is called, this is set toNone
. - raising (bool) –
If
TimeoutError
should be raised if a timeout occurred.Note
contrary to the parameter of same name in
pytestqt.qtbot.QtBot.waitSignal()
, this parameter does not consider the qt_wait_signal_raising ini option. - 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.
- timeout (int) – maximum time to wait for a signal to be triggered. Can
be changed before
MultiSignalBlocker¶
-
class
pytestqt.wait_signal.
MultiSignalBlocker
(timeout=1000, raising=True, check_params_cbs=None, order='none')[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.
- Variables identical to
SignalEmittedError¶
-
class
pytestqt.wait_signal.
SignalEmittedError
[source]¶ New in version 1.11.
The exception thrown by
pytestqt.qtbot.QtBot.assertNotEmitted()
if a signal was emitted unexpectedly.
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:"QtInfoMsg"
,"QtDebugMsg"
,"QtWarningMsg"
or"QtCriticalMsg"
. - log_type_name (str) – type name similar to the logging package:
INFO
,DEBUG
,WARNING
andCRITICAL
. - 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.