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).type() == QVariant::Int);
 QVERIFY(arguments.at(1).type() == QVariant::String);
 QVERIFY(arguments.at(2).type() == QVariant::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

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

This function was introduced in Qt 5.14.

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

This function was introduced in Qt 5.4.

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

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 = 5000)

Starts an event loop that runs until the given signal is received. Optionally the event loop can return earlier on a timeout (in milliseconds).

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

Example:

 QVERIFY(spy.wait(1000));

This function was introduced in Qt 5.0.