Documentation for 3.27
Personalising TextTest's User Interfaces
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
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:
(affect every time you start TextTest)
(affect the dynamic GUI only)
“cvs_gui-static.xml” (affect the
static GUI only when running the CVS configuration)
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
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
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
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
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
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
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:
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
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:
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
“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.
“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
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: