QSignalSpy Class Reference

\inmodule QtTest More...

#include <qsignalspy.h>

Inheritance diagram for QSignalSpy:

Collaboration diagram for QSignalSpy:

Public Member Functions
	QSignalSpy (const QObject *obj, const char *aSignal)
	Constructs a new QSignalSpy that listens for emissions of the signal from the QObject object.
template<typename Func>
	QSignalSpy (const typename QtPrivate::FunctionPointer< Func >::Object *obj, Func signal0)
	QSignalSpy (const QObject *obj, QMetaMethod signal)
Q_TESTLIB_EXPORT	~QSignalSpy ()
	Destructor.
bool	isValid () const noexcept
	Returns true if the signal spy listens to a valid signal, otherwise false.
QByteArray	signal () const
	Returns the normalized signal the spy is currently listening to.
bool	wait (int timeout)
Q_TESTLIB_EXPORT bool	wait (std::chrono::milliseconds timeout=std::chrono::seconds{5})
Public Member Functions inherited from QList< QList< QVariant > >
DataPointer &	data_ptr () &
	QList (DataPointer dd) noexcept
QList< T > &	operator= (std::initializer_list< QList< QVariant > > args)
void	swap (QList &other) noexcept
QTypeTraits::compare_eq_result_container< QList, U >	operator== (const QList &other) const
QTypeTraits::compare_eq_result_container< QList, U >	operator!= (const QList &other) const
QTypeTraits::compare_lt_result_container< QList, U >	operator< (const QList &other) const noexcept(noexcept(std::lexicographical_compare< typename QList< U >::const_iterator, typename QList::const_iterator >(std::declval< QList< U > >().begin(), std::declval< QList< U > >().end(), other.begin(), other.end())))
QTypeTraits::compare_lt_result_container< QList, U >	operator> (const QList &other) const noexcept(noexcept(other< std::declval< QList< U > >()))
QTypeTraits::compare_lt_result_container< QList, U >	operator<= (const QList &other) const noexcept(noexcept(other< std::declval< QList< U > >()))
QTypeTraits::compare_lt_result_container< QList, U >	operator>= (const QList &other) const noexcept(noexcept(std::declval< QList< U > >()< other))
constexpr qsizetype	size () const noexcept
constexpr qsizetype	count () const noexcept
constexpr qsizetype	length () const noexcept
constexpr bool	isEmpty () const noexcept
void	resize (qsizetype size)
void	resizeForOverwrite (qsizetype size)
qsizetype	capacity () const
void	reserve (qsizetype size)
void	squeeze ()
void	detach ()
bool	isDetached () const noexcept
bool	isSharedWith (const QList< T > &other) const
pointer	data ()
const_pointer	constData () const noexcept
void	clear ()
const_reference	at (qsizetype i) const noexcept
reference	operator[] (qsizetype i)
void	append (parameter_type t)
void	prepend (rvalue_ref t)
reference	emplaceBack (Args &&... args)
reference	emplaceFront (Args &&... args)
iterator	insert (qsizetype i, parameter_type t)
QList &	assign (qsizetype n, parameter_type t)
iterator	emplace (const_iterator before, Args &&... args)
void	replace (qsizetype i, parameter_type t)
void	remove (qsizetype i, qsizetype n=1)
void	removeFirst () noexcept
void	removeLast () noexcept
value_type	takeFirst ()
value_type	takeLast ()
QList< T > &	fill (parameter_type t, qsizetype size=-1)
void	removeAt (qsizetype i)
qsizetype	removeAll (const AT &t)
bool	removeOne (const AT &t)
qsizetype	removeIf (Predicate pred)
QList< QVariant >	takeAt (qsizetype i)
void	move (qsizetype from, qsizetype to)
iterator	begin ()
iterator	end ()
const_iterator	cbegin () const noexcept
const_iterator	cend () const noexcept
const_iterator	constBegin () const noexcept
const_iterator	constEnd () const noexcept
reverse_iterator	rbegin ()
reverse_iterator	rend ()
const_reverse_iterator	crbegin () const noexcept
const_reverse_iterator	crend () const noexcept
iterator	erase (const_iterator begin, const_iterator end)
QList< QVariant > &	first ()
const QList< QVariant > &	constFirst () const noexcept
QList< QVariant > &	last ()
const QList< QVariant > &	constLast () const noexcept
bool	startsWith (parameter_type t) const
bool	endsWith (parameter_type t) const
QList< T >	mid (qsizetype pos, qsizetype len=-1) const
QList< T >	sliced (qsizetype pos) const
QList< QVariant >	value (qsizetype i) const
void	swapItemsAt (qsizetype i, qsizetype j)
void	push_back (parameter_type t)
void	push_front (rvalue_ref t)
void	pop_back () noexcept
void	pop_front () noexcept
reference	emplace_back (Args &&... args)
bool	empty () const noexcept
reference	front ()
reference	back ()
void	shrink_to_fit ()
constexpr qsizetype	max_size () const noexcept
QList< T > &	operator+= (const QList< T > &l)
QList< T >	operator+ (const QList< T > &l) const &
QList< T > &	operator<< (parameter_type t)
QList< T >	toList () const noexcept
QList< T >	toVector () const noexcept
Public Member Functions inherited from QListSpecialMethodsBase< QList< QVariant > >
qsizetype	indexOf (const AT &t, qsizetype from=0) const noexcept
qsizetype	lastIndexOf (const AT &t, qsizetype from=-1) const noexcept
bool	contains (const AT &t) const noexcept

Friends
class	QSignalSpyPrivate

Additional Inherited Members
Public Types inherited from QList< QList< QVariant > >
using	Type
using	value_type
using	pointer
using	const_pointer
using	reference
using	const_reference
using	size_type
using	difference_type
using	parameter_type
using	rvalue_ref
using	Iterator
using	ConstIterator
using	reverse_iterator
using	const_reverse_iterator
Static Public Member Functions inherited from QList< QList< QVariant > >
static constexpr qsizetype	maxSize ()
static QList< T >	fromList (const QList< T > &list) noexcept
static QList< T >	fromVector (const QList< T > &vector) noexcept
static QList< T >	fromReadOnlyData (const QList< QVariant >(&t)[N]) noexcept
Protected Types inherited from QListSpecialMethodsBase< QList< QVariant > >
using	Self
Protected Member Functions inherited from QListSpecialMethods< QList< QVariant > >
	QListSpecialMethods ()=default
Protected Member Functions inherited from QListSpecialMethodsBase< QList< QVariant > >
	QListSpecialMethodsBase ()=default
Self *	self ()

Detailed Description

\inmodule QtTest

The QSignalSpy class enables introspection of signal emission.

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

Definition at line 21 of file qsignalspy.h.

Constructor & Destructor Documentation

QSignalSpy() [1/3]

QSignalSpy::QSignalSpy ( const QObject * object, const char * signal )

inlineexplicit

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

Definition at line 30 of file qsignalspy.h.

QSignalSpy() [2/3]

template<typename Func>

QSignalSpy::QSignalSpy ( const typename QtPrivate::FunctionPointer< Func >::Object * obj, Func signal0 )

inline

Definition at line 37 of file qsignalspy.h.

References QSignalSpy().

Referenced by QSignalSpy().

Here is the call graph for this function:

Here is the caller graph for this function:

QSignalSpy() [3/3]

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

inline

Since

5.14

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

Definition at line 40 of file qsignalspy.h.

~QSignalSpy()

QSignalSpy::~QSignalSpy ( )

default

Destructor.

Member Function Documentation

isValid()

bool QSignalSpy::isValid ( ) const

inlinenoexcept

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

Definition at line 44 of file qsignalspy.h.

signal()

QByteArray QSignalSpy::signal ( ) const

inline

Returns the normalized signal the spy is currently listening to.

Definition at line 45 of file qsignalspy.h.

wait() [1/2]

bool QSignalSpy::wait ( int timeout )

inline

Since

5.0

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.

Definition at line 47 of file qsignalspy.h.

wait() [2/2]

bool QSignalSpy::wait

(

std::chrono::milliseconds

timeout = std::chrono::seconds{5}

)

Since

6.6

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

Definition at line 145 of file qsignalspy.cpp.

Friends And Related Symbol Documentation

QSignalSpyPrivate

friend class QSignalSpyPrivate

friend

Definition at line 27 of file qsignalspy.h.

---

The documentation for this class was generated from the following files:

• qtbase/src/testlib/qsignalspy.h (672afb13ca5ffc3d95ee92fb71416c6d23f7feda)
• qtbase/src/testlib/qsignalspy.cpp (7216eb292f730c14e649358f6435a7e758f4db13)