Documentation for 3.12
Automatic Failure Interpretation in TextTest
There are situations when it saves a fair bit of time to
inform TextTest about what your system is likely to log and what
it means. This means that TextTest can find such patterns
automatically and instead of just saying “differences in
output” can provide you a much more succinct description
of what went wrong. TextTest can also automatically try to
collect information about what happened from the system: for
example core files that have been dumped on UNIX. This document
aims to give a guide to how TextTest can interpret failures at a
higher level than file differences.
This will just happen. Each test is run with a unique
temporary directory as the current working directory. This means
that TextTest will pick up any core file written there and try
to extract the stack trace from it. If it succeeds, it will
report the test as having “CRASHED” and display the
stack trace in the “Text Info” window.
Since version 3.7, it does this by using an external script
“interpretcore.py” which outputs stack traces given
core files. It has been tested on quite a few flavours of UNIX :
HPUX-11, powerpc, Sparc Solaris and Linux RHEL3, RHEL4 and seems
to be quite portable (much more so than the old code that was
part of TextTest until version 3.6) This script is plugged in by
default via the default value of the “collate_script”
entry on UNIX.
It is provided as standard with TextTest, but can clearly
also be used externally to TextTest. It works by using the
standard debugger 'gdb'. If it fails to find the stack trace for
any reason the test will still be reported as “CRASHED”
but the reason for failure will be given in the “Text
Info” window instead.
It can be useful to associate a succinct problem description
with the appearance of certain logged text. For example, your
application may well report “Internal Error!!!” when
something bad happens. In this case you could tell TextTest
about this so it can describe such a test failure as an Internal
Error and save you the trouble of reading the log file.
Another common usage, as the title hints, is for known bugs
in the system under test. This may be needed because the bug
appears only intermittently, or because time has not yet been
found to fix it even though its presence is known. In either
case, telling TextTest about it can prevent lots of people
examining lots of failed tests in order to discover the same
The easiest way to do this is by using the dialog in the
static GUI. Right-click the test or testsuite where the bug should
apply (for example, if it applies everywhere, select the root
test suite) and select "Enter Failure Information". (The screenshot
below is from an earlier version of TextTest but the contents of the old Bugs
tab is the same as what the dialog will show)
Here we imagine that when our application logs “after
<n> seconds” this implies it has gone into a delay
that isn't appropriate. So we fill in the dialog appropriately
with the text to match, and some description information, a full
text to give and a short description. This creates a special
file knownbugs.<app> in the test or suite's
directory, which has a format that is easy to edit in a normal editor.
If we then run the test and it produces the indicated text,
we then get a nice summary instead of the usual complete file
differences. Note it has used our “brief description”
given above in the Details column of the test tree view, while
the full description appears in the Text Info window at the
Ordinarily, you will search for some text that will be produced in a certain file, as
given by the "file to search in" entry. This will search the unfiltered version of the file
(not the diff produced in the Text Info window). This can be inverted via the check box at the bottom,
so that the bug is triggered when the text is not present.
There is also a special entry 'free_text' in the "file to search in" drop-down list. This
works by checking the actual result, more or less what appears in the Text Info window.
Note however that it isn't generally possible to match on the first line of this text,
which is an additional explanatory line added by the GUI and not part of the state of the
test. This line will be different in the case of running in batch mode
, which is why it isn't a good idea for TextTest
to use it for matching.
When the tests are run, TextTest wll then find all such "knownbugs" files, using its
mechanism for finding
and prioritising files in the hierarchy
. All information from all such files will be used,
the files do not overwrite each other as versioned files used to up to version 3.10.
If you have a bug-tracking system with an API of some sort,
you can probably get it to talk to TextTest without
very much effort. Instead of providing textual descriptions you
can then just provide the bug ID from the bug system and
TextTest will extract the (current) information for you. It will
try to determine whether the bug has been fixed (closed in the
bugsystem) and if so it will be reported as “internal
error” rather than as “known bug”, as it is
expected the bug text would not continue to occur if the bug had
If you use Bugzilla
track your bugs, there are two plugins already written and bundled
with TextTest. To use these, you need to give TextTest the URL to your bugzilla installation,
using the config file entry "bug_system_location". For example, for bugzilla version 3 you might
add this in your config file:
For bugzilla version 3 there is a plugin called "bugzilla" that calls bugzilla's native
web service API to extract the relevant information. This should work against any bugzilla installation out of the box.
There is also a plugin called "bugzillav2" that can interface with the older versions of bugzilla that don't
have a web service, however for this to work, you also need to install the
program. This is essentially an additional open source CGI script that runs on the
bugzilla server. From TextTest 3.11 the command line perl program 'bugcli' is no longer used, only the cli.cgi program. Note that bugcli is not supported by anyone any more: if you find problems you'll just need to upgrade Bugzilla.
If you use some other bug tracker with an API,
it should be fairly easy to copy the “bugzilla.py” module from the TextTest
source and change it to provide the 'findBugInfo' method as appropriate for your
bug system. By providing the name of the module in the bug
system field when reporting the bug, it will load this module
and extract the relevant information.