Improve Qt Test documentation regarding skipping/expecting failures

- Mention QEXPECT_FAIL on the best practices page.
- Link to the best practices page from "Chapter 6: Skipping Tests with
QSKIP".
- Add some more links.

Pick-to: 6.2 6.5 6.6
Change-Id: I0c9e0adb9fe500791dad44869434cf6ecdcf51a1
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>

2 files changed, 17 insertions, 10 deletions

diff --git a/src/testlib/doc/src/qttest-best-practices.qdoc b/src/testlib/doc/src/qttest-best-practices.qdoc
index 54a51f4ace..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.
-
-    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.
+    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.
+
+    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
diff --git a/src/testlib/doc/src/qttestlib-tutorial6.qdoc b/src/testlib/doc/src/qttestlib-tutorial6.qdoc
index 06feef5218..602ca0b28e 100644
--- a/src/testlib/doc/src/qttestlib-tutorial6.qdoc
+++ b/src/testlib/doc/src/qttestlib-tutorial6.qdoc
@@ -12,7 +12,7 @@
 
     \section2 Using QSKIP(\a description) in a test function
 
-    If the QSKIP() macro is called from a test function, it stops
+    If the \l QSKIP() macro is called from a test function, it stops
     the execution of the test without adding a failure to the test log.
     It can be used to skip tests that are certain to fail. The text in
     the QSKIP \a description parameter is appended to the test log,
@@ -20,7 +20,7 @@
 
     QSKIP can be used to skip testing when the implementation is not yet
     complete or not supported on a certain platform. When there are known
-    failures, QEXPECT_FAIL is recommended, as it supports running the rest
+    failures, \l QEXPECT_FAIL is recommended, as it supports running the rest
     of the test, when possible.
 
     Example of QSKIP in a test function:
@@ -45,4 +45,6 @@
 
     If called from \c initTestCase() or \c initTestCase_data(), the
     QSKIP() macro will skip all test and _data functions.
+
+    \sa {Select Appropriate Mechanisms to Exclude Tests}
 */