Installing Squish for Qt from Desktop Source Packages

In most situations, Squish can be quickly and easily installed from a binary package. However, you can build it from source if no suitable binary package is available or if you need to use features that require a source build, for example.

Once Squish is built, it can be distributed to different computers running the same operating system, as instructed in Distributing and Sharing an Installation.

For source builds, Squish is supplied as two separate packages: the Squish tools source package that must be built and the Squish IDE package that just needs to be installed. The tools are supplied as a .zip file for Windows and as a .tar.gz file on Unix-like platforms. Once the tools have been built, you can install the Squish IDE.

In many common cases, the build process can be done in just a few simple steps, as described in Quick Install. If your setup does not meet the Quick Install requirements, you can still build Squish from source, but you will need to follow one of the non-standard build processes that are documented after the Quick Install section.

Quick Install

You can build Squish from sources for testing Qt applications built with a native compiler by using a prebuilt binary package. If you need non-standard compiler options or a non-standard Qt configuration, you have 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. Any of these may differ from the versions and configurations used for the pre-built binary packages.

The quickest route to such a customized installation:

• limits the components to be build from sources to those interacting with the AUT directly
• makes use of a prebuilt binary package for the standard functionality

Basic 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.

• Qt 4.8 or greater must be available. See Detailed Installation Instructions for building Squish with older Qt versions.
• A C++ compiler matching the version used for building Qt.

Minimal Steps

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

It is 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 commands in your Squish desktop directory:

Step 3 of 4

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

Step 4 of 4

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

The modified Squish binary package should be ready for use with your application.

Detailed Installation Instructions

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. Squish comes with its own built-in JavaScript interpreter and so does not depend on a third-party interpreter.

• Qt 3.2.0 or greater must be available.
• Qt must be configured and built with support for threads. This is the default since Qt 4.
• Qt must be configured and built as a shared library.
• To use Python as a scripting language for test scripts, you must have Python 2.6+ or Python 3.5+ installed with development headers.
• To use Perl as a scripting language for test scripts, you must have Perl 5.18 or any later 5.x version installed.
• To use Ruby as a scripting language for test scripts, you must have Ruby 1.9 installed.
• To use Tcl as a scripting language for test scripts, you must have Tcl 8.4 or later installed.

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 table regarding what you need to install and where to get it for your platform and scripting language.

To use Squish to test Qt 3.x applications, see Installation for Testing Qt 3.x Applications. To test embedded Qt applications, see Installing Squish for Qt from Embedded Source Packages.

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.

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.

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.

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 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 Switches

When invoked, configure tries to automatically detect your system's configuration system and the optimal configuration for Squish. In some cases, the results of the automatic detection or the defaults Squish uses do not match what you want. In these situations it is possible to override the detected and default settings by passing various command line options to configure.

Here are a few examples:

For a complete list, execute configure --help on the command line or see configure.

Partial Build

By default, configure builds all the components that it can find. However, you might want to build only the components necessary to:

• Produce a distributable installation that requires a minimal runtime installation on the target machine and only the essential execution tools, like squishrunner, on the tester's machine.
• Build with Qt libraries that have a different configuration from the Qt libraries needed by Squish itself, such as the configuration described in Installation for testing with a single-threaded Qt library.

You can do a partial build by setting particular command line switches for configure that can be used to exclude or include various Squish components.

Squish can be told to build a particular component (providing it can find it) by using --enable-component and replacing component with the name of the component you want to build. Similarly, Squish can be told not to build a particular component by using --disable-component and again, replacing component with the name of the component. In this case, of the one you don't want Squish to build. You can use as many enable and disable command line switches as you need. The components that you can choose to enable or disable are listed below.

For instance, if you don't want to build Squish's examples, you could configure and build Squish like this:

configure --disable-examples
build

You can combine these switches freely within the constraints of internal dependencies. This is where the all component comes in handy:

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

This disables every component except for the server, the IDL compiler and the wrapper libraries. This might be useful in scenarios where one machine runs the squishserver, and other machines run the squishrunner.

Overriding Build Variables

When configure is run, it will output the configuration it creates—based on the components it automatically detects, but respecting any command line switches we have used to override the automatic detection—into the files config.h and Build.conf.

The config.h file is included with Squish's source code files, and the Build.conf file is used as an input file for the build tool. If the automatic detection produced unsatisfactory results, you could choose to modify these files before running the build application. The variables written to Build.conf can easily be changed, without needing to manually edit the file. This is achieved by specifying arguments of the form VARIABLE=value or VARIABLE+=value at the configure command line. These arguments will replace (if you use =) or extend (if you use +=), the named variables.

Here is an example that replaces a variable's value with a new value; in this case changing the default optimization flag:

configure "CXXOPT=-O1"

And here is another example, in this case we extend the values stored by two variables—the effect of this is to change the gcc compiler's default mode of operation, forcing it to do a 32-bit build on a 64-bit system:

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

Installation for Testing Pure Qt 4 Applications

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, 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, 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, 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:

You can perform the above steps on different machines 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.

Installation for Testing Qt 3.x Applications

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 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 lineChecking 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 Squish IDE (assuming that you have installed it; see Standalone Installation of the IDE):

/home/user/squishide/squishide

This will automatically start and stop a local squishserver as needed.

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.

Installation for testing with a single-threaded Qt library

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:

Statically-linked Qt Libraries

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

1. The correct version/static build of Qt must be installed.
2. The Squish source package must be extracted, configured with special options, and built against the static Qt library.
3. Your AUT must be instrumented to use a built-in hook.
4. For the squishidl, squishserver, Squish IDE, and squishrunner, you will need a Squish binary package that matches the source package version number. This would be squish-6.4.2-qt55x-win64-msvc12.exe for Squish 6.4.2 with Qt 5.5, for example.
5. squishserver must be configured so that usesBuiltinHook is set for the AUT.

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.

Configuring and 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:

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

Instrumenting Your AUT

See Using the Qt Built-in Hook for instructions how to extend your AUT build rules and (if needed) code to make a statically linked Qt application work with the previously built package.

Finally 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.