QSignalSpy Class

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.