Learn how to test applications running in Remote Displays.
Table of Contents
This tutorial will show you how to create, run, and modify tests for a remote display, such as VNC. In the process you will learn about Squish's most frequently used features so that by the end of the tutorial you will be able to start writing your own tests for your own applications.
This chapter presents most of the major concepts behind Squish and provides the information you need to get started using Squish for testing your own applications. This tutorial does not discuss all of Squish's features, and those that it does cover are not covered in full detail. After reading this tutorial we recommend reading the User Guide (Chapter 5), and at least skimming the API Reference Manual (Chapter 6) and the Tools Reference Manual (Chapter 7), so that you are familiar with all the features that Squish has to offer, even if you don't need to use them all straight away.
This tutorial is divided into several sections. If you are new to Squish, it is best to read all of them. If you are already using Squish you might want to just skim the tutorial, stopping only to read those sections that cover any new features that you haven't used before—or you could just skip straight to the User Guide (Chapter 5).
Squish comes with an IDE and command line tools. Using the IDE is the easiest and best way to start, but once you build up lots of tests you will want to automate them, (e.g., doing nightly runs of your regression test suite), so it is worth knowing how to use the command line tools since they can be run from batch files or shell scripts.
Squish for VNC can be used in 2 ways:
Using the VNC protocol, where only the VNC server must be installed and running on the Tested System.
Natively, where Squish for VNC must be installed and running on the Test Driver and also the Tested System.
In both cases, Squish runs a small server (squishserver) that handles the communication between a Virtual AUT and the test script. We say the AUT is virtual because it actually represents an open network connection, either VNC or "Native", between the squishserver and the remote display. When the connection is terminated, we say the AUT is not running.
The test script is executed by the squishrunner tool, which in turn connects to the squishserver. The squishserver starts the Virtual AUT, or establishes a remote display connection, and injects the Squish hook into it. The hook is a small library that makes the Virtual AUT accessible and that can communicate with the squishserver. With the hook in place, the squishserver can automate the remote display, and can execute commands—all on behalf of the squishrunner. The squishrunner itself requests that the Virtual AUT performs whatever actions the test script specifies.
The following diagrams illustrate the two ways that the individual Squish tools work together. The first shows the most common use-case, where Squish is used to automate displays that have a running VNC server. In this case, it is not necessary to install/configure any of Squish for VNC on the Tested system.
Using Squish for VNC with the VNC Protocol
The second diagram shows the squishserver installed and configured on the Tested system. Instead of VNC, tests can use Squish's own Native proprietary remote protocol which allows a similar remote control and display.
Using Squish for VNC with the Native protocol
![[Note]](images/note.png) | The Squish Directory |
|---|---|
Throughout the manual, we often refer to the |
A test suite is a collection of one or more test cases (tests). Using a test suite is convenient since it makes it easy to share tests scripts and test data between tests.
To begin with start up the Squish IDE, either by clicking or double-clicking the squishide icon, or by launching squishide from the taskbar menu or by executing squishide on the command line—whichever you prefer and that is suitable for the platform you are using. Once Squish starts up you might be greeted with a Welcome Page in case you're starting the squishide for the first time. Click the Workbench button in the upper right to dismiss it. Then, the squishide will look similar to the screenshot—but probably slightly different depending on the windowing system, colors, fonts, and theme that you use, and so on.
Once Squish has started click | to pop-up the New Squish Test Suite wizard (Section 8.3.13) shown below.
Enter a name for your test suite and choose the folder where you want
the test suite to be stored. In the screenshot we have called the test
suite suite_py and will put it inside the
addressbook folder. (For your own tests you might
use a more meaningful name such as "suite_addressbook"; we chose
"suite_py" because for the sake of the tutorial we will create several
suites, one for each scripting language that Squish supports.)
Naturally, you can choose whatever name and folder you prefer. Once the
details are complete, click to go on to the
Toolkit (or Scripting Language) page.
On this wizard page, we choose the Squish Edition we are using. For this example, we select VNC since we are automating a remote desktop. Then click to go to the Scripting Language page.
Choose whichever scripting language you want—the only constraint is that you can only use one scripting language per test suite. (So if you want to use multiple scripting languages, just create multiple test suites, one for each scripting language you want to use.) The functionality offered by Squish is the same for all languages. Having chosen a scripting language, click once more to get to the wizard's last page.
If VNC is the desired protocol, select from the Protocol drop down menu. From here you can configure how Squish connects to a remote target.
In this form you can enter the needed settings for your specific VNC server.
Enter the hostname of the machine running the VNC server.
If your VNC server uses a custom port, enter it, otherwise Squish will use the default port (5900) for VNC.
Squish for VNC supports basic authentication, so if your VNC server is only accessible with a valid username password combination, enter it here.
To avoid hardcoding passwords in the test cases, Squish offers a separate GUI for entering passwords, and a separate file for storing them. The Password: drop-down is initially empty. You can add entries to the dropdown by clicking on to the right of that. A Passwords dialog pops up.
Passwords can be added here, and/or later added/modified from the - Password Information (Section 8.2.16.6) tab.
If, in the Connection settings, the Protocol chosen is Native, this means that instead of VNC, we use Squish's Remote Control protocol between squishrunner and squishserver, and squishserver must be installed and running on the Tested System.
First, follow these steps on the Tested System:
Install Squish for VNC
Edit
SQUISHDIR/etc/squishserverrcand include Test Driver IP address for ALLOWED HOSTS. See Distributed Tests (Section 7.1.2) for details.Start squishserver from the command line (use the default port or pick one).
Next, on the Test Driver system, from the Squish IDE go to Preferences|Squish|Remote Testing and enter the IP address (and port, if you specified one when you started squishserver) of the Tested System.
After the New Test Suite wizard is finished, the connection parameters can later be configured from the Test Suite Settings - Connection Information (Section 8.2.16.3) tab.
This configuration is what is used whenever the Virtual AUT needs to be started, which is whenever you record or play a test, or explicitly select |.
We are now ready to start creating tests.
Squish records tests using the scripting language that was specified
for the test suite. Once a
test has been recorded, we can (
) and
Squish will faithfully repeat all the actions that we inserted or recorded,
but without all the pauses that humans are prone to
but which computers don't need. It is also possible—and very
common—to edit recorded tests, or to copy parts of recorded tests
into manually created tests, as we will see later on in the tutorial.
Recordings are made into existing test cases. We begin by
creating a New Script Test Case.
There are two ways we can do this. One way
is to click |. This will pop up the New Squish Test Case wizard (Section 8.3.10)—simply enter the name
for the test case and then click . Another
way is to click the (
) button (to
the right of the Test Cases label in the
Test Suites view); this will create a new test
case with a default name (which you can easily change). Use one of these
methods and give the new test case the name “tst_general”.
Squish automatically creates a sub-folder inside the test suite's
folder with this name and also a test file, for example
test.py. (If we had chosen JavaScript as our
scripting language the file would be called
test.js, and correspondingly for Perl, Ruby, or Tcl.)
| Note |
|---|---|
If you get a sample |
To make the test script file (e.g., test.py) appear
in an Editor view (Section 8.2.6), click—or double-click
depending on the ||
setting—the test case.
(Incidentally, the checkboxes are used to control which test cases are
run when the (
) toolbar button is clicked; we can always run
a single test case by clicking its () button.) Initially, the
script contains a hello-world main script.
The name "main" is special to
Squish—tests may contain as many functions and other code as we
like (providing it is legal for the scripting language), but when the
test is executed (i.e., run), Squish always executes the
main function. This is actually very convenient since it
means we are free to create other functions, import libraries, and so
on, without problems. It is also possible to share commonly used code
between test scripts—this is covered in the User Guide (Chapter 5). (In fact, two other function names are special
to Squish, cleanup and init; see Tester-Created Special Functions (Section 6.1) for details.)
Once the new test case has been created, we are now free to write test code manually, or to record a test. If we choose to record we can either replace all the test's code with the recorded code, or insert recorded code into the middle of some existing test code. We will show how to record snippets later in the tutorial.
We are now ready to record our first test. Click the (
) toolbar button
to the right of the tst_general test case shown in the Test Suites view (Section 8.2.19)'s Test Cases list. This will cause
Squish to connect to the squishserver, hide the Squish IDE, open the
Control Bar, and also the
Squish Remote Control
window which displays the screen of the target display.
This window will be your way to
interact with the remote server.
The Remote Control window of Squish for VNC
The Squish Control Bar
Recording Mouse Clicks
The Squish Remote Control window is able to record key
presses directly but not mouse clicks, although the remote display
will still react to your mouse. To insert mouse clicks, use the
Insert
(
)
drop-down button, (one exists on the Control Bar, and
also on the Squish Remote Control window)
combined with
or , to pick the location
of the desired click.
This helps avoid the need for recording mouse clicks with desktop coordinates.
Please see How to Do Image-Based Testing (Section 5.24) for more information.
Inserting Verifications
From the Control Bar, or from the Squish Remote Control window, you can click to drop-down a menu. From here, you can verify or . For more information about OCR search and verification, see OCR setup (Section 5.24.1).
After you are done with recording, press
(
)
to save it as a script.
If the recorded test doesn't appear, click (or double-click depending on
your platform and settings) the tst_general test
case; this will make Squish show the test's
test.py file in an editor window as shown in the
screenshot.
Now that we've recorded the test we can try to play it back, i.e., run it. This in itself is useful in that if the play back failed it might mean that we forgot to insert a mouse-click somewhere. Furthermore, every verification we inserted will be checked.
While replaying a test, the Squish Remote Control window
can be hidden/shown with the button
(
) in the
Control Bar.
One important thing to note is that opening and closing the
Squish Remote Control
window is not synonymous with starting and stopping the Virtual AUT.
To actually close the Virtual AUT's VNC or Native connection, use the
button
(
).
When Image Search Fails
With Image Search, playback may fail due to a single different pixel in the expected versus actual image. For example, there could be differences due to changes in hardware, color profile, brightness of surroundings (in the case where a device has a light sensor), time of day (for example Day Mode vs Night Mode), lossy compression, or sub-pixel antialiasing rendering. Or maybe the image is different and needs to be acquired again.
Image Not Found dialog
If this happens, the Image Not Found dialog (Section 8.3.4) pops up. At this point, there are lots of things you can do.
If the expected image is out of date, you can Update the image from the current desktop.
If you want to relax the image search parameters for that particular statement, you can click .
If you want to apply a default tolerant image search for your test suite based on how closely the current actual matches the expected, click followed by Change Defaults.
Default tolerance levels for the test suite can later be seen/set from - Image Search (Section 8.2.16.5) tab.
Recording Snippets
After playback is finished, the Virtual AUT terminates. The Squish Remote Control window is tinted red and not responding to events, or invisible. By selecting |, the VNC or Native connection is re-established and the Squish Remote Control window responds to the mouse and keyboard, and can be used as a terminal for your remote display.
The Squish IDE is now in Spy perspective, neither recording nor
playing back a test case.
At this point, you can click to focus the cursor anywhere in your test script,
and then () a snippet to be inserted at that location.
Click
()
to see the snippet inserted into your test script.