There are many things which can be configured about the TextTest GUIs, some of which are mostly a matter of personal taste. All of them involve placing files in your personal TextTest configuration directory. This directory is located by default in a subdirectory of your home directory called “.texttest”.(“Home directories” on Windows are formed either from the $HOME variable or a combination of the variables $HOMEDRIVE and $HOMEPATH). You can also place it anywhere at all and identify the directory with the environment variable $TEXTTEST_PERSONAL_CONFIG.

The look and feel of the GUI widgets themselves can be configured by providing a GTK configuration file. This file should be called “.gtkrc-2.0” and should be placed in the directory described above, if you want it to only affect TextTest, or in your home directory if you want it to affect all GTK GUIs you might run. The syntax of these files is described, for example, at the PyGTK homepage.

This can be done by placing XML files in your personal TextTest configuration directory. Such an XML file should be named to indicate to TextTest when it should kick in. (Note this naming scheme has changed since version 3.10) For example:

The first element (before the dash) indicates that the file should only be loaded when the indicated GUI configuration module is being run. The second should be "static", "dynamic" or absent. The file name should always end in .xml.

As for the contents, the easiest thing is to look at the files in the "etc" subdirectory of the source tree and pattern-match. Note you only need to add extra XML sections, you don't need to copy these files, though they give you the names of all possible elements. For an example which extends the standard toolbar, look in the self-tests under GUI/Appearance/UserDefinedGUIDescription/personaldir.

This is done via "personal config files", which are also placed in your personal TextTest configuration directory. They should be named "config" to apply to all TextTest test suites you might run, and may also have application and version-specific suffices so that they only apply in certain cases. They work much like the application config files, in that you can place any entries that are supported by the config files in them (although it is advisable to stick to GUI appearance). Additionally, there are some settings that will only be accepted in such a personal configuration file, these are listed in a separate table.

It is also possible to have site-specific config files in the same way, which should be placed in a subdirectory "site/etc" of the source code tree. In some cases (for example when troubleshooting) it is useful to disable reading of personal and site-specific configuration: in this case the "--vanilla" command line option should be used. You can provide "--vanilla site" to disable the site configuration, "--vanilla personal" to disable personal configuration, while any other argument (or no argument) after "--vanilla" will disable both.

You can edit and view these files by going to the “Config” tab in the static GUI, where you will also see the config files for the applications you're currently running on.

By default the whole test suite will be expanded on starting up the static GUI. This can sometimes be awkward, especially for test writers who are only interested in a small part of the test suite. For them, it is best that everything starts collapsed so they can just view the parts that matter to them.

To this end there is a setting “static_collapse_suites”. This should be set to 1 to disable the automatic expand of the test suite. Instead, it will only expand the first level of suites/tests.

The shortcut bar at the bottom allows you to create GUI shortcuts for sequences of clicks that you do regularly. This is the GUI shortcut functionality as provided by StoryText, which TextTest itself relies on, primarily for its own testing, but also to allow for this customisation possibility.

To create such a shortcut, you click the "New" button on the "shortcut bar", and then perform the clicks you want recorded. When you have finished, you enter a name at the bottom and press "Stop". A new button then appears which will reproduce the clicks on demand. The shortcut is stored in the directory indicated by the variable USECASE_HOME, which will default to $TEXTTEST_HOME/usecases. It is in a very high-level plain text format and it should be possible to edit them by hand if necessary.

TextTest comes by default with four bars: all of which are optional: a menubar and toolbar at the top and a shortcut bar and status bar at the bottom. The menubar and toolbar are fairly standard and generally provide access to the same functionality. The shortcut bar is described above. The status bar at the very bottom tries to indicate what TextTest is doing right now or has just done. The “throbber” at the far right indicates whether it is doing something: sometimes searching a large test suite for example may take a little time.

All of these can be hidden by default using the “hide_gui_element” entry, as above, see the table of personal config file settings for the key format. If you don't hide the menubar via this mechanism you can also show and hide them via the “View” menu.

There are plenty of configuration options in various tabs around the GUI, and all are identified with a label next to them. This label is used to identify them in the config file: take any label, make it lower case and replace all spaces replaced by underscores (“_”) and you have a way to identify the control in the config file..

Default values are changed by using the config entry “gui_entry_overrides”. For text boxes, simply provide the key as given above with the text you want as the default. For check boxes provide “0” or “1” as appropriate. For radio buttons form the key by concatenating the label with the label for the specific button you want selected, and providing “1” also.

In a similar way you can configure what options are presented in drop-down lists to the user, in the case of the text boxes. This is done via the “gui_entry_options” config file entry, which is keyed in the same way. For example:

[gui_entry_overrides]
show_differences_where_present:0
current_selection_refine:1
run_this_version:sparc

[gui_entry_options]
run_this_version:linux

This will cause the "Approve As..." dialog not to automatically check the box for "Show differences where present", as in the example above. It will also cause the static GUI to include the version "linux" in a drop-down list for the "Run this version" text box and to set it to “sparc” by default. And finally the radio button on the “Select Tests” tab will select “Refine” instead of the default “Discard”

As a special case, the "Test-file to search" box often contains a very long drop-down list if your application has a few different files, as it searches the test tree for all possible test-files. By making use of [gui_entry_options] in the same way for this box, you can cause these to appear at the top of the list. In this way you can identify files that you often want to search for.

There is also the possibility to enable and configure GTK's entry completion functionality. This is separate from the drop-down boxes and works by guessing what you're typing based on what has been typed before. It is enabled by default, and will by default match based on the beginning of what has been typed. To disable it, set “gui_entry_completion_matching” to 0. To cause the matching to occur on any part of what has been typed, set the same entry to 2. If you want previous matching text to be automatically inlined into what you're typing, set the “gui_entry_completion_inline” entry to 1. Note that this can be confusing if you aren't used to it!

Additionally, you can “hardcode” completions that should always be present, by adding to the config file list entry “gui_entry_completions”.

The colours for the test tree view (left window) and the file view (top right window under Test tab) can be configured via the GUI dictionary entries “test_colours” and “file_colours” respectively. These are keyed with particular pre-defined names for the different test states: to see what they are, look at the default values in the table of config file settings. Any name that appears in the Status tab in the dynamic GUI can also be used as a key here, so you can also for example say:

[test_colours]
success:pale green
stdout different:pink
[end]

The values should be text strings as recognised by RGB files.

The static GUI uses the special key "static" which defaults to a pale grey, and colours are less important there. However it is possible to set the different types of files in the file view to be different colours if desired, use the keys static_data, static_standard and static_definition for this purpose.

The toolbar actions generally have keyboard accelerators, whose values can be seen from the menus which also contain them. These can be configured via the “gui_accelerators” dictionary entry. The keys in this dictionary should correspond to the labels on the relevant buttons, and the values should be for example “<control><alt>r” or “F4”. If in doubt, consult the format of the default ones in the >table of config file settings. The values should be text strings as recognised by RGB files.

If you find the TextTest window sizes to be inconvenient you can also configure this. There is a config file dictionary entry “window_size”. This has various keys, which can be prefixed by “static_” or “dynamic_” to make them specific to the particular GUIs if desired.

“maximize”, if set to 1, will maximise the window on startup.

“height_pixels” and “width_pixels” give the window an absolute size at startup (not recommended outside personal files!)

“height_screen” and “width_screen” give the window a size as a fraction (not percentage!) of the size of your screen.

“horizontal_separator_position” and “vertical_separator_position” allow a default configuration of where the pane separators start out, also as a fraction of screen size.

Naturally, when you press Quit in the GUI it will try to clean up everything it has created in terms of both files and processes. For what happens to the temporary files created, see the section on the temporary directory.

As we've seen above, it is quite possible to start many different viewers and editors from TextTest and many different dynamic GUI runs from the static GUI. If all of these had to be closed by hand it would probably be cumbersome – so the default operation of TextTest is to find all of these processes and kill them. On UNIX, they will be sent SIGINT, SIGTERM and SIGKILL with a pause in between. On Windows, they will be terminated with “taskkill” which tends to be fairly final. If for any reason the tests don't terminate as rapidly as they should, pressing Quit a second time is recommended.

It can be useful to configure a questioning dialog such that TextTest will ask you before killing such processes. (By default it will always ask you before killing dynamic GUI processes on terminating the static GUI). This is the purpose of the “query_kill_processes” config file entry. This is a composite dictionary whose keys are “static”, “dynamic” or “default” (this last for both static and dynamic GUIs) and the values are patterns of “process names”: i.e. names of editors, viewers, the dynamic GUI etc. For eaxmple:

[query_kill_processes]
default:.*emacs
static:tkdiff
dynamic:texttest.*