diff options
Diffstat (limited to 'src/imports/testlib/SignalSpy.qml')
-rw-r--r-- | src/imports/testlib/SignalSpy.qml | 129 |
1 files changed, 129 insertions, 0 deletions
diff --git a/src/imports/testlib/SignalSpy.qml b/src/imports/testlib/SignalSpy.qml index 5b05778c5d..8318f156a0 100644 --- a/src/imports/testlib/SignalSpy.qml +++ b/src/imports/testlib/SignalSpy.qml @@ -42,6 +42,43 @@ import QtQuick 2.0 import QtTest 1.0 +/*! + \qmltype SignalSpy + \inqmlmodule QtTest + \brief Enables introspection of signal emission + \since 4.8 + \ingroup qtquicktest + + In the following example, a SignalSpy is installed to watch the + "clicked" signal on a user-defined Button type. When the signal + is emitted, the \l count property on the spy will be increased. + + \code + Button { + id: button + SignalSpy { + id: spy + target: button + signalName: "clicked" + } + TestCase { + name: "ButtonClick" + function test_click() { + compare(spy.count, 0) + button.clicked(); + compare(spy.count, 1) + } + } + } + \endcode + + The above style of test is suitable for signals that are emitted + synchronously. For asynchronous signals, the wait() method can be + used to block the test until the signal occurs (or a timeout expires). + + \sa {QtTest::TestCase}{TestCase}, {Qt Quick Test Reference Documentation} +*/ + Item { id: spy visible: false @@ -50,18 +87,101 @@ Item { id: util } // Public API. + /*! + \qmlproperty object SignalSpy::target + + This property defines the target object that will be used to + listen for emissions of the \l signalName signal. + + \sa signalName, count + */ property var target: null + /*! + \qmlproperty string SignalSpy::signalName + + This property defines the name of the signal on \l target to + listen for. + + \sa target, count + */ property string signalName: "" + /*! + \qmlproperty int SignalSpy::count + + This property defines the number of times that \l signalName has + been emitted from \l target since the last call to clear(). + + \sa target, signalName, clear() + \readonly + */ readonly property alias count: spy.qtest_count + /*! + \qmlproperty bool SignalSpy::valid + + This property defines the current signal connection status. It will be true when the \l signalName of the \l target is connected successfully, otherwise it will be false. + + \sa count, target, signalName, clear() + \readonly + */ readonly property alias valid:spy.qtest_valid + /*! + \qmlproperty list SignalSpy::signalArguments + + This property holds a list of emitted signal arguments. Each emission of the signal will append one item to the list, containing the arguments of the signal. + When connecting to a new \l target or new \l signalName or calling the \l clear() method, the \l signalArguments will be reset to empty. + + \sa signalName, clear() + \readonly + */ readonly property alias signalArguments:spy.qtest_signalArguments + /*! + \qmlmethod SignalSpy::clear() + + Clears \l count to 0, resets \l valid to false and clears the \l signalArguments to empty. + + \sa count, wait() + */ function clear() { qtest_count = 0 qtest_expectedCount = 0 qtest_signalArguments = [] } + /*! + \qmlmethod SignalSpy::wait(timeout = 5000) + + Waits for the signal \l signalName on \l target to be emitted, + for up to \a timeout milliseconds. The test case will fail if + the signal is not emitted. + + \code + SignalSpy { + id: spy + target: button + signalName: "clicked" + } + + function test_async_click() { + ... + // do something that will cause clicked() to be emitted + ... + spy.wait() + compare(spy.count, 1) + } + \endcode + + There are two possible scenarios: the signal has already been + emitted when wait() is called, or the signal has not yet been + emitted. The wait() function handles the first scenario by immediately + returning if the signal has already occurred. + + The clear() method can be used to discard information about signals + that have already occurred to synchronize wait() with future signal + emissions. + + \sa clear(), TestCase::tryCompare() + */ function wait(timeout) { if (timeout === undefined) timeout = 5000 @@ -87,13 +207,21 @@ Item { qtest_update() } + /*! \internal */ property var qtest_prevTarget: null + /*! \internal */ property string qtest_prevSignalName: "" + /*! \internal */ property int qtest_expectedCount: 0 + /*! \internal */ property var qtest_signalArguments:[] + /*! \internal */ property int qtest_count: 0 + /*! \internal */ property bool qtest_valid:false + /*! \internal */ + /*! \internal */ function qtest_update() { if (qtest_prevTarget != null) { var prevFunc = qtest_prevTarget[qtest_prevSignalName] @@ -119,6 +247,7 @@ Item { } } + /*! \internal */ function qtest_activated() { ++qtest_count spy.qtest_signalArguments[spy.qtest_signalArguments.length] = arguments |