diff --git a/doc/qtcreator/images/icons/jumpto.png b/doc/qtcreator/images/icons/jumpto.png new file mode 100644 index 00000000000..a913b47d8c1 Binary files /dev/null and b/doc/qtcreator/images/icons/jumpto.png differ diff --git a/doc/qtcreator/images/icons/objectsmap.png b/doc/qtcreator/images/icons/objectsmap.png new file mode 100644 index 00000000000..ca01cdc9113 Binary files /dev/null and b/doc/qtcreator/images/icons/objectsmap.png differ diff --git a/doc/qtcreator/images/qtcreator-squish-control-bar-record-test-case.png b/doc/qtcreator/images/qtcreator-squish-control-bar-record-test-case.png new file mode 100644 index 00000000000..85093103b7e Binary files /dev/null and b/doc/qtcreator/images/qtcreator-squish-control-bar-record-test-case.png differ diff --git a/doc/qtcreator/images/qtcreator-squish-control-bar-run-test-case.png b/doc/qtcreator/images/qtcreator-squish-control-bar-run-test-case.png new file mode 100644 index 00000000000..a7d06933766 Binary files /dev/null and b/doc/qtcreator/images/qtcreator-squish-control-bar-run-test-case.png differ diff --git a/doc/qtcreator/images/qtcreator-squish-create-test-suite-aut.png b/doc/qtcreator/images/qtcreator-squish-create-test-suite-aut.png new file mode 100644 index 00000000000..a3c90866549 Binary files /dev/null and b/doc/qtcreator/images/qtcreator-squish-create-test-suite-aut.png differ diff --git a/doc/qtcreator/images/qtcreator-squish-create-test-suite-language.png b/doc/qtcreator/images/qtcreator-squish-create-test-suite-language.png new file mode 100644 index 00000000000..087e2c1bfa6 Binary files /dev/null and b/doc/qtcreator/images/qtcreator-squish-create-test-suite-language.png differ diff --git a/doc/qtcreator/images/qtcreator-squish-create-test-suite-location.png b/doc/qtcreator/images/qtcreator-squish-create-test-suite-location.png new file mode 100644 index 00000000000..601bdd7b227 Binary files /dev/null and b/doc/qtcreator/images/qtcreator-squish-create-test-suite-location.png differ diff --git a/doc/qtcreator/images/qtcreator-squish-create-test-suite-setup.png b/doc/qtcreator/images/qtcreator-squish-create-test-suite-setup.png new file mode 100644 index 00000000000..f7c56cf44a2 Binary files /dev/null and b/doc/qtcreator/images/qtcreator-squish-create-test-suite-setup.png differ diff --git a/doc/qtcreator/images/qtcreator-squish-create-test-suite.png b/doc/qtcreator/images/qtcreator-squish-create-test-suite.png new file mode 100644 index 00000000000..61fdd85a72a Binary files /dev/null and b/doc/qtcreator/images/qtcreator-squish-create-test-suite.png differ diff --git a/doc/qtcreator/images/qtcreator-squish-debugging-view.png b/doc/qtcreator/images/qtcreator-squish-debugging-view.png new file mode 100644 index 00000000000..32572eaf765 Binary files /dev/null and b/doc/qtcreator/images/qtcreator-squish-debugging-view.png differ diff --git a/doc/qtcreator/images/qtcreator-squish-locals.png b/doc/qtcreator/images/qtcreator-squish-locals.png new file mode 100644 index 00000000000..7968d75432e Binary files /dev/null and b/doc/qtcreator/images/qtcreator-squish-locals.png differ diff --git a/doc/qtcreator/images/qtcreator-squish-output-runner-server-log.png b/doc/qtcreator/images/qtcreator-squish-output-runner-server-log.png new file mode 100644 index 00000000000..25a56a22720 Binary files /dev/null and b/doc/qtcreator/images/qtcreator-squish-output-runner-server-log.png differ diff --git a/doc/qtcreator/images/qtcreator-squish-output-test-results.png b/doc/qtcreator/images/qtcreator-squish-output-test-results.png new file mode 100644 index 00000000000..3c9c9985961 Binary files /dev/null and b/doc/qtcreator/images/qtcreator-squish-output-test-results.png differ diff --git a/doc/qtcreator/images/qtcreator-squish-preferences.png b/doc/qtcreator/images/qtcreator-squish-preferences.png new file mode 100644 index 00000000000..02a5b8f284f Binary files /dev/null and b/doc/qtcreator/images/qtcreator-squish-preferences.png differ diff --git a/doc/qtcreator/images/qtcreator-squish-server-settings-add-attachable-aut.png b/doc/qtcreator/images/qtcreator-squish-server-settings-add-attachable-aut.png new file mode 100644 index 00000000000..9ae743706db Binary files /dev/null and b/doc/qtcreator/images/qtcreator-squish-server-settings-add-attachable-aut.png differ diff --git a/doc/qtcreator/images/qtcreator-squish-server-settings.png b/doc/qtcreator/images/qtcreator-squish-server-settings.png new file mode 100644 index 00000000000..a200cb65f43 Binary files /dev/null and b/doc/qtcreator/images/qtcreator-squish-server-settings.png differ diff --git a/doc/qtcreator/images/qtcreator-squish-symbolic-names.png b/doc/qtcreator/images/qtcreator-squish-symbolic-names.png new file mode 100644 index 00000000000..30427675f04 Binary files /dev/null and b/doc/qtcreator/images/qtcreator-squish-symbolic-names.png differ diff --git a/doc/qtcreator/images/qtcreator-squish-test-script-edit.png b/doc/qtcreator/images/qtcreator-squish-test-script-edit.png new file mode 100644 index 00000000000..4fff8fae3bb Binary files /dev/null and b/doc/qtcreator/images/qtcreator-squish-test-script-edit.png differ diff --git a/doc/qtcreator/images/qtcreator-squish-view-open-squish-suites.png b/doc/qtcreator/images/qtcreator-squish-view-open-squish-suites.png new file mode 100644 index 00000000000..b473e4f6da9 Binary files /dev/null and b/doc/qtcreator/images/qtcreator-squish-view-open-squish-suites.png differ diff --git a/doc/qtcreator/images/qtcreator-squish-view.png b/doc/qtcreator/images/qtcreator-squish-view.png new file mode 100644 index 00000000000..1165c642128 Binary files /dev/null and b/doc/qtcreator/images/qtcreator-squish-view.png differ diff --git a/doc/qtcreator/src/howto/creator-only/creator-autotest.qdoc b/doc/qtcreator/src/howto/creator-only/creator-autotest.qdoc index 6069a7eb5a2..68fd18875c6 100644 --- a/doc/qtcreator/src/howto/creator-only/creator-autotest.qdoc +++ b/doc/qtcreator/src/howto/creator-only/creator-autotest.qdoc @@ -4,7 +4,7 @@ /*! \previouspage creator-ctf-visualizer.html \page creator-autotest.html - \nextpage creator-advanced.html + \nextpage creator-squish.html \title Running Autotests diff --git a/doc/qtcreator/src/howto/creator-only/creator-squish.qdoc b/doc/qtcreator/src/howto/creator-only/creator-squish.qdoc new file mode 100644 index 00000000000..85d7e273e78 --- /dev/null +++ b/doc/qtcreator/src/howto/creator-only/creator-squish.qdoc @@ -0,0 +1,330 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \previouspage creator-autotest.html + \page creator-squish.html + \nextpage creator-advanced.html + + \title Using Squish + + \l{https://doc.froglogic.com/squish/latest/}{Squish} is an automated GUI + testing framework for testing Android, iOS, Java, Qt, Tk, Windows, and + XView applications, as well as HTML-based web applications running in + browsers, such as Apple Safari, Mozilla Firefox, Google Chrome, and + Microsoft Internet Explorer and Edge. + + The experimental Squish plugin integrates Squish into \QC. You can: + + \list + \li Open existing Squish test suites. + \li Create new test suites and test cases. + \li Record test cases (in a very limited way compared to what you can do + inside the Squish IDE). + \li Use Squish Runner and Server to run test suites or cases and view + the results in the \uicontrol Squish \l{Viewing Output}{output}. + \li Set breakpoints before running tests to stop at certain locations and + inspect the local variables, similarly to when debugging a test. + \endlist + + When running test suites or cases, the Squish Runner instructs the Squish + Server to start the application under test (AUT). The server can be running + on multiple machines, and the AUT can be located on a different path on each + of them. Therefore, you must either map AUTs to their corresponding paths or + specify AUT paths to search from in the server settings. + + In addition, you can test an already running application by attaching to it. + This enables you to test your application using a Squish Server running on + another machine. However, you can have only one server attached to your + application at a time. Also, the attached application is not closed when the + test case is completed. + + To use the plugin, you must download and install Squish, create a connection + to the Squish Server, and specify AUTs to run. + + \section1 Enabling the Squish Plugin + + To enable the Squish plugin: + + \list 1 + \li Select \uicontrol Help > \uicontrol {About Plugins} > + \uicontrol Utilities > \uicontrol Squish to enable the plugin. + \li Select \uicontrol {Restart Now} to restart \QC and load the plugin. + \endlist + + \section1 Specifying a Squish Server + + To specify a Squish Server to run: + + \list 1 + \li Select \uicontrol Edit > \uicontrol Preferences > \uicontrol Squish. + \image qtcreator-squish-preferences.png "Squish general preferences" + \li In the \uicontrol {Squish path} field, specify the path to the Squish + installation directory. + \li In the \uicontrol {License path} field, specify the path to your + Squish license file if it is not located in your home folder. For + example, if you have a global installation with several users, where + the license key is installed in the global folder. + \li Select the \uicontrol {Local server} check box to use a locally + installed \c {squishserver.exe}. To use a server running in another + machine, deselect the check box and specify the server address in the + \uicontrol {Server host} field and the port number in the + \uicontrol {Server port} field. If no port is specified, \QC starts + \c squishserver in a way that enables it to automatically select an + open port. + \li Select the \uicontrol {Verbose log} check box to include additional + logging levels in the log output. + \li Select the \uicontrol {Minimize IDE} check box to automatically + minimize \QC when running or recording test cases. + \endlist + + \section1 Specifying AUTs + + To specify applications to test using Squish, select \uicontrol {Tools} > + \uicontrol {Squish} > \uicontrol {Server Settings}. + + \image qtcreator-squish-server-settings.png "Squish Server Settings" + + \section2 Mapping AUTs + + To specify the path to an AUT to run, select \uicontrol {Mapped AUTs} > + \uicontrol Add and locate the AUT. + + The Squish server checks whether the name of the AUT to run is mapped to a + path and starts the AUT using the mapped path. This way, it does not need + to search from all the specified AUT paths. + + Mapping AUTs prevents the server from accidentally executing the wrong AUT + if two different executables have the same name, as the server executes the + first matching AUT it finds in the \uicontrol {AUT Paths} list. + + To change the path to the selected AUT, select \uicontrol {Edit}. + + To remove the mapping to the selected AUT, select \uicontrol {Remove}. + + \section2 Specifying AUT Paths + + To specify a path to search AUTs from, select \uicontrol {AUT Paths} > + \uicontrol Add. + + The Squish Server searches for the executable to run from the specified + AUT paths and runs the first one with the specified name that it finds in + any path. + + To change the selected AUT path, select \uicontrol {Edit}. + + To remove the selected AUT path, select \uicontrol {Remove}. + + \section2 Adding Attachable AUTs + + To specify the path to a running AUT, select \uicontrol {Attachable AUTs} > + \uicontrol Add. In the \uicontrol {Add Attachable AUT} dialog, specify a + connection to a running application to register an attachable AUT. + + \image qtcreator-squish-server-settings-add-attachable-aut.png "Add Attachable AUT dialog" + + To change the connection to the selected AUT, select \uicontrol {Edit}. + + To remove the connection to the selected AUT, select \uicontrol {Remove}. + + \section1 Managing Test Suites and Cases + + You can manage Squish test suites and cases in the \uicontrol Squish + \l {Working with Sidebars}{view}. + + \image qtcreator-squish-view.png "Squish sidebar view" + + To show existing test suites in \uicontrol {Test Suites}, select + \uicontrol {Open Squish Suites} in the context menu. + + \image qtcreator-squish-view-open-squish-suites.png "Open Squish Test Suites dialog" + + You can open the \uicontrol {Squish Test Suite} wizard for creating a new + test suite by selecting \uicontrol {Create New Test Suite} in the context + menu. + + To add a test case to a test suite, select it and then select + \uicontrol {Add New Test Case} in the context menu. + + To close all test suites, select \uicontrol {Close All Test Suites} in the + context menu. + + To add a shared folder to \uicontrol {Shared Folders}, select + \uicontrol {Add Shared Folder} in the context menu. To remove all + shared folders, select \uicontrol {Remove All Shared Folders}. + + Double-click a test suite in \uicontrol {Test Suites} to open the + \c {suite.conf} configuration file for editing. + + \section2 Creating Test Suites + + To create a new test suite: + + \list 1 + \li Select \uicontrol File > \uicontrol {New Project} + > \uicontrol {Squish} > \uicontrol {Squish Test Suite} > + \uicontrol Choose. + \image qtcreator-squish-create-test-suite.png "Create Squish Test Suite wizard" + \li On the \uicontrol {Location} page, in \uicontrol {Test Suite Name}, + enter a name for the test suite. + \image qtcreator-squish-create-test-suite-location.png "Location page" + \li In \uicontrol {Test Suite folder's parent folder}, enter the path to + the folder to create the test suite folder, and then select + \uicontrol Next. + \li On the \uicontrol Setup page, select the GUI toolkit used by the AUT, + and then select \uicontrol Next. + \image qtcreator-squish-create-test-suite-setup.png "Setup page" + Currently, only desktop GUI toolkits are supported. + \li On the \uicontrol {Script Language} page, select the scripting + language to use for the test suite's test script, and then select + \uicontrol Next. + \image qtcreator-squish-create-test-suite-language.png "Languages page" + \li On the \uicontrol {AUT} page, select the AUT to test, and then select + \uicontrol Next. + \image qtcreator-squish-create-test-suite-aut.png "AUT page" + \li On the \uicontrol {Summary} page review the test suite settings, and + then select \uicontrol Finish to create the test suite. + \endlist + + The test suite is listed in \uicontrol {Test Suites} in the \uicontrol Squish + sidebar view. + + \section2 Recording Test Cases + + Squish records tests using the scripting language that you specified for the + test suite. Recordings are made into existing test cases. + + In \uicontrol {Test Suites}, select the \inlineimage icons/recordfill.png + (\uicontrol {Record Test Case}) button next to the test case name. The AUT + that you selected for the test suite is displayed and you can start recording + the test case. + + \image qtcreator-squish-control-bar-record-test-case.png "Squish control bar for recording test cases" + + When you are done, select the \inlineimage icons/stop_small.png + (\uicontrol {Stop}) button in the \uicontrol {Control Bar}. + + You can edit recorded test scripts or copy parts of them into manually + created test scripts. + + \image qtcreator-squish-test-script-edit.png "A test script open in the editor" + + \section2 Running Test Suites + + You can run a recorded test case to have Squish repeat all the actions that + you applied when recording the test, but without the pauses that humans are + prone to but which computers don't need. + To run a test case, select the \inlineimage icons/run_small.png + (\uicontrol {Run}) button next to the test case in \uicontrol {Test Suites}. + + \image qtcreator-squish-control-bar-run-test-case.png "Squish control bar for running test cases" + + While the test is running, you can view test results as well as interrupt and + stop tests in the \uicontrol {Control Bar}. + + \section2 Mapping Symbolic Names + + When Squish records a test, it uses \e {symbolic names} to identify the UI + elements. Symbolic names are stored in an object map that can be either + text-based or script-based. Text-based symbolic names are plain strings + starting with a colon (:), whereas script-based symbolic names are script + variables. + + Squish generates symbolic names programmatically, but you can use them in + hand-written code, or when you edit test cases or use extracts from recorded + test cases. + + Symbolic names have one major advantage over real names: if a property + that a real name depends on changes in the AUT, the real name becomes + invalid, and you must update all occurrences of it in test scripts. + When using symbolic names, you only need to update the real name in the + object map. You do not need to make any changes to the tests. + + To edit the object map of a test suite, select the + \inlineimage icons/objectsmap.png + button next to the test suite in \uicontrol {Test Suites}. + + \image qtcreator-squish-symbolic-names.png "Symbolic Names view" + + You can filter the symbolic names in the \uicontrol {Symbolic Names} view. + To edit a symbolic name or the names or values of its properties, + double-click the name or value in the view and enter a new one. + + To add a new symbolic name, select \uicontrol New. Double-click the + placeholder for the name and enter a new name. Then select \uicontrol New + next to \uicontrol Properties to enter properties for the symbolic name. + + To remove the selected symbolic name or property, select \uicontrol Remove. + + To jump to the symbolic name associated to the selected + property, select \inlineimage icons/jumpto.png + . + + \section2 Inspecting Local Variables + + If you set breakpoints in the test code before running the test, the test + execution is automatically interrupted when a breakpoint is hit. You can + inspect the contents of local variables in the \uicontrol {Squish Locals} + view. + + \image qtcreator-squish-locals.png "Squish Locals view" + + Use the \uicontrol {Step Into}, \uicontrol {Step Over}, and + \uicontrol {Step Out} buttons in the \uicontrol Squish debugging + view to step through the code. + + \image qtcreator-squish-debugging-view.png "Squish debugging view" + + \section2 Specifying Settings for Running Tests + + To specify settings for running tests, select \uicontrol Tools > + \uicontrol Squish > \uicontrol {Server Settings}: + + \list + \li In the \uicontrol {Maximum startup time} field, set the maximum time + to wait for the AUT to start before throwing an error. + \li In the \uicontrol {Maximum response time} field, set the maximum time + to wait for the AUT to respond before throwing an error. + \li In the \uicontrol {Maximum post-mortem wait time} field, set the + maximum time to wait after the main AUT has exited. This is useful + for AUTs invoked through launcher applications, such as shell scripts + or batch files. + \li Select the \uicontrol {Animate mouse cursor} check box to to animate + the mouse cursor when playing back a test. + \endlist + + \section1 Viewing Test Results + + Squish uses compare, verify, and exception functions to record the results of + tests applied to a running AUT in the test log as \e {passes} or \e {fails}. + In addition, any kind of test results can be recorded in the test log. + + You can view the test log in the \uicontrol Squish output, + \uicontrol {Test Results} tab. + + \image qtcreator-squish-output-test-results.png "Test Results output" + + The \uicontrol Result column displays the time when each test run started + and finished, log information and warnings, and test result status: + + \list + \li \uicontrol Pass - The test passed. + \li \uicontrol Fail - The test failed. + \li \uicontrol ExpectedFail - The test failed, as expected. For example, + a known bug in the AUT caused a comparison or verification to fail. + \li \uicontrol UnexpectedPass - The test passed unexpectedly. For + example, a comparison or verification succeeded even though it was + expected to fail. + \endlist + + The \uicontrol Message column displays log messages and information about + the type of the operation that was performed: comparison, verification, or + exception. + + \section1 Viewing Squish Runner and Server Logs + + You can view the Squish Runner and Server logs in the \uicontrol Squish + output, \uicontrol {Runner/Server Log} tab. + + \image qtcreator-squish-output-runner-server-log.png "Runner and Server Log output" +*/ diff --git a/doc/qtcreator/src/overview/creator-only/creator-advanced.qdoc b/doc/qtcreator/src/overview/creator-only/creator-advanced.qdoc index 08be6d3130e..3dfe546f60b 100644 --- a/doc/qtcreator/src/overview/creator-only/creator-advanced.qdoc +++ b/doc/qtcreator/src/overview/creator-only/creator-advanced.qdoc @@ -8,7 +8,7 @@ // ********************************************************************** /*! - \previouspage creator-autotest.html + \previouspage creator-squish.html \page creator-advanced.html \nextpage creator-os-supported-platforms.html diff --git a/doc/qtcreator/src/overview/creator-only/creator-testing.qdoc b/doc/qtcreator/src/overview/creator-only/creator-testing.qdoc index a5f88bcbc0c..0f704f59bcf 100644 --- a/doc/qtcreator/src/overview/creator-only/creator-testing.qdoc +++ b/doc/qtcreator/src/overview/creator-only/creator-testing.qdoc @@ -37,9 +37,13 @@ \li \l{Running Autotests} - You can create, build and run Qt tests, Qt Quick tests, Google + Create, build and run Qt tests, Qt Quick tests, Google tests, and Boost tests using \QC. + \li \l{Using Squish} + + Map AUTs to \QC and run Squish test suites and cases from it. + \endlist */ diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-creating.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-creating.qdoc index c4ae027d2e3..8b2f050adc8 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-creating.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-creating.qdoc @@ -208,6 +208,11 @@ \li Imports an existing project that does not use any of the supported build systems: qmake, Qbs, CMake, or Autotools. This enables you to use \QC as a code editor. + \row + \li Squish + \li Squish Test Suite + \li Creates a new \l {Using Squish}{Squish test suite}. + \endtable To create a new project, select \uicontrol File > \uicontrol{New Project} and diff --git a/doc/qtcreator/src/qtcreator-toc.qdoc b/doc/qtcreator/src/qtcreator-toc.qdoc index 17aa8fdf4a9..7a491e0312c 100644 --- a/doc/qtcreator/src/qtcreator-toc.qdoc +++ b/doc/qtcreator/src/qtcreator-toc.qdoc @@ -187,6 +187,7 @@ \li \l{Visualizing Chrome Trace Events} \endlist \li \l{Running Autotests} + \li \l{Using Squish} \endlist \li \l{Advanced Use} \list diff --git a/doc/qtcreator/src/qtcreator.qdoc b/doc/qtcreator/src/qtcreator.qdoc index a0050fe74d2..fe7e2c788d1 100644 --- a/doc/qtcreator/src/qtcreator.qdoc +++ b/doc/qtcreator/src/qtcreator.qdoc @@ -87,6 +87,7 @@ \li \l{Debugging} \li \l{Analyzing Code} \li \l{Running Autotests} + \li \l{Using Squish} \endlist \li \b {\l{Advanced Use}} \list diff --git a/doc/qtcreator/src/user-interface/creator-ui.qdoc b/doc/qtcreator/src/user-interface/creator-ui.qdoc index bd9285df447..dd429ef8ac2 100644 --- a/doc/qtcreator/src/user-interface/creator-ui.qdoc +++ b/doc/qtcreator/src/user-interface/creator-ui.qdoc @@ -379,9 +379,13 @@ \li \uicontrol{Version Control} \if defined(qtcreator) - \li \uicontrol{Test Results} + \li \l{Running Autotests}{Test Results} + + \li \l{Using Squish}{Squish} test results and Squish Server and + Runner logs \li \uicontrol {To-Do Entries} + \endif \endlist