## 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 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 ``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`.

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.