diff options
Diffstat (limited to 'src/testlib/doc/src/qttest-best-practices.qdoc')
| -rw-r--r-- | src/testlib/doc/src/qttest-best-practices.qdoc | 25 |
1 files changed, 15 insertions, 10 deletions
diff --git a/src/testlib/doc/src/qttest-best-practices.qdoc b/src/testlib/doc/src/qttest-best-practices.qdoc index 4220312149..cea5b3a8de 100644 --- a/src/testlib/doc/src/qttest-best-practices.qdoc +++ b/src/testlib/doc/src/qttest-best-practices.qdoc @@ -180,14 +180,19 @@ \section2 Select Appropriate Mechanisms to Exclude Tests It is important to select the appropriate mechanism to exclude inapplicable - tests: \l QSKIP(), using conditional statements to exclude parts of a test - function, or not building the test for a particular platform. + tests. + + Use \l QSKIP() to handle cases where a whole test function is found at + run-time to be inapplicable in the current test environment. When just a + part of a test function is to be skipped, a conditional statement can be + used, optionally with a \c qDebug() call to report the reason for skipping + the inapplicable part. - Use QSKIP() to handle cases where a whole test function is found at run-time - to be inapplicable in the current test environment. When just a part of a - test function is to be skipped, a conditional statement can be used, - optionally with a \c qDebug() call to report the reason for skipping the - inapplicable part. + When there are known test failures that should eventually be fixed, + \l QEXPECT_FAIL is recommended, as it supports running the rest of the + test, when possible. It also verifies that the issue still exists, and + lets the code's maintainer know if they unwittingly fix it, a benefit + which is gained even when using the \l {QTest::}{Abort} flag. Test functions or data rows of a data-driven test can be limited to particular platforms, or to particular features being enabled using @@ -383,12 +388,12 @@ only tell you whether \e{the test} was built in debug mode, and that does not guarantee that the \e{Qt libraries} were also built in debug mode. - Your tests can (since Qt 6.3) verify that they do not trigger calls to \l - qWarning() by calling \l QTest::failOnWarnings(). This takes the warning + Your tests can (since Qt 6.3) verify that they do not trigger calls to + \l qWarning() by calling \l QTest::failOnWarning(). This takes the warning message to test for or a \l QRegularExpression to match against warnings; if a matching warning is produced, it will be reported and cause the test to fail. For example, a test that should produce no warnings at all can - \c{QTest::failOnWarnings(QRegularExpression(u".*"_s))}, which will match any + \c{QTest::failOnWarning(QRegularExpression(u".*"_s))}, which will match any warning at all. You can also set the environment variable \c QT_FATAL_WARNINGS to cause |