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:

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.

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 from Source Packages (Section 3.1.2).

	Clean Installation
	When you unpack a Squish tool binary package, the files are uncompressed into the directory you specify—and nowhere else. Squish does not touch the Windows registry or interfere with any system files or directories—for example, Squish doesn't put any files in C:\Windows or /usr/bin. This also makes it easy to delete a Squish package should the need arise.

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>

The easiest way to configure a Squish 4.1 or later binary package it is to simply run the New 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 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.

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

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

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

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.

	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.

In order to be able to test Qt applications, you need to tell Squish where to find the Qt library used by the applications you intend to test. You can either enter the full path to the file into the input field, or click the button labeled Browse at the right of the input field. Clicking this will open a convenient file selection dialog, which lets you browse your files and select the library. 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.

	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—or if you are testing Web applications on Windows or Mac OS X—this configuration page will not appear, in which case you can safely skip to the next section and continue from there.

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 used (e.g., Internet Explorer® or Safari®), so this configuration page does 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.

	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 will not appear.

Select your preferred web browser, then 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.

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

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

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

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

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, 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.1.1) for details.)

3.1.1.2.7. Configuration Review

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

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.

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

[D]

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

This Quick Install section describes how to perform a standard build and installation of Squish. It covers the most common cases and is the easiest way to install Squish apart from simply installing a binary package.

Requirements

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

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

	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.

If you want to use Python, Perl, or Tcl for your test scripts, see the following tables regarding what you need to install and where to get it for your platform and scripting language.

If you want to use Squish to test Qt 3.x applications, see Installation for Testing Qt 3.x Applications (Section 3.1.2.3). If you want to test Qt/Embedded 2.3 applications, see Installation for testing Qt/Embedded 2.3 applications (Section 3.1.2.4). 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.2.5).

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.6) and Installation for testing with a static Qt library (Section 3.1.2.7)).

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.1.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, and Windows 7), with Microsoft® VC++ 6 through 10, and with Intel C++ 7. For Unix-like systems, Squish has been tested on all modern versions of Mac OS X with gcc; 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 8 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.

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:

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

	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.

Now run the configuration script:

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

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

Building Squish can take quite a bit of time, since as part of the process the build tool also creates wrappers for the Qt library. As the build process progresses you will probably see a lot of warnings from the squishidl (Section 16.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:

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

configure --disable-examples
build

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

configure "CXXOPT=-O1"

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

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

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

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

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

Using Qt 4 Debug Libraries

If you build your application using the Qt 4 debug libraries then you will need to use those same libraries when building Squish. If you want to be able to test both release and debug versions of your application you will need two versions of Squish: one built against the normal Qt 4 libraries, and the other built against the Qt 4 debug libraries, so you will need to do two separate builds. For example, on Windows for the normal Qt 4 libraries, you might use directories: C:\Squish-Qt4 C:\Squish-Qt4-and-Qt3 C:\Qt\4.7.1 C:\Qt\Qt4-and-Qt3 And for the Qt 4 debug libraries, you might use directories: C:\Squish-Qt4-debug C:\Squish-Qt4-and-Qt3-debug C:\Qt\4.7.1-debug C:\Qt\Qt4-and-Qt3-debug Those using Unix-like systems and 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).

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

Step 2 of 6

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

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

Step 3 of 6

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

Step 4 of 6

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

Step 5 of 6

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

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:

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

Step 6 of 6

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

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

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

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

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

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

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

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

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

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

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

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

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:

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 New IDE (assuming that you have installed it; see Installing the New 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.)

If using the Classic IDE, it can be run from the Squish tools' directory:

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

Just like the New IDE the Classic IDE should automatically start and stop a local squishserver as needed. (This behavior is controlled by the Preferences setting. To change it click Edit|Preferences. The Start squishserver locally on startup 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.

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 New IDE (assuming that you have installed it; see Installing the New IDE (Section 3.2)):

$ /usr/local/squishide/squishide

Alternatively, you could use the Classic IDE:

$ /usr/local/squish-desktop/bin/squish

If you have installed the New Squish IDE it can be run as:

$ /usr/local/squish-desktop/bin/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. The required setting is the same for both the Classic and New IDEs, but is set differently for each one.

For the New 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”.

For the Classic IDE, click Edit|Preferences. Make sure the Start squishserver locally on startup checkbox is unchecked and that the squishserver host is set to “localhost” (or to “127.0.0.1”), and that the squishserver port is set to “4322”.

(See Distributed Tests (Section 16.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 New IDE, click the Test Suite Settings toolbar button, and in the Application Under Test (AUT) section, enter “-qws” in the Arguments line editor. And for the Classic IDE, click Test Suite|Settings and enter “-qws” in the Arguments line editor.

Now you can run tests or record them, as described in the User Guide (Chapter 14). 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/
$ 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 (New IDE) or squishserver host (Classic IDE) in the Squish IDE's Remote Testing settings (New IDE) or Preferences dialog (Classic IDE).

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?

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

#if 0 // enable for cross-compilations

#if 1

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

SQUISH_DESKTOP=/path/to/squish-desktop
LD_LIBRARY_PATH=${SQUISH_DESKTOP}/lib:${LD_LIBRARY_PATH}
export LD_LIBRARY_PATH
${SQUISH_DESKTOP}/bin/squishidl "$@"

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

$ ./build

$ 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

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.

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

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

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

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

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

If you want to link the AUT against a static version of Qt, it may work—at least in some cases, and on some Unix variants— but it is not recommended. We only mention it here because some customers have had some success running Squish tests with a statically linked AUT—especially with Qt 3—but not with recording, since that isn't possible at all.

	Don't Use Static Qt Libraries
	We recommend using a dynamic (shared) Qt library for both recording and running tests. Running tests using a static Qt library might work with some versions of Qt on some Unix variants, but this is not officially supported.

For recording test cases, the application must be linked against a dynamic Qt library—recording will not work with a static Qt library. For running tests, you can try linking the application against a static Qt library. On Windows and on Mac OS X this simply won't work, so the AUT must always be linked against a shared Qt library. For some Unix variants, such as Linux and Solaris, running tests using a static library might work, for example, with Qt 3 and with early Qt 4 versions, but is much less likely to work with up to date Qt 4 libraries.

If you want to try running tests on Unix using a statically linked application, there is one important requirement. When linking the application, its symbols must be exported so that Squish can hook into the application. To do this using the gcc compiler, for example, specify -rdynamic on the link line. This switch is harmless, so you can leave it in permanently and ship the application linked this way. On some operating systems (e.g., Solaris) all the application's symbols are exported by default, so no special linker switch is necessary. In this case the configuration of the static Qt library doesn't matter at all.

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 16.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 17.3.11), 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.

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 16.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 17.3.11), 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.