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 ;
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
rules expect that compilation/linking succeeds. The
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
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
input-files as command-line
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
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
and for the other rules it is
run* rules also capture all output from the program, and
store it in a file named
preserve-test-targets feature has the value
run and the
rules will remove the executable after running it. This somewhat decreases
disk space requirements for continuous testing environments. The default
preserve-test-targets feature is
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:
It is possible to process the list of tests, Boost.Build output
and the presense/absense of the
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.
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" ;
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.
By default, the executable is run directly. Sometimes, it is desirable to run the executable using some helper command. You should use the 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:
A description of the test. This is displayed as part of the
--dump-tests command-line option.