This tutorial will show you how to create, run, and modify tests for an example Java AWT/Swing application. 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. (If you want to test Java SWT applications, you might prefer to read, Tutorial: Starting to Test Java™ SWT Applications (Chapter 6).)

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 13), and at least skimming the API Reference Manual (Chapter 14) and the Tools Reference Manual (Chapter 15), 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 (or to the new IDE introduced in Squish 4), 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 13).

Whenever we show how to achieve something using the IDE we will always follow with an explanation of how to do the same thing using the command line tools. Using an 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. (Note that we use the new IDE introduced in Squish 4 throughout the tutorial. The old IDE is still packaged with Squish and so is still available; however, we recommend using the new IDE.)

The application we will test is a very simple Address Book application. Users can add new addresses via a dialog, edit addresses in-place, and remove addresses. They can also open and save address book data files. Although the application is very simple it has all the standard features that you are likely to want to use in your own tests, including menus, a table, and a pop-up dialog with line edits and buttons. Once you know how to test any of these user interface elements you will be able to apply the same principles to testing elements present in your own applications that are not used in the tutorial, such as tree views and number and date spinners. (The User Guide (Chapter 13) has more comprehensive examples that show how to test lists, tables, and trees, and also the most common widgets, including spinners.)

The screenshot shows the application in action with a user adding a new name and address.

The Java AWT/Swing addressbook example.

The application (i.e., the AUT—Application Under Test) can be found with Squish's examples in squish/examples/java/addressbook/AddressBook.java. The tests that we will discuss in the following sections are in sub-folders, for example, the versions of the tests using the Python language are in squish/examples/java/addressbook/suite_py, with the tests written in other languages in similarly names sub-folders.

In principle, testing Java AWT/Swing and Java SWT applications works the same, so all the practices described in this tutorial can be applied to either. The only significant differences are that both of these toolkits use their own distinct set of widgets with different APIs (Application Programming Interfaces), and so our tests must of course access the toolkit-specific widgets and use the toolkit-specific APIs when we want to interact with them—for example, when checking that a particular widget's property holds a particular value.

Using the Examples

The first time you try running a test for one of the example AUTs you might get a fatal error that begins “Squish couldn't find the AUT to start...”. If this occurs, click the Test Suite Settings toolbar button, and in the Application Under Test (AUT) section choose the AUT from the combobox if it is available, or click the Browse... button and choose the .class file that has the AUT's static main function via the file open dialog that pops up. This only needs to be done once per example AUT. (This doesn't arise when testing your own AUTs.)

	Mac OS X-specific
	For Squish to operate correctly on Mac OS X when testing Java AWT/Swing AUTs the environment variable SQUISH_USE_AWT must be set to 1. This can be done as follows: export SQUISH_USE_AWT=1 open SQUISHDIR/squishide.app It is probably most convenient to set the environment variable in your login shell script or to create a shell script that sets the variable just before running Squish.

In the following sections we will create a test suite and then create some tests, but first we will very briefly review some key Squish concepts.