From df3da2c1d16ad9faa749f9bf0a778a8956c48616 Mon Sep 17 00:00:00 2001
From: Nico Vertriest <nico.vertriest@qt.io>
Date: Wed, 14 Feb 2018 13:23:46 +0100
Subject: Doc: Add doc for QSKIP
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Change-Id: Ib8cd1b4926652984b41b5a05bf4dbf3214f2856f
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
---
 src/testlib/doc/src/qttestlib-manual.qdoc | 47 +++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

(limited to 'src/testlib/doc/src/qttestlib-manual.qdoc')

diff --git a/src/testlib/doc/src/qttestlib-manual.qdoc b/src/testlib/doc/src/qttestlib-manual.qdoc
index 6bdf6c33c7..9bd210d71f 100644
--- a/src/testlib/doc/src/qttestlib-manual.qdoc
+++ b/src/testlib/doc/src/qttestlib-manual.qdoc
@@ -382,6 +382,7 @@
     \li \l {Chapter 3: Simulating GUI Events}{Simulating GUI Events}
     \li \l {Chapter 4: Replaying GUI Events}{Replaying GUI Events}
     \li \l {Chapter 5: Writing a Benchmark}{Writing a Benchmark}
+    \li \l {Chapter 6: Skipping Tests with QSKIP}{Skipping Tests}
     \endlist
 
 */
@@ -715,6 +716,7 @@
 
     \previouspage {Chapter 4: Replaying GUI Events}{Chapter 4}
     \contentspage {Qt Test Tutorial}{Contents}
+    \nextpage {Chapter 6: Skipping Tests with QSKIP}{Chapter 6}
 
     \title Chapter 5: Writing a Benchmark
     \brief How to write a benchmark.
@@ -765,3 +767,48 @@
     for more information on these tools and a simple graphing example.
 
 */
+/*!
+    \page qttestlib-tutorial6.html
+
+    \previouspage {Chapter 5: Writing a Benchmark}{Chapter 5}
+    \contentspage {Qt Test Tutorial}{Contents}
+
+    \title Chapter 6: Skipping Tests with QSKIP
+    \brief How to skip tests in certain cases.
+
+    \section2 Using QSKIP(\a description) in a test function
+
+    If the 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,
+    and explains why the test was not carried out.
+
+    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, it is recommended to use QEXPECT_FAIL, so that the test is
+    always completely executed.
+
+    Example of QSKIP in a test function:
+
+    \snippet code/doc_src_qtqskip.cpp 0
+
+    In a data-driven test, each call to QSKIP() skips only the current
+    row of test data. If the data-driven test contains an unconditional
+    call to QSKIP, it produces a skip message for each row of test data.
+
+    \section2 Using QSKIP in a _data function
+
+    If called from a _data function, the QSKIP() macro stops
+    execution of the _data function. This prevents execution of the
+    associated test function.
+
+    See below for an example:
+
+    \snippet code/doc_src_qtqskip.cpp 1
+
+    \section2 Using QSKIP from initTestCase() or initTestCase_data()
+
+    If called from \c initTestCase() or \c initTestCase_data(), the
+    QSKIP() macro will skip all test and _data functions.
+*/
-- 
cgit v1.2.3