Binary packages contain the Squish IDE and the Squish Tools (squishrunner, squishserver, and others). They have different minimum system requirements.

The binary Squish packages are available in your Customer Download Area on the froglogic website. To find out which package you need, the first thing you need to know is what toolkit is used to build the applications you are going to test. The toolkit could be Qt®, Java™, native Windows (e.g., MFC or .NET), macOS (i.e., Cocoa), Web, and so on. You also need to know which operating system you are going to use to test the applications, e.g., Linux, macOS, or Microsoft® Windows.

If you will be testing Qt applications, you need to collect some additional technical information in order to choose the correct package:

If you don't know this information, you'll need to ask one of the application's developers. Once you know the operating system, Squish edition, toolkit version, and the compiler name and version, you can identify the correct Squish package as follows: Every Squish package name is of the form squish-<squishVersion>-toolkit<toolkitVersion>-<platform>-<compiler> and ending with .exe (on Windows), .run (on Linux) or .dmg (on macOS). Some package names don't specify the <toolkitVersion>, in which case the package can be used with any version of the toolkit; others have an x in the toolkit version, in which case they can be used with a version of the toolkit that has any digit in that position—so qt43x means any Qt 4.3 version, Qt 4.3.0, Qt 4.3.1, and so on. Some packages don't specify the <compiler>, in which case they can be used with any compiler that runs on the platform. Some examples are shown in the table below.

Squish packages for macOS machines—and that are processor-dependent—embed a processor identifier in their name, e.g., macppc for PowerPC processors and i386 for Intel processors. Similarly, some Java™ packages specify whether they are for 32-bit or 64-bit machines (e.g., using java-win32 or java-win64 in their names). Yet in some cases the architecture of the machine doesn't matter. For example, Squish for Windows (i.e., for applications using the native MFC or .NET toolkit) is designed to work with all Windows compilers and with both 32-bit and 64-bit versions of Windows—so in this case the package names just have the Squish version, e.g., squish-6.6.1-windows.exe.

If you cannot find a Squish package in your customer area that matches your information, it is best that you build Squish from source. This will ensure that Squish integrates correctly with your local software configuration. Building Squish from source is described in Installing Squish for Qt from Desktop Source Packages (Section 3.1.2).

After you have decided which Squish package you need, download it from your customer area onto your computer, and execute it.

	On Linux
	On Linux, you need to make the .run file which you downloaded executable first. Popular desktop environments allow this by right-clicking the file and enabling the Execute permission. You can however also make the installer executable on the command line by executing: $ chmod a+x <packagename>

The installation program will guide you through the configuration process by presenting multiple pages.

	On Solaris & AIX
	The following instructions depicting the installation procedure using the graphical installer only apply to Windows, Linux and macOS. For other platforms, such as Solaris or AIX, the Squish package is a plain ZIP archive. After uncompressing it, the installation is performed in text mode by running the squishconfig (Section 7.4.2) program.

The installation program is shown running in the screenshot above (and in several screenshots that follow). However, the list of configuration steps varies depending on which edition of Squish you are installing, so don't be concerned if one or more of the configuration pages mentioned below is not presented to you, or if additional pages are shown.

	Changing Configuration Settings
	Once you start the installation program, if you want to go back and change a setting you made during the configuration, you can use the Back button to go back to the relevant page, change the configuration setting, and then move forward again using the Next button.

3.1.1.3.1. Entering a License Key

After acknowledging the welcome page by pressing the Next button at the bottom of the setup program's window, the next page will request you to enter the Squish license key, activation code, or address to a Floating License Server. If you have a 19-character license key to enter, this section is for you. If you want to enter a hostname:port of a Floating License Server, see Entering a Floating License Server Address (Section 3.1.1.3.2).

If you already have a previous Squish installation on your computer—perhaps an evaluation version—or if you have already copied the license file to your HOME directory, and renamed it to start with a period, the license key will be shown in the input field. If there is no license shown, or if you want to use a different one, enter your license here exactly as it appears in the Squish License Key that is available in your download area, including any dashes.

	License File Location
	Windows %HOMEDRIVE%%HOMEPATH%\.squish-license Linux/Unix/macOS $HOME/.squish-license To use a license key file stored somewhere else, set the SQUISH_LICENSEKEY_DIR environment variable to the desired location. (See Environment Variables (Section 7.5).)

Click the Next button to advance to the next step in the configuration process. If there are any problems with the license (for example, if it has expired or you mistyped it) then a message box will be shown, explaining the problem; you can then have another try.

3.1.1.3.2. Entering a Floating License Server Address

Select the corresponding section to use a floating license with Squish. The installer will try to discover license servers on the network and populate the drop down menu with them. If the license server you plan to use is not listed, you may enter a server address manually in the form of (hostname_or_IP_address:port). When a valid server address is selected the Next button will be enabled.

Click Next to advance to the next step in the configuration process. If there are any problems with the license server or its license (for example, the server is not reachable or its license doesn't include the required Squish editions) then a message box will be shown, explaining the problem; you can then have another try.

3.1.1.3.3. Acknowledging the Terms of Use

After entering your license key or server address, you will be presented with the license under which you are permitted to use your copy of Squish. Please read the entire license text carefully before proceeding. Click one of the two radio buttons (I accept the license. or I do not accept the license.), that appear below the license text, to indicate whether you agree or disagree with the terms. If you disagree, then you cannot install or use Squish so you should click the Cancel button (or close the window) to terminate the installation.

	License Text Differences
	The license text varies depending on the license key—for example, the terms are different for evaluation versions than for paid for versions.

If you accept the license, the Next button will become enabled, so you can proceed to the next step of the configuration process.

3.1.1.3.4. Component Selection

In this step, the installation of Squish can be customized by (de-)selecting optional components.

The basic Squish Tools (such as squishrunner or squishserver) are mandatory and thus are always selected. However, other components are optional:

Squish IDE

You can choose to not install the Squish IDE in order to save disk space. This can be useful in case the Squish installation is only meant to be used for automatic (e.g. nightly or CI-driven) test execution but not for test development.

Squish Test Center

The Squish Test Center is a separate component for aggregating and displaying Squish test reports. This component is typically only installed on a single system and then shared across the network with other workstations.

3.1.1.3.5. Script Languages

In this step, the script languages to use for test scripts can be configured. Furthermore, in case the Squish package contains multiple versions of any given language, this page permits selecting the version to use for executing tests. Note that these settings can also be reconfigured later on by running the squishconfig (Section 7.4.2) program.

This page is not displayed if a Squish package contains only a single version of each script language.

3.1.1.3.6. Installation Folder

This step decides into which location on your system the Squish package will be uncompressed.

3.1.1.3.7. Path to the Qt Library

This step is only necessary if you are configuring a Squish package set up for testing Qt applications on macOS, and if your license key entitles you to test Qt applications. If either of these conditions doesn't apply, this configuration page will not appear, in which case you can safely skip to the next section and continue from there.

Locating the Qt library

Most Qt applications on the macOS contain Qt libraries in the application bundle. If this is the case for your AUT, then use the Finder to navigate to the AUT, right click on it and say Show Package Contents, then drill down to Contents/Frameworks to find QtCore.framework. To copy that path to the clipboard, View - Show Path Bar, right click on the Frameworks button in the bottom path bar, Copy "Frameworks" as Pathname, then paste it into the line edit in the installer dialog.

After specifying the path to the requested Qt library, use the Next button to advance to the next step of the setup.

	Changing the path to Qt libraries later
	If later, you wish to change the location of the Qt library, without reinstalling Squish, you can issue the command: $ SQUISHDIR/bin/squishconfig --qt=/path/to/QtCore.framework

3.1.1.3.8. Paths for Java™ Settings

This step is only necessary if you are configuring a Squish package set up for testing Java™ applications or if you are configuring a Squish package for testing Web applications and if your license key entitles you to test Java™ or Web applications. If either of these conditions doesn't apply, this configuration page will not appear, in which case you can safely skip to the next section and continue from there.

In order to be able to test Java™ applications, you need to tell Squish where your Java™ runtime libraries are installed. If you are using the Java™ SDK (Software Development Kit), then you must specify the runtime library directory—called jre—which is located inside the SDK's directory. If you only have the JRE (Java™ Runtime Environment) installed, then simply specify the JRE's directory (and not a directory inside the JRE).

After specifying the path to the Java™ runtime library, use the Next button to advance to the next step of the setup.

3.1.1.3.9. Ready to Install

At this point all the configuration options have been set and the installation is ready to launch. A page is shown which displays the disk space required by the selected Squish configuration.

When you press the Next button on this page it means that the configuration shown will be saved to disk and Squish will use these settings from now on.

3.1.1.3.10. Executing the Installation

The installation program now commences installing Squish on your system. You can click the Show Details button to get a detailed list of actions performed as part of the installation.

You can close the installer at any time, e.g. by closing the window or by pressing the Cancel button (only visible on platforms other than macOS). All changes done so far will be rolled back.

3.1.1.3.11. Concluding the Configuration

Congratulations! You have finished configuring Squish, and all the settings have been saved successfully. This page concludes the setup of your Squish binary package.

You should now click the Finish button close the installation program. An option is presented which can be used to define whether the Squish IDE should be launched after the installation finished.

	Windows-specific
	In some cases, a restart is required when installing Squish on Windows. This is due to some reconfiguration required which only becomes effective when starting the operating system. Please make sure to restart your computer before using Squish to ensure that it operates properly.

	macOS-specific
	On macOS Squish requires enabling Accessibility access for the Squish IDE or the Terminal to be able to replay interactions in menus and use the nativeType or the nativeMouseClick function. Upon starting the Squish IDE or launching squishserver from the Terminal a dialog will pop up leading you through the process. For more details see the macOS Universal Access section.

It is possible to perform the installation of Squish completely unattended, passing any required values up front. Unattended installation requires no user interactions whatsoever and is equivalent to manually interacting with the installer interface. To perform an unattended installation, invoke the Squish installation program from the command line passing at least the argument unattended=1:

$ ./squish-6.6.1-windows unattended=1 <more options...>

That argument will launch the installation without any graphical user interface. Instead, progress information and potential error messages are written to the console.

In addition to the unattended=1 argument, you may want to specify further arguments to specify the target directory, the license key and further settings. Please see the installer reference documentation for a full list of recognised arguments.

In case any required values are missing, the installation will print a message and stop, e.g.:

$ ./squish-6.6.1-windows unattended=1
IFW Version: 2.0.81, built with Qt 5.5.0.
Build date: Nov 30 2015
Installer Framework SHA1: cf9e21b
[0] Language: en
[0] Arguments: ./squish-6.6.1-windows, unattended=1, targetdir=/tmp/foo
[4] Operations sanity check succeeded.
<..>
[162] Cannot perform unattended installation; target directory not specified.
[162] Please pass 'targetdir=<PATH>' on the command line.

Omitting optional arguments will make the installer pick a sensible default value. A message will be printed indicating this condition, and how to override it. For instance, here's the output generated while installing a Squish for Web package on macOS:

<..>
[569] No Firefox executable specified, using auto-detected path '/Applications/Firefox.app'
[569] Specify 'firefox=<PATH>' on the command line to override this.
[569] No Chrome executable specified, using auto-detected path '/Applications/Google Chrome.app'
[569] Specify 'chrome=<PATH>' on the command line to override this.
<..>

This section covers the build of Squish from sources for testing of Qt applications build with a native compiler. This scenario is normally best covered through the use of a prebuilt binary package. In the case of non-standard compiler options or a non-standard Qt configuration it's necessary to compile Squish from sources using the very same compiler and Qt library that is being used for the appliction.

The most often found use case for such a minimal build is to create a custom build of those components that will have to match the environment of the tested application. The main influencing factors are the Qt libraries, compiler and hardware. Either of these may differ from the versions and configurations used for the pre-built binary packages.

The quickest route to such a customized installation

Requirements

For a build and installation, certain requirements must be met. Some of these requirements concern the Qt library that Squish itself is built with, and some concern the tools used during the build.

The following minimal steps are based on a Linux/Unix system but will apply to other operating systems in a similar fashion.

It it assumed that a Squish source package has been unpacked into the directory C:\squish\ on Windows or /usr/local/squish/ on Linux/Unix, respectively. It is also assumed that your Qt installation is found in the directory C:\Qt or /usr/local/qt, respectively.

Start by changing the current working directory into the unpacked Squish source directory, and run the configuration script:

After the configure run has finished start the build process:

Further setup

The build instructions above take care of creating the components specific to your Qt installation. The other components like the Squish IDE and squishrunner can be taken from any Squish package for Qt 4 or 5 that matches the source packages version number. This would be squish-5.1.0-qt50x-linux64.zip or squish-5.1.0-qt48x-win32-msvc10.zip for Squish 5.1.0 for example.

Step 1 of 4

Install this package as if you would be testing an application build with a standard Qt library. To C:\squish-5.1.0-qt48x-win32-msvc10\ on Windows and /home/user/squish-5.1.0-qt50x-linux64 on Linux/Unix for example.

Step 2 of 4

To prepare an existing Squish desktop installation for copying custom Qt support into it issue the following in your Squish desktop directory:

Step 3 of 4

To install your custom Qt support into an existing Squish desktop installation, issue the following in your build directory:

	Note
	The paths used below are just examples, please adjust them to your setup.

Step 4 of 4

To finish setup of the customized Squish desktop installation issue the following in your Squish desktop directory:

At this point this modified Squish binary package should be ready for use with your application.

This section describes how to perform a build and installation of Squish including various configuration options.

Requirements

For a build and installation, certain requirements must be met. Some of these requirements concern the Qt library that Squish itself is built with, and some concern the scripting languages you want to be able to use with Squish. Note that the reason JavaScript isn't mentioned is that Squish comes with its own built-in JavaScript interpreter and so does not depend on a third-party interpreter.

	Qt 4-specific
	If you want to use Qt 4, then you must either have built it with Qt3Support enabled, or alternatively if you don't want to enable Qt3Support, you must do a split build, in which case, see Installation for Testing Pure Qt 4 Applications (Section 3.1.2.3).

	macOS-specific—Xcode Required
	If you want to build Squish on macOS you must install Xcode—this will provide the compiler and related development tools.

Before building Squish you must make sure that you have the scripting languages you want to use for your test scripts already installed. (This does not include JavaScript which is built into Squish.) See the following tables regarding what you need to install and where to get it for your platform and scripting language.

If you want to use Squish to test Qt 3.x applications, see Installation for Testing Qt 3.x Applications (Section 3.1.2.4). If you want to test embedded Qt applications, see Installing Squish for Qt from Embedded Source Packages (Section 3.3).

Some of Squish's components must use the same Qt library as the application you want to test. If the Qt library your application uses does not fulfill the requirements above (i.e. it is not a shared, multi-threaded Qt library), you must do a split build of Squish (see Installation for testing with a single-threaded Qt library (Section 3.1.2.5)).

There are no additional requirements if you want to use JavaScript as a scripting language for test scripts: a small JavaScript interpreter is built into Squish. The JavaScript interpreter is automatically built unless JavaScript support is switched off using the configure program's --disable-js switch; see Configure Switches (Section 3.1.2.2.1).

Supported Compilers

Squish has been tested on a wide variety of Windows and Unix-like systems and with several different compilers. In the case of Windows, Squish has been tested on all modern versions (Windows 7 and Windows 10), with Microsoft® VC++ 2013 through 2019, and with Intel C++. For Unix-like systems, Squish has been tested on all modern versions of macOS with gcc and clang; on AIX with xlC; on HP-UX 11.11 with aCC and gcc; on IRIX 6.5 with gcc and MIPSPro C++; on Linux with gcc and Intel C++; on SUN Solaris 9 and 10 with gcc and SunCC; and on FreeBSD 6 with gcc.

The operating system versions and compiler versions mentioned here are not comprehensive, so if your particular setup isn't mentioned, Squish may well run perfectly well on your system—you can always contact support to ask whether your particular operating system/compiler combination is supported.

For the C++ compiler requirements that should match Qt, please refer to the Supported Configurations section in the Qt Documentation.

Building Squish

For ease of explanation, we will assume that you unpacked the Squish source into one of the directories below, depending on the platform you are using.

You can install Squish anywhere on your system, provided you have write permissions. If you wish to use another location, unpack the tarball to the desired location when following the install instructions.

The first step is to ensure that you have a license key. Download the file called squish-3-license from the download area where you obtained your Squish package. (This key is valid for both Squish 3 and Squish 4.) Copy (and rename) this file as follows:

To use a license key file stored somewhere else, set the SQUISH_LICENSEKEY_DIR environment variable to the desired location. (See Environment Variables (Section 7.5).)

	Building Squish for Other Users
	If you build Squish for another user, you must make sure that each user has a valid license file located in their own HOME directory.

Now Squish is ready to be configured according to your system's settings. On Windows you must be in a console window (sometimes call the Command Prompt or MS-DOS Prompt), on macOS in a Terminal.app window, and on other Unix-like systems in a shell window such as an xterm. (Note that for Unix-like systems we show $ as the prompt; it may differ on your system, but that doesn't matter.)

Start by changing to Squish's installation directory.

Now run the configuration script:

The configure script searches for your C++ compiler, the Qt libraries that Squish depends on, the interpreters and header files for the third-party scripting languages Squish supports—Python, Perl, Ruby, and Tcl—and other system components that Squish may need, such as the Java runtime environment. The output indicates which compiler has been detected. If you are testing Qt applications, you should use the same compiler for Squish that you used to build Qt (if you built it yourself), and for your applications. If you want to force configure to use a different compiler from the one it detected, set the CXX environment variable to the executable of the compiler you want Squish to use, as the following examples illustrate.

Now configure asks you to run the Squish build tool to compile Squish.

Building Squish can take quite a bit of time, since as part of the process the build tool also creates wrappers for the Qt library. As the build process progresses you will probably see a lot of warnings from the squishidl (Section 7.4.5) tool. It is safe to ignore these warnings.

Once the build process has finished, Squish is installed. The binaries and libraries are in the following directories:

You might want to add the bin directory to your PATH environment variable so you can invoke the Squish tools without specifying their path. How this is achieved depends on the platform.

configure --disable-examples
build

configure --disable-all --enable-idl --enable-server --enable-wrappers

configure "CXXOPT=-O1"

configure "CXXFLAGS+=-m32" "LFLAGS+=-m32"

Testing a Qt 4.x application that does not use the Qt 3.x support functionality (i.e., a “pure” Qt 4.x application), requires us to do a split build of Squish. (This is necessary because Squish itself uses the Qt 3 compatibility so that it can test both Qt 3 and Qt 4 applications.)

A split build means that you must compile the components that come in direct contact with the AUT using your pure Qt 4.x library. The rest of Squish can be compiled with either Qt 3 or with a Qt 4 installation that includes the Qt3Support module.

Performing a split build requires you to run both configure and build twice: the first time to build the parts that will use the pure Qt 4 library and the second time to build the parts that require Qt 3, or Qt 4 with Qt3Support.

Here is a very basic example that assumes Squish has been unpacked twice, each time into a different directory. One directory will be used for the pure Qt 4 parts, and the other will be used for the Qt 4 with Qt3Support (or just Qt 3 if preferred) parts. For Unix-like systems, we have assumed a username of “user” which must be changed to your actual username.

Using Qt 4 Debug Libraries

If you build your application using the Qt 4 debug libraries then you will need to use those same libraries when building Squish. If you want to be able to test both release and debug versions of your application you will need two versions of Squish: one built against the normal Qt 4 libraries, and the other built against the Qt 4 debug libraries, so you will need to do two separate builds. For example, on Windows for the normal Qt 4 libraries, you might use directories: C:\Squish-Qt4 C:\Squish-Qt4-and-Qt3 C:\Qt\4.7.1 C:\Qt\Qt4-and-Qt3 And for the Qt 4 debug libraries, you might use directories: C:\Squish-Qt4-debug C:\Squish-Qt4-and-Qt3-debug C:\Qt\4.7.1-debug C:\Qt\Qt4-and-Qt3-debug Those using Unix-like systems and macOS would need to use similar directory layouts adapted to their filesystems.

Step 1 of 6

First unpack the Squish tools source package, then rename its directory (e.g., to C:\Squish-Qt4). Then unpack the Squish source tools package a second time, and again rename its directory (e.g., to C:\Squish-Qt4-and-Qt3).

For the purposes of this example, we have assumed that the pure Qt 4 (used by your AUTs) and the Qt 4 with Qt3Support (needed to build many of Squish's components) are installed in the directories listed below. The directory names don't matter—all that matters is that you have a pure Qt 4 installation in one directory, and a Qt 4 with Qt3Support (or Qt 3) installation in a separate directory.

Step 2 of 6

Next, we build those parts that only require a pure Qt 4 installation—the IDL compiler, the Qt wrappers, and the examples. These are all built using the pure Qt 4 library:

Once configure has finished, it is wise to verify that the configuration log output includes the line Checking Qt version ...... 4.x where x is the Qt 4 release you are using.

Step 3 of 6

Now build the wrappers and the examples using the pure Qt 4 installation:

Step 4 of 6

Now change to the directory of the second Squish installation, and make configure use the Qt 4 with Qt3Support (or Qt 3) installation, and select the remaining components to be configured and built:

Step 5 of 6

Now that the rest of the components are configured, we can build them:

If you want to, you could even perform the above steps on different machines, if you prefer to execute the tests remotely.

Step 6 of 6

The last step necessary to complete the split build is to copy over the required files which were built in the pure Qt 4 directory over to your Qt 4 with Qt3Support (or Qt 3) build directory:

Now, the build in your Qt 4 with Qt3Support directory (or Qt 3 directory) is fully usable for creating and running tests for applications that link against a pure Qt 4.x library.

To test applications that are built against Qt 3.1 or later it is possible to use a suitable Squish binary package matching your Qt version, or if one isn't available, to do a standard build. This means that as long as you are using Qt 3.1 or later you can just build Squish normally using the Quick Install (Section 3.1.2.1) procedure.

Testing a Qt 3.0 application requires a split build of Squish—but this is not necessary for Qt 3.1 or later for which the standard build works fine. But for Qt 3.0 only, you must compile the components that come in direct contact with the AUT using the same Qt 3 library you use to build the AUT. The rest of Squish must be compiled with a separate version of the Qt library, either Qt 4 with the Qt3Support module (or with Qt 3.1 or later).

A split build means that you must compile the components that come in direct contact with the AUT using your Qt 3.0 library. The rest of Squish can be compiled with either Qt 3 or with a Qt 4 installation that includes the Qt3Support module.

Performing a split build requires you to run both configure and build twice: the first time to build the parts that will use the Qt 3 library that your AUT uses, and the second time to build the parts of Squish that require Qt 4 with Qt3Support (or Qt 3.1 or later).

Here is a very basic example that assumes that the Squish tools package has been unpacked twice, each time into a different directory. One directory will be used for the Qt 3 parts, and the other will be used for the Qt 4 with Qt3Support (or just Qt 3.1 if preferred) parts. For Unix-like systems, we have assumed a username of “user” which must be changed to your actual username. We have assumed that the Squish tools package has been unpacked twice, and each time had its directory renamed so that you now have two identical Squish directories with the following names:

We also assume that Qt 3 and Qt 4 with Qt 3 support are installed in the directories listed below. (Naturally, it doesn't matter what directories are used, so long as you adapt the instructions to match.)

First, build just the server, IDL compiler, the Qt wrappers, and the examples, using Qt 3:

Once configure has finished, it is wise to verify that the configuration log output includes the line Checking Qt version ...... 3.x where x is the Qt 3 release you are using. Now build the wrappers and the examples using the Qt 3 installation:

Now change to the directory of the second Squish installation, and make configure use the Qt 4 with Qt3Support (or Qt 3.1 or later) installation, and select the remaining components to be configured and built:

Now that the rest of the components are configured, we can now build them:

If you want to, you could even perform the above steps on different machines, if you prefer to execute the tests remotely.

Usage Example

Here is a very brief summary of an example usage of this setup on a Unix system. Apart from the different path names, the approach is the same on Windows. We will assume an AUT with the path /opt/ourcompany/ourapp.

/home/user/squish-qt3/bin/squishserver &
/home/user/squish-qt3/bin/squishserver --config addAppPath /opt/ourcompany

At this point you could verify that the application will indeed be found in the given path:

/home/user/squish-qt4-and-qt3/bin/squishrunner --info applications

The name of your application should be printed out—possibly along with the names of any other applications that you have registered with Squish.

Now run the IDE (assuming that you have installed it; see Standalone Installation of the IDE (Section 3.10)):

/home/user/squishide/squishide

This will automatically start and stop a local squishserver as needed. (This behavior is controlled by the Remote Testing setting. To change it click Preferences, then click the Squish item's triangle to expand it, and then this item's Remote Testing item to show the Remote Testing pane. The Start local Squish server automatically checkbox should be checked.)

All that's left, before you can start creating new test cases, is the creation of a new test suite and the selection of ourapp in the suite's settings dialog.

The easiest approach is to link the AUT and all of Squish to the same Qt library. If it is possible to link your AUT to a shared, multi-threaded Qt library, we recommend using this for both Squish and your AUT. Any other Qt configuration settings, (STL, etc.) don't matter.

If you don't want to use a multi-threaded Qt library for your AUT, you can use one Qt library for your AUT and a different one for Squish (some parts of Squish, mainly the squishserver and the squishrunner, require a multi-threaded Qt library).

However, the parts of Squish that hook into your AUT (Squish's qtwrapper, hook, and object model libraries), must be built against exactly the same Qt library as your AUT. Also make sure that the same C++ compiler is used. The other Squish tools can be linked with any Qt library.

So in order to support a single-threaded Qt library, you must perform a split build of Squish, i.e., build some parts against a multi-threaded Qt library and some parts against the single-threaded Qt library that your AUT uses.

For example, suppose that the single- and multi-threaded Qt libraries are in the following locations:

The first step is to compile only the multi-threaded parts of Squish by running configure, and disabling everything except for the server and runner:

The second step is to compile the remaining parts of Squish with the single-threaded Qt by running configure again, this time disabling only the server and the runner:

Make sure that the AUT is linked against exactly the same single-threaded Qt library as you have used for building the single-threaded parts of Squish. If in doubt, use one of the following tools to verify the correct linkage:

Recording and running tests is now possible with applications built with statically-linked Qt libraries. Here is a summary of the requirements:

Extract the Squish source package to C:\Users\user on Windows, /home/user on Linux/Unix or to /Applications on macOS. The exact name of the directory is determined by the archive filename, but we will refer to it below as simply squish.

Install the Squish binary package to a directory right next to that. We will refer to that directory below as Squish_for_Qt.

It is assumed that your static Qt installation is found in the directory C:\Qt on Windows, /usr/local/qt on Linux/Unix or /Users/Qt on macOS.

Building Squish

It is best practice to configure and build outside of the source directory. First, create an empty build directory, and then configure from within that directory:

Prepare the Squish build by running the configure script:

	macOS-specific
	For macOS Mojave users, an additional flag to the configure step is required, --enable-64bit.

Once the configure step is complete, start the build process:

Instrumenting your AUT

Navigate to the *.pro file of your Qt application and add the following:

# Include Squish/Qt if a Squish installation prefix was provided to qmake
!isEmpty(SQUISH_PREFIX) {
	message("Including Squish/Qt files")
	include($$SQUISH_PREFIX/qtbuiltinhook.pri)
}

Now add the built-in hook to the main function of your application, or right after your QApplication or QGuiApplication object is setup (e.g., main.cpp):

#ifdef HAVE_SQUISH
#include <qtbuiltinhook.h>
#endif
...
int main(int argc, char **argv)
{
   QApplication app(argc, argv)
#ifdef HAVE_SQUISH
      Squish::installBuiltinHook();
#endif
   ...
}

Rebuild your application using make:

Configuring squishserver

For each AUT that uses the built in hook, squishserver must be registered properly. This can not be done from the Squish IDE and can not be un-done unless you manually edit the server.ini in your user settings directory.

Create a new test suite with the appropriate settings and choose the newly instrumented application binary as the Application Under Test.

You should now be able to launch the AUT and record and replay tests.

If you want to use Squish with a renamed Qt 3 library, you must use additional options to configure. On Unix and macOS you must use the -with-qtlibname=<renamed Qt library>.

On Windows, you must specify three options (you must specify all three options, even if one of the libraries is not renamed; in which case, just specify the original version):

With the option --with-qtdllname you must specify the path to the renamed Qt DLL, with --with-qtlibname you must specify the path to the renamed Qt import library, and with the option --with-qtmainlibname you must specify the path to the renamed qtmain.lib library.

The renamed Qt DLL and import library should contain the characters mt if you have a multi-threaded Qt library. configure uses this to detect if the Qt library is mult-threaded or single-threaded. If you don't follow this convention, the automatic detection fails and some parts of Squish are incorrectly disabled.

If you want to use Squish with a renamed Qt library, you must use an additional option to configure: if you configured your Qt library with the option -qtlibinfix <infix>, you must configure Squish with the option --with-qtlibinfix=<infix>.