There are 3 kinds of files which are expected to be hand-edited by the user. These all have slightly different formats which are documented in full here. These are config files, environment files and options files. A fourth file type, testsuite files, are auto-generated by the static GUI but are also possible to manipulate by hand and hence are also documented here.

This consists of a series of pre-defined entries which tell TextTest how to run your application and how to interpret its results. Its purpose is documented more fully here.

The full list of these entries is dependent on your configuration module, and is documented here in the form of tables for the default and queuesystem configurations, as well as the personal config file. These list what type the various entries have, which affects how they appear in the file.

Blank lines and lines beginning with '#' will be ignored, the latter being interpreted as comments. Environment variables of the form $VAR or ${VAR} will be expanded, using both the environment set externally and the environment set by TextTest. (These variables are also documented in tables for the default and queuesystem configurations.)

The basic format is "<key>:<value>" for ordinary entries. For example the entry "executable" has type "String", while the entry "lines_of_text_difference" has type "Int". These entries can therefore be entered like this:

# Full path to my application
executable:/the/path/to/my/application.sh

# How long do we want our diff previews to be?
lines_of_text_difference:100

Some entries are lists, which in all cases implicitly means a list of strings. This is achieved by adding several entries for the same <key>, repeating the key each time. For example the entry "copy_test_path" has type "List", so we can configure it like this:

# We have several different data file types!
copy_test_path:my_data_file1.txt
copy_test_path:my_data_file2
copy_test_path:another_data_path.dat

When writing versioned files that override settings in a parent config file, special syntax is needed to remove entries from such a list entry (Ints and Strings can just be set to some harmless value or back to the default again). To remove one of the above entries again, we can e.g. add

# This version doesn't like .txt files
copy_test_path:{CLEAR my_data_file1.txt}

We can also remove the entire list and start again.

# This version uses completely different data files
copy_test_path:{CLEAR LIST}
copy_test_path:versioned_data_file1
copy_test_path:versioned_data_file2

Some entries are dictionaries, and hence are listed as "Dictionary" or "CompositeDictionary", with the type of the values indicated in brackets. The keys have different meanings, sometimes they also have predefined possible values, in which case such values will be listed in the default value. Sometimes they will refer to e.g. particular result file in the test tree. The specific documentation for these entries should describe this.

These entries make use of a "section header"-style format. For example "window_size" (in the personal config file) lists "maximize : 0" as its default value. To set this to 1, we therefore write as follows

[window_size]
maximize:1

Sometimes the values in the dictionary are themselves lists. In this case the syntax is a fairly obvious combination with the "list syntax" described above. For example "run_dependent_text" has this form:

[run_dependent_text]
stdout:Filter this line
stdout:And lines like this

Such sections do not need special termination if they are followed by other sections. If they are followed by ordinary String, Int or List settings though, they must be terminated with [end]. For example, combining some previous examples :

[run_dependent_text]
stdout:Filter this line
stdout:And lines like this
# Can also write [end] here too but isn't necessary

[window_size]
maximize:1
[end] 
# But without [end] here the next setting will not be found

copy_test_path:my_data_file1.txt

TextTest will try to warn you if you forget such an [end] marker.

Entries listed as "CompositeDictionary" are exactly like Dictionary entries with the added factor that the key "default" has a special meaning. It is basically a fallback value for if the requested key has not been specifically defined, and as such is a way to avoid repeating information across several different keys. If the values are Strings or Ints, specific settings simply replace the "default" key. For example, "view_program" could be set as follows:

[view_program]
html_file:firefox
default:emacs

which would cause all files to be viewed with "emacs" except "html_file" which would be viewed in firefox.

If the values are lists, the values from the default key will be appended to those from the specific key. For example:

[collate_script]
html_file:xmllint
default:my_custom_script.py

This would cause all files to be fed through "my_custom_script.py" before being compared, except for "html_file" which would be passed through "xmllint" as well as "my_custom_script.py".

If you only wish to override the "default" value of a CompositeDictionary, it is acceptable to use the format for non-dictionary entries, i.e. simply

view_program:emacs

collate_script:my_custom_script.py

These consist of a series of environment variable assignments of the form "<key>:<value>". It is used to set environment variables to be passed to the system under test for all tests under a certain point in the hierarchy. So if we wish to set MY_ENV_VAR to 3 for the system under test, we just write

MY_ENV_VAR:3

As with config files, blank lines and lines beginning with '#' will be ignored, and environment variables will be expanded, both from the external environment and from the variables set by TextTest.

(See the Test Suite Guide for a fuller explanation of the purpose of these files)

These consist for the most part of options to passed "as is" to the system under test on the command line. The only complications are for when a file wishes to reset options set in previously read files. In that case a similar syntax to that in the config file can be used, i.e.

{CLEAR -a} -b -c

will append -b and -c to the command line and remove -a if it was previously added, while

{CLEAR} -b -c

will ignore everything previously set and also append -b and -c. (See the Test Suite Guide for a fuller explanation of the purpose of these files)

These are auto-generated by the Static GUI and do not ordinarily need to be manipulated directly, but it is easy to do so if you wish. They consist of an ordered series of test names, which should correspond to existing directories which define the tests. Comments above the test names are interpreted as a description of the following test. For example:

# Our very first test!
FirstTest

# This comment will be ignored

# This time the description
# required several lines
ComplicatedTest

Their purpose is also explained more fully in the Test Suite Guide.

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.