1508 lines
53 KiB
Plaintext
1508 lines
53 KiB
Plaintext
/****************************************************************************
|
|
**
|
|
** Copyright (C) 2020 The Qt Company Ltd.
|
|
** Contact: https://www.qt.io/licensing/
|
|
**
|
|
** This file is part of the documentation of the Qt Toolkit.
|
|
**
|
|
** $QT_BEGIN_LICENSE:FDL$
|
|
** Commercial License Usage
|
|
** Licensees holding valid commercial Qt licenses may use this file in
|
|
** accordance with the commercial license agreement provided with the
|
|
** Software or, alternatively, in accordance with the terms contained in
|
|
** a written agreement between you and The Qt Company. For licensing terms
|
|
** and conditions see https://www.qt.io/terms-conditions. For further
|
|
** information use the contact form at https://www.qt.io/contact-us.
|
|
**
|
|
** GNU Free Documentation License Usage
|
|
** Alternatively, this file may be used under the terms of the GNU Free
|
|
** Documentation License version 1.3 as published by the Free Software
|
|
** Foundation and appearing in the file included in the packaging of
|
|
** this file. Please review the following information to ensure
|
|
** the GNU Free Documentation License version 1.3 requirements
|
|
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
|
|
** $QT_END_LICENSE$
|
|
**
|
|
****************************************************************************/
|
|
|
|
/*!
|
|
\namespace QTest
|
|
\inmodule QtTest
|
|
|
|
\brief The QTest namespace contains all the functions and
|
|
declarations that are related to Qt Test.
|
|
|
|
See the \l{Qt Test Overview} for information about how to write unit tests.
|
|
*/
|
|
|
|
/*! \macro QVERIFY(condition)
|
|
|
|
\relates QTest
|
|
|
|
The QVERIFY() macro checks whether the \a condition is true or not. If it is
|
|
true, execution continues. If not, a failure is recorded in the test log
|
|
and the test won't be executed further.
|
|
|
|
You can use \l QVERIFY2() when it is practical and valuable to put additional
|
|
information into the test failure report.
|
|
|
|
\note This macro can only be used in a test function that is invoked
|
|
by the test framework.
|
|
|
|
For example, the following code shows this macro being used to verify that a
|
|
\l QSignalSpy object is valid:
|
|
|
|
\snippet code/src_qtestlib_qtestcase_snippet.cpp 0
|
|
|
|
For more information about the failure, use \c QCOMPARE(x, y) instead of
|
|
\c QVERIFY(x == y), because it reports both the expected and actual value
|
|
when the comparison fails.
|
|
|
|
\sa QCOMPARE(), QTRY_VERIFY(), QSignalSpy, QEXPECT_FAIL()
|
|
*/
|
|
|
|
/*! \macro QVERIFY2(condition, message)
|
|
|
|
\relates QTest
|
|
|
|
The QVERIFY2() macro behaves exactly like QVERIFY(), except that it reports
|
|
a \a message when \a condition is false. The \a message is a plain C string.
|
|
|
|
The message can also be obtained from a function call that produces a plain
|
|
C string, such as qPrintable() applied to a QString, which may be built in
|
|
any of its usual ways, including applying \c {.args()} to format some data.
|
|
|
|
Example:
|
|
\snippet code/src_qtestlib_qtestcase.cpp 1
|
|
|
|
For example, if you have a file object and you are testing its \c open()
|
|
function, you might write a test with a statement like:
|
|
|
|
\snippet code/src_qtestlib_qtestcase.cpp 32
|
|
|
|
If this test fails, it will give no clue as to why the file failed to open:
|
|
|
|
\c {FAIL! : tst_QFile::open_write() 'opened' returned FALSE. ()}
|
|
|
|
If there is a more informative error message you could construct from the
|
|
values being tested, you can use \c QVERIFY2() to pass that message along
|
|
with your test condition, to provide a more informative message on failure:
|
|
|
|
\snippet code/src_qtestlib_qtestcase.cpp 33
|
|
|
|
If this branch is being tested in the Qt CI system, the above detailed
|
|
failure message will be inserted into the summary posted to the code-review
|
|
system:
|
|
|
|
\c {FAIL! : tst_QFile::open_write() 'opened' returned FALSE.
|
|
(open /tmp/qt.a3B42Cd: No space left on device)}
|
|
|
|
\sa QVERIFY(), QCOMPARE(), QEXPECT_FAIL()
|
|
*/
|
|
|
|
/*! \macro QCOMPARE(actual, expected)
|
|
|
|
\relates QTest
|
|
|
|
The QCOMPARE() macro compares an \a actual value to an \a expected value
|
|
using the equality operator. If \a actual and \a expected match, execution
|
|
continues. If not, a failure is recorded in the test log and the test
|
|
function returns without attempting any later checks.
|
|
|
|
Always respect QCOMPARE() parameter semantics. The first parameter passed to
|
|
it should always be the actual value produced by the code-under-test, while
|
|
the second parameter should always be the expected value. When the values
|
|
don't match, QCOMPARE() prints them with the labels \e Actual and \e
|
|
Expected. If the parameter order is swapped, debugging a failing test can be
|
|
confusing and tests expecting zero may fail due to rounding errors.
|
|
|
|
QCOMPARE() tries to output the contents of the values if the comparison fails,
|
|
so it is visible from the test log why the comparison failed.
|
|
|
|
Example:
|
|
\snippet code/src_qtestlib_qtestcase.cpp 2
|
|
|
|
When comparing floating-point types (\c float, \c double, and \c qfloat16),
|
|
\l {qFuzzyCompare()} is used for finite values. If \l {<QtGlobal>::}{qFuzzyIsNull()}
|
|
is true for both values, they are also considered equal. Infinities
|
|
match if they have the same sign, and any NaN as actual value matches
|
|
with any NaN as expected value (even though NaN != NaN, even when
|
|
they're identical).
|
|
|
|
When comparing QList, arrays and initializer lists of the value type
|
|
can be passed as expected value:
|
|
\snippet code/src_qtestlib_qtestcase.cpp 34
|
|
|
|
Note that using initializer lists requires a defining a helper macro
|
|
to prevent the preprocessor from interpreting the commas as macro argument
|
|
delimiters:
|
|
\snippet code/src_qtestlib_qtestcase.cpp 35
|
|
|
|
\note QCOMPARE() can only be used in a test function that is invoked
|
|
by the test framework.
|
|
|
|
For your own classes, you can use \l QTest::toString() to format values for
|
|
outputting into the test log.
|
|
|
|
Example:
|
|
\snippet code/src_qtestlib_qtestcase_snippet.cpp 34
|
|
|
|
The return from \c toString() must be a \c {new char []}. That is, it shall
|
|
be released with \c delete[] (rather than \c free() or plain \c delete) once
|
|
the calling code is done with it.
|
|
|
|
\sa QVERIFY(), QTRY_COMPARE(), QTest::toString(), QEXPECT_FAIL()
|
|
*/
|
|
|
|
/*! \macro QVERIFY_EXCEPTION_THROWN(expression, exceptiontype)
|
|
\since 5.3
|
|
|
|
\relates QTest
|
|
\deprecated [6.3] Use \c{QVERIFY_THROWS_EXCEPTION(exceptiontype, expression)} instead.
|
|
*/
|
|
|
|
/*!
|
|
\macro QVERIFY_THROWS_EXCEPTION(exceptiontype, ...)
|
|
\since 6.3
|
|
|
|
The QVERIFY_THROWS_EXCEPTION macro executes the expression given in the variadic
|
|
argument and expects to catch an exception thrown from the expression.
|
|
|
|
There are several possible outcomes:
|
|
|
|
\list
|
|
\li If the expression throws an exception that is either the same as
|
|
\a exceptiontype or derived from \a exceptiontype, then execution will continue.
|
|
|
|
\li Otherwise, if the expression throws no exception, or the
|
|
exception thrown derives from \c{std::exception}, then a failure
|
|
will be recorded in the test log and the macro returns early
|
|
(from enclosing function).
|
|
|
|
\li If the thrown exception derives neither from \c{std::exception} nor from
|
|
\a exceptiontype, a failure will be recorded in the test log, and the exception is
|
|
re-thrown. This avoids problems with e.g. pthread cancellation exceptions.
|
|
\endlist
|
|
|
|
The macro uses variadic arguments so the expression can contain commas that the
|
|
preprocessor considers argument separators, e.g. as in
|
|
\code
|
|
QVERIFY_THROWS_EXCEPTION(std::bad_alloc,
|
|
// macro arguments: ^ exceptiontype
|
|
std::vector<std::pair<int, long>>{42'000'000'000, {42, 42L}});
|
|
// macro arguments: \---------- 1 ----------/ \-------- 2 --------/ \3/ \ 4 /
|
|
// \----------------------- expression -----------------------/
|
|
\endcode
|
|
|
|
\note This macro can only be used in a test function that is invoked
|
|
by the test framework.
|
|
*/
|
|
|
|
/*!
|
|
\macro QVERIFY_THROWS_NO_EXCEPTION(...)
|
|
\since 6.3
|
|
|
|
\relates QTest
|
|
|
|
The QVERIFY_THROWS_NO_EXCEPTION macro executes the expression given in its
|
|
variadic argument and tries to catch any exception thrown from the expression.
|
|
|
|
There are several different outcomes:
|
|
|
|
\list
|
|
\li If the expression does not throw an exception, then execution will continue.
|
|
|
|
\li Otherwise, if an exception derived from \c{std::exception} is caught, a failure
|
|
will be recorded in the test log and the macro returns early (implicit return from
|
|
enclosing function).
|
|
|
|
\li If an exception not derived from \c{std::exception} is caught, a failure will be
|
|
recorded in the test log and the exception will be re-thrown. This avoids problems
|
|
with e.g. pthread cancellation exceptions.
|
|
\endlist
|
|
|
|
The macro uses variadic arguments so the expression can contain commas that the
|
|
preprocessor considers argument separators, e.g. as in
|
|
\code
|
|
QVERIFY_THROWS_NO_EXCEPTION(std::pair<int, long>{42, 42L});
|
|
// macro arguments: \---- 1 ----/ \-- 2 -/ \3 /
|
|
\endcode
|
|
|
|
\note This macro can only be used in a test function that is invoked
|
|
by the test framework.
|
|
*/
|
|
|
|
/*! \macro QTRY_VERIFY_WITH_TIMEOUT(condition, timeout)
|
|
\since 5.0
|
|
|
|
\relates QTest
|
|
|
|
The QTRY_VERIFY_WITH_TIMEOUT() macro is similar to QVERIFY(), but checks the \a condition
|
|
repeatedly, until either the condition becomes true or the \a timeout (in milliseconds) is
|
|
reached. Between each evaluation, events will be processed. If the timeout
|
|
is reached, a failure is recorded in the test log and the test won't be
|
|
executed further.
|
|
|
|
\note This macro can only be used in a test function that is invoked
|
|
by the test framework.
|
|
|
|
\sa QTRY_VERIFY(), QTRY_VERIFY2_WITH_TIMEOUT(), QVERIFY(), QCOMPARE(), QTRY_COMPARE(),
|
|
QEXPECT_FAIL()
|
|
*/
|
|
|
|
|
|
/*! \macro QTRY_VERIFY(condition)
|
|
\since 5.0
|
|
|
|
\relates QTest
|
|
|
|
Checks the \a condition by invoking QTRY_VERIFY_WITH_TIMEOUT() with a timeout of five seconds.
|
|
|
|
\note This macro can only be used in a test function that is invoked
|
|
by the test framework.
|
|
|
|
\sa QTRY_VERIFY_WITH_TIMEOUT(), QTRY_VERIFY2(), QVERIFY(), QCOMPARE(), QTRY_COMPARE(),
|
|
QEXPECT_FAIL()
|
|
*/
|
|
|
|
/*! \macro QTRY_VERIFY2_WITH_TIMEOUT(condition, message, timeout)
|
|
\since 5.6
|
|
|
|
\relates QTest
|
|
|
|
The QTRY_VERIFY2_WITH_TIMEOUT macro is similar to QTRY_VERIFY_WITH_TIMEOUT()
|
|
except that it outputs a verbose \a message when \a condition is still false
|
|
after the specified \a timeout (in milliseconds). The \a message is a plain C string.
|
|
|
|
Example:
|
|
\code
|
|
QTRY_VERIFY2_WITH_TIMEOUT(list.size() > 2, QByteArray::number(list.size()).constData(), 10000);
|
|
\endcode
|
|
|
|
\note This macro can only be used in a test function that is invoked
|
|
by the test framework.
|
|
|
|
\sa QTRY_VERIFY(), QTRY_VERIFY_WITH_TIMEOUT(), QVERIFY(), QCOMPARE(), QTRY_COMPARE(),
|
|
QEXPECT_FAIL()
|
|
*/
|
|
|
|
/*! \macro QTRY_VERIFY2(condition, message)
|
|
\since 5.6
|
|
|
|
\relates QTest
|
|
|
|
Checks the \a condition by invoking QTRY_VERIFY2_WITH_TIMEOUT() with a timeout
|
|
of five seconds. If \a condition is then still false, \a message is output.
|
|
The \a message is a plain C string.
|
|
|
|
Example:
|
|
\code
|
|
QTRY_VERIFY2_WITH_TIMEOUT(list.size() > 2, QByteArray::number(list.size()).constData());
|
|
\endcode
|
|
|
|
\note This macro can only be used in a test function that is invoked
|
|
by the test framework.
|
|
|
|
\sa QTRY_VERIFY2_WITH_TIMEOUT(), QTRY_VERIFY2(), QVERIFY(), QCOMPARE(), QTRY_COMPARE(),
|
|
QEXPECT_FAIL()
|
|
*/
|
|
|
|
/*! \macro QTRY_COMPARE_WITH_TIMEOUT(actual, expected, timeout)
|
|
\since 5.0
|
|
|
|
\relates QTest
|
|
|
|
The QTRY_COMPARE_WITH_TIMEOUT() macro is similar to QCOMPARE(), but performs the comparison
|
|
of the \a actual and \a expected values repeatedly, until either the two values
|
|
are equal or the \a timeout (in milliseconds) is reached. Between each comparison, events
|
|
will be processed. If the timeout is reached, a failure is recorded in the
|
|
test log and the test won't be executed further.
|
|
|
|
\note This macro can only be used in a test function that is invoked
|
|
by the test framework.
|
|
|
|
\sa QTRY_COMPARE(), QCOMPARE(), QVERIFY(), QTRY_VERIFY(), QEXPECT_FAIL()
|
|
*/
|
|
|
|
/*! \macro QTRY_COMPARE(actual, expected)
|
|
\since 5.0
|
|
|
|
\relates QTest
|
|
|
|
Performs a comparison of the \a actual and \a expected values by
|
|
invoking QTRY_COMPARE_WITH_TIMEOUT() with a timeout of five seconds.
|
|
|
|
\note This macro can only be used in a test function that is invoked
|
|
by the test framework.
|
|
|
|
\sa QTRY_COMPARE_WITH_TIMEOUT(), QCOMPARE(), QVERIFY(), QTRY_VERIFY(),
|
|
QEXPECT_FAIL()
|
|
*/
|
|
|
|
/*! \macro QFETCH(type, name)
|
|
|
|
\relates QTest
|
|
|
|
The fetch macro creates a local variable named \a name with the type \a type
|
|
on the stack. The \a name and \a type must match a column from the test's
|
|
data table. This is asserted and the test will abort if the assertion fails.
|
|
|
|
Assuming a test has the following data:
|
|
|
|
\snippet code/src_qtestlib_qtestcase.cpp 3
|
|
|
|
The test data has two elements, a QString called \c aString and an integer
|
|
called \c expected. To fetch these values in the actual test:
|
|
|
|
\snippet code/src_qtestlib_qtestcase.cpp 4
|
|
|
|
\c aString and \c expected are variables on the stack that are initialized with
|
|
the current test data.
|
|
|
|
\note This macro can only be used in a test function that is invoked
|
|
by the test framework. The test function must have a _data function.
|
|
*/
|
|
|
|
/*! \macro QFETCH_GLOBAL(type, name)
|
|
|
|
\relates QTest
|
|
|
|
This macro fetches a variable named \a name with the type \a type from
|
|
a row in the global data table. The \a name and \a type must match a
|
|
column in the global data table. This is asserted and the test will abort
|
|
if the assertion fails.
|
|
|
|
Assuming a test has the following data:
|
|
|
|
\snippet code/src_qtestlib_qtestcase_snippet.cpp 30
|
|
|
|
The test's own data is a single number per row. In this case,
|
|
\c initTestCase_data() also supplies a locale per row. Therefore,
|
|
this test will be run with every combination of locale from the
|
|
latter and number from the former. Thus, with four rows in the
|
|
global table and three in the local, the test function is run for
|
|
12 distinct test-cases (4 * 3 = 12).
|
|
|
|
\snippet code/src_qtestlib_qtestcase_snippet.cpp 31
|
|
|
|
The locale is read from the global data table using QFETCH_GLOBAL(),
|
|
and the number is read from the local data table using QFETCH().
|
|
|
|
\note This macro can only be used in test methods of a class with an
|
|
\c initTestCase_data() method.
|
|
*/
|
|
|
|
/*! \macro QWARN(message)
|
|
|
|
\relates QTest
|
|
\threadsafe
|
|
\deprecated Use qWarning() instead.
|
|
|
|
Appends \a message as a warning to the test log. This macro can be used anywhere
|
|
in your tests.
|
|
*/
|
|
|
|
/*! \macro QFAIL(message)
|
|
|
|
\relates QTest
|
|
|
|
This macro can be used to force a test failure. The test stops
|
|
executing and the failure \a message is appended to the test log.
|
|
|
|
\note This macro can only be used in a test function that is invoked
|
|
by the test framework.
|
|
|
|
Example:
|
|
|
|
\snippet code/src_qtestlib_qtestcase.cpp 5
|
|
*/
|
|
|
|
/*! \macro QTEST(actual, testElement)
|
|
|
|
\relates QTest
|
|
|
|
QTEST() is a convenience macro for \l QCOMPARE() that compares
|
|
the value \a actual with the element \a testElement from the test's data.
|
|
If there is no such element, the test asserts.
|
|
|
|
Apart from that, QTEST() behaves exactly as \l QCOMPARE().
|
|
|
|
Instead of writing:
|
|
|
|
\snippet code/src_qtestlib_qtestcase.cpp 6
|
|
|
|
you can write:
|
|
|
|
\snippet code/src_qtestlib_qtestcase.cpp 7
|
|
|
|
\sa QCOMPARE()
|
|
*/
|
|
|
|
/*! \macro QSKIP(description)
|
|
|
|
\relates QTest
|
|
|
|
If called from a test function, the QSKIP() macro stops execution of the test
|
|
without adding a failure to the test log. You can use it to skip tests that
|
|
wouldn't make sense in the current configuration. For example, a test of font
|
|
rendering may call QSKIP() if the needed fonts are not installed on the test
|
|
system.
|
|
|
|
The text \a description is appended to the test log and should contain an
|
|
explanation of why the test couldn't be executed.
|
|
|
|
If the test is data-driven, each call to QSKIP() in the test function will
|
|
skip only the current row of test data, so an unconditional call to QSKIP()
|
|
will produce one skip message in the test log for each row of test data.
|
|
|
|
If called from an \c _data function, the QSKIP() macro will stop execution of
|
|
the \c _data function and will prevent execution of the associated test
|
|
function. This entirely omits a data-driven test. To omit individual rows,
|
|
make them conditional by using a simple \c{if (condition) newRow(...) << ...}
|
|
in the \c _data function, instead of using QSKIP() in the test function.
|
|
|
|
If called from \c initTestCase_data(), the QSKIP() macro will skip all test
|
|
and \c _data functions. If called from \c initTestCase() when there is no
|
|
\c initTestCase_data(), or when it only sets up one row, QSKIP() will
|
|
likewise skip the whole test. However, if \c initTestCase_data() contains
|
|
more than one row, then \c initTestCase() is called (followed by each test
|
|
and finally the wrap-up) once per row of it. Therefore, a call to QSKIP() in
|
|
\c initTestCase() will merely skip all test functions for the current row of
|
|
global data, set up by \c initTestCase_data().
|
|
|
|
\note This macro can only be used in a test function or \c _data
|
|
function that is invoked by the test framework.
|
|
|
|
Example:
|
|
\snippet code/src_qtestlib_qtestcase.cpp 8
|
|
|
|
\section2 Skipping Known Bugs
|
|
|
|
If a test exposes a known bug that will not be fixed immediately, use the
|
|
QEXPECT_FAIL() macro to document the failure and reference the bug tracking
|
|
identifier for the known issue. When the test is run, expected failures will
|
|
be marked as XFAIL in the test output and will not be counted as failures
|
|
when setting the test program's return code. If an expected failure does
|
|
not occur, the XPASS (unexpected pass) will be reported in the test output
|
|
and will be counted as a test failure.
|
|
|
|
For known bugs, QEXPECT_FAIL() is better than QSKIP() because a developer
|
|
cannot fix the bug without an XPASS result reminding them that the test
|
|
needs to be updated too. If QSKIP() is used, there is no reminder to revise
|
|
or re-enable the test, without which subsequent regressions will not be
|
|
reported.
|
|
|
|
\sa QEXPECT_FAIL(), {Select Appropriate Mechanisms to Exclude Tests}
|
|
*/
|
|
|
|
/*! \macro QEXPECT_FAIL(dataIndex, comment, mode)
|
|
|
|
\relates QTest
|
|
|
|
The QEXPECT_FAIL() macro marks the next \l QCOMPARE() or \l QVERIFY() as an
|
|
expected failure. Instead of adding a failure to the test log, an expected
|
|
failure will be reported.
|
|
|
|
If a \l QVERIFY() or \l QCOMPARE() is marked as an expected failure,
|
|
but passes instead, an unexpected pass (XPASS) is written to the test log.
|
|
|
|
The parameter \a dataIndex describes for which entry in the test data the
|
|
failure is expected. Pass an empty string (\c{""}) if the failure
|
|
is expected for all entries or if no test data exists.
|
|
|
|
\a comment will be appended to the test log for the expected failure.
|
|
|
|
\a mode is a \l QTest::TestFailMode and sets whether the test should
|
|
continue to execute or not. The \a mode is applied regardless of
|
|
whether the expected test failure occurs.
|
|
|
|
\note This macro can only be used in a test function that is invoked
|
|
by the test framework.
|
|
|
|
Example 1:
|
|
\snippet code/src_qtestlib_qtestcase.cpp 9
|
|
|
|
In the example above, an expected fail will be written into the test output
|
|
if the variable \c i is not 42. If the variable \c i is 42, an unexpected pass
|
|
is written instead. The QEXPECT_FAIL() has no influence on the second QCOMPARE()
|
|
statement in the example.
|
|
|
|
Example 2:
|
|
\snippet code/src_qtestlib_qtestcase.cpp 10
|
|
|
|
The above testfunction will not continue executing for the test data
|
|
entry \c{data27} (regardless of the value of \c i).
|
|
|
|
\sa QTest::TestFailMode, QVERIFY(), QCOMPARE()
|
|
*/
|
|
|
|
/*! \macro QFINDTESTDATA(filename)
|
|
\since 5.0
|
|
|
|
\relates QTest
|
|
|
|
Returns a QString for the testdata file referred to by \a filename, or an
|
|
empty QString if the testdata file could not be found.
|
|
|
|
This macro allows the test to load data from an external file without
|
|
hardcoding an absolute filename into the test, or using relative paths
|
|
which may be error prone.
|
|
|
|
The returned path will be the first path from the following list which
|
|
resolves to an existing file or directory:
|
|
|
|
\list
|
|
\li \a filename relative to QCoreApplication::applicationDirPath()
|
|
(only if a QCoreApplication or QApplication object has been created).
|
|
\li \a filename relative to the test's standard install directory
|
|
(QLibraryInfo::TestsPath with the lowercased testcase name appended).
|
|
\li \a filename relative to the directory containing the source file from which
|
|
QFINDTESTDATA is invoked.
|
|
\endlist
|
|
|
|
If the named file/directory does not exist at any of these locations,
|
|
a warning is printed to the test log.
|
|
|
|
For example, in this code:
|
|
\snippet code/src_qtestlib_qtestcase_snippet.cpp 26
|
|
|
|
The testdata file will be resolved as the first existing file from:
|
|
|
|
\list
|
|
\li \c{/home/user/build/myxmlparser/tests/tst_myxmlparser/testxml/simple1.xml}
|
|
\li \c{/usr/local/Qt-5.0.0/tests/tst_myxmlparser/testxml/simple1.xml}
|
|
\li \c{/home/user/sources/myxmlparser/tests/tst_myxmlparser/testxml/simple1.xml}
|
|
\endlist
|
|
|
|
This allows the test to find its testdata regardless of whether the
|
|
test has been installed, and regardless of whether the test's build tree
|
|
is equal to the test's source tree.
|
|
|
|
\note reliable detection of testdata from the source directory requires
|
|
either that qmake is used, or the \c{QT_TESTCASE_BUILDDIR} macro is defined to
|
|
point to the working directory from which the compiler is invoked, or only
|
|
absolute paths to the source files are passed to the compiler. Otherwise, the
|
|
absolute path of the source directory cannot be determined.
|
|
|
|
\note The \c{QT_TESTCASE_BUILDDIR} macro is also implicitly defined if CMake is used
|
|
and the QtTest module is linked to the target. You can change the default
|
|
\c{QT_TESTCASE_BUILDDIR} by setting the QT_TESTCASE_BUILDDIR property on the target.
|
|
|
|
\note For tests that use the \l QTEST_APPLESS_MAIN() macro to generate a
|
|
\c{main()} function, \c{QFINDTESTDATA} will not attempt to find test data
|
|
relative to QCoreApplication::applicationDirPath(). In practice, this means that
|
|
tests using \c{QTEST_APPLESS_MAIN()} will fail to find their test data
|
|
if run from a shadow build tree.
|
|
*/
|
|
|
|
/*! \macro QTEST_MAIN(TestClass)
|
|
|
|
\relates QTest
|
|
|
|
Implements a main() function that instantiates an application object and
|
|
the \a TestClass, and executes all tests in the order they were defined.
|
|
Use this macro to build stand-alone executables.
|
|
|
|
If \c QT_WIDGETS_LIB is defined, the application object will be a QApplication,
|
|
if \c QT_GUI_LIB is defined, the application object will be a QGuiApplication,
|
|
otherwise it will be a QCoreApplication. If qmake is used and the configuration
|
|
includes \c{QT += widgets}, then \c QT_WIDGETS_LIB will be defined automatically.
|
|
Similarly, if qmake is used and the configuration includes \c{QT += gui}, then
|
|
\c QT_GUI_LIB will be defined automatically.
|
|
|
|
\note On platforms that have keypad navigation enabled by default,
|
|
this macro will forcefully disable it if \c QT_WIDGETS_LIB is defined. This is done
|
|
to simplify the usage of key events when writing autotests. If you wish to write a
|
|
test case that uses keypad navigation, you should enable it either in the
|
|
\c {initTestCase()} or \c {init()} functions of your test case by calling
|
|
\l {QApplication::setNavigationMode()}.
|
|
|
|
Example:
|
|
\snippet code/src_qtestlib_qtestcase.cpp 11
|
|
|
|
\sa QTEST_APPLESS_MAIN(), QTEST_GUILESS_MAIN(), QTest::qExec(),
|
|
QApplication::setNavigationMode()
|
|
*/
|
|
|
|
/*! \macro QTEST_APPLESS_MAIN(TestClass)
|
|
|
|
\relates QTest
|
|
|
|
Implements a main() function that executes all tests in \a TestClass.
|
|
|
|
Behaves like \l QTEST_MAIN(), but doesn't instantiate a QApplication
|
|
object. Use this macro for really simple stand-alone non-GUI tests.
|
|
|
|
\sa QTEST_MAIN()
|
|
*/
|
|
|
|
/*! \macro QTEST_GUILESS_MAIN(TestClass)
|
|
\since 5.0
|
|
|
|
\relates QTest
|
|
|
|
Implements a main() function that instantiates a QCoreApplication object
|
|
and the \a TestClass, and executes all tests in the order they were
|
|
defined. Use this macro to build stand-alone executables.
|
|
|
|
Behaves like \l QTEST_MAIN(), but instantiates a QCoreApplication instead
|
|
of the QApplication object. Use this macro if your test case doesn't need
|
|
functionality offered by QApplication, but the event loop is still necessary.
|
|
|
|
\sa QTEST_MAIN()
|
|
*/
|
|
|
|
/*!
|
|
\macro QBENCHMARK
|
|
|
|
\relates QTest
|
|
|
|
This macro is used to measure the performance of code within a test.
|
|
The code to be benchmarked is contained within a code block following
|
|
this macro.
|
|
|
|
For example:
|
|
|
|
\snippet code/src_qtestlib_qtestcase.cpp 27
|
|
|
|
\sa {Qt Test Overview#Creating a Benchmark}{Creating a Benchmark},
|
|
{Chapter 5: Writing a Benchmark}{Writing a Benchmark}
|
|
*/
|
|
|
|
/*!
|
|
\macro QBENCHMARK_ONCE
|
|
\since 4.6
|
|
|
|
\relates QTest
|
|
|
|
\brief The QBENCHMARK_ONCE macro is for measuring performance of a
|
|
code block by running it once.
|
|
|
|
This macro is used to measure the performance of code within a test.
|
|
The code to be benchmarked is contained within a code block following
|
|
this macro.
|
|
|
|
Unlike QBENCHMARK, the contents of the contained code block is only run
|
|
once. The elapsed time will be reported as "0" if it's to short to
|
|
be measured by the selected backend. (Use)
|
|
|
|
\sa {Qt Test Overview#Creating a Benchmark}{Creating a Benchmark},
|
|
{Chapter 5: Writing a Benchmark}{Writing a Benchmark}
|
|
*/
|
|
|
|
/*! \enum QTest::TestFailMode
|
|
|
|
This enum describes the modes for handling a check, such as by \l
|
|
QVERIFY() or \l QCOMPARE() macros, that is known to fail. The mode
|
|
applies regardless of whether the check fails or succeeds.
|
|
|
|
\value Abort Aborts the execution of the test. Use this mode when
|
|
it doesn't make sense to execute the test any further after
|
|
the problematic check.
|
|
|
|
\value Continue Continues execution of the test after the
|
|
problematic check.
|
|
|
|
\sa QEXPECT_FAIL()
|
|
*/
|
|
|
|
/*! \enum QTest::KeyAction
|
|
|
|
This enum describes possible actions for key handling.
|
|
|
|
\value Press The key is pressed.
|
|
\value Release The key is released.
|
|
\value Click The key is clicked (pressed and released).
|
|
\value Shortcut A shortcut is activated. This value has been added in Qt 5.6.
|
|
*/
|
|
|
|
/*! \enum QTest::MouseAction
|
|
|
|
This enum describes possible actions for mouse handling.
|
|
|
|
\value MousePress A mouse button is pressed.
|
|
\value MouseRelease A mouse button is released.
|
|
\value MouseClick A mouse button is clicked (pressed and released).
|
|
\value MouseDClick A mouse button is double clicked (pressed and released twice).
|
|
\value MouseMove The mouse pointer has moved.
|
|
*/
|
|
|
|
/*! \fn void QTest::keyClick(QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
|
|
|
|
Simulates clicking of \a key with an optional \a modifier on a \a widget.
|
|
If \a delay is larger than 0, the test will wait for \a delay milliseconds
|
|
before clicking the key.
|
|
|
|
Examples:
|
|
\snippet code/src_qtestlib_qtestcase_snippet.cpp 14
|
|
|
|
The first example above simulates clicking the \c escape key on \c
|
|
myWidget without any keyboard modifiers and without delay. The
|
|
second example simulates clicking \c shift-escape on \c myWidget
|
|
following a 200 ms delay of the test.
|
|
|
|
\sa QTest::keyClicks()
|
|
*/
|
|
|
|
/*! \fn void QTest::keyClick(QWidget *widget, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
|
|
\overload
|
|
|
|
Simulates clicking of \a key with an optional \a modifier on a \a widget.
|
|
If \a delay is larger than 0, the test will wait for \a delay milliseconds
|
|
before clicking the key.
|
|
|
|
Example:
|
|
\snippet code/src_qtestlib_qtestcase_snippet.cpp 13
|
|
|
|
The example above simulates clicking \c a on \c myWidget without
|
|
any keyboard modifiers and without delay of the test.
|
|
|
|
\sa QTest::keyClicks()
|
|
*/
|
|
|
|
/*! \fn void QTest::keySequence(QWidget *widget, const QKeySequence &keySequence)
|
|
\overload
|
|
\since 5.10
|
|
|
|
Simulates typing of \a keySequence into a \a widget.
|
|
|
|
\sa QTest::keyClick(), QTest::keyClicks()
|
|
*/
|
|
|
|
/*! \fn void QTest::keyClick(QWindow *window, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
|
|
\overload
|
|
\since 5.0
|
|
|
|
Simulates clicking of \a key with an optional \a modifier on a \a window.
|
|
If \a delay is larger than 0, the test will wait for \a delay milliseconds
|
|
before clicking the key.
|
|
|
|
Examples:
|
|
\snippet code/src_qtestlib_qtestcase_snippet.cpp 29
|
|
|
|
The first example above simulates clicking the \c escape key on \c
|
|
myWindow without any keyboard modifiers and without delay. The
|
|
second example simulates clicking \c shift-escape on \c myWindow
|
|
following a 200 ms delay of the test.
|
|
|
|
\sa QTest::keyClicks()
|
|
*/
|
|
|
|
/*! \fn void QTest::keyClick(QWindow *window, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
|
|
\overload
|
|
\since 5.0
|
|
|
|
Simulates clicking of \a key with an optional \a modifier on a \a window.
|
|
If \a delay is larger than 0, the test will wait for \a delay milliseconds
|
|
before clicking the key.
|
|
|
|
Example:
|
|
\snippet code/src_qtestlib_qtestcase_snippet.cpp 28
|
|
|
|
The example above simulates clicking \c a on \c myWindow without
|
|
any keyboard modifiers and without delay of the test.
|
|
|
|
\sa QTest::keyClicks()
|
|
*/
|
|
|
|
/*! \fn void QTest::keySequence(QWindow *window, const QKeySequence &keySequence)
|
|
\overload
|
|
\since 5.10
|
|
|
|
Simulates typing of \a keySequence into a \a window.
|
|
|
|
\sa QTest::keyClick(), QTest::keyClicks()
|
|
*/
|
|
|
|
/*! \fn void QTest::keyEvent(KeyAction action, QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
|
|
|
|
Sends a Qt key event to \a widget with the given \a key and an associated \a action.
|
|
Optionally, a keyboard \a modifier can be specified, as well as a \a delay
|
|
(in milliseconds) of the test before sending the event.
|
|
*/
|
|
|
|
/*! \fn void QTest::keyEvent(KeyAction action, QWidget *widget, char ascii, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
|
|
\overload
|
|
|
|
Sends a Qt key event to \a widget with the given key \a ascii and an associated \a action.
|
|
Optionally, a keyboard \a modifier can be specified, as well as a \a delay
|
|
(in milliseconds) of the test before sending the event.
|
|
*/
|
|
|
|
/*! \fn void QTest::keyEvent(KeyAction action, QWindow *window, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
|
|
\overload
|
|
\since 5.0
|
|
|
|
Sends a Qt key event to \a window with the given \a key and an associated \a action.
|
|
Optionally, a keyboard \a modifier can be specified, as well as a \a delay
|
|
(in milliseconds) of the test before sending the event.
|
|
*/
|
|
|
|
/*! \fn void QTest::keyEvent(KeyAction action, QWindow *window, char ascii, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
|
|
\overload
|
|
\since 5.0
|
|
|
|
Sends a Qt key event to \a window with the given key \a ascii and an associated \a action.
|
|
Optionally, a keyboard \a modifier can be specified, as well as a \a delay
|
|
(in milliseconds) of the test before sending the event.
|
|
*/
|
|
|
|
/*! \fn void QTest::keyPress(QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
|
|
|
|
Simulates pressing a \a key with an optional \a modifier on a \a widget. If \a delay
|
|
is larger than 0, the test will wait for \a delay milliseconds before pressing the key.
|
|
|
|
\note At some point you should release the key using \l keyRelease().
|
|
|
|
\sa QTest::keyRelease(), QTest::keyClick()
|
|
*/
|
|
|
|
/*! \fn void QTest::keyPress(QWidget *widget, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
|
|
\overload
|
|
|
|
Simulates pressing a \a key with an optional \a modifier on a \a widget.
|
|
If \a delay is larger than 0, the test will wait for \a delay milliseconds
|
|
before pressing the key.
|
|
|
|
\note At some point you should release the key using \l keyRelease().
|
|
|
|
\sa QTest::keyRelease(), QTest::keyClick()
|
|
*/
|
|
|
|
/*! \fn void QTest::keyPress(QWindow *window, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
|
|
\overload
|
|
\since 5.0
|
|
|
|
Simulates pressing a \a key with an optional \a modifier on a \a window. If \a delay
|
|
is larger than 0, the test will wait for \a delay milliseconds before pressing the key.
|
|
|
|
\note At some point you should release the key using \l keyRelease().
|
|
|
|
\sa QTest::keyRelease(), QTest::keyClick()
|
|
*/
|
|
|
|
/*! \fn void QTest::keyPress(QWindow *window, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
|
|
\overload
|
|
\since 5.0
|
|
|
|
Simulates pressing a \a key with an optional \a modifier on a \a window.
|
|
If \a delay is larger than 0, the test will wait for \a delay milliseconds
|
|
before pressing the key.
|
|
|
|
\note At some point you should release the key using \l keyRelease().
|
|
|
|
\sa QTest::keyRelease(), QTest::keyClick()
|
|
*/
|
|
|
|
/*! \fn void QTest::keyRelease(QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
|
|
|
|
Simulates releasing a \a key with an optional \a modifier on a \a widget.
|
|
If \a delay is larger than 0, the test will wait for \a delay milliseconds
|
|
before releasing the key.
|
|
|
|
\sa QTest::keyPress(), QTest::keyClick()
|
|
*/
|
|
|
|
/*! \fn void QTest::keyRelease(QWidget *widget, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
|
|
\overload
|
|
|
|
Simulates releasing a \a key with an optional \a modifier on a \a widget.
|
|
If \a delay is larger than 0, the test will wait for \a delay milliseconds
|
|
before releasing the key.
|
|
|
|
\sa QTest::keyClick()
|
|
*/
|
|
|
|
/*! \fn void QTest::keyRelease(QWindow *window, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
|
|
\overload
|
|
\since 5.0
|
|
|
|
Simulates releasing a \a key with an optional \a modifier on a \a window.
|
|
If \a delay is larger than 0, the test will wait for \a delay milliseconds
|
|
before releasing the key.
|
|
|
|
\sa QTest::keyPress(), QTest::keyClick()
|
|
*/
|
|
|
|
/*! \fn void QTest::keyRelease(QWindow *window, char key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
|
|
\overload
|
|
\since 5.0
|
|
|
|
Simulates releasing a \a key with an optional \a modifier on a \a window.
|
|
If \a delay is larger than 0, the test will wait for \a delay milliseconds
|
|
before releasing the key.
|
|
|
|
\sa QTest::keyClick()
|
|
*/
|
|
|
|
/*! \fn void QTest::keyClicks(QWidget *widget, const QString &sequence, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
|
|
|
|
Simulates clicking a \a sequence of keys on a \a
|
|
widget. Optionally, a keyboard \a modifier can be specified as
|
|
well as a \a delay (in milliseconds) of the test before each key
|
|
click.
|
|
|
|
Example:
|
|
\snippet code/src_qtestlib_qtestcase_snippet.cpp 15
|
|
|
|
The example above simulates clicking the sequence of keys
|
|
representing "hello world" on \c myWidget without any keyboard
|
|
modifiers and without delay of the test.
|
|
|
|
\sa QTest::keyClick()
|
|
*/
|
|
|
|
/*! \fn void QTest::mousePress(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier = 0, QPoint pos = QPoint(), int delay=-1)
|
|
|
|
Simulates pressing a mouse \a button with an optional \a modifier
|
|
on a \a widget. The position is defined by \a pos; the default
|
|
position is the center of the widget. If \a delay is specified,
|
|
the test will wait for the specified amount of milliseconds before
|
|
the press.
|
|
|
|
\sa QTest::mouseRelease(), QTest::mouseClick()
|
|
*/
|
|
|
|
/*! \fn void QTest::mousePress(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey = 0, QPoint pos = QPoint(), int delay=-1)
|
|
\overload
|
|
\since 5.0
|
|
|
|
Simulates pressing a mouse \a button with an optional \a stateKey modifier
|
|
on a \a window. The position is defined by \a pos; the default
|
|
position is the center of the window. If \a delay is specified,
|
|
the test will wait for the specified amount of milliseconds before
|
|
the press.
|
|
|
|
\sa QTest::mouseRelease(), QTest::mouseClick()
|
|
*/
|
|
|
|
/*! \fn void QTest::mouseRelease(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier = 0, QPoint pos = QPoint(), int delay=-1)
|
|
|
|
Simulates releasing a mouse \a button with an optional \a modifier
|
|
on a \a widget. The position of the release is defined by \a pos;
|
|
the default position is the center of the widget. If \a delay is
|
|
specified, the test will wait for the specified amount of
|
|
milliseconds before releasing the button.
|
|
|
|
\sa QTest::mousePress(), QTest::mouseClick()
|
|
*/
|
|
|
|
/*! \fn void QTest::mouseRelease(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey = 0, QPoint pos = QPoint(), int delay=-1)
|
|
\overload
|
|
\since 5.0
|
|
|
|
Simulates releasing a mouse \a button with an optional \a stateKey modifier
|
|
on a \a window. The position of the release is defined by \a pos;
|
|
the default position is the center of the window. If \a delay is
|
|
specified, the test will wait for the specified amount of
|
|
milliseconds before releasing the button.
|
|
|
|
\sa QTest::mousePress(), QTest::mouseClick()
|
|
*/
|
|
|
|
/*! \fn void QTest::mouseClick(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier = 0, QPoint pos = QPoint(), int delay=-1)
|
|
|
|
Simulates clicking a mouse \a button with an optional \a modifier
|
|
on a \a widget. The position of the click is defined by \a pos;
|
|
the default position is the center of the widget. If \a delay is
|
|
specified, the test will wait for the specified amount of
|
|
milliseconds before pressing and before releasing the button.
|
|
|
|
\sa QTest::mousePress(), QTest::mouseRelease()
|
|
*/
|
|
|
|
/*! \fn void QTest::mouseClick(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey = 0, QPoint pos = QPoint(), int delay=-1)
|
|
\overload
|
|
\since 5.0
|
|
|
|
Simulates clicking a mouse \a button with an optional \a stateKey modifier
|
|
on a \a window. The position of the click is defined by \a pos;
|
|
the default position is the center of the window. If \a delay is
|
|
specified, the test will wait for the specified amount of
|
|
milliseconds before pressing and before releasing the button.
|
|
|
|
\sa QTest::mousePress(), QTest::mouseRelease()
|
|
*/
|
|
|
|
/*! \fn void QTest::mouseDClick(QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers modifier = 0, QPoint pos = QPoint(), int delay=-1)
|
|
|
|
Simulates double clicking a mouse \a button with an optional \a
|
|
modifier on a \a widget. The position of the click is defined by
|
|
\a pos; the default position is the center of the widget. If \a
|
|
delay is specified, the test will wait for the specified amount of
|
|
milliseconds before each press and release.
|
|
|
|
\sa QTest::mouseClick()
|
|
*/
|
|
|
|
/*! \fn void QTest::mouseDClick(QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey = 0, QPoint pos = QPoint(), int delay=-1)
|
|
\overload
|
|
\since 5.0
|
|
|
|
Simulates double clicking a mouse \a button with an optional \a stateKey
|
|
modifier on a \a window. The position of the click is defined by
|
|
\a pos; the default position is the center of the window. If \a
|
|
delay is specified, the test will wait for the specified amount of
|
|
milliseconds before each press and release.
|
|
|
|
\sa QTest::mouseClick()
|
|
*/
|
|
|
|
/*! \fn void QTest::mouseMove(QWidget *widget, QPoint pos = QPoint(), int delay=-1)
|
|
|
|
Moves the mouse pointer to a \a widget. If \a pos is not
|
|
specified, the mouse pointer moves to the center of the widget. If
|
|
a \a delay (in milliseconds) is given, the test will wait before
|
|
moving the mouse pointer.
|
|
*/
|
|
|
|
/*! \fn void QTest::mouseMove(QWindow *window, QPoint pos = QPoint(), int delay=-1)
|
|
\overload
|
|
\since 5.0
|
|
|
|
Moves the mouse pointer to a \a window. If \a pos is not
|
|
specified, the mouse pointer moves to the center of the window. If
|
|
a \a delay (in milliseconds) is given, the test will wait before
|
|
moving the mouse pointer.
|
|
*/
|
|
|
|
/*!
|
|
\fn template <typename T1, typename T2> char *QTest::toString(const QPair<T1, T2> &pair)
|
|
\overload
|
|
\since 5.11
|
|
Returns a textual representation of the \a pair.
|
|
*/
|
|
|
|
/*!
|
|
\fn template <typename T1, typename T2> char *QTest::toString(const std::pair<T1, T2> &pair)
|
|
\overload
|
|
\since 5.11
|
|
Returns a textual representation of the \a pair.
|
|
*/
|
|
|
|
/*!
|
|
\fn char *QTest::toString(const QVector2D &v)
|
|
\overload
|
|
\since 5.11
|
|
Returns a textual representation of the 2D vector \a v.
|
|
*/
|
|
|
|
/*!
|
|
\fn char *QTest::toString(const QVector3D &v)
|
|
\overload
|
|
\since 5.11
|
|
Returns a textual representation of the 3D vector \a v.
|
|
*/
|
|
|
|
/*!
|
|
\fn char *QTest::toString(const QVector4D &v)
|
|
\overload
|
|
\since 5.11
|
|
Returns a textual representation of the 4D vector \a v.
|
|
*/
|
|
|
|
/*!
|
|
\fn template<typename T> char *QTest::toString(const T &value)
|
|
|
|
Returns a textual representation of \a value. This function is used by
|
|
\l QCOMPARE() to output verbose information in case of a test failure.
|
|
|
|
You can add specializations or overloads of this function to your test to enable
|
|
verbose output.
|
|
|
|
\note Starting with Qt 5.5, you should prefer to provide a toString() function
|
|
in the type's namespace instead of specializing this template.
|
|
If your code needs to continue to work with the QTestLib from Qt 5.4 or
|
|
earlier, you need to continue to use specialization.
|
|
|
|
\note The caller of toString() must delete the returned data
|
|
using \c{delete[]}. Your implementation should return a string
|
|
created with \c{new[]} or qstrdup(). The easiest way to do so is to
|
|
create a QByteArray or QString and call QTest::toString() on it
|
|
(see second example below).
|
|
|
|
Example for specializing (Qt ≤ 5.4):
|
|
|
|
\snippet code/src_qtestlib_qtestcase_snippet.cpp 16
|
|
|
|
The example above defines a toString() specialization for a class
|
|
called \c MyPoint. Whenever a comparison of two instances of \c
|
|
MyPoint fails, \l QCOMPARE() will call this function to output the
|
|
contents of \c MyPoint to the test log.
|
|
|
|
Same example, but with overloading (Qt ≥ 5.5):
|
|
|
|
\snippet code/src_qtestlib_qtestcase_snippet.cpp toString-overload
|
|
|
|
\sa QCOMPARE()
|
|
*/
|
|
|
|
/*!
|
|
\fn char *QTest::toString(const QLatin1String &string)
|
|
\overload
|
|
|
|
Returns a textual representation of the given \a string.
|
|
*/
|
|
|
|
/*!
|
|
\fn char *QTest::toString(std::nullptr_t)
|
|
\overload
|
|
\since 5.8
|
|
|
|
Returns a string containing \nullptr.
|
|
*/
|
|
|
|
/*!
|
|
\fn char *QTest::toString(const QStringView &string)
|
|
\overload
|
|
\since 5.11
|
|
|
|
Returns a textual representation of the given \a string.
|
|
*/
|
|
|
|
/*!
|
|
\fn char *QTest::toString(const QUuid &uuid)
|
|
\overload
|
|
\since 5.11
|
|
|
|
Returns a textual representation of the given \a uuid.
|
|
*/
|
|
|
|
/*!
|
|
\fn char *QTest::toString(const QString &string)
|
|
\overload
|
|
|
|
Returns a textual representation of the given \a string.
|
|
*/
|
|
|
|
/*!
|
|
\fn char *QTest::toString(const QByteArray &ba)
|
|
\overload
|
|
|
|
Returns a textual representation of the byte array \a ba.
|
|
|
|
\sa QTest::toHexRepresentation()
|
|
*/
|
|
|
|
/*!
|
|
\fn char *QTest::toString(const QCborError &c)
|
|
\overload
|
|
\since 5.12
|
|
|
|
Returns a textual representation of the given CBOR error \a c.
|
|
*/
|
|
|
|
/*!
|
|
\fn template <class... Types> char *QTest::toString(const std::tuple<Types...> &tuple)
|
|
\overload
|
|
\since 5.12
|
|
|
|
Returns a textual representation of the given \a tuple.
|
|
*/
|
|
|
|
/*!
|
|
\fn char *QTest::toString(const QTime &time)
|
|
\overload
|
|
|
|
Returns a textual representation of the given \a time.
|
|
*/
|
|
|
|
/*!
|
|
\fn char *QTest::toString(const QDate &date)
|
|
\overload
|
|
|
|
Returns a textual representation of the given \a date.
|
|
*/
|
|
|
|
/*!
|
|
\fn char *QTest::toString(const QDateTime &dateTime)
|
|
\overload
|
|
|
|
Returns a textual representation of the date and time specified by
|
|
\a dateTime.
|
|
*/
|
|
|
|
/*!
|
|
\fn char *QTest::toString(const QChar &character)
|
|
\overload
|
|
|
|
Returns a textual representation of the given \a character.
|
|
*/
|
|
|
|
/*!
|
|
\fn char *QTest::toString(const QPoint &point)
|
|
\overload
|
|
|
|
Returns a textual representation of the given \a point.
|
|
*/
|
|
|
|
/*!
|
|
\fn char *QTest::toString(const QSize &size)
|
|
\overload
|
|
|
|
Returns a textual representation of the given \a size.
|
|
*/
|
|
|
|
/*!
|
|
\fn char *QTest::toString(const QRect &rectangle)
|
|
\overload
|
|
|
|
Returns a textual representation of the given \a rectangle.
|
|
*/
|
|
|
|
/*!
|
|
\fn char *QTest::toString(const QUrl &url)
|
|
\since 4.4
|
|
\overload
|
|
|
|
Returns a textual representation of the given \a url.
|
|
*/
|
|
|
|
/*!
|
|
\fn char *QTest::toString(const QPointF &point)
|
|
\overload
|
|
|
|
Returns a textual representation of the given \a point.
|
|
*/
|
|
|
|
/*!
|
|
\fn char *QTest::toString(const QSizeF &size)
|
|
\overload
|
|
|
|
Returns a textual representation of the given \a size.
|
|
*/
|
|
|
|
/*!
|
|
\fn char *QTest::toString(const QRectF &rectangle)
|
|
\overload
|
|
|
|
Returns a textual representation of the given \a rectangle.
|
|
*/
|
|
|
|
/*!
|
|
\fn char *QTest::toString(const QVariant &variant)
|
|
\overload
|
|
|
|
Returns a textual representation of the given \a variant.
|
|
*/
|
|
|
|
/*!
|
|
\fn char *QTest::toString(QSizePolicy::ControlType ct)
|
|
\overload
|
|
\since 5.5
|
|
|
|
Returns a textual representation of control type \a ct.
|
|
*/
|
|
|
|
/*!
|
|
\fn char *QTest::toString(QSizePolicy::ControlTypes cts)
|
|
\overload
|
|
\since 5.5
|
|
|
|
Returns a textual representation of control types \a cts.
|
|
*/
|
|
|
|
/*!
|
|
\fn char *QTest::toString(QSizePolicy::Policy p)
|
|
\overload
|
|
\since 5.5
|
|
|
|
Returns a textual representation of policy \a p.
|
|
*/
|
|
|
|
/*!
|
|
\fn char *QTest::toString(QSizePolicy sp)
|
|
\overload
|
|
\since 5.5
|
|
|
|
Returns a textual representation of size policy \a sp.
|
|
*/
|
|
|
|
/*!
|
|
\fn template <typename Tuple, int... I> char *QTest::toString(const Tuple &tuple, QtPrivate::IndexesList<I...> )
|
|
\internal
|
|
\since 5.12
|
|
*/
|
|
|
|
/*!
|
|
\fn QPointingDevice * QTest::createTouchDevice(QInputDevice::DeviceType devType = QInputDevice::DeviceType::TouchScreen, QInputDevice::Capabilities caps = QInputDevice::Capability::Position)
|
|
\since 5.8
|
|
|
|
Creates a dummy touch device of type \a devType with capabilities \a caps for
|
|
simulation of touch events.
|
|
|
|
The touch device will be registered with the QPA window system interface,
|
|
and deleted automatically when the QCoreApplication is deleted. So you
|
|
should typically use createTouchDevice() to initialize a QPointingDevice
|
|
member variable in your test case class, and use the same instance for all tests.
|
|
|
|
\sa QTest::QTouchEventSequence, touchEvent()
|
|
*/
|
|
|
|
/*!
|
|
\class QTest::QTouchEventSequence
|
|
\inmodule QtTest
|
|
\since 4.6
|
|
|
|
\brief The QTouchEventSequence class is used to simulate a sequence of touch events.
|
|
|
|
To simulate a sequence of touch events on a specific device for a window or widget, call
|
|
QTest::touchEvent to create a QTouchEventSequence instance. Add touch events to
|
|
the sequence by calling press(), move(), release() and stationary(), and let the
|
|
instance run out of scope to commit the sequence to the event system.
|
|
|
|
Example:
|
|
\snippet code/src_qtestlib_qtestcase_snippet.cpp 25
|
|
*/
|
|
|
|
/*!
|
|
\fn QTest::QTouchEventSequence::~QTouchEventSequence()
|
|
|
|
Commits this sequence of touch events, unless autoCommit was disabled, and frees allocated resources.
|
|
*/
|
|
|
|
/*!
|
|
\fn void QTest::QTouchEventSequence::commit(bool processEvents)
|
|
|
|
Commits this sequence of touch events to the event system. Normally there is no need to call this
|
|
function because it is called from the destructor. However, if autoCommit is disabled, the events
|
|
only get committed upon explicitly calling this function.
|
|
|
|
In special cases tests may want to disable the processing of the events. This can be achieved by
|
|
setting \a processEvents to false. This results in merely queuing the events, the event loop will
|
|
not be forced to process them.
|
|
*/
|
|
|
|
/*!
|
|
\fn QTouchEventSequence &QTest::QTouchEventSequence::press(int touchId, const QPoint &pt, QWindow *window)
|
|
\since 5.0
|
|
|
|
Adds a press event for touchpoint \a touchId at position \a pt to this sequence and returns
|
|
a reference to this QTouchEventSequence.
|
|
|
|
The position \a pt is interpreted as relative to \a window. If \a window is the null pointer, then
|
|
\a pt is interpreted as relative to the window provided when instantiating this QTouchEventSequence.
|
|
|
|
Simulates that the user pressed the touch screen or pad with the finger identified by \a touchId.
|
|
*/
|
|
|
|
/*!
|
|
\fn QTouchEventWidgetSequence &QTest::QTouchEventWidgetSequence::press(int touchId, const QPoint &pt, QWidget *widget)
|
|
|
|
Adds a press event for touchpoint \a touchId at position \a pt to this sequence and returns
|
|
a reference to this QTouchEventWidgetSequence.
|
|
|
|
The position \a pt is interpreted as relative to \a widget. If \a widget is the null pointer, then
|
|
\a pt is interpreted as relative to the widget provided when instantiating this QTouchEventWidgetSequence.
|
|
|
|
Simulates that the user pressed the touch screen or pad with the finger identified by \a touchId.
|
|
*/
|
|
|
|
/*!
|
|
\fn QTouchEventSequence &QTest::QTouchEventSequence::move(int touchId, const QPoint &pt, QWindow *window)
|
|
\since 5.0
|
|
|
|
Adds a move event for touchpoint \a touchId at position \a pt to this sequence and returns
|
|
a reference to this QTouchEventSequence.
|
|
|
|
The position \a pt is interpreted as relative to \a window. If \a window is the null pointer, then
|
|
\a pt is interpreted as relative to the window provided when instantiating this QTouchEventSequence.
|
|
|
|
Simulates that the user moved the finger identified by \a touchId.
|
|
*/
|
|
|
|
/*!
|
|
\fn QTouchEventWidgetSequence &QTest::QTouchEventWidgetSequence::move(int touchId, const QPoint &pt, QWidget *widget)
|
|
|
|
Adds a move event for touchpoint \a touchId at position \a pt to this sequence and returns
|
|
a reference to this QTouchEventWidgetSequence.
|
|
|
|
The position \a pt is interpreted as relative to \a widget. If \a widget is the null pointer, then
|
|
\a pt is interpreted as relative to the widget provided when instantiating this QTouchEventWidgetSequence.
|
|
|
|
Simulates that the user moved the finger identified by \a touchId.
|
|
*/
|
|
|
|
/*!
|
|
\fn QTouchEventSequence &QTest::QTouchEventSequence::release(int touchId, const QPoint &pt, QWindow *window)
|
|
\since 5.0
|
|
|
|
Adds a release event for touchpoint \a touchId at position \a pt to this sequence and returns
|
|
a reference to this QTouchEventSequence.
|
|
|
|
The position \a pt is interpreted as relative to \a window. If \a window is the null pointer, then
|
|
\a pt is interpreted as relative to the window provided when instantiating this QTouchEventSequence.
|
|
|
|
Simulates that the user lifted the finger identified by \a touchId.
|
|
*/
|
|
|
|
/*!
|
|
\fn QTouchEventWidgetSequence &QTest::QTouchEventWidgetSequence::release(int touchId, const QPoint &pt, QWidget *widget)
|
|
|
|
Adds a release event for touchpoint \a touchId at position \a pt to this sequence and returns
|
|
a reference to this QTouchEventWidgetSequence.
|
|
|
|
The position \a pt is interpreted as relative to \a widget. If \a widget is the null pointer, then
|
|
\a pt is interpreted as relative to the widget provided when instantiating this QTouchEventWidgetSequence.
|
|
|
|
Simulates that the user lifted the finger identified by \a touchId.
|
|
*/
|
|
|
|
/*!
|
|
\fn QTouchEventSequence &QTest::QTouchEventSequence::stationary(int touchId)
|
|
|
|
Adds a stationary event for touchpoint \a touchId to this sequence and returns
|
|
a reference to this QTouchEventSequence.
|
|
|
|
Simulates that the user did not move the finger identified by \a touchId.
|
|
*/
|
|
|
|
/*!
|
|
\fn QTouchEventSequence QTest::touchEvent(QWindow *window, QPointingDevice *device, bool autoCommit)
|
|
\since 5.0
|
|
|
|
Creates and returns a QTouchEventSequence for the \a device to
|
|
simulate events for \a window.
|
|
|
|
When adding touch events to the sequence, \a window will also be used to translate
|
|
the position provided to screen coordinates, unless another window is provided in the
|
|
respective calls to press(), move() etc.
|
|
|
|
The touch events are committed to the event system when the destructor of the
|
|
QTouchEventSequence is called (ie when the object returned runs out of scope), unless
|
|
\a autoCommit is set to false. When \a autoCommit is false, commit() has to be called
|
|
manually.
|
|
|
|
\l createTouchDevice() can be called to create a test touch device for use with this
|
|
function.
|
|
*/
|
|
|
|
/*!
|
|
\fn QTouchEventSequence QTest::touchEvent(QWidget *widget, QPointingDevice *device, bool autoCommit)
|
|
|
|
Creates and returns a QTouchEventSequence for the \a device to
|
|
simulate events for \a widget.
|
|
|
|
When adding touch events to the sequence, \a widget will also be used to translate
|
|
the position provided to screen coordinates, unless another widget is provided in the
|
|
respective calls to press(), move() etc.
|
|
|
|
The touch events are committed to the event system when the destructor of the
|
|
QTouchEventSequence is called (ie when the object returned runs out of scope), unless
|
|
\a autoCommit is set to false. When \a autoCommit is false, commit() has to be called
|
|
manually.
|
|
|
|
\l createTouchDevice() can be called to create a test touch device for use with this
|
|
function.
|
|
*/
|
|
|
|
// Internals of qtestmouse.h:
|
|
|
|
/*! \fn void QTest::mouseEvent(MouseAction action, QWidget *widget, Qt::MouseButton button, Qt::KeyboardModifiers stateKey, QPoint pos, int delay=-1)
|
|
\internal
|
|
*/
|
|
|
|
/*! \fn void QTest::mouseEvent(MouseAction action, QWindow *window, Qt::MouseButton button, Qt::KeyboardModifiers stateKey, QPoint pos, int delay=-1)
|
|
\internal
|
|
*/
|