QSignalSpy Class

 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

 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);

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

 // get the first argument from the first received signal:
 SomeStruct result = qvariant_cast<SomeStruct>(spy.at(0).at(0));

Member Function Documentation

[explicit] QSignalSpy::QSignalSpy(const QObject *object, const char *signal)

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 nullptr 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:

 QSignalSpy spy(myPushButton, SIGNAL(clicked(bool)));

template <typename PointerToMemberFunction> QSignalSpy::QSignalSpy(const QObject *object, PointerToMemberFunction signal)

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 nullptr 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:

 QSignalSpy spy(myPushButton, &QPushButton::clicked);

QSignalSpy::QSignalSpy(const QObject *obj, const QMetaMethod &signal)

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 nullptr 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:

 QObject object;
 auto mo = object.metaObject();
 auto signalIndex = mo->indexOfSignal("objectNameChanged(QString)");
 auto signal = mo->method(signalIndex);

 QSignalSpy spy(&object, signal);
 object.setObjectName("A new 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:

 void tst_QWindow::writeMinMaxDimensionalProps_data()
     QTest::addColumn<int>("propertyIndex");

     // Collect all relevant properties
     static const auto mo = QWindow::staticMetaObject;
     for (int i = mo.propertyOffset(); i < mo.propertyCount(); ++i) {
         auto property = mo.property(i);

         // ...that have type int
         if (property.type() == QVariant::Int) {
             static const QRegularExpression re("^minimum|maximum");
             const auto name = property.name();

             // ...and start with "minimum" or "maximum"
             if (re.match(name).hasMatch()) {
                 QTest::addRow("%s", name) << i;
             }
         }
     }
 }

 void tst_QWindow::writeMinMaxDimensionalProps()
 {
     QFETCH(int, propertyIndex);

     auto property = QWindow::staticMetaObject.property(propertyIndex);
     QVERIFY(property.isWritable());
     QVERIFY(property.hasNotifySignal());

     QWindow window;
     QSignalSpy spy(&window, property.notifySignal());

     QVERIFY(property.write(&window, 42));
     QCOMPARE(spy.count(), 1);
 }

bool QSignalSpy::isValid() const

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

QByteArray QSignalSpy::signal() const

Returns the normalized signal the spy is currently listening to.

bool QSignalSpy::wait(int timeout)

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.

[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.