diff --git a/doc/config/qtcreator-project.qdocconf b/doc/config/qtcreator-project.qdocconf index 0cbfa5740f9..d4dc2f247c1 100644 --- a/doc/config/qtcreator-project.qdocconf +++ b/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 diff --git a/doc/images/qtcreator-autotests-sort-naturally.png b/doc/images/qtcreator-autotests-sort-naturally.png new file mode 100644 index 00000000000..2f349047d46 Binary files /dev/null and b/doc/images/qtcreator-autotests-sort-naturally.png differ diff --git a/doc/images/qtcreator-autotests.png b/doc/images/qtcreator-autotests.png new file mode 100644 index 00000000000..ee16633a59d Binary files /dev/null and b/doc/images/qtcreator-autotests.png differ diff --git a/doc/images/qtcreator-closesidebar.png b/doc/images/qtcreator-closesidebar.png deleted file mode 100644 index fd88604c369..00000000000 Binary files a/doc/images/qtcreator-closesidebar.png and /dev/null differ diff --git a/doc/images/qtcreator-run-selected-tests.png b/doc/images/qtcreator-run-selected-tests.png new file mode 100644 index 00000000000..60545bc56f9 Binary files /dev/null and b/doc/images/qtcreator-run-selected-tests.png differ diff --git a/doc/src/analyze/cpu-usage-analyzer.qdoc b/doc/src/analyze/cpu-usage-analyzer.qdoc index 5db12465b50..1a2971b79de 100644 --- a/doc/src/analyze/cpu-usage-analyzer.qdoc +++ b/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 diff --git a/doc/src/howto/creator-autotest.qdoc b/doc/src/howto/creator-autotest.qdoc new file mode 100644 index 00000000000..8500c1c1282 --- /dev/null +++ b/doc/src/howto/creator-autotest.qdoc @@ -0,0 +1,179 @@ +/**************************************************************************** +** +** 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}. +*/ diff --git a/doc/src/howto/creator-ui.qdoc b/doc/src/howto/creator-ui.qdoc index c85a65bc50c..01941b78215 100644 --- a/doc/src/howto/creator-ui.qdoc +++ b/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 diff --git a/doc/src/overview/creator-advanced.qdoc b/doc/src/overview/creator-advanced.qdoc index 8a198eba7fd..d5364b50579 100644 --- a/doc/src/overview/creator-advanced.qdoc +++ b/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 diff --git a/doc/src/overview/creator-commercial-overview.qdoc b/doc/src/overview/creator-commercial-overview.qdoc index b4c393c4c05..3665d5c095a 100644 --- a/doc/src/overview/creator-commercial-overview.qdoc +++ b/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: diff --git a/doc/src/overview/creator-overview.qdoc b/doc/src/overview/creator-overview.qdoc index c1a9c8c2f7a..be8189706e8 100644 --- a/doc/src/overview/creator-overview.qdoc +++ b/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 diff --git a/doc/src/overview/creator-testing.qdoc b/doc/src/overview/creator-testing.qdoc index 059cbe2680f..40ac2388f32 100644 --- a/doc/src/overview/creator-testing.qdoc +++ b/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 */ diff --git a/doc/src/projects/creator-projects-creating.qdoc b/doc/src/projects/creator-projects-creating.qdoc index e88869504be..3418bc1c790 100644 --- a/doc/src/projects/creator-projects-creating.qdoc +++ b/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 diff --git a/doc/src/qtcreator.qdoc b/doc/src/qtcreator.qdoc index a5b4b632fdc..fc253e7ab08 100644 --- a/doc/src/qtcreator.qdoc +++ b/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