Testing

Boost.Build has convenient support for running unit tests. The simplest way is the unit-test rule, which follows the common syntax. For example:

unit-test helpers_test : helpers_test.cpp helpers ;

The unit-test rule behaves like the exe rule, but after the executable is created it is also run. If the executable returns an error code, the build system will also return an error and will try running the executable on the next invocation until it runs successfully. This behaviour ensures that you can not miss a unit test failure.

There are few specialized testing rules, listed below:

rule compile ( sources : requirements * : target-name ? )
rule compile-fail ( sources : requirements * : target-name ? )
rule link ( sources + : requirements * : target-name ? )
rule link-fail ( sources + : requirements * : target-name ? )

They are given a list of sources and requirements. If the target name is not provided, the name of the first source file is used instead. The compile* tests try to compile the passed source. The link* rules try to compile and link an application from all the passed sources. The compile and link rules expect that compilation/linking succeeds. The compile-fail and link-fail rules expect that the compilation/linking fails.

There are two specialized rules for running applications, which are more powerful than the unit-test rule. The run rule has the following signature:

rule run ( sources + : args * : input-files * : requirements * : target-name ?
    : default-build * )

The rule builds application from the provided sources and runs it, passing args and input-files as command-line arguments. The args parameter is passed verbatim and the values of the input-files parameter are treated as paths relative to containing Jamfile, and are adjusted if b2 is invoked from a different directory. The run-fail rule is identical to the run rule, except that it expects that the run fails.

All rules described in this section, if executed successfully, create a special manifest file to indicate that the test passed. For the unit-test rule the files is named target-name.passed and for the other rules it is called target-name.test. The run* rules also capture all output from the program, and store it in a file named target-name.output.

If the preserve-test-targets feature has the value off, then run and the run-fail rules will remove the executable after running it. This somewhat decreases disk space requirements for continuous testing environments. The default value of preserve-test-targets feature is on.

It is possible to print the list of all test targets (except for unit-test) declared in your project, by passing the --dump-tests command-line option. The output will consist of lines of the form:

boost-test(test-type) path : sources

It is possible to process the list of tests, Boost.Build output and the presense/absense of the *.test files created when test passes into human-readable status table of tests. Such processing utilities are not included in Boost.Build.

The following features adjust behaviour of the testing metatargets.

testing.arg

Defines an argument to be passed to the target when it is executed before the list of input files.

unit-test helpers_test
  : helpers_test.cpp helpers
  : <testing.arg>"--foo bar"
  ;

testing.input-file

Specifies a file to be passed to the executable on the command line after the arguments. All files must be specified in alphabetical order due to constrainsts in the current implementation.

testing.launcher

By default, the executable is run directly. Sometimes, it is desirable to run the executable using some helper command. You should use this property to specify the name of the helper command. For example, if you write:

unit-test helpers_test
  : helpers_test.cpp helpers
  : <testing.launcher>valgrind
  ;

The command used to run the executable will be:

valgrind bin/$toolset/debug/helpers_test

test-info

A description of the test. This is displayed as part of the --dump-tests command-line option.