Back to Doc.qt.io
Contact Us Blog Download Qt
On this page

QEventSpy Class

The QEventSpy class enables introspection of event delivery. More...

Header: #include <QEventSpy>
CMake: find_package(Qt6 REQUIRED COMPONENTS Test)
target_link_libraries(mytarget PRIVATE Qt6::Test)
qmake: QT += testlib
Since: Qt 6.13

Public Types

Filter

Public Functions

QEventSpy(QObject *object)
QEventSpy(QObject *object, QEvent::Type type)
QEventSpy(QObject *object, QEventSpy::Filter filter)
QEventSpy(QObject *object, const QList<QEvent::Type> &types)
~QEventSpy()
const QEvent *at(qsizetype i) const
const EventType *at(qsizetype i) const
void clear()
bool contains(QEvent::Type type) const
qsizetype count() const
qsizetype count(QEvent::Type type) const
QList<QEvent::Type> eventList() const
bool isEmpty() const
bool isValid() const
QObject *object() const
QObject *receiver(qsizetype i) const
qsizetype size() const

Detailed Description

QEventSpy installs itself as an event filter on a QObject and records the events delivered to it, in the order they arrive. QEventSpy never filters out or modifies the events it observes.

The following example verifies that showing a widget delivers a single Show event to it:

QWidget widget;
QEventSpy spy(&widget, QEvent::Show);
widget.show();
QCOMPARE(spy.count(), 1);

To record several event types, or all events, pass a list of types, or an empty list:

QEventSpy spy(&widget, { QEvent::FocusIn, QEvent::FocusOut });
...
QCOMPARE(spy.eventList(), QList({ QEvent::FocusIn, QEvent::FocusOut }));

For more fine-grained control, pass a QEventSpy::Filter. This is useful when spying on the application object, which sees the events of all objects:

QEventSpy spy(qApp, [&](QObject *receiver, const QEvent *event) {
    return receiver == &widget && !event->spontaneous();
});

QEventSpy stores a copy of each recorded event, made with QEvent::clone() at the time the event filter sees it. The copy can be inspected using at():

QEventSpy spy(&widget, QEvent::MouseButtonPress);
QTest::mouseClick(&widget, Qt::LeftButton, {}, QPoint(10, 10));
QCOMPARE(spy.at<QMouseEvent>(0)->position(), QPointF(10, 10));

Event types that do not reimplement QEvent::clone() are recorded as a plain QEvent of the same type.

To wait for events that are delivered asynchronously, use one of the QTRY_ macros, or QTest::qWaitFor(), with a condition that states what the test is waiting for:

QEventSpy spy(&window, QEvent::Expose);
window.show();
QTRY_VERIFY(spy.contains(QEvent::Expose));

QEventSpy must be created in the thread of the object it spies on.

See also QSignalSpy and QObject::installEventFilter().

Member Type Documentation

[alias] QEventSpy::Filter

A synonym for std::function<bool(QObject *receiver, const QEvent *event)>.

A filter returns true for each event that the spy should record.

Member Function Documentation

[explicit] QEventSpy::QEventSpy(QObject *object)

Constructs a QEventSpy that records all events delivered to object.

If object is nullptr, a warning is output using qWarning() and subsequent calls to isValid() return false.

QEventSpy::QEventSpy(QObject *object, QEvent::Type type)

Constructs a QEventSpy that records events of the given type delivered to object.

If object is nullptr, a warning is output using qWarning() and subsequent calls to isValid() return false.

QEventSpy::QEventSpy(QObject *object, QEventSpy::Filter filter)

Constructs a QEventSpy that records the events delivered to object for which filter returns true. If filter is empty, all events are recorded.

If object is nullptr, a warning is output using qWarning() and subsequent calls to isValid() return false.

QEventSpy::QEventSpy(QObject *object, const QList<QEvent::Type> &types)

Constructs a QEventSpy that records events of the given types delivered to object. If types is empty, all events are recorded.

If object is nullptr, a warning is output using qWarning() and subsequent calls to isValid() return false.

[noexcept] QEventSpy::~QEventSpy()

Destroys the QEventSpy, and removes it as an event filter from the spied-on object.

const QEvent *QEventSpy::at(qsizetype i) const

Returns a copy of the recorded event at index position i.

i must be a valid index position (0 <= i < count()). The returned pointer is valid until the event is removed from the spy, or the spy is destroyed.

template <typename EventType> const EventType *QEventSpy::at(qsizetype i) const

Returns a copy of the recorded event at index position i, cast to EventType.

The caller must ensure that the event is of type EventType, for example by checking QEvent::type().

This is an overloaded function.

void QEventSpy::clear()

Removes all recorded events from the spy.

[noexcept] bool QEventSpy::contains(QEvent::Type type) const

Returns true if the spy has recorded at least one event of the given type, otherwise false.

[noexcept] qsizetype QEventSpy::count() const

Returns the number of recorded events.

[noexcept] qsizetype QEventSpy::count(QEvent::Type type) const

Returns the number of recorded events of the given type.

This is an overloaded function.

QList<QEvent::Type> QEventSpy::eventList() const

Returns the types of the recorded events, in the order the spy saw them, including repeated types.

QCOMPARE(spy.eventList(), QList({ QEvent::ChildAdded, QEvent::ChildAdded }));

[noexcept] bool QEventSpy::isEmpty() const

Returns true if the spy has not recorded any events, otherwise false.

[noexcept] bool QEventSpy::isValid() const

Returns true if the spy was constructed with a valid object, otherwise false.

The spy remains valid if the object is later destroyed.

QObject *QEventSpy::object() const

Returns the object the spy was installed on, or nullptr if the object has been destroyed.

QObject *QEventSpy::receiver(qsizetype i) const

Returns the object that the event at index position i was delivered to.

i must be a valid index position (0 <= i < count()). The object may have been destroyed since the event was recorded.

[noexcept] qsizetype QEventSpy::size() const

Same as count().

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.