// Copyright (C) 2022 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \page creator-how-to-connect-squish-server.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-test

    \title Connect to Squish Server

    To create a connection to Squish Server:

    \list 1
        \li Select \preferences > \uicontrol Squish > \uicontrol General.
            \image {qtcreator-squish-preferences.png} {General tab in Squish preferences}
        \li In \uicontrol {Squish path}, specify the path to the Squish
            installation directory.
        \li In \uicontrol {License path}, 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 \uicontrol {Local server} to use a locally
            installed \c {squishserver.exe}. To use a server running on another
            computer, clear the checkbox and specify the server address in the
            \uicontrol {Server host} and the port number in the
            \uicontrol {Server port}. If no port is specified, \QC starts
            \c squishserver in a way that enables it to automatically select an
            open port.
        \li Select \uicontrol {Verbose log} to include additional
            logging levels in the log output.
        \li Select \uicontrol {Minimize IDE} to automatically
            minimize \QC when running or recording test cases.
    \endlist

    \sa {Create Squish test suites}, {Enable and disable plugins},
    {Manage Squish test suites and cases}, {Select Squish AUTs}, {Squish}
*/

/*!
    \page creator-how-to-select-squish-auts.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-test

    \title Select Squish AUTs

    To select applications to test using Squish, go to \uicontrol {Tools} >
    \uicontrol {Squish} > \uicontrol {Server Settings}.

    \image {qtcreator-squish-server-settings.png} {Squish Server Settings dialog}

    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 computers, 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.

    To test an already running application using a Squish Server running on
    another computer, attach to the application. You can attach only one server
    to your application at a time. The attached application is not closed when
    the test case is completed.

    \section1 Map 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 \uicontrol {AUT Paths}.

    To change the path to the selected AUT, select \uicontrol {Edit}.

    To remove the mapping to the selected AUT, select \uicontrol {Remove}.

    \section1 Specify 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}.

    \section1 Add 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 Specify settings for running tests

    To specify settings for running tests:

    \list
        \li In \uicontrol {Maximum startup time}, set the maximum time
            to wait for the AUT to start before throwing an error.
        \li In \uicontrol {Maximum response time}, set the maximum time
            to wait for the AUT to respond before throwing an error.
        \li In \uicontrol {Maximum post-mortem wait time}, 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 \uicontrol {Animate mouse cursor} to animate
            the mouse cursor when playing back a test.
    \endlist

    \sa {Connect to Squish Server}, {Create Squish test suites},
    {Enable and disable plugins}, {Manage Squish test suites and cases},
    {Squish}
*/

/*!
    \page creator-how-to-manage-squish-test-suites.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-test

    \title Manage Squish test suites and cases

    Manage Squish test suites and cases in the \uicontrol Squish
    \l {Show and hide sidebars}{sidebar 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}

    To open the \uicontrol {Squish Test Suite} wizard for creating a new
    test suite, select \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.

    \section1 Record 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
    \inlineimage {icons/recordfill.png} {Record Test Case}
    (\uicontrol {Record Test Case}) next to the test case name. The
    application under test (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 \inlineimage {icons/stop_small.png} {Stop}
    (\uicontrol {Stop}) in \uicontrol {Control Bar}.

    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}

    \section1 Run test suites

    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 \imagerunsmall
    (\uicontrol {Run}) 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}.

    \section1 Map 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
    \inlineimage {icons/objectsmap.png} {Object Map} (\uicontrol {Object Map})
    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} {Jump To}.

    \section1 Inspect 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}

    \sa {Connect to Squish Server}, {Create Squish test suites},
    {Enable and disable plugins}, {Select Squish AUTs}, {Squish}
*/

/*!
    \page creator-how-to-create-squish-test-suites.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-test

    \title Create Squish test suites

    To create a new test suite:

    \list 1
        \li Go to \uicontrol File > \uicontrol {New Project}.
        \li Select \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
            application under test (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 scripts, 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.

    \sa {Connect to Squish Server}, {Manage Squish test suites and cases}, {Enable and disable plugins},
    {Select Squish AUTs}, {Squish}
*/

/*!
    \page creator-reference-squish-output.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-ui
    \ingroup creator-how-to-test

    \target Squish
    \title View Squish output

    Use the \uicontrol Squish view to see test, runner, and server logs.

    Squish uses compare, verify, and exception functions to record the results of
    tests applied to a running application under test (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.

    \section1 View Squish test log

    To view the test log, go to 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 View Squish runner and server logs

    To view the Squish Runner and Server logs, go to the \uicontrol Squish
    output, \uicontrol {Runner/Server Log} tab.

    \image {qtcreator-squish-output-runner-server-log.webp} {Runner and Server Log output}

    \section1 Squish view toolbar

    Select options on the view toolbar to perform the following actions:

    \list
        \li To clear the view, select \inlineimage {icons/clean_pane_small.png}
            {Clear} (\uicontrol Clear).
        \li To move between test results or log entries, select
            \inlineimage {icons/arrowdown.png} {Next Item} (\uicontrol {Next Item})
            and \inlineimage {icons/arrowup.png} {Previous Item}
            (\uicontrol {Previous Item}).
        \li To filter test results or log entries, select
            \inlineimage {icons/filtericon.png} {Filter Tree}
            (\uicontrol {Filter Tree}).
        \li To expand or collapse the test results or log entries, select
            \inlineimage {icons/expand.png} {Expand All} (\uicontrol {Expand All})
            or \inlineimage {icons/collapse.png} {Collapse All}
            (\uicontrol {Collapse All}).
    \endlist

    \sa {Connect to Squish Server}, {Create Squish test suites},
    {Enable and disable plugins}, {Manage Squish test suites and cases},
    {Select Squish AUTs}, {View output}
*/
