Documentation for 3.10
Making the logging configurable
integration with log frameworks
It is naturally possible to conduct all your logging for
TextTest by writing just to standard output. However, there are
drawbacks to doing this.
- It isn't possible to have some log statements present
for some tests and absent for others.
- Where logs cannot be easily disabled, they can slow down
the system in production.
- You are compelled to log at one level only: it isn't
possible to separate high-level domain-relevant logs from
lower-level debug logs that will only be understood by the
Logging frameworks exist to solve these problems. TextTest
aims to handle their configuration smoothely and seamlessly to
make it easy to use them in your program when testing it.
We recommend you look at the log4x family of tools, for
(Python) and log4cpp
(C++). However, it should be possible to plug in a wide variety
of logging frameworks, provided they support the features that
TextTest assumes, as described below.
This is done via the config file dictionary entry
The simplest form of logging you can have is a single number
to determine the “log level”, so that you can have
more or less logging in the same file. This is done by providing
the entry “trace_level_variable” in the
“diagnostics” dictionary. This provides the name of
an environment variable understood by the SUT to determine this
level. It can then be configured via “-trace” on the
command line, or by filling in the static GUI entry “Target
application trace level”.
This is a bit limited, though, not least because it is
usually hard to judge what effect setting the log level to 5 is
going to have. The log4x frameworks are somewhat more
sophisticated, in aiming to separate the concept of a “logger”
from what files (if any) it will write to. You can then have
multiple loggers present (named in an informative way) and they
can then be controlled via the logging framework's configuration
file: aimed at different files, the same files or disabled
without any need for re-compilation of the SUT.
To use such a logging framework with TextTest, you should
make the target files of all loggers write to a single directory
controlled by some environment variable (or property in the case
of Java and log4j). The name of this environment variable or
property should then be put in the config file in the entry
“write_directory_variable” of the “diagnostics”
dictionary. This means that TextTest can easily redirect them to
its own temporary directory and pick them up without trouble.
You should also configure the SUT to look for the logging
framework's configuration file via some environment variable.
You can then provide the name of this variable in the entry
“configuration_file_variable” of the “diagnostics”
dictionary. Note: this behaviour was different in TextTest 3.8
and earlier, see the equivalent documentation there for details.
Java programs (hence log4j) are a special case because they
have their own environment mechanism, meaning they are generally
controlled from properties files rather than environment
variables. Here “configuration_file_variable” and
“write_directory_variable” should instead be Java
properties, read from some intermediate properties file. The
name of this properties file needs to be provided in the entry
“properties_file” of the “diagnostics”
dictionary: it will then be auto-generated by TextTest in the
current working directory of the test.
Assumes the SUT
locates the log4py configuration file in the directory
determined by $DIAG_INPUT_FILE, and all its files are written to
the directory $DIAG_OUTPUT.
Assumes the SUT reads the local
properties file log4jconf.properties, which will contain the two
properties “diag_input” and “diag_output”.
These in turn will be used to determine where to read the actual
log4j properties file and all files will be written to the
directory determined by the “diag_output” property.
You simply name your logging framework configuration file
“logging.<app>” and place it anywhere in the
directory structure of the test suite (see the guide
to TextTest's files and directories
). This will cause that
logging configuration to apply by default to all tests under
that point in the hierarchy. You will generally want to place at
least one such file, at the top level, as a default “testing
configuration” for the logs. Others can then be created
using the “New File” tab of the static GUI, at
appropriate places. Any log enabled by default should write to a
file with the same extension as the application, relative to the
write_directory_variable as above. It will then be automatically
picked up and compared by each test.
When TextTest comes to run the tests, on finding a logging
setup in the config file as above, it will start at the test
suite directory looking for a log framework configuration file.
If it doesn't find one, it will look in the parent test suite,
and repeat until it reaches the top of the hierarchy. If it
still doesn't find one, no configuration file will be read.
Note that “temporary diagnostic mode” from
TextTest 3.8 and earlier has been removed. For more details,
read the migration notes from the help menu.