class QSignalSpy

The QSignalSpy class enables introspection of signal emission. More…

Synopsis

Methods

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

Detailed Description

Warning

This section contains snippets that were automatically translated from C++ to Python and may contain errors.

QSignalSpy can connect to any signal of any object and records its emission. QSignalSpy itself is a list of QVariant lists. Each emission of the signal will append one item to the list, containing the arguments of the signal.

The following example records all signal emissions for the clicked() signal of a QCheckBox:

box = ...
spy = QSignalSpy(box, SIGNAL(clicked(bool)))
# do something that triggers the signal
box.animateClick()
QCOMPARE(spy.count(), 1) # make sure the signal was emitted exactly one time
arguments = spy.takeFirst() # take the first signal
QVERIFY(arguments.at(0).toBool() == True) # verify the first argument

spy.takeFirst() returns the arguments for the first emitted signal, as a list of QVariant objects. The clicked() signal has a single bool argument, which is stored as the first entry in the list of arguments.

The example below catches a signal from a custom object:

spy = QSignalSpy(myCustomObject, SIGNAL(mySignal(int,QString,double)))
myCustomObject.doSomething() # trigger emission of the signal
arguments = spy.takeFirst()
QVERIFY(arguments.at(0).typeId() == QMetaType.Int)
QVERIFY(arguments.at(1).typeId() == QMetaType.QString)
QVERIFY(arguments.at(2).typeId() == QMetaType.Double)

Note

Non-standard data types need to be registered, using the qRegisterMetaType() function, before you can create a QSignalSpy . For example:

qRegisterMetaType<SomeStruct>()
spy = QSignalSpy(model, SIGNAL(whatever(SomeStruct)))

To retrieve the instance, you can use qvariant_cast:

# get the first argument from the first received signal:
result = SomeStruct(spy.at(0).at(0))

Verifying Signal Emissions

The QSignalSpy class provides an elegant mechanism for capturing the list of signals emitted by an object. However, you should verify its validity after construction. The constructor does a number of sanity checks, such as verifying that the signal to be spied upon actually exists. To make the diagnosis of test failures easier, the results of these checks should be checked by calling QVERIFY(spy.isValid()) before proceeding further with a test.

See also

QVERIFY()

__init__(signal)
Parameters:

signal – PySideSignalInstance

Constructs a new QSignalSpy that listens for emissions of the signal.

__init__(obj, signal)
Parameters:

Warning

This section contains snippets that were automatically translated from C++ to Python and may contain errors.

Constructs a new QSignalSpy that listens for emissions of the signal from the QObject obj. If QSignalSpy is not able to listen for a valid signal (for example, because obj is None or signal does not denote a valid signal of obj), an explanatory warning message will be output using qWarning() and subsequent calls to isValid() will return false.

This constructor is convenient to use when Qt’s meta-object system is heavily used in a test.

Basic usage example:

object = QObject()
mo = object.metaObject()
signalIndex = mo.indexOfSignal("objectNameChanged(QString)")
signal = mo.method(signalIndex)
spy = QSignalSpy(object, signal)
object.setObjectName("A object() name")
QCOMPARE(spy.count(), 1)

Imagine we need to check whether all properties of the QWindow class that represent minimum and maximum dimensions are properly writable. The following example demonstrates one of the approaches:

def writeMinMaxDimensionalProps_data(self):
    QTest.addColumn<int>("propertyIndex")
    # Collect all relevant properties
    mo = QWindow.staticMetaObject()
    for i in range(mo.propertyOffset(), mo.propertyCount()):
        property = mo.property(i)
        # ...that have type int
        if property.type() == QVariant.Int:
            re = QRegularExpression("^minimum|maximum")
            name = property.name()
            # ...and start with "minimum" or "maximum"
            if re.match(name).hasMatch():
                QTest.addRow("%s", name) << i




def writeMinMaxDimensionalProps(self):

    QFETCH(int, propertyIndex)
    property = QWindow.staticMetaObject.property(propertyIndex)
    QVERIFY(property.isWritable())
    QVERIFY(property.hasNotifySignal())
    window = QWindow()
    spy = QSignalSpy(window, property.notifySignal())
    QVERIFY(property.write(window, 42))
    QCOMPARE(spy.count(), 1)
__init__(obj, aSignal)
Parameters:

Warning

This section contains snippets that were automatically translated from C++ to Python and may contain errors.

Constructs a new QSignalSpy that listens for emissions of the signal from the QObject object. If QSignalSpy is not able to listen for a valid signal (for example, because object is None or signal does not denote a valid signal of object), an explanatory warning message will be output using qWarning() and subsequent calls to isValid() will return false.

Example:

spy = QSignalSpy(myPushButton, SIGNAL(clicked(bool)))
at(arg__1)
Parameters:

arg__1 – int

Return type:

.list of QVariant

count()
Return type:

int

isValid()
Return type:

bool

Returns true if the signal spy listens to a valid signal, otherwise false.

signal()
Return type:

QByteArray

Returns the normalized signal the spy is currently listening to.

size()
Return type:

int

wait(timeout)
Parameters:

timeout – int

Return type:

bool

This is an overloaded function, equivalent passing timeout to the chrono overload:

wait(std::chrono::milliseconds{timeout});

Returns true if the signal was emitted at least once in timeout, otherwise returns false.