Documentation for 3.9.1
Testing a GUI with TextTest and a Use Case Recorder
This is a step-by-step guide to testing a GUI with texttest.
It assumes you have read and followed the instructions in the
. 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
of your choice, at least enough to be able to
create some simple scripts. If you have a PyGTK GUI, use
. 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
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
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
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”
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
<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
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
In summary, our config file should look something like this: