This is a step-by-step guide to testing a GUI with texttest. It assumes you have read and followed the instructions in the installation guide. There is a fair amount of overlap with the document for getting started testing a non-GUI program, so it can be helpful to read that first.

We will use a simple PyGTK 'video store' program as an example – which comes with the download of PyUseCase. Most of what is said here should apply to any use case recorder, though. Text in italics is background information only.

The first step is to get your program using the use case recorder of your choice, at least enough to be able to create some simple scripts. If you have a PyGTK GUI, use PyUseCase. If you have a Java Swing GUI, use JUseCase. If you use another GUI toolkit – write your own use case recorder and tell me about it!

First, create a directory and a config file as described in the guide for testing “hello world”.

For testing GUIs, you need some further entries in the config file. In particular, you should add the line 'use_case_record_mode:GUI'. If you are using JUseCase, you also need to set 'use_case_recorder:jusecase'. This is because JUseCase uses Java Properties files rather than environment variables for its interface, so TextTest needs to know to generate these rather than set environment variables.

First, we create an “empty test” as for “hello world”.

However, command line options are not sufficient to define a GUI test. We also need to define the use case that will be performed with the GUI. To do this, we go to the “Recording” tab at the bottom right and then click the “Record Use-Case” button. This will start an instance of the dynamic GUI, as with running tests. This in turn fires up our Video Store GUI in record mode. We simply perform the actions that constitute the use case, and then close this GUI.

The dynamic GUI will then turn the test red and highlight that it has collected new files for us. By clicking this red-line in the test view we get the view below. The contents of the new files can be seen in textual format in the “Text Info” window, or viewed by double-clicking them if they are too large.

If we made a mistake recording, we should simply quit the dynamic GUI at this point and repeat the procedure. If we are happy with the recording we should save the results: press the save button with the test selected.

Unless we disabled this from the “Record” dialog at the start, TextTest will then automatically restart it in replay mode, in order to collect the output files. This operation is done invisibly as it is assumed to always work – but (for example) PyUseCase produces different text when replaying than when recording, and it is that text we are interested in. It can be configured to also happen via the dynamic GUI – this is useful if you don't trust your recorder to replay what it has just recorded! Messages in the status bar at the very bottom of the static GUI keep you posted as to progress, anyway. When all is done, it should look like this:

Note that the definition file is now the usecase file recorded by PyUseCase. Naturally there could be command line options as well if desired. This is much the same as the final result of the “hello world” set up.

Clearly, there is no need to run it once in order to collect the output as we did with “hello world”: this is built into the “Record use-case” operation. Currently, if we run the test, the GUI will pop up and the actions will be performed as fast as possible.

On UNIX, we can prevent the target GUIs popping up by default, using the virtual display server Xvfb (a standard UNIX tool). We simply set the config file entry “virtual_display_machine:<machine_name>” where <machine_name> is some machine where we would like to run Xvfb. TextTest will then start an Xvfb server on that machine and use it as the DISPLAY variable for each test GUI, by default. It will also restart the server automatically if it becomes unusable.

The display number to be used for the Xvfb server is determined by the config file entry “virtual_display_number”. For no good reason this defaults to 42.

On Windows, target GUIs are hidden automatically without the need to configure. However, note that this operation is not recursive, so any dialogs, extra windows etc. that get started will (unfortunately) appear.

We might want to examine the behaviour of the GUI for a test. To do this, we set a default speed in the config file, using the config file setting 'slow_motion_replay_speed:<delay>', where <delay> is the number of seconds we want it to pause between each GUI action. For a particular run, we then select “slow motion replay mode”, from the “how to run” tab in the static GUI. This will force the GUI to pop up for this run, whatever is set in the virtual_display_machine entry.

In summary, our config file should look something like this: