3.1. Installing the Command Line Tools, Server, and IDEs

3.1.1. Installing from Binary Packages
3.1.2. Installing Squish for Qt from Desktop Source Packages
3.1.3. Installing Squish for Qt from Embedded Source Packages
3.1.4. Distributing and Sharing an Installation
3.1.5. Installing Squish for Mac
3.1.6. Installation for Web Testing using browsers on mobile devices
3.1.7. Installation for Web Testing using Opera® up to version 12
3.1.8. Installation for Flex applets in web pages
3.1.9. Installing Squish for Android

3.1.1. Installing from Binary Packages

In most cases, Squish can be installed from a binary package. These simply need to be unpacked and then configured to make Squish ready for use.

Binary packages are available for Linux®, Mac OS X®, and Microsoft® Windows®. Different versions of each Squish edition are provided to ensure the tightest possible integration between Squish, the operating system, and the applications or websites you want to test. In view of this, the first step to installing Squish is to choose the correct package for your machine.

3.1.1.1. Choosing the Correct Squish Package

The binary Squish packages are available in your Customer 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), Mac OS X (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, Mac OS X, 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:

  1. Which version of Qt is used by the application you want to test?

  2. Which compiler (and which version of the compiler) was used to compile the Qt library (and the application which you want to test)?

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

For non-Qt applications, similar naming schemes to that just described are used. For example, Squish packages for Mac OS X 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-4.1.0-windows.zip.

Note that for Squish for Web in almost every case it doesn't matter whether you use a 32- or 64-bit edition. The exception is Firefox 3.x. If testing Firefox 3.x on Windows and Mac OS X the a 32-bit Squish for Web must be used (even on 64-bit systems). For Linux use 32-bit Squish for Web on 32-bit systems and 64-bit Squish on 64-bit systems.

Table 3.1. A Cut-Down List of Example Package Names

Example Package NameDescription
squish-4.1.0-qt47x-linux64.zipSquish 4.1.0 for 64-bit AUTs running on Linux and built with Qt 4.7.x and using any compiler
squish-4.1.0-qt42x-win32-msvc7.zipSquish 4.1.0 for 32-bit AUTs running on Windows and built with Qt 4.2.x using the MSVC 7.1 (.NET 2003) compiler.
squish-4.1.0-qt45x-win64-msvc8.zipSquish 4.1.0 for 64-bit AUTs running on Windows and built with Qt 4.5.x using the MSVC 8.0 (2005) compiler.
squish-4.1.0-qt45x-macppc-gcc4.0.zipSquish 4.1.0 for AUTs running on PPC Mac OS X machines and built with Qt 4.5.x using the GCC 4.0 compiler.
squish-4.1.0-qt45x-maci386-gcc4.0.zipSquish 4.1.0 for AUTs running on Intel Mac OS X machines and built with Qt 4.5.x using the GCC 4.0 compiler.
squish-4.1.0-web-win32.zipSquish 4.1.0 for Web using a 32-bit browser on Windows.
squish-4.1.0-web-linux32.zipSquish 4.1.0 for Web using a 32-bit browser on Linux.
squish-4.1.0-web-mac.zipSquish 4.1.0 for Web using a 32-bit browser on Mac OS X.
squish-4.1.0-java-win32.zipSquish 4.1.0 for Java—all 32-bit versions from 1.4 using AWT/Swing or SWT—running on Windows.
squish-4.1.0-java-win64.zipSquish 4.1.0 for Java—all 64-bit versions from 1.4 using AWT/Swing or SWT—running on Windows.


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 uncompress it somewhere. If you are using Windows, you can probably uncompress the package using Window's built-in utilities. Start Windows Explorer and navigate to the directory that contains the Squish package. Right-click the package, and if you get an Extract All... option, click the option and use the Windows Extraction Wizard to uncompress the Squish package to the directory of your choice. If you don't have this option, you will need to obtain a ZIP uncompression tool. Several such tools are available, including the open source UnZip from the InfoZip project and the commercial WinZip. From Squish 4.1, the Linux and Mac OS X packages also use .zip files. In case you don't have a graphical interface for your uncompressor, change to the directory into which you downloaded the package and then execute the following command:

On Windows (using InfoZip's UnZip and assuming it is in the PATH—or you could prefix the name with its path instead)

C:\squish> unzip -o <packagename>

On Linux and Mac OS X

$ unzip -o <packagename>

<packagename> stands for the actual name of the binary Squish package you downloaded from your customer area. (If you don't have the unzip command on Linux, install it using your distribution's package manager.)

If you are using a package for a Squish version prior to 4.1 on Linux or Mac OS X the package will be a tarball (with extension .tar.gz). In case you don't have a graphical interface for your uncompressor, change to the directory into which you downloaded the package and then execute the following command:

$ tar zxf <packagename>

3.1.1.2. Configuring the Package

The easiest way to configure a Squish 4.1 or later binary package it is to simply run the IDE. Start the executable (SQUISHDIR\bin\squishide.exe on Windows, SQUISHDIR/bin/squishide on Unix, and SQUISHDIR/bin/squishide.app on Mac OS X); this will cause Squish's setup application to run after which the Squish IDE will start normally. (This only happens once, although you can run the setup application at a later time if you want to change Squish's configuration in a way that isn't possible through the Squish IDE.)

The Squish setup program in action.

The setup 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.

[Tip]Changing Configuration Settings

Once you start setup, 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. (It is also possible to run the setup program again if you need to make a change after you have finished using it.)

[Note]Windows MSVC8-specific

In very rare cases if you're using a binary package of Squish built for the Microsoft® Visual Studio 2005 compiler (MSVC8), your system might lack certain runtime libraries. If your attempt to run Squish setup fails with an error message something like “This application has failed to start because the application configuration is incorrect”, then you must install the missing runtime libraries, and then run setup again. To install the missing libraries, simply run the vcredist_x86 program which is in the same directory as the setup program.

3.1.1.2.1. Entering the 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. (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-3-license file that is available in your download area, including any dashes. (The same license file is used by both Squish 3 and Squish 4.)

[Note]License File Location

The default location for the license key is $HOME on Unix-like systems and %HOMEPATH% (or %USERPROFILE% if %HOMEPATH% isn't defined) on Windows systems. This can be changed by setting the SQUISH_LICENSEKEY_DIR environment variable. (See Environment Variables (Section 19.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.2.2. Acknowledging the Terms of Use
A picture of the license test page from the froglogic Squish configuration program.

After entering your license key, 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 (Accept or Decline), 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 so that setup can terminate.

[Note]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.2.3. Path to the Qt Library

This step is only necessary if you are configuring a Squish package set up for testing Qt applications, 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.

A picture of the page from the froglogic Squish configuration program where you configure which Qt library should be used for the tested application.

In order to be able to test Qt applications, Squish needs to know where to find the Qt library used by the applications you intend to test. Since Squish 4.1, Squish has been smart enought to find the path to the Qt library path itself, in which case a Path determined by OS radiobutton will be visible and checked and all you need to do is click the Next button.

Letting Squish automatically find an AUT's Qt library is particularly convenient since even if you test two or more AUTs which have been built with different Qt libraries, so long as those libraries are installed, Squish will find and use the right one for the AUT you are testing.

If you want to specify a single Qt library (bypassing Squish's ability to find the right Qt library per AUT), you can do so by checking the Fixed path radiobutton and then choosing a path from the combobox (if the one you want is there), or entering the full path, or clicking the Browse button to identify the Qt path by choosing the “QtCore” file. No matter which Qt libraries your application uses (Core, GUI, XML, etc.), the only one that you need to enter is the Core library, e.g., QtCore4.dll on Windows, libQtCore.so on Unix-like systems (except Mac OS X), and QtCore.framework on Mac OS X. Once Squish knows where Qt's Core library is it can find the rest on its own.

[Note]Locating the Qt library

If you don't know where the library is stored on your computer, you could try using your system's Search facility, or you could ask your system administrator.

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

3.1.1.2.4. Preferred Web Browser

This step is only necessary if you are configuring a Squish package set up for testing Web applications, and if your license key entitles you to test 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.

A picture of the page from the froglogic Squish configuration program where you choose the web browser that should be used when testing web applications.

When using Squish to test web applications, you must choose the browser which you want to use for recording and replaying the tests. On Windows and Mac OS X, the default browser is normally used (e.g., Internet Explorer® or Safari®), so this configuration page may not appear on those platforms. However, Linux systems have no default browser as such, and if more than one supported browser is detected you must choose which browser should be used.

[Note]Linux-specific

If you are using Linux and setup only detects a single supported browser, this browser will be chosen automatically, and this configuration page may not appear.

If you are choosing a Firefox 4 browser, setup will automatically detect and select the path to its executable. (If you have multiple versions installed and don't want to use the one chosen by setup you can specify the path to use yourself.)

Select your preferred web browser and continue with the configuration by clicking the Next button.

3.1.1.2.5. Paths for Java™ Settings

This step is only necessary if you are configuring a Squish package set up for testing Java™ applications, and if your license key entitles you to test Java™ 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.

A picture of the page from the froglogic Squish configuration program where you configure the necessary Java paths.

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 JavaSDK (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.2.6. Review

If you chose a Firefox 4 browser on the Browser Support page, setup will now start the browser and the browser will ask if you want to install the Squish plugin. You must accept the plugin to be able to use Squish to test web applications with Firefox 4. After accepting you must close Firefox—on Mac OS X you should Quit Firefox (since just closing the window won't stop it running on Mac OS X). Once Firefox has been terminated, setup will continue.

3.1.1.2.7. Preferred Scripting Language

Test scripts created for use with Squish can be written in any of the scripting languages that Squish supports, which normally includes JavaScript, Perl, Python, Ruby, and Tcl. You can choose the language to use on a per-test suite basis, but since most people only use one scripting language, this configuration page lets you set the default language. You can still override the default and choose a different language when you create test suites though.

A picture of the page from the froglogic Squish configuration program where you choose the scripting language that should be used by default.

If you are unfamiliar with all of the scripting languages on offer and will be learning one from scratch, Python is probably the easiest to learn (Squish supports Python 2), followed by JavaScript. Perl and Ruby are quite a bit harder, as is Tcl, simply because Tcl is so unusual.

Select your preferred scripting language here (or choose the default), then proceed to the next step using the Next button.

[Note]Using Custom Scripting Language Versions

Note that if you use a prebuilt binary package you will get the versions of the scripting languages (Python, Tcl, etc.) that are included in the package—for example, Python 2.4 (or Python 2.3 on Mac OS X). If you want to use different versions, you will need to build Squish from source and tell Squish's configure program which versions of Python, Perl, Ruby, or Tcl you want to use. Unfortunately, regarding Python, at present, only Python 2.x versions can be used with Squish. (See Configure Switches (Section 3.1.2.2.1) for details.)

3.1.1.2.8. Configuration Review

At this point all the configuration options have been set and a summary is presented for you to review.

A picture of the configuration review page from the froglogic Squish configuration program.

If you notice any mistakes, you can keep pressing the Back button until you reach the relevant configuration page, and then correct the information, and then keep pressing the Next button until you reach the review page once more.

[Warning]Overwriting the Existing 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. If, afterwards, you realize that you made a mistake—or some aspect of your configuration changes that requires you to change Squish's configuration—you can always run the setup program again, which will cause it to overwrite the existing configuration settings with the new ones.

Once you are confident that the configuration settings are correct, click the Next button, to save the configuration shown, and to advance to the setup program's last page.

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

A picture of the final page from a setup program.

You should now click the Finish button close the setup program. Most versions of setup offer options to open the Squish manual and to run the IDE at the end.

3.1.2. Installing Squish for Qt from Desktop Source Packages

In most situations Squish can be quickly and easily installed using one of the binary packages (see Installing from Binary Packages (Section 3.1.1)). However, if you prefer to build it from source—or if you must build it from source because no suitable binary package is available, or because you need to use features that require a source build—this section explains how to build it.

Once Squish is built, it can be distributed to different computers running the same operating system (see Distributing and Sharing an Installation (Section 3.1.4)).

Note that 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 (as described here), you can then go on to install the Squish IDE (see Standalone Installation of the IDE (Section 3.2)).

In many common cases the build process can be done in just a few simple steps, as described in Quick Install (Section 3.1.2.1). 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.

3.1.2.1. Quick Install

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

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

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/qt5, respectively.

Start by changing to Squish's source directory.

Windows

C:\> cd \squish

Linux/Unix/Mac OS X

$ cd /usr/local/squish

Now run the configuration script:

Windows

C:\squish> configure --with-qmake=C:\Qt\bin\qmake --disable-all --enable-idl --enable-qt

Linux/Unix/Mac OS X

$ ./configure --with-qmake=/usr/local/qt/bin/qmake --disable-all --enable-idl --enable-qt

After the configure run has finished start the build process:

Windows

C:\squish> build

Linux/Unix/Mac OS X

$ ./build

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 2

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 2

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

Windows

C:\squish> build install DESTDIR=c:\squish-5.1.0-qt48x-win32-msvc10

Linux/Unix/Mac OS X

$ ./build install DESTDIR=/home/user/squish-5.1.0-qt50x-linux64

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

3.1.2.2. 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. 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 3.1.0 or greater must be available.

  • Qt must be configured and built with support for threads. (This is the default as of Qt 4.).

  • Qt must be configured and built as a shared library.

  • If you want to use Python as a scripting language for test scripts, then you must have Python 2.3 or any later Python 2.x version installed. (Python 3 is not currently supported.)

  • If you want to use Perl as a scripting language for test scripts, then you must have Perl 5.8 or any later 5.x version installed.

  • If you want to use Ruby as a scripting language for test scripts, then you must have Ruby 1.9.

  • If you want to use Tcl as a scripting language for test scripts, then you must have Tcl 8.4 or later installed.

[Note]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).

[Note]Mac OS X-specific—Xcode Required

If you want to build Squish on Mac OS X 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.

LanguageWindows
PythonWe recommend installing the standard Python package available at http://www.python.org/download/releases/2.6.2/ or a more recent version from that site. Download the “Windows x86 MSI Installer”—which works on all Windows machines—unless you know for certain that your machine uses an 64-bit processor, in which case download the “Windows AMD64 MSI Installer”.
PerlWe recommend installing ActiveState's Perl package. You can download it from http://www.activestate.com/activeperl/downloads/. It is supplied as an MSI installer—with versions for 32-bit and 64-bit processors. If you run the installer and accept all the default settings it will be installed in C:\Perl.
RubyThe official installation page for Ruby is http://www.ruby-lang.org/en/downloads/. Most Linux distributions will have it as a standard package.
TclWe recommend installing ActiveState's Tcl build. You can download it from http://www.activestate.com/activetcl/downloads/. It is supplied as a Windows setup program. If you run this and accept all the default settings it will be installed in C:\Tcl.
LanguageLinux/Unix
PythonThe Python interpreter executable must be in the PATH. Most Unixes already have Python pre-installed, but if it isn't, a package should be available from your system's package management tool, or you can download a version from http://www.python.org/download/releases/2.6.2/. Note that if you install a package, you must install the -dev or -devel version, since Squish needs to access the header files when it is built.
PerlThe Perl interpreter executable must be in the PATH unless you specify a location for it using the --with-perl configure switch. Most Unixes already have Perl pre-installed, but if it isn't, a package should be available from your system's package management tool, or you can download a version from http://www.activestate.com/activeperl/downloads/. Note that if you install a package, you must install the -dev or -devel version, since Squish needs to access the header files when it is built.
RubyThe Ruby interpreter executable must be in the PATH unless you specify a location for it using the --with-ruby configure switch. Most Unixes already have Ruby pre-installed, but if it isn't (or is too old a version), a package should be available from your system's package management tool, or you can download a version from http://www.ruby-lang.org/en/downloads/. Note that if you install a package, you must install the -dev or -devel version, since Squish needs to access the header files when it is built.
TclMost Unixes already have Tcl installed, but if it isn't, a package should be available from your system's package management tool, or you can download a version from http://www.activestate.com/activetcl/downloads/. Note that if you install a package, you must install the -dev or -devel version, since Squish needs to access the header files when it is built.
LanguageMac OS X
PythonA pre-installed version of Python is provided with Mac OS X—this includes the headers and is sufficient for Squish's needs.
PerlA pre-installed version of Perl is provided with Mac OS X—this includes the headers and should be sufficient for Squish's needs.
RubyAt the time of this writing Ruby 1.8 is the pre-installed version on Mac OS X, and this is too old. To use Ruby on Mac OS X you must build and install Ruby 1.9.
TclA pre-installed version of Tcl is provided with Mac OS X—this includes the headers and is sufficient for Squish's needs.

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 Qt/Embedded 2.3 applications, see Installation for testing Qt/Embedded 2.3 applications (Section 3.1.3.3). Qt Embedded (previously QtopiaCore and Qtopia 4.x)-specific instructions can be found in Installation for testing of Qt/Embedded, QtopiaCore and Qtopia 4.x applications (Section 3.1.3.2).

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 Platforms

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 2000, Windows XP, Windows Vista, Windows 7 and Windows 8), with Microsoft® VC++ 6 through 2013, and with Intel C++ 7. For Unix-like systems, Squish has been tested on all modern versions of Mac OS X with gcc and clag; on AIX 6.1 with xlC 9; 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++ 7; 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.

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.

Windows

C:\squish

Linux/Unix/Mac OS X

/usr/local/squish

You can of course install Squish anywhere on your machine, including a local install (e.g., somewhere in your HOME directory). Of course, if you don't have Administrator/superuser access rights you will have to do a local install. If you don't use one of the directories shown in the table above, simply change the directory to the one you do use, when following the instructions that follow.

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:

Windows

%HOMEPATH%\.squish-3-license

Linux/Unix/Mac OS X

$HOME/.squish-3-license

If %HOMEPATH% is not defined on your version of Windows, use %USERPROFILE% instead. Although we have assumed the use of the default location (i.e., %HOMEPATH% or $HOME), it is possible to store the license file in another directory by setting the SQUISH_LICENSEKEY_DIR environment variable. (See Environment Variables (Section 19.5).)

Notice the change of name to include a leading period. Alternatively, you can enter the license key contained in the file when configure (or the GUI setup application) asks for it.

[Note]Building Squish for Other Users

If you build Squish for another user, you must make sure that each user copies the license file into 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 Mac OS X 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.

Windows

C:\> cd \squish

Linux/Unix/Mac OS X

$ cd /usr/local/squish

Now run the configuration script:

Windows

C:\squish> configure

Linux/Unix/Mac OS X

$ ./configure

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.

Windows

If configure detected MSVC++ but you want to use Intel C++, run configure like this:

C:\squish> set CXX=icl

C:\squish> configure

Linux/Unix

If configure detected SunCC on Solaris, but you want to use gcc, run configure like this:

$ CXX=g++ ./configure

Mac OS X

If configure detected the default gcc version, but you want to use gcc 3.3, run configure like this:

$ CXX=g++-3.3 ./configure

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

Windows

C:\squish> build

Linux/Unix/Mac OS X

$ ./build

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 19.4.3) 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:

Windows

C:\squish\bin

C:\squish\lib

Linux/Unix/Mac OS X

/usr/local/squish/bin

/usr/local/squish/lib

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.

Windows

Open the advanced system settings in the Windows control panel and append ;C:\Squish\bin at the end of the PATH environment value's text—notice the leading “;” to separate this path entry from the others.

Linux/Unix

Edit .bashrc (or the appropriate file for the shell you are using) and extend the PATH, for example, by writing: export PATH=$PATH:/usr/local/squish/bin, or if there is already a line like this simply by appending :/usr/local/squish/bin to the end of the line. Alternatively, you may prefer to create symbolic links, in /usr/local/bin, to the executables in /usr/local/squish/bin.

Mac OS X

Edit .bashrc (or the appropriate file for the shell you are using) and extend the PATH, for example, by writing: export PATH=$PATH:/usr/local/squish/bin, or if there is already a line like this simply by appending :/usr/local/squish/bin to the end of the line. Alternatively, you may prefer to create symbolic links, in /usr/local/bin, to the executables in /usr/local/squish/bin.

3.1.2.2.1. 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:

--disable-examples

See Partial Build for a complete explanation

--with-tclconfig=/usr/lib/tcl8.3

Tells configure which version of Tcl you want to use by specifying the path to the version-specific tclConfig.sh file.

--with-pydir=C:\Python26

Tells configure which directory contains the Python executable, e.g., on Windows, the directory containing python.exe

--with-qtdir=C:\Qt\4.7.0

Tells configure where the version of Qt you want to use is installed, overriding the QTDIR environment variable if it is set

--enable-64bit

Forces a 64-bit build on platforms where this is supported

For a complete list, execute configure --help on the command line or see configure (Section 19.4.11) in the reference manual.

Partial Build

By default, configure builds all the components that it can find. However, in some cases it may be desirable to only build those components that you actually need. You might want to minimize the components built because:

  • you want 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;

  • you want to 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 (Section 3.1.2.5).

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 (if available) or disable are listed below.

all

use this to enable or disable all Squish's components—this is enabled by default which is why the build system builds everything it can find by default

server

the squishserver application (needed to run tests)—this is built by default

runner

the squishrunner application (needed to run tests)—this is built by default

ide

the Classic IDE —this IDE is deprectated and is not built by default anymore

explorer

the wrapper explorer (used for looking into wrapped libraries)—this is built by default

idl

the IDL compiler (needed for generating wrapper libraries)—this is built by default

wrappers

Squish's framework wrapper libraries—this is built by default

examples

the example applications and their tests (useful for following the tutorial and includes the examples used in the manual)—these are built by default

64bit

forces a 64-bit build on platforms where this is supported

pure-qt4

if enabled, tells Squish not to use Qt 3 support when testing Qt 4 applications

tk

Tk testing

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"

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

[Note]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 Mac OS X 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).

Windows

C:\Squish-Qt4

C:\Squish-Qt4-and-Qt3

Linux/Unix

/home/user/squish-qt4

/home/user/squish-qt4-and-qt3

Mac OS X

/Users/user/squish-qt4

/Users/user/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.

Windows

C:\Qt\4.7.1

C:\Qt\Qt4-and-Qt3

Linux/Unix

/usr/local/qt47

/usr/local/qt4-and-qt3

Mac OS X

/opt/local/qt47

/opt/local/qt4-and-qt3

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:

Windows

C:\> cd C:\Squish-Qt4

C:\Squish-Qt4> configure --enable-pure-qt4 --with-qtdir=C:\Qt\4.7.1 --disable-all --enable-idl --enable-wrappers --enable-examples

Linux/Unix

$ cd /home/user/squish-qt4

$ ./configure --enable-pure-qt4 --with-qtdir=/usr/local/qt47 --disable-all --enable-idl --enable-wrappers --enable-examples

Mac OS X

$ cd /Users/user/squish-qt4

$ ./configure --enable-pure-qt4 --with-qtdir=/opt/local/qt47 --disable-all --enable-idl --enable-wrappers --enable-examples

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:

Windows

C:\Squish-Qt4> build

Linux/Unix/Mac OS X

$ ./build

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:

Windows

C:\Squish-Qt-4> cd C:\Squish-Qt4-and-Qt3

C:\Squish-Qt4-and-Qt3> configure --with-qtdir=c:\Qt\Qt4-and-Qt3 --disable-idl --disable-wrappers --disable-examples --disable-explorer

Linux/Unix

$ cd /home/user/squish-qt4-and-qt3

$ ./configure --with-qtdir=/usr/local/qt4-and-qt3 --disable-idl --disable-wrappers --disable-examples --disable-explorer

Mac OS X

$ cd /Users/user/squish-qt4-and-qt3

$ ./configure --with-qtdir=/opt/local/qt4-and-qt3 --disable-idl --disable-wrappers --disable-examples --disable-explorer

Step 5 of 6

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

Windows

C:\Squish-Qt4-and-Qt3> build

Linux/Unix/Mac OS X

$ ./build

This second build compiles another set of binaries, but there is one part missing from this build: the registration of the Qt wrapper. Normally this is done automatically, but when the split build was performed the tool for registration (squishrunner) was missing at the point when the wrapper was built (because we had disabled it). This can be solved by rebuilding the target like this:

Windows

C:\Squish-Qt4-and-Qt3> build qtwrapperinit

Linux/Unix/Mac OS X

$ ./build qtwrapperinit

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:

Windows

C:\Squish-Qt4-and-Qt3> copy C:\Squish-Qt4\bin\dllpreload.exe bin\

C:\Squish-Qt4-and-Qt3> copy C:\Squish-Qt4\bin\extrawindowwatcher.exe bin\

C:\Squish-Qt4-and-Qt3> copy C:\Squish-Qt4\bin\injectdll*.exe bin\

C:\Squish-Qt4-and-Qt3> copy C:\Squish-Qt4\bin\squishhook.dll bin\

C:\Squish-Qt4-and-Qt3> copy C:\Squish-Qt4\bin\squishqtbuiltinhook.dll bin\

C:\Squish-Qt4-and-Qt3> copy C:\Squish-Qt4\bin\squishqtwrapper.dll bin\

C:\Squish-Qt4-and-Qt3> copy C:\Squish-Qt4\bin\startaut.exe bin\

C:\Squish-Qt4-and-Qt3> copy C:\Squish-Qt4\bin\startwinaut.exe bin\

C:\Squish-Qt4-and-Qt3> copy C:\Squish-Qt4\bin\winhook.dll bin\

C:\Squish-Qt4-and-Qt3> copy C:\Squish-Qt4\lib\_extrawindowwatcher.exe lib\

C:\Squish-Qt4-and-Qt3> copy C:\Squish-Qt4\lib\_startwinaut.exe lib\

C:\Squish-Qt4-and-Qt3> copy C:\Squish-Qt4\lib\extensions\qt\*.* lib\extensions\qt\

C:\Squish-Qt4-and-Qt3> copy C:\Squish-Qt4\lib\extensions\win\*.* lib\extensions\win\

C:\Squish-Qt4-and-Qt3> copy C:\Squish-Qt4\lib\squishqtpre.dll lib\

C:\Squish-Qt4-and-Qt3> copy C:\Squish-Qt4\src\wrappers\qt\*.tcl lib\

Linux/Unix

$ cp /home/user/squish-qt4/bin/isstaticapp /home/user/squish-qt4-and-qt3/bin

$ cp /home/user/squish-qt4/bin/startaut /home/user/squish-qt4-and-qt3/bin

$ cp /home/user/squish-qt4/lib/extensions/qt/*.* /home/user/squish-qt4-and-qt3/lib/extensions/qt

$ cp /home/user/squish-qt4/lib/libsquishhook.so /home/user/squish-qt4-and-qt3/lib

$ cp /home/user/squish-qt4/lib/libsquishqtbuiltinhook.so /home/user/squish-qt4-and-qt3/lib

$ cp /home/user/squish-qt4/lib/libsquishqtpre.so /home/user/squish-qt4-and-qt3/lib

$ cp /home/user/squish-qt4/lib/libsquishqtwrapper.so /home/user/squish-qt4-and-qt3/lib

$ cp /home/user/squish-qt4/src/wrappers/qt/*.tcl /home/user/squish-qt4-and-qt3/lib

Mac OS X

$ cp /Users/user/squish-qt4/bin/isstaticapp /Users/user/squish-qt4-and-qt3/bin

$ cp /Users/user/squish-qt4/bin/startaut /Users/user/squish-qt4-and-qt3/bin

$ cp /Users/user/squish-qt4/lib/extensions/qt/*.* /Users/user/squish-qt4-and-qt3/lib/extensions/qt

$ cp /Users/user/squish-qt4/lib/libsquishhook.so /Users/user/squish-qt4-and-qt3/lib

$ cp /Users/user/squish-qt4/lib/libsquishqtbuiltinhook.so /Users/user/squish-qt4-and-qt3/lib

$ cp /Users/user/squish-qt4/lib/libsquishqtpre.so /Users/user/squish-qt4-and-qt3/lib

$ cp /Users/user/squish-qt4/lib/libsquishqtwrapper.so /Users/user/squish-qt4-and-qt3/lib

$ cp /Users/user/squish-qt4/src/wrappers/qt/*.tcl /Users/user/squish-qt4-and-qt3/lib

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.

3.1.2.4. 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 (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:

Windows

C:\Squish-Qt3

C:\Squish-Qt4-and-Qt3

Linux/Unix

/home/user/squish-qt3

/home/user/squish-qt4-and-qt3

Mac OS X

/Users/user/squish-qt3

/Users/user/squish-qt4-and-qt3

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

Windows

C:\Qt\3.2.3

C:\Qt\4.7.1

Linux/Unix

/usr/local/qt3

/usr/local/qt4

Mac OS X

/opt/local/qt3

/opt/local/qt4

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

Windows

C:\> cd C:\Squish-Qt3

C:\Squish-Qt3> configure --with-qtdir=c:\Qt\3.2.3 --disable-all --enable-server --enable-idl --enable-wrappers --enable-examples

Linux/Unix

$ cd /home/user/squish-qt3

$ ./configure --with-qtdir=/usr/local/qt3 --disable-all --enable-server --enable-idl --enable-wrappers --enable-examples

Mac OS X

$ cd /Users/user/squish-qt3

$ ./configure --with-qtdir=/opt/local/qt3 --disable-all --enable-server --enable-idl --enable-wrappers --enable-examples

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:

Windows

C:\Squish-Qt3> build

Linux/Unix/Mac OS X

$ ./build

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:

Windows

C:\Squish-Qt3> cd C:\Squish-Qt4-and-Qt3

C:\Squish-Qt4-and-Qt3> configure --with-qtdir=c:\Qt\4.7.1 --disable-server --disable-idl --disable-wrappers --disable-examples

Linux/Unix

$ cd /home/user/squish-qt4-and-qt3

$ ./configure --with-qtdir=/usr/local/qt4 --disable-server --disable-idl --disable-wrappers --disable-examples

Mac OS X

$ cd /Users/user/squish-qt4-and-qt3

$ ./configure --with-qtdir=/opt/local/qt4 --disable-server --disable-idl --disable-wrappers --disable-examples

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

Windows

C:\Squish-Qt4-and-Qt3> build

Linux/Unix/Mac OS X

$ ./build

This second build compiles another set of binaries, but there is one part missing from this build: the registration of the Qt wrapper. Normally this is done automatically, but when the split build was performed the tool for registration (squishrunner) was missing at the point when the wrapper was built (because we had disabled it). This can be solved by rebuilding the target like this:

Windows

C:\Squish-Qt4-and-Qt3> build qtwrapperinit

Linux/Unix/Mac OS X

$ ./build qtwrapperinit

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.2)):

/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 Window|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.

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

[Note]Windows-specific

If you want to use a single-threaded Qt library on Windows, please take a look at Q: 22.1.6.

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

Windows

C:\Qt\singlethreaded

C:\Qt\multithreaded

Linux/Unix

/usr/local/qt-singlethreaded

/usr/local/qt-multithreaded

Mac OS X

/opt/local/qt-singlethreaded

/opt/local/qt-multithreaded

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:

Windows

C:\squish> configure --with-qtdir=C:\Qt\multithreaded --disable-all --enable-server --enable-runner --enable-ide-utils

C:\squish> build

Linux/Unix

$ ./configure --with-qtdir=/usr/local/qt-multithreaded --disable-all --enable-server --enable-runner --enable-ide-utils

$ ./build

Mac OS X

$ ./configure --with-qtdir=/opt/local/qt-multithreaded --disable-all --enable-server --enable-runner --enable-ide-utils

$ ./build

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:

Windows

C:\squish> configure --with-qtdir=C:\Qt\singlethreaded --disable-server --disable-runner --disable-ide-utils --disable-win

C:\squish> build

Linux/Unix

$ ./configure --with-qtdir=/usr/local/qt-singlethreaded --disable-server --disable-runner --disable-ide-utils

$ ./build

Mac OS X

$ ./configure --with-qtdir=/opt/local/qt-singlethreaded --disable-server --disable-runner --disable-ide-utils

$ ./build

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:

Windows

Dependency Walker (depends.exe)

Linux/Unix

ldd or chatr

Mac OS X

otool

3.1.2.6. Statically linked Qt libraries

We recommend using a dynamic (shared) Qt library for both recording and running tests. Running tests using a static Qt library used to work with old versions of Qt on some Unix variants, but is not supported for technical reasons anymore.

3.1.2.7. Installation for testing with a renamed Qt library

3.1.2.7.1. Qt 3

If you want to use Squish with a renamed Qt 3 library, you must use additional options to configure. On Unix and Mac OS X 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-qtdllname=<path to Qt>/bin/<renamedqt-mt.dll>

  • --with-qtlibname=<path to Qt>/lib/<renamedqt-mt.lib>

  • --with-qtmainlibname=<path to Qt>/lib/<qtmain.lib>

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.

3.1.2.7.2. Qt 4 or later

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

3.1.2.8. Solving Build Errors

Missing prerequisites, incompatible system libraries or misconfigured development tools may lead to the build process failing.

We have started to list most commonly reported build errors and solutions in the Knowledge Base. For errors not covered please file a technical support request including the error output and configuration files like config.log and Build.conf.

We'll help solving obvious problems through our standard support offering. For more involved cases including remote or on-device debugging, tool chain setups or code adaptions we provide a Customization Service. Case-specific conditions are available upon request.

3.1.2.9. Warnings About Parse Errors

During the phase of the build build that generates the Qt wrapper you'll see warnings about parse errors floating by. Such as this one about the use of an STL header in Qt:

C:/Qt/include/QtCore/qlist.h:30: warning: Couldn't find include file iterator
C:/Qt/include/QtCore/qlist.h:30: #include <iterator>
C:/Qt/include/QtCore/qlist.h:30: ^

Or, about internals of the Standard C++ Library:

/opt/gcc/4.6.3/x86_64/include/c++/4.6.3/ext/type_traits.h:188: warning: ';' expected found '+'
/opt/gcc/4.6.3/x86_64/include/c++/4.6.3/ext/type_traits.h:188: typedef __typeof__(_Tp2() + _Up2()) __type;
/opt/gcc/4.6.3/x86_64/include/c++/4.6.3/ext/type_traits.h:188: ^

These warnings look alarming on first sight but have been examined and turned out to be harmless. After all, the main purpose of the squishidl runs are the creation of bindings to the Qt API. For completeness (global type definitions and macros) the tool will try to visit other included headers. If it bails out because it encounters code it cannot parse (because of e.g. proprietary language features) there is no negative impact in the concrete cases at hand.

3.1.3. Installing Squish for Qt from Embedded Source Packages

Customers targetting an embedded device, i.e. a platform other than their local system are offered a source package featuring the capability to cross-compile a minimal set of Squish components for QNX, Android, VxWorks, Embedded Linux, etc. running on ARM, MIPS, PPC and other hardware architectures.

As Qt installations on embedded systems often use non-standard configurations or non-standard library names or locations froglogic engineers will help with adaptions to the configuration of Squish. See the description of this customization service for more details.

The file name of the source package suitable for compilation to target system will follow this naming scheme: squish-x.y.z-qt-embedded-src.zip

3.1.3.1. Installation for embedded Qt 4/5 applications

3.1.3.1.1. Build instructions

Testing of applications running on a device often requires the use of a cross-compiler. The installation steps resemble those of Quick Install (Section 3.1.2.1). The main differences:

  • The main build will be done with the cross-compiler specified via the XCXX environment variable.
  • Since the squishidl helper tool needs to be run during the build it won't be cross-compiled for the target but taken from a pre-built binary package.
  • The created files will be copied onto the target device. Together with either bin/squishserver and lib/_squishserver or bin/startaut. The choice between the latter files depends on whether Squish should launch the AUT remotely (throught squishserver) or whether it should connect to an AUT running already (started through startaut).

If the Qt installation already contains a suitable configuration (qmake mkspec) for the target system, the --enable-qmake-config switch can be used to make configure fetch all toolchain configuration by asking qmake:

$ ./configure \
  --with-qmake=/usr/local/qt5/bin/qmake \
  --with-squishidl=/home/user/squish-desktop/bin/squishidl \
  --disable-all \
  --enable-qt \
  --enable-server

If qmake does not handle this or if qmake returns wrong toolchain information or paths a manual configuration is necessary which involves setting the compiler as well as the Qt directory to use.

NOTE: For Qt 5 you need a working qmake that responds with the correct installation path when executing the following command:

$ /usr/local/qt5-cross/bin/qmake -query QT_INSTALL_PREFIX

Additional information can be found in Cross-compilation (Section 3.1.3.2.2) whereas the instructions for Qt 4 equally apply to Qt 5.

3.1.3.1.2. Further setup

Similar to a desktop installation, everything needed for the target device can be copied into a single directory by issuing the following in the build directory:

$ ./build install DESTDIR=/home/user/squish-embedded

This will put all files needed on the target device beneath /home/user/squish-embedded. The resulting directory may then be copied to the target.

After deploying the cross-compiled binaries to the target device follow Section 3.1.2.1, “Further setup” to set up the Squish IDE on your desktop system.

3.1.3.2. Installation for testing of Qt/Embedded, QtopiaCore and Qtopia 4.x applications

3.1.3.2.1. Build instructions

In general, the build instructions used for a build against Qt/Embedded 2.x, apply to QtopiaCore and therefore to Qtopia 4.x as well. It's mainly the changed directory layout between the two versions that makes a difference for our purposes.

To build the parts of Squish that hook into the AUT, unpack the source package into a directory, change to that directory and use configure to specify the location of the QtopiaCore installation. For example:

$ ./configure --with-qtdir=/home/user/qtopia-build/qtopiacore/target \
--disable-all --enable-server --enable-examples --enable-idl \
--enable-wrappers --enable-pure-qt4

(We've escaped newlines to make the command line fit better on the page, but it can be entered as a single line if preferred.)

Here we have used the --with-qtdir switch to specify the location of the QtopiaCore installation, i.e., to the directory that contains the lib directory that contains the QtCore library (lib/libQtCore.so).

Once configure has finished, we can do the build.

$ ./build

This will build bin/squishserver and most importantly the QtopiaCore-specific wrapper library. The client side tools (e.g. squishrunner and the IDE) can either be obtained by compiling a source package against a Qt/X11, Qt/Win, or Qt/Mac installation, or by installing a pre-built binary version of Squish.

3.1.3.2.2. Cross-compilation

A cross-compilation is performed when building software on a local host system that will later be run on a target system that has a different architecture. This is a common requirement when building software for special purpose hardware that is too limited in terms of CPU, memory or tools, to be used as a development platform itself.

Part of the build process requires the execution of the squishidl (Section 19.4.3) tool that scans the Qt header files to provide script bindings for the scripting languages that Squish supports. The tool must be run on the host system and therefore it must be built with a native compiler. This is done in the first phase:

Unpack a Squish source package into a directory such as squish-desktop.

In all cases, now run configure and build the squishidl tool:

$ ./configure --with-qtdir=</path/to/desktop/qt> --disable-all --enable-idl
$ ./build

This will build the squishidl tool in the bin directory.

For the second phase—the actual cross-compilation—perform the following steps:

Unpack the source package in a different directory, such as squish-embedded. Use a text editor to create a shell script called squishidl in the bin directory that has the following content:

SQUISH_DESKTOP=/path/to/squish-desktop
${SQUISH_DESKTOP}/bin/squishidl "$@"

Make the shell script executable by executing chmod +x bin/squishidl. You can test whether this wrapper around the real tool is working by executing ./bin/squishidl --help.

Now, ask the AUT's developers which cross-compiler they use for application development. Specify the cross-compiler's path for the configure program by setting the XCXX environment variable, and tell configure to build only those components that need to be installed on the target:

$ ./configure --with-qtdir=/path/to/qt-embedded --disable-all \
--enable-server --enable-wrappers --enable-pure-qt4

(We've escaped newlines to make the command line fit better on the page, but it can be entered as a single line if preferred.)

Once the configuration has completed, start the build—this may take a few minutes:

$ ./build
3.1.3.2.3. Installation on the target device

Once the executables and libraries are built, the easiest next step is to copy the bin/, lib/, and etc/ directories (including their contents) to the target device.

If you would rather only copy the minimum amount of files possible to the target device, there are two possible scenarios. If you want to launch the AUT through the Squish IDE you only need to copy bin/squishserver, bin/isstaticapp, lib/_squishserver, lib/libsquishqtwrapper.so, and lib/libsquishhook.so. Or, if you want to launch the AUT manually (e.g., with the squishserver on a separate PC), you only need to copy bin/startaut, lib/libsquishqtwrapper.so, and lib/libsquishhook.so. And unless the built-in hook is used lib/libsquishqtpre.so needs to be copied over as well.

The Qt directory in your build environment is likely to differ from that used by the target system. As the executables use Qt themselves they need to be told where to find it. That can be accomplished by adapting the LibraryPath variable in etc/paths.ini.

In addition, Squish might need to be told where to look for the Qt libraries used by the application. This may be the same set as those used by the tool itself but could be different. By default Squish will look in the directory that is was told about during the configuration of the build system. There are two ways to tell it about the path on the target system:

  1. Set the environment variable SQUISH_LIBQTDIR to Qt's lib/ directory before starting the squishserver. (See also, Environment Variables (Section 19.5).)

  2. Add an entry like UserQtLibDirectory="</path/to/qt/lib>" to the [General] section of the etc/squish.ini file.

By default Squish expects the Qt library's unversioned files libQtCore.so and libQtGui.so to be installed. These are typically used for development purposes. However, the target system might only have the versioned runtime library libQtCore.so.4 installed. It is possible to modify the build system to expect only the latter (contact support for help on that), but there is a simple alternative. Create the same symlinks that you will find on your computer by executing the following commands (changing the paths to the ones that are correct for your system):

$ ln -s /path/to/qt/lib/libQtCore.so.4 /path/to/qt/lib/libQtCore.so
$ ln -s /path/to/qt/lib/libQtGui.so.4 /path/to/qt/lib/libQtGui.so

3.1.3.3. Installation for testing Qt/Embedded 2.3 applications

Using Squish with Qt/E 2.3.x on X11 with QVFb
Installation

Unpack Squish into two directories, e.g. /usr/local/squish-desktop, /usr/local/squish-embedded.

The squish-desktop directory will be used to build the client-side parts of Squish. For this we need Qt version 3.1.x or higher (X11 version), with thread support switched on. For the rest of the example, we assume the use of Qt 3.2 installed in /usr/local/qt32.

The squish-embedded directory will be used to build the parts of Squish that hook into the AUT, as well as the squishserver. For this build we need Qt/Embedded version 2.3.x, that has been compiled with thread support switched on and built as a shared library. The command line, with the parameters that must be passed to configure, should look something like this:

$ ./configure -depths 8,16,32 -qvfb -debug -thread -shared

For the rest of the example we assume that Qt/Embedded is installed in the directory /usr/local/qt23embedded.

First we build the desktop version of Squish. Change into the directory /usr/local/squish-desktop and build it normally, linking against Qt 3.1.x or higher (see the Quick Install (Section 3.1.2.1) for a more detailed description):

$ cd /usr/local/squish-desktop
$ ./configure --with-qtdir=/usr/local/qt32
$ ./build

Next we must build the Qt/Embedded version that hooks into the AUT and the squishserver. For this, change to the /usr/local/squish-embedded directory and configure Squish with everything disabled except the server, the wrappers, and the IDL compiler—and also with the examples so that we have a small program for testing:

$ cd /usr/local/squish-embedded
$ ./configure --with-qtdir=/usr/local/qt23embedded --enable-debug \
--disable-all --enable-server --enable-wrappers --enable-examples \
--disable-tk --enable-idl

(We've escaped newlines to make the command line fit better on the page, but it can be entered as a single line if preferred.)

Once this second configuration is complete, we can build the Qt/Embedded version of Squish:

$ ./build

That's all that we need to do to prepare for testing Qt/Embedded applications.

Testing a Qt/Embedded Application

Now we can start with an initial test of a Qt/Embedded application. First we must add the AUT path of the application we want to test to the squishserver. For this example we will use the Qt 3 addressbook example:

$ /usr/local/squish-embedded/bin/squishserver \
--config addAppPath /usr/local/squish-embedded/examples/qt3/addressbook

(We've escaped newlines to make the command line fit better on the page, but it can be entered as a single line if preferred.)

Now we can start the Qt Virtual Framebuffer; it might be more convenient to do this in a separate shell window:

$ /usr/local/qt32/tools/qvfb/qvfb -width 1280 -height 1024 &

Next, set the QTDIR environment variable to the directory where your version of Qt/Embedded 2.3.x is installed, and start the squishserver:

$ export QTDIR=/usr/local/qt23embedded
$ /usr/local/squish-embedded/bin/squishserver

Now, open another shell window, from which you can start the IDE (assuming that you have installed it; see Standalone Installation of the IDE (Section 3.2)):

$ /usr/local/squishide/squishide

Once the Squish IDE has started, open the example test suite, /usr/local/squish-embedded/examples/suite_addressbook/suite.conf.

You must also tell the Squish IDE to connect to the squishserver we started, rather than starting one of its own.

In the IDE, click Window|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. Make sure that the Start local Squish server automatically checkbox is unchecked, and that the Host is set to “localhost” (or to “127.0.0.1”), and that the Port is set to “4322”.

(See Distributed Tests (Section 19.1.2) for more details about local and remote squishservers.)

Finally we must also tell Squish to start our AUT with the -qws argument. To do this using the IDE, click the Test Suite Settings toolbar button, and in the Application Under Test (AUT) section, enter “-qws” in the Arguments line editor.

Now you can run tests or record them, as described in the User Guide (Chapter 17). You will see that the AUT (address book example), which is compiled as a Qt/Embedded application, opens up in the Qt Virtual Framebuffer and you can record events and replay the test cases in there.

Using Squish with a cross-compiled Qt/E 2.3.x
Installation

The installation procedure for building Squish with a cross-compiled Qt/Embedded 2.3.x is almost identical to the procedure for Qt/Embedded with the Qt Virtual Framebuffer. The only differences are the use of a different squishidl and the setting of the XCXX environment variable, specifying the cross compiler.

Make sure that the cross compiled Qt 2.3.x/Embedded is built as a shared library with thread support switched on. For the rest of the example we assume it is installed in /usr/local/qt23xcompiled.

After you have built Squish with the desktop version of Qt, copy the squishidl tool over and set the LD_LIBRARY_PATH variable to Qt's library path, if the library is not found automatically.

$ cd /usr/local/squish-embedded
$ mkdir bin
$ cp /usr/local/squish-desktop/bin/squishidl bin/
$ cp /usr/local/squish-desktop/lib/_squishidl lib/
$ export LD_LIBRARY_PATH=/usr/local/qt32/lib

Note that the squishidl tool is needed only at compile-time; it is not used at run-time during the test.

Next configure the embedded build. You must set the environment variable XCXX to the cross-compiler you are using. This time we also disable the squishidl tool. (We copied this tool in the previous step.)

$ XCXX=arm-linux-g++ ./configure --with-qtdir=/usr/local/qt23xcompiled \
--enable-debug --disable-all --enable-server --enable-wrappers \
--enable-examples --disable-tk

(We've escaped newlines to make the command line fit better on the page, but it can be entered as a single line if preferred.)

Now that the configuration is complete we can do the build:

$ ./build

This will build the cross-compiled version of Squish.

Testing the address book example

This is essentially the same as when we use the frame buffer, only this time we must start the squishserver on the device itself and enter the device's IP address, instead of “localhost”, as the Host in the Squish IDE's Remote Testing settings dialog.

To avoid problems during testing we recommend verifying the correctness of your Qt and AUT setup prior to test execution. For example, is the QTDIR environment variable pointing to the Qt installation directory (it must be set prior to launching the server)? And can you successfully run the AUT standalone?

3.1.3.4. Installation for Maemo

Squish can be used to test Qt software developed for Maemo devices. The testing can take place on a simulated device or on an actual device.

The installation is a three-step process:

  1. Install the Squish Tools on a Desktop PC.

  2. Install the Squish IDE on a Desktop PC.

  3. Install a separate squishserver on the Maemo device (or in the simulator).

The first two steps are exactly the same as when installing Squish normally. Step one is described in Installing the Command Line Tools, Server, and IDEs (Section 3.1), and step two in Standalone Installation of the IDE (Section 3.2). Once these steps have been completed, return here to complete the third step.

The third step is to install a squishserver on the Maemo device (or in the scratchbox simulator) and start the server running. Note that the Maemo software must be version maemo5+pr1.2 or later. First the squishserver must be installed.

  1. Download the squishserver Maemo package, e.g., squishserver_4.0.1-qt462-maemo-1_armel.deb—naturally the version number may be different from that shown here.

  2. Copy the .deb package to the Maemo device (or to the scratchbox).

  3. Login to the device (or scratchbox) as root.

  4. Install the package by executing:

    $ dpkg -i squishserver_4.0.1-qt462-maemo-1_armel.deb
    

    Of course you should use the name of the file that was actually downloaded if that's different from the one shown.

    If this command fails with an “unmet dependencies” error, use the apt-get program to solve the problem:

    $ apt-get -f install
    

    This will install any depended upon packages (e.g., libqt4-core and libqt4-gui).

  5. Edit the Maemo device's (or scratchbox's) /opt/squishserver_4.0.1-qt462-maemo-1_armel/etc/squishserverrc file, and set the ALLOWED_HOSTS line to the IP address of the Desktop PC you are using to test with. For example:

    ALLOWED_HOSTS = 127.0.0.1 192.168.0.7
    

    Here, we've said that the server can accept connections on the same machine (for the typical case that the simulator is running on the same machine as we use for running Squish), and also another machine on the network. After this step the squishserver is installed and ready for use.

Once the squishserver is installed on the Maemo device (or in the scratchbox), it can be run whenever you want to test a Maemo AUT. The squishserver should be operated using the user account—not the root account.

3.1.3.4.1. Maemo-Specific Testing Notes

Each AUT you want to test on the Maemo device (or in the scratchbox) must first be registered with the device's (or scratchbox's) squishserver. This is done using the --config option (Configuring squishserver (Section 19.4.2.3)). For example:

$ /opt/squishserver-4.0.1-qt462-maemo/bin/squishserver --config addAUT superapp /opt/SuperApps/bin

Here, we've registered an application called superapp that's in the /opt/SuperApps/bin directory.

Once the AUT registering is done the squishserver can be run. For example:

$ run-standalone.sh /opt/squishserver-4.0.1-qt462-maemo/bin/squishserver

Once the squishserver is up and running on the Maemo device (or in the scratchbox), we can connect to it from the Desktop PC's Squish. To do this, start the Squish IDE on the Desktop PC, then click Window|Preferences to invoke the Pref­er­ences dialog (Section 20.3.12), then expand the Squish item and choose the Remote Testing item. Make sure that the Start local Squish server automatically checkbox is unchecked since we must always use the squishserver on the Maemo device (or in the scratchbox), and we must start that manually. For the Host enter the Maemo device's (or scratchbox's) IP address—unless you are running scratchbox on the same machine as the Squish IDE in which case the default of localhost is fine. There shouldn't be any need to change the port number.

Now the Squish IDE can be used to record tests of the AUT on the Maemo device (or in the scratchbox), almost the same as with normal Desktop testing. (See the Tutorial: Starting to Test Qt Applications (Chapter 4) to get started if you are new to Squish.) However, there are two small differences from normal desktop testing. The first concerns the Test Suite Settings, and the other concerns the recording of tests.

Regarding the Test Suite Settings, there is one small difference when you're ready to create a Test Suite for your Maemo AUT. At this point make sure that the squishserver on the Maemo device (or in scratchbox) is running (and that you've registered the AUT—something you only need to do once per AUT). Now, in the Squish IDE click File|New Test Suite as usual. So long as the squishserver is running on the device (or in scratchbox) when you get to the wizard's Application Under Test page the Application combobox will list all the Maemo AUTs you have registered. Choose the one you want and continue as usual. Now, before recording any tests, click the Test Suite Settings toolbar button and make sure that the Automatically start the AUT checkbox is checked.

Regarding the recording of tests, if you use the Nokia titlebar menu during the test, playback doesn't work—at least not straightaway. The problem is that the titlebar menu is a special case and actually consists of QPushButtons rather than QMenu items. This is easy to work around though, simply by preceding each click of one of the titlebar menu's buttons with a native mouse click on the titlebar (to activate it). For example, if you have recorded code like this:

clickButton(waitForObject(":Open..._QPushButton"))

insert a native mouse click on the titlebar just before it, so the code becomes:

nativeMouseClick(400, 5, MouseButton.LeftButton)
clickButton(waitForObject(":Open..._QPushButton"))

The coordinates just put the click roughly in the middle of the titlebar. Make sure you do this change before every click on a menu item's button—or avoid the problem and use the toolbar buttons to interact with the AUT.

3.1.3.5. Installation for MeeGo

Squish can be used to test Qt software developed for MeeGo devices. The testing can take place on a simulated device, such as the qemu runtime provided by the MeeGo SDK, or on an actual device.

The installation is a three-step process:

  1. Install the Squish Tools on a Desktop PC.

  2. Install the Squish IDE on a Desktop PC.

  3. Install a separate squishserver on the MeeGo device (or in the qemu runtime system).

The first two steps are exactly the same as when installing Squish normally. Step one is described in Installing the Command Line Tools, Server, and IDEs (Section 3.1), and step two in Standalone Installation of the IDE (Section 3.2). Once these steps have been completed, return here to complete the third step.

The third step is to install a squishserver on the MeeGo device (or in a qemu runtime system) and start the server running. Note that the MeeGo Core Software Platform must be version 1.1.2 or later. First the squishserver must be installed.

  1. Download the squishserver MeeGo package, e.g., squishserver-4.1-1.meego.i586.rpm or squishserver-4.1-1.meego.armv7.rpm—naturally the version number may be different from that shown here.

  2. Copy the .rpm package to the MeeGo device (or to the qemu runtime system).

  3. Login to the device (or to the qemu runtime system) as root.

  4. Install the package by executing:

    $ rpm -i squishserver-4.1-1.meego.i586.rpm
    

    Of course you should use the name of the file that was actually downloaded if that's different from the one shown.

Once the squishserver is installed on the MeeGo device (or in a qemu runtime system), it can be run whenever you want to test a MeeGo AUT. The squishserver should be operated using the user account—not the root account.

3.1.3.5.1. MeeGo-Specific Testing Notes

Each AUT you want to test on the MeeGo device (or in the qemu runtime system) must first be registered with the device's (or qemu runtime system's) squishserver. This is done using the --config option (Configuring squishserver (Section 19.4.2.3)). For example:

$ squishserver --config addAUT superapp /opt/SuperApps/bin

Here, we've registered an application called superapp that's in the /opt/SuperApps/bin directory.

Once the AUT is registered the squishserver can be run. For example:

$ squishserver

Once the squishserver is up and running on the MeeGo device (or in a qemu runtime system), we can connect to it from the Desktop PC's Squish. To do this, start the Squish IDE on the Desktop PC, then click Window|Preferences to invoke the Pref­er­ences dialog (Section 20.3.12), then expand the Squish item and choose the Remote Testing item. Make sure that the Start local Squish server automatically checkbox is unchecked since we must always use the squishserver on the MeeGo device (or in the qemu runtime system), and we must start that manually. For the Host enter the MeeGo device's (or qemu runtime system's) IP address—unless you are running qemu runtime system on the same machine as the Squish IDE in which case the default of localhost is fine. For the Port enter a value of 13219. This port number is different from Squish's usual default (4322) because the qemu runtime system installed by the MeeGo SDK does not provide full networking and only forwards a few ports (including 13219) from inside the runtime to localhost. The squishserver install for MeeGo defaults to use the same port as is used for Qt Creator remote debugging.

Now the Squish IDE can be used to record AUT tests on the MeeGo device (or in the qemu runtime system), almost the same as with normal desktop testing. (See the Tutorial: Starting to Test Qt Applications (Chapter 4) to get started if you are new to Squish).

Regarding the Test Suite Settings, there is one small difference when you're ready to create a Test Suite for your MeeGo AUT. At this point make sure that the squishserver on the MeeGo device (or in the qemu runtime system) is running (and that you've registered the AUT—something you only need to do once per AUT). Now, in the Squish IDE click File|New Test Suite as usual. So long as the squishserver is running on the device (or in qemu runtime system) when you get to the wizard's Application Under Test page the Application combobox will list all the MeeGo AUTs you have registered. Choose the one you want and continue as usual. Now, before recording any tests, click the Test Suite Settings toolbar button and make sure that the Automatically start the AUT checkbox is checked.

3.1.4. Distributing and Sharing an Installation

Rationale

Once you have completed the build steps described in the previous section you have a system ready to use on the local machine. You may repeat these steps for licensed users on as many machines as you like. (Squish is normally licensed per user rather than per machine, so one licensee can install Squish on all the machines they use.)

This section is for users or system administrators that wish to distribute or share a build performed on one machine to a different location or for users on other machines. If access to a local installation is all you need, you can safely skip the rest of this section and proceed to the Standalone Installation of the IDE (Section 3.2) section, and then to the chapters about using Squish, starting with Squish Concepts (Section 4.1) if you are new to Squish.

There are many reasons why you might want to reuse the built executables and libraries—for example:

  • Division of labor between developers or system administrators (who will build Squish) and testers (who will use Squish).

  • Separation between machines used for product development and machines used specifically for testing.

  • Reduced maintenance work required when upgrading the software.

  • Saving time by doing a single compilation and distributing the results.

  • Saving disk space since only the executables and their supporting libraries need to be distributed, not the entire source code.

Distributables

After completing the build, the distributables can be found in the top-level bin, lib, and etc directories. The bin directory contains the executables (and some supporting .dll files on Windows), while other supporting libraries and script files are in the lib directory. The etc directory is used to hold installation configuration files—user specific settings are stored elsewhere, as explained shortly. Here is the list of all the files that comprise the Squish toolset (including those needed by the IDE). We have used wildcard syntax to indicate multiple files where appropriate.

Windows

bin\*.*

lib\*.*

etc\paths.ini

etc\squish.ini

etc\*wrapper_descriptors.xml

Linux/Unix/Mac OS X

bin/*

lib/*

etc/paths.ini

etc/squish.ini

etc/*wrapper_descriptors.xml

Notice that the wrapper library and wrapper descriptors have been specified using a wildcard (*) because there may be several of these depending on the toolkits you built Squish to make use of (e.g., Qt, Java, etc.).

Distribution

To distribute the build to another location on the same machine, or on a different one, just copy over all the files (or only those in the groups required), from the three directories listed above. The original build path is hard-coded into the binaries, but they will still work in a different location. To enable the executables to locate the libraries and other files that they depend on, it is important that the relative positions of the files remains the same. This means that you can copy the files from the bin, lib, and etc directories, to whatever directories you want, providing that the relative paths between the files remain the same, i.e., the directories used to store the files must have the same parent directory.

For example, if you copied the bin directory's files to the directory C:\tools\squish\executable, then the companion files from the lib, and etc directories must go in directories under C:\tools\squish, such as C:\tools\squish\library and C:\tools\squish\configuration.

When Squish hooks into the AUT, it loads the Qt library. The Qt library (with the full path) is hard-coded into the binaries. If the Qt library is in a different location on the target machine, you must set the environment variable SQUISH_LIBQTDIR to point to your Qt library's lib directory. (See also, Environment Variables (Section 19.5).)

Shared Installation

To allow all licensed users to access Squish from a shared network location, make the bin, lib, and etc directories accessible to them. This can be done via a share on Windows or via an NFS mount on Unix, for example. As mentioned earlier, the bin, lib and etc directories must all share the same parent directory.

User-specific settings are stored locally on a per-user basis in the application data directory on Windows (%APPDATA%\froglogic\Squish), or the $HOME/.squish directory on Unix and Mac OS X.

3.1.5. Installing Squish for Mac

Squish for Mac is provided in a package that once downloaded, must be unpacked and set up before Squish can be used. The package can be unpacked into any directory you like, and you can move this directory to a different location later on if you want to. However, it is important that you do not change the structure of the directories and files that have been unpacked.

Before running Squish for the first time you must run the setup program to ensure that Squish works correctly for your system, and respects your preferences. The setup program is located in the unpacked package's root directory, and can be started by double-clicking it in Finder. The setup is a wizard-style application that takes you step by step through the Squish set up process.

  • The first page is the welcome page. Read through it and press Next to get to the next page.

  • On the second page you must enter your Squish license key. You can find the license key in your download account in a file called squish-3-license.

    If you already have a previous Squish installation on your computer, the license key used previously will be shown in the input field. If the license key is blank, or if you have a new license key (for example, the old one was for an evaluation version and you've now bought a license), enter the license key here exactly as it appears in the license key file, including any dashes.

    Click the Next button. If there are any problems with the license (for example, if it has expired or is malformed), then a message box will be shown, explaining the problem.

  • The next page is the license agreement. Please read carefully through the license text and choose Accept if you accept the terms of license. You can only proceed to the next step of the installation if you accept the terms of the license.

  • Test scripts in Squish are written in standard scripting languages such as JavaScript, Python, Perl, Ruby, and Tcl. On the next page of the wizard, you can choose your preferred scripting language. This setting does not stop you from using any scripting language that Squish supports—it merely makes the language you set here the pre-selected default language for when you create new test suites.

  • Next, a summary of your selections is presented for you to review. If you are satisfied with your choices, click Next, and Squish will save your settings to disk. (Otherwise, click Back as often as necessary to reach the page that has the setting you want to change, and make your change—then keep clicking Next to get back to the summary page.)

  • Now that the settings have been saved you can choose whether the setup program should start Squish and open the documentation before it finishes. Press the Finish button to complete the set up process. (You can always run setup again if you need to change something at a later date.)

Now, Squish is installed, set up, and ready for command line use. To add the IDE, you will need to install a separate package, see Standalone Installation of the IDE (Section 3.2).

[Note]Squish Doesn't Change Your System

Apart from the two exceptions noted below, Squish's setup program does not copy or install any files anywhere on your system—all of Squish's files are kept in the directory where you unpacked Squish. Squish does not touch the Windows registry and does not install anything in system directories such as C:\Windows or /usr/bin.

The only things that the setup program touches outside of the directory where you unpacked Squish are the license file, $HOME/.squish-3-license on Unix-like systems or %HOMEPATH%\.squish-3-license on Windows, which contains your license key, and the directory, $HOME/.squish on Unix-like systems or %APPDATA%\froglogic on Windows, which is used to store various user-specific settings. Both the directory used to store the license key and the directory used to store the user settings can be changed by setting appropriate environment variables—SQUISH_LICENSEKEY_DIR and SQUISH_USER_SETTINGS_DIR—see Environment Variables (Section 19.5) for details.

3.1.6. Installation for Web Testing using browsers on mobile devices

This section assumes Squish for Web 5.0 or later is installed on a desktop operating system. (see Installing the Command Line Tools, Server, and IDEs (Section 3.1))

[Note]Note
Examples contain system prompt symbols which may vary, and using Windows, the commands do not include the leading ./

3.1.6.1. Configure Squish to use Standalone Proxy Server

Configure Squish to a use standalone proxy server listening on a specific port by executing the following command from your Squish install directory (where 8001 represents the port):

$ ./bin/squishserver --config setProxyConnectAddress localhost:8001

3.1.6.2. Configure HTTP Proxy

Start an HTTP-Proxy server (using a different port number than the standalone proxy server) by executing the following command in the console (where 8001 is the Squish proxy server port, 8044 is the HTTP-proxy server port, and pc_name_or_ip contains the actual computer name or IP address):

[Note]Mac users
Confirm Python 2.6 or greater installed before proceeding
$ ./bin/webproxy/proxy -H pc_name_or_ip -p 8044 localhost 8001

3.1.6.3. Configure Device Proxy Connection

Connect your mobile device or tablet to the same network as your computer, and configure the device to use the computer's proxy server as follows:

3.1.6.3.1. Android Device
  1. From Settings, tap Wi-Fi

  2. Tap and hold the currently active wireless network connection, and select Modify network

  3. Tap the Show advanced options check box

  4. Click the Proxy box and select Manual

  5. Enter the computer's IP address or name in the Proxy hostname box

  6. Enter the computers's HTTP-proxy server port in the Proxy port box

  7. Tap Save

3.1.6.3.2. iOS Device
  1. From Settings, tap Wi-Fi

  2. Tap the Information button (i) for the currently active wireless network connection

  3. Tap Manual in the HTTP PROXY section

  4. Enter the computer's IP address or name in the Server box

  5. Enter the computer's HTTP-proxy server port in the Port box

  6. Tap <Wi-Fi

3.1.6.3.3. Test Device Connection

To test the connection, open a browser on the device and navigate to http://<anyURL>/startsquish/. The browser page loads: “Squish/Web Automated GuiTesting Waiting for start of next testcase...

3.1.6.1. Configure Squish for Web IDE

From the computer, open the Squish (for Web) IDE, select Edit|Server Settings|Browser, and choose the Browser on Mobile Device option.

This completes the device-specific setup for Squish for Web! You can now record and playback tests using the Squish IDE on the computer just as you can with standard web testing; only now when recording, the actions all take place on the device—and, of course, the playback also takes place on the device.

At the time of publication, testing Browsers on devices had some limitations compared with web testing on desktops. The most significant known limitations are:

  • No support for testing native dialogs; this includes file upload fields.

  • Cannot use one proxy for multiple parallel test executions/recordings.

  • Does not work with popup blockers when using a manually-started browser/proxy; popup blockers need to be disabled in the browser prior to testing.

  • Cannot use Screenshot Verification points with remote browsers (iphone/ipad browser testing), this is due to the screenshot code being purely C++ code in the webhook.

  • Complex Touch/Gesture events are currently not recognized/recorded/replayable with Safari on iOS. Simple tap interactions do work.

  • The HTTPS protocol is not supported.

  • Windows: Sometimes picking only works on the complete browser window and buttons; this can be fixed by renaming SQUISHDIR\bin\winhook.dll.

  • Browser shows a "session not correctly ended" dialog. This is due to the way we exit the browser; usually the browser has a setting to avoid the dialog.

  • Browser shows a progress indicator all the time. This is due to the way the internal communication with Squish/Web and the proxy works.

3.1.7. Installation for Web Testing using Opera® up to version 12

The Opera browser in versions up to 12 uses its own configuration settings for proxy servers. This makes it necessary to configure it to use the Squish for Web proxy manually, so Squish is able to automate Websites running in Opera.

Configuring the proxy can be done in the settings of Opera, they can be opened from the Menu by selecting the "Settings" entry and then in the submenu again selecting "Settings". In the dialog that appears the tab labelled "Advanced" needs to be selected to allow accessing the network configuration. The list on the left side of the tabs content has a corresponding entry called "Network" which needs to be selected. Click the button "Proxy servers" in the dialog to configure the proxy servers that Opera uses. In the newly opened dialog make sure the radio button "Use manual proxyserver configuration" is selected and check the checkbox next the "HTTP" entry. The fields "proxyserver" and "port" need to be filled with the values "localhost" and "8000" respectively. In addition the checkbox "Use the proxy for local servers" further down should be activated to make it possible to test the addressbook application that ships with Squish.

In addition to configuring the proxy, the Crash Recovery dialog in Opera should be disabled. Since the dialog cannot be automated with Squish for Web it would otherwise cause test execution abortion as it appears on each start of Opera after Squish has exited the browser. This setting needs to be changed in Operas configuration editor, which can be opened by putting "about:config" into the location bar. The page that is being opened allows to search for specific settings. Use "Problem" as keyword for the search so it will reveal the configuration entry for enabling and disabling the dialog. The title of the setting is "Show Problem Dialog" and the configuration entry needs to be disabled by unchecking the checkbox next to the text.

This completes the steps needed to setup Opera for testing with Squish, you can now select the Opera executable as a browser in the IDE and record and replay tests with it.

[Note]Note
Opera versions newer than 12 are currently not supported by Squish for Web

3.1.8. Installation for Flex applets in web pages

In order to automate Flex applets running in a web browser, the “Adobe Flash Debug Player” must be installed. You can find out which version of Flash Player (if any) you're currently running by visiting the Flash Player version page. Make sure to visit this page using the browser which you will be using for recording and running Squish tests - so if Google Chrome is your default browser but Microsoft Internet Explorer is the one used for executing tests, make sure to use Microsoft Internet Explorer for visiting the Flash Player version page.

Start the player check by clicking the Check Now button on the web page. The Your Flash Version field should say (debug version). If this is not the case, please uninstall the player following the instructions given on the Uninstall Flash Player (Windows) or Uninstall Flash Player (Mac) pages.

The debug players can be downloaded from the Adobe Flash Player Support Center - do not use the Get the latest version link at the top of the page but rather use the links further down the page:

[Note]Internet Explorer on Windows 8 and newer

Windows 8 and later include the Flash Player for Internet Explorer as an integral part of the system and it is currently not possible to remove that or replace it with the debug version of the Flash Player from Adobe. Even though the download page at Adobe provides downloads for Windows 8 we have not seen any success in trying to use them. So in case you are using Windows 8 or later you'll have to use either Firefox of Google Chrome to test Flex applications with Squish.

  • Windows Flash Player ActiveX control content debugger” if you use Microsoft Internet Explorer on Windows 7 or older.

  • Flash Player for Windows 8” if you use Microsoft Internet Explorer on Windows 8; make sure to use the “x86” package for 32bit Windows and “x64” for 64bit Windows.

  • Flash Player for Windows 8.1” if you use Microsoft Internet Explorer on Windows 8.1; make sure to use the “x86” package for 32bit Windows and “x64” for 64bit Windows.

  • Windows Flash Player Plugin content debugger” if you use Firefox/Mozilla or Google Chrome on Windows.

  • Macintosh Flash Player Plugin content debugger” if you use a browser on Mac OS X.

  • Linux Flash Player Plugin content debugger” if you use a browser on Linux.

[Note]Google Chrome-specific Setup

Google Chrome has a built-in Flash plugin which needs to be disabled so that the debug player is used instead. To do so, perform these steps after installing the debug player mentioned above:

  1. Start Google Chrome from the Squish IDE using the Launch AUT button. This is important as starting Google Chrome from Squish uses a separate directory for storing all kinds of user data and part of this data is the enablement of the Flex plugin and which of the Flex plugins is used.

  2. Enter about:plugins into the location bar of the newly opened Google Chrome window to open the plugin configuration.

  3. Click the [+] Details link at the right hand side of the Plug-ins section to see the details for all installed plugins.

  4. Locate the Flash part in the Plug-ins section. There should be at least two plugins listed - the builtin plugin and the one which was just downloaded and installed.

  5. The newly installed debug player can be identified by considering the file name of the plugin shown in the Location: field - use the following table to tell whether a plugin is the built-in Flash player or the recently installed debug player (the "system player"):

    PlatformBuilt-in Flash Player filenameSystem Flash Player plugin filename
    Windowspepflashplayer.dllFilename starts with NPSWF32
    Mac OS XFlash Player Plug-in for Chrome.pluginFlash Player.plugin
    Linuxlibpepflashplayer.solibflashplayer.so

    Make sure that the built-in player(s) are disabled by clicking the Disable link and enable the system plugin by clicking Enable if needed - you may find that it's enabled already.

  6. Close the Plugins tab and any other open tabs to shut down the browser.

The builtin Flash player is now disabled, and Google Chrome will use the downloaded debug player.

After installing the correct player, please visit the Flash Player version page to verify that you're now running Flash Player and that the Your Flash Version field says (debug version).

3.1.9. Installing Squish for Android

Squish can be used to test software for Android that meets the following prerequisites:

  1. The application must provide a user interface.
  2. From the application, a test package has to be made and installed.

For the second prerequisite, a JavaJDK, version 7 or higher, and optionally the Android SDK has to be installed.

With the prerequisites in place, Squish can be used to test the application, either using an Android emulator or using an Android device connected to the machine running Squish via USB.

[Note]Note
When testing on a real device using USB on MS Windows, a special USB driver (for development/debugging purposes) from the vendor of the specific Android device/model must be installed (see OEM USB Drivers, the fact that an Android device shows up as a usable device in the operating system is usually not sufficient).

[Note]Note
Linux users testing on a real device using USB should make sure the access permissions to the device are configured properly (see Using Hardware Devices).

3.1.9.1. Make the Android app testable

Squish can record and replay test scripts for your application when there is a package containing the SquishHook instrumentation that has the target set to your application's package name.

3.1.9.1.1. Using a separate test package

This is the method used by the Squish IDE. The IDE will build a test apk, resign your apk and finally install both. Either when choosing a new package in the test suite settings page or “Manage Android AUTs” in the “Server Settings”.

For command-line users, to create a test package, resign yours and install, run

apk-tool -a <path-to-android-sdk> -j <jdk> -pkg <your-apk> -o <temp-dir> -d <device>

where apk-tool is a script found in the Squish' bin directory, jdk the full path to a JavaJDK, version 7 or higher, and temp-dir some directory where apk-tool writes some temporary files.

The -a option may be omitted. Squish has the required tools packed. Use it when your app uses more up-to-date resources from the Android SDK.

The -j option may be omitted when both java and jarsigner are in your path.

You can pass multiple -d device pairs to the apk-tool.

[Note]Note
The by apk-tool installed packages may conflict with a previous installed package due to resigning. Either uninstall it manually first or edit the apk-tool script Settings for Signing field to match the keystore and credential your apk is using.
3.1.9.1.2. Using a built-in SquishHook

This is an alternative method to get a testable application. Instead of creating a test apk, the squish hook can be build-in too. This may be a faster compile/test cycle in some work loads.

We take as example AddressBook, which you can find in the android directory under examples.

This project was created as

$ android-sdk/tools/android create project --target android-8 \
    --name AddressBook --path AddressBook \
    --activity AddressBook --package com.froglogic.addressbook

To compile this application yourself, first create a local.properties file containing

sdk.dir=path-to-your-android-sdk

[Note]Note
When on MS Windows, either use forward slashes or use double backslashes for the path.

Next, create a project.properties file containing

target=android-8

[Note]Note
Look in your Android SDK directory for the possible targets. The targets are the subdirectories under android-sdk/targets/. Here we use target android-8.

Then create a libs subdirectory and copy the file squishandroid.jar in there.

Edit the AndroidManifest.xml file to enable Squish instrumentation.

Edit the AndroidManifest.xml file to add android.permission.INTERNET permission.

[Note]Note
The above two steps have been done for the AddressBook application already

To build the application, execute

$ ant debug

Start the device or emulator, and once it is ready, install the application by executing

$ android-sdk/platform-tools/adb install -r bin/AddressBook-debug.apk

Naturally, you must replace android-sdk with the full path to your Android SDK installation.

For more information of starting the application in a test script, see Notes on using startApplication with Android (Section 17.12.2)

You can check to see if Squish can see multiple devices and emulators by executing:

squishrunner --info androidDevices
To see all applications that Squish can used, run
squishrunner --info androidInstrumentation
[Note]Note
squishserver must be running to handle the --info request.