Documentation for 3.13
Understanding TextTest Test Suites
A Guide to the Files and
To avoid confusion, here is a quick list of definitions:
- System Under Test (SUT)
– The program that you wish to test. Assumed to be
available as an executable file.
- Test Application (or just
Application) – A set of TextTest files corresponding
to testing a particular SUT.
- Test Case –
defines a particular way to run the SUT, and the textual output
to be expected.
- Test Suite – a group of Test Cases or
(recursively) Test Suites which are in some way related.
This is the first thing determined by TextTest on being
called, and is where in your file system it will start to look
for tests. All test files are placed in subdirectories of this
directory. It is determined as follows:
- If the command line option
"-d" has been set, use the value of that.
- If not, but the environment
variable "TEXTTEST_HOME" is set, use that.
- If neither of the above, use the current working
normal usage, you should set TEXTTEST_HOME to an appropriate
value. It is always set internally by TextTest, however its
value is initially determined, so its value may be used in the
configuration files that are described below.
To test a system with TextTest, the first thing to do is to
choose a unique identifier to be used as an extension for all
files relevant to that application. It does not matter what this
is. For the next few paragraphs this variable is indicated by
<app>. On Windows, you will probably want to associate
this extension with a text editor like notepad or wordpad. The
use of file extensions for this purpose is historical: TextTest
grew up on UNIX where file extensions do not have the meaning
that they do on Windows.
Basic information about an application and how to run it
appears in a file called config.<app>,
generally referred to as the “config file”. TextTest
will look for files with names of this format to determine which
applications it will run. It will start looking at the root
directory and look in that directory and one level down in the
directory structure: this is so that tests for related
applications can easily be grouped together in subdirectories of
the root directory. When TextTest is started, it will by default
look for and use all config files it can find. To tell it to
look for just one particular application, specify "-a
<app>" on the command line.
This file basically consists of key, value pairs, where the
keys are “properties” with names predefined by
TextTest. The most important of these is the entry "executable" (formerly known as "binary"),
which defines the path to the SUT and without which nothing much
will happen. This should be an absolute path, although
environment variables may be included. It can also be the name of a Java
class that will be found on the Java class path, provided you
set “interpreter” to “java” (below).
The entry “interpreter” allows you to specify a
program to use as interpreter for the SUT, in the case that it
is a script rather than a binary. To some extent TextTest will
try to infer this from the file extension (e.g. set it to
“python” if the file ends in “.py”,
“java” if it ends in “.jar”), but it is
sometimes necessary to specify it explicitly.
The file itself has a specific format, called Standard
. It is worth familiarising yourself with
this, and often the best way is to look at the many examples in
TextTest's tests for itself (that come with the download).
It is also possible to have a personalised config file which
accepts all the same settings as the normal config file, and
will override anything provided there. This is particularly
useful for setting things like GUI
. On UNIX, provide a file called “.texttest”
in your home directory. On Windows, put a file called
“.texttest” somewhere, and point the environment
variable TEXTTEST_PERSONAL_CONFIG at that location.
Sometimes it can be very useful to share configuration
settings between several related applications. In that case you
can use the “import_config_file” entry to identify
files of the same format whose settings should be included. The
file should be found under TEXTTEST_HOME, in the same way as
described in the above paragraph for the config files
themselves. Such a file doesn't need to have a particular name.
It can also be stored in an arbitrary location, see below for
a description of how TextTest searches for files.
A Test Suite is a recursive collection of test cases arranged
in a particular order. It is defined for a Test Application by a
directory in the file system containing a local file called
. This lists subdirectories
in the order in which they should be considered. These
subdirectories may correspond to test cases or may themselves be
test suites. The file is in Standard
. Having found a test application by finding
, will then look at
in the same directory to
determine what the full test suite consists of. It will then
look, in the order given, at all the subdirectories specified,
and where they are themselves test suites, will repeat this
process recursively until all specified test cases have been
found. Each test suite directory, apart from the top level one,
will have the same name as the test suite itself.
Note that testsuite.<app> files are
generated and edited automatically when using the static GUI to
create test cases or test suites. However, it is also useful to
view and edit them by hand: the static GUI will automatically
refresh if the elements in the test suite file are re-ordered,
and the contents of the Description fields are added as comments
to this file.
If you find that managing an explicit order of tests is too
much effort, you can set the “auto_sort_test_suites”
config file setting to “1”. The order in the
testsuite files will then be ignored and all test suites and
test cases presented in alphabetical order.
A test case is represented in TextTest by a particular
directory in the file system, and the name of the test case is
always the same as the name of the directory. Many test
applications may share the same test case if desired. To define
a test case for a test application, at least one test definition
file must be present. Definition files tell TextTest how to run
the SUT for this test case. The following files will be taken as
test definition files:
- This will be interpreted as command line options to be given
to the system under test.
- This will be redirected to the system under test as standard
- The use case recorder will be configured to replay the system
under test from this file.
The expected output files from the SUT are also stored in
this directory: these will be compared with the actual result
for each test run. By default, the standard output of the system
under test is redirected to output.<app>
while its standard error is redirected to errors.<app>
Other textual output files can also be collected, and the
collection of these can be disabled: look here
for details of how.
TextTest assumes that high-level information of interest to
it will be logged to one particular result file. This file is
indicated by the “log_file” config file entry and
defaults to “output” (i.e. the standard output of
the SUT). Many different features of TextTest will look here for
information to extract of one sort or another.
All of these files are in whatever format is expected or
produced by the SUT: TextTest does not itself look at their
By now the idea should be emerging that TextTest
follows the principle of "Convention over Configuration", and uses particular names
to indicate files for particular purposes. A TextTest test suite therefore
consists of such a hierarchical directory structure, where many such files may be
There arise many situations where TextTest has to find a particular file in this structure.
Files containing environment variable settings (described below), files containing test data
, and files containing
failure interpretation information
all need to be organised in some hierarchical way. The
basic idea is that the position a file is stored indicates which tests it should apply to, so
that a file in a test suite applies to all tests contained in that test suite.
So if TextTest needs to find a particular file, it will first look in the test, then in the
parent test suite, and recursively repeat up to the root test suite. The config file entry
"extra_search_directory" can then be used to extend this search path further to look for
additional files outside the test structure. As this is a dictionary it can be keyed on
the type of file search for, so that different search paths can be provided for different file
types. The “default” key can be specified to make the same search path apply to all files.
This setting can also apply to the "imported config files" described above, so that
they can also be stored outside the given test suite structure.
Any test suite or test case can tell TextTest to set
environment variables by providing an environment file. This is
a file called environment.<app>
(it has been found that applications
often need to share environment variables). This file is in
, with the environment variable names as keys and
their values as entries. These environment files are found and prioritised
via the mechanism described above: all such files are considered and all variables
will be set, although if the same variable is set by several files the most
specific one in the hierarchy will of course be chosen.
The values of the variables may themselves contain
environment variables: if so, this should be done UNIX-style
When a large test suite has been created, you often want to
gather information from it, or even update its contents in a
predictable way. It is very useful to be able to re-use
TextTest's ability to parse and understand the structure while
writing your own script in Python to analyse or update in terms
of the applications, test suites and test cases.
There is thus a mechanism to plug in arbitrary scripts, which
are run with “-s <module_name>.<class_name>”,
where <module_name> is some Python module and <class_name>
is the name of the script. In order to pass arguments to such
scripts, a form with <option>=<value> is used. For
example, to call the default.ReplaceText script with appropriate
arguments, you would call:
texttest.py -s “default.ReplaceText file=errors old=bad new=good”
TextTest includes several such scripts which have been found to
be generally useful, which are listed
. To see how to write your own such scripts, consult the
guide to writing your own
The above example (default.ReplaceText) is a particularly
useful way to update lots of results in a predictable way. It is
basically a search-and-replace mechanism with the advantage that
you can select tests in the normal ways and the files relevant
to the testsuite will be chosen for you. The above example will
naturally replace all instances of “bad” with “good”
in all “errors” result files.
As another example of the above plugin script mechanism, it is possible
to have several different test suites that are based on testing broadly the same
application. For example you might have one master test suite with many different
possible functionalities, where other projects want to take a part of it to
adapt. You can achieve this with the "default.ExportTests" plugin script. This is used as follows:
texttest.py <options> -s “default.ExportTests dest=/path/to/destination/suite”
The tests chosen via <options> will then be copied to an equivalent position in the destination
suite. If they existed there already they will not be updated currently.
TextTest reads two file formats - Standard List Format (for
testsuite files) and Standard Dictionary Format (for
config and environment files). These are designed
to be as human readable as possible.
Both will filter out blank lines and lines beginning with
"#", the latter being interpreted as comments. It's
good practice to use the latter feature to document things about
your application and its tests in the TextTest files themselves.
Both will also expand environment variables, indicated by
Standard List Format is simple: each entry is a complete
line. So a Standard List File is simply interpreted as an
ordered list of the lines in it which are not blank and do not
start with "#".
Standard Dictionary Format has entries in the form
<key>:<value>, where <key> indicates an
environment variable to be set to <value> in the case of
the environment file, and a variable understood by
TextTest in the case of the config file.
In the case of the config file, it can be useful to
have the value be a list itself. This is achieved by adding
several entries for the same <key>. So if we want to set
the key “my_key” to a list containing A and B,, this
is done by
Providing the entry
allows overriding files to remove entries added in a parent
It can also be useful to have the value be a dictionary. This
is achieved by the "section header" format,
Entries within section headers can also use the list format
In a few cases the value is essentially a dictionary, but
with two keys (a “composite dictionary entry”). This
is used for the batch mode and performance-related settings. The
format does not look very different to the above, but because
anything can appear in the dictionary rather than predefined key
names, it is necessary to have a mechanism to share values. This
is achieved by the special predefined key name “default”.
Here a lookup of first_key in my_composite_dictionary will
produce “first_value”. A lookup of “second_key”
(or anything else) will produce “default_value”.
If you only wish to override the default value of such a
dictionary, it is acceptable to use the format for
non-dictionary entries, i.e. simply
The TextTest download includes a test suite for itself. It is
recommended that you look around this (or any other example you
can find) to get an idea of how it works. There is also a quick
guide document included to help you find the simple “target
application” test suites which are used for testing
itself. These are simple in order to provide minimal tests, so
function as demonstration examples also.
When writing your own tests it is often best to start with
working files for another application and edit them suitably.
This reduces the risk of typing things wrongly, particularly in
the config file.