![]() |
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
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't miss a unit test failure.
By default, the executable is run directly. Sometimes, it's
desirable to run the executable using some helper command. You should use the
testing.launcher
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
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 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, on the opposite, 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 bjam 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
and
for the other rules it is called
target-name
.passed
.
The target-name
.testrun*
rules also capture all output from the program,
and store it in a file named
.target-name
.output
The run
and the run-fail
rules, if
the test passes, automatically delete the linked executable, to
save space. This behaviour can be suppressed by passing the
--preserve-test-targets
command line option.
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, the output of
bjam during command run, 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.