Documentation for 3.9.1
Other versions: trunk  3.27  3.26  3.25  3.24  3.23  3.22  3.21  3.20  3.19  3.18  Older...

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.
  1. It isn't possible to have some log statements present for some tests and absent for others.
  2. Where logs cannot be easily disabled, they can slow down the system in production.
  3. 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 developers.
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 example log4j (Java) log4py (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.
Telling TextTest about the SUT's logging framework
This is done via the config file dictionary entry “diagnostics”.
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.
Example configuration (log4py)
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.
Example 2 (log4j)
Assumes the SUT reads the local properties file, 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.
Configuring the logging in your test suite
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.

Last updated: 05 October 2012