Doc: experimental Auto Test plugin

Commercial only.

Change-Id: Id2ee9a7765f226c32ec1595e32f4b53ee94d1207
Reviewed-by: Christian Stenger <christian.stenger@theqtcompany.com>

doc/config/qtcreator-project.qdocconf

@@ -22,6 +22,7 @@ indexes +=    $QDOC_INDEX_DIR/qtwidgets/qtwidgets.index \
               $QDOC_INDEX_DIR/qtlinguist/qtlinguist.index \
               $QDOC_INDEX_DIR/qtscript/qtscript.index \
               $QDOC_INDEX_DIR/qtsensors/qtsensors.index \
+              $QDOC_INDEX_DIR/qttestlib/qttestlib.index \
               $QDOC_INDEX_DIR/qtuitools/qtuitools.index \
               $QDOC_INDEX_DIR/qtwebkit/qtwebkit.index \
               $QDOC_INDEX_DIR/qtxml/qtxml.index

doc/src/analyze/cpu-usage-analyzer.qdoc

@@ -26,7 +26,7 @@
     \contentspage {Qt Creator Manual}
     \previouspage creator-clang-static-analyzer.html
     \page creator-cpu-usage-analyzer.html
-    \nextpage creator-advanced.html
+    \nextpage creator-autotest.html
 
     \title Analyzing CPU Usage
 

doc/src/howto/creator-autotest.qdoc

+/****************************************************************************
+**
+** Copyright (C) 2015 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing
+**
+** This file is part of Qt Creator.
+**
+** 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 http://www.qt.io/terms-conditions.  For further information
+** use the contact form at http://www.qt.io/contact-us.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, The Qt Company gives you certain additional
+** rights.  These rights are described in The Qt Company LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+****************************************************************************/
+
+/*!
+    \contentspage {Qt Creator Manual}
+    \previouspage creator-cpu-usage-analyzer.html
+    \page creator-autotest.html
+    \nextpage creator-advanced.html
+
+    \title Running Autotests
+
+    \QC integrates the \l{Qt Test} framework for unit testing Qt based
+    applications and libraries (commercial only). You can use \QC to build and
+    run autotests for your projects.
+
+    \image qtcreator-autotests.png
+
+    To enable the experimental Auto Test plugin, select \uicontrol Help >
+    \uicontrol {About Plugins} > \uicontrol Utilities > \uicontrol {Auto Test}.
+    Restart \QC to be able to use the plugin.
+
+    \section1 Creating Autotests
+
+    You can use a wizard to create projects that contain autotests:
+
+    \list 1
+        \li Select \uicontrol File > \uicontrol {New File or Project} >
+            \uicontrol {Other Project} > \uicontrol {Auto Test} >
+            \uicontrol Choose to create a project with boilerplate code for an
+            autotest.
+
+        \li In the \uicontrol {Project and Test Information} dialog, specify
+            settings for the project and autotest:
+
+            \list 1
+
+                \li Select the \uicontrol {GUI Application} check box to create
+                    a Qt application.
+
+                \li In the \uicontrol {Test case name} field, enter a name for
+                    the test case.
+
+                \li Select the \uicontrol {Requires QApplication} check box to
+                    add the include statement for QApplication to the main.cpp
+                    file of the project.
+
+                \li Select the \uicontrol {Generate initialization and cleanup
+                    code} checkbox to add functions to your test that are
+                    executed by the testing framework to initialize and clean
+                    up the test.
+
+                \li In the \uicontrol {Build auto tests} field, select
+                    \uicontrol Always to always build the autotest when building
+                    the project or \uicontrol {Debug Only} to only build it
+                    during debug builds.
+
+            \endlist
+
+    \endlist
+
+    \QC creates the autotest in the \c{tests\auto} directory in the project
+    directory. Edit the .cpp file to add private slots for each test
+    function in your test. For more information about creating autotests, see
+    \l{Creating a Test}.
+
+    \section1 Building and Running Autotests
+
+    To build and run autotests:
+
+    \list 1
+
+        \li Open a project that contains autotests.
+
+        \li In the \uicontrol {Test Results} output pane, select
+            \inlineimage qtcreator-run.png
+            (\uicontrol {Run All Tests}) to run all test or
+            \inlineimage qtcreator-run-selected-tests.png
+            (\uicontrol {Run Selected Tests}) to run the selected tests.
+
+            You can select the tests to run in the \uicontrol Tests view in the
+            \uicontrol Projects pane. For more information, see
+            \l{Viewing Tests}.
+
+            \note By default, \QC builds a project before deploying and running
+            it.
+
+    \endlist
+
+    If a test takes more than a minute to execute, the default timeout might
+    stop the test execution. To increase the timeout, select  \uicontrol Tools >
+    \uicontrol Options > \uicontrol {Test Settings}.
+
+    The code inside a benchmark test is measured, and possibly also repeated
+    several times in order to get an accurate measurement. This depends on the
+    measurement back-end that you can select in \uicontrol {Test Settings}:
+    walltime, CPU tick counter, event counter, Vallgrind Callgring, and Linux
+    Perf. For more information, see \l{Creating a Benchmark}.
+
+    \section1 Viewing Test Output
+
+    The test results are displayed in the \uicontrol {Test Results} output pane.
+
+    \table
+        \header
+            \li Result
+            \li Description
+        \row
+            \li BENCH
+            \li Benchmark test.
+        \row
+            \li BFAIL
+            \li Blacklisted test case failed. Since Qt 5.4, you can
+                provide a BLACKLIST file for tests. It is mainly used internally
+                by the Qt CI system.
+        \row
+            \li BPASS
+            \li Blacklisted test case passed.
+        \row
+            \li DEBUG
+            \li Debug message.
+        \row
+            \li XFAIL
+            \li Test case is expected to fail, so it is marked by using the
+                QEXPECT_FAIL macro. If the test case passes instead, an
+                unexpected pass (XPASS) is written to the test log.
+        \row
+            \li FAIL
+            \li Test case failed. Double-click the line for more information.
+        \row
+            \li INTERNAL
+            \li Internal message.
+        \row
+            \li PASS
+            \li Test case passed.
+        \row
+            \li SKIP
+            \li Test case was skipped.
+        \row
+            \li XPASS
+            \li Test case passed even though it was expected to fail.
+        \row
+            \li WARN
+            \li Warning message.
+    \endtable
+
+    To view only messages of a particular type, select
+    \inlineimage qtcreator-filter.png
+    (\uicontrol {Filter Test Results}), and then select the types of messages to
+    show.
+
+    To hide internal messages and run configuration warnings, select
+    \uicontrol Tools > \uicontrol Options > \uicontrol {Test Settings}.
+*/

doc/src/howto/creator-ui.qdoc

@@ -132,6 +132,9 @@
         \li \uicontrol Outline shows the symbol hierarchy of a C++ file and the type
             hierarchy of a QML file.
 
+        \li \uicontrol Tests lists autotests and Qt Quick tests in the project
+            (commercial only).
+
         \li \uicontrol {Type Hierarchy} shows the base classes of a class.
 
         \li \uicontrol {Include Hierarchy} shows which files are included in the current file
@@ -154,7 +157,7 @@
             (\uicontrol {Split}). Select new content to view in the split view.
 
         \li To close a sidebar view, click
-            \inlineimage qtcreator-closesidebar.png
+            \inlineimage qtcreator-remove-split-button.png
             (\uicontrol {Close}).
 
     \endlist
@@ -242,6 +245,29 @@
 
     \endlist
 
+    \section2 Viewing Tests
+
+    The \uicontrol Tests view shows the autotests and Qt Quick tests in the
+    current project (commercial only). Select the test cases to run. If a Qt
+    Quick test case does not have a name, it is marked \uicontrol Unnamed in the
+    list. Unnamed test cases are always executed when the application that
+    contains them is run, and therefore you cannot select or deselect them.
+
+    To show or hide init and cleanup or data functions, select
+    \uicontrol {Filter Test Tree} > \uicontrol {Show Init and Cleanup Functions}
+    or \uicontrol {Show Data Functions}. Double-click a function in the list
+    to open its source code in the code editor.
+
+    The test cases are listed in alphabetic order. To list them in the order in
+    which they are defined in the source code, select
+    \inlineimage qtcreator-autotests-sort-naturally.png
+    (\uicontrol {Sort Naturally}).
+
+    To run tests, select \uicontrol {Run All Tests} or
+    \uicontrol {Run Selected Tests} in the context menu.
+
+    To refresh the view, select \uicontrol {Rescan Tests} in the context menu.
+
     \section2 Viewing Type Hierarchy
 
     To view the base classes of a class, right-click the class and select
@@ -275,6 +301,8 @@
 
        \li \uicontrol{General Messages}
 
+       \li \uicontrol{Test Results} (commercial only)
+
     \endlist
 
     Output panes are available in all \l{Modes}{modes}. Click the name of an
@@ -289,7 +317,8 @@
     To open the \uicontrol{General Messages} and \l{Using Version Control Systems}
     {Version Control} panes, select
     \uicontrol {Window > Output Panes}. To display the \uicontrol {To-Do Entries} pane,
-    enable the Todo plugin.
+    enable the Todo plugin and to display the \l{Running Autotests}
+    {Test Results} pane, enable the Auto Tests plugin.
 
     \section2 Issues
 

doc/src/overview/creator-advanced.qdoc

@@ -24,7 +24,7 @@
 
 /*!
     \contentspage {Qt Creator Manual}
-    \previouspage creator-cpu-usage-analyzer.html
+    \previouspage creator-autotest.html
     \page creator-advanced.html
     \nextpage creator-os-supported-platforms.html
 

doc/src/overview/creator-commercial-overview.qdoc

@@ -32,6 +32,7 @@
     \l{http://qt.io/licensing/}{Qt license}:
 
     \list
+        \li \l{Running Autotests}
         \li \l{Using Clang Static Analyzer}{Clang Static Analyzer} integration.
         \li Additional \l{Understanding the Data}{QML Profiler} event
             categories:

doc/src/overview/creator-overview.qdoc

@@ -92,7 +92,7 @@
                 different setups and target platforms.
 
                 For more information, see \l{Building and Running}.
-            \li \b {\l{Debugging and Analyzing}}
+            \li \b {\l{Testing}}
 
                 \QC is integrated to several external native debuggers: GNU
                 Symbolic Debugger (GDB), Microsoft Console Debugger (CDB), and
@@ -105,7 +105,11 @@
                 execution. In addition, the QML Profiler enables you to profile
                 Qt Quick applications.
 
-                For more information, see \l{Debugging and Analyzing}.
+                \QC is integrated to the \l{Qt Test} framework for unit testing
+                Qt based applications and libraries. You can use \QC to build
+                and run autotests (commercial only).
+
+                For more information, see \l{Testing}.
             \li \b {Publishing}
 
                 \QC allows you to create installation packages for mobile

doc/src/overview/creator-testing.qdoc

@@ -28,7 +28,7 @@
     \page creator-testing.html
     \nextpage creator-debugging.html
 
-    \title Debugging and Analyzing
+    \title Testing
 
     \image creator_testing.png
 
@@ -51,6 +51,11 @@
             installed as part of \QC. It enables you to profile your Qt Quick
             applications.
 
+        \li \l{Running Autotests}
+
+            You can use an experimental Auto Test plugin to build and run
+            autotests using \QC (commercial only).
+
     \endlist
 
 */

doc/src/projects/creator-projects-creating.qdoc

@@ -159,6 +159,11 @@
 
                 Qt unit tests for features or classes
 
+            \li Qt Auto Test (commercial only)
+
+                Projects with boilerplate code for an autotest. For more
+                information, see \l {Creating Autotests}.
+
             \li Qt Custom Designer Widgets
 
                 Custom \QD widget or widget collection

doc/src/qtcreator.qdoc

@@ -87,10 +87,11 @@
                     \li \l{Deploying to Mobile Devices}
                     \li \l{Connecting Mobile Devices}
             \endlist
-            \li \b {\l{Debugging and Analyzing}}
+            \li \b {\l{Testing}}
                 \list
                     \li \l{Debugging}
                     \li \l{Analyzing Code}
+                    \li \l{Running Autotests}
                 \endlist
         \row
             \li \inlineimage creator_advanceduse.png
@@ -245,7 +246,7 @@
             \endlist
             \li \l{Customizing the Build Process}
         \endlist
-        \li \l{Debugging and Analyzing}
+        \li \l{Testing}
         \list
             \li \l{Debugging}
             \list
@@ -270,7 +271,7 @@
                 \li \l{Using Clang Static Analyzer}
                 \li \l{Analyzing CPU Usage}
             \endlist
-
+            \li \l{Running Autotests}
         \endlist
         \li \l{Advanced Use}
         \list