QSignalSpy Class
The QSignalSpy class enables introspection of signal emission. More...
| Header: | #include <QSignalSpy> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Test)target_link_libraries(mytarget PRIVATE Qt6::Test) |
| qmake: | QT += testlib |
| Inherits: | QList |
Public Functions
| ~QSignalSpy() | |
(since 6.6) bool | wait(std::chrono::milliseconds timeout = std::chrono::seconds{5}) |
Detailed Description
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:
QCheckBox *box = ...; QSignalSpy spy(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 QList<QVariant> 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:
QSignalSpy spy(myCustomObject, SIGNAL(mySignal(int,QString,double))); myCustomObject->doSomething(); // trigger emission of the signal QList<QVariant> 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>(); QSignalSpy spy(&model, SIGNAL(whatever(SomeStruct)));
To retrieve the instance, you can use qvariant_cast:
// get the first argument from the first received signal: SomeStruct result = qvariant_cast<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().
Member Function Documentation
[noexcept] QSignalSpy::~QSignalSpy()
Destructor.
[since 6.6] bool QSignalSpy::wait(std::chrono::milliseconds timeout = std::chrono::seconds{5})
Starts an event loop that runs until the given signal is received or timeout has passed, whichever happens first.
timeout is any valid std::chrono::duration (std::chrono::seconds, std::chrono::milliseconds ...etc).
Returns true if the signal was emitted at least once in timeout, otherwise returns false.
Example:
using namespace std::chrono_literals; QSignalSpy spy(object, signal); spy.wait(2s);
This function was introduced in Qt 6.6.