TestPlan has many purposes and thus no one output, or logging mechanism, will be appropriate in all cases. The default output by TestPlan has been chosen to match some common use cases, though if it is not exactly what you want then you can use several options to control the output.

For example, to record metrics for your test:

testplan root/base.test System.Recorder.MetricFile=/out/basemetrics.csv

Metrics

If you need to obtain timing information for tests, for example when doing stress of performance testing, you will be interesting in using the metrics gathering facility of TestPlan.

Simply set System.Recorder.MetricFile to a filename and this will be populated with every single unit call, as well as web request timings, and a few other items.

The format is a CSV file which includes the unit or metric, whether it failed or succeeded, the length of time it took (or other metric), and the time when it occurred.

You may use the Metric→ function to record additional data to this log.

Checkpoint

Every Check→, Checkpoint→, and several other internal controls result in checkpoint log entries.

These checkpoint entries are only written to the main log when they fail.

To get a complete log of all events one can enable the checkpoint log file. This is simply by done by setting the System.Recorder.CheckpointFile to a filename.

Checkpoint Exceptions

If you have a large test suite that takes a while to run, it may not be possible to simply recreate error conditions at a later time. For this reason TestPlan also offers the option to record extended stack information at the time of any checkpoint failure.

To enable this set a filename for System.Recorder.CheckpointException. Anytime a checkpoint fails in your units the complete stack trace (unit stack and Java stack) will be recorded to this file.

Status Output

The final status output, showing a tree of all units and their success value, is normally written to the console out. You can override this with Run.StatusOutput.

This does not accept an append option.

Main Output

By default the main output is enabled. It can be disabled by setting System.ShowMainLog to false.

Using the command-line tool this can also be indicated with the option --hideMainLog.

Recording Primary Output

The main output combines the output of all of the log entries from each of the LogicalRoot's→ in the execution.

These can also all be separated into individual files by specifying the System.LogDir. The primary output will have the prefix 1_ and all child logs will be prefixed by their label number shown in the parent log file.

This is primarily useful when using spawn→ as the main output is then a mix of the outputs from the two parallel child units.

Standard Options

Most files may also have an additional parameter set .Append which indicates if any existing file should be appended. The default is false.

STDOUT can be used in place of a filename above to echo the file to the console running the process.

NULL can be used to suppress the output, this is useful in cases where you wish to suppress a default -- though in most cases the default is not to output anyway.