libs/test/doc/adv_scenarios/test_module_runner_overview.qbk

   1 [/
   2  / Copyright (c) 2003 Boost.Test contributors
   3  /
   4  / Distributed under the Boost Software License, Version 1.0. (See accompanying
   5  / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   6  /]
   7
   8 [section:test_module_runner_overview Test module runner]
   9
  10 A ['test module runner] is an ['orchestrator] or a ['driver] that, given the test tree, ensures the test tree is initialized,
  11 tests are executed and necessary reports generated. It performs the following operations:
  12
  13 * initialize the test module using the supplied [link boost_test.adv_scenarios.test_module_init_overview ['initialization function]];
  14 * select output media for the test log and the test results report;
  15 * execute test cases as specified by run-time parameters;
  16 * produce the test results report;
  17 * generate the appropriate return code.
  18
  19 The __UTF__ comes with the default test runner. There is no need to call it explicitly. The default generated test module's
  20 [link boost_test.adv_scenarios.entry_point_overview entry point] invokes the default test runner. The default test runner is
  21 declared with the following signature:
  22
  23 ```
  24 namespace boost { namespace unit_test {
  25
  26   typedef bool (*init_unit_test_func)();
  27
  28   int unit_test_main( init_unit_test_func init_func, int argc, char* argv[] );
  29
  30 } }
  31 ```
  32
  33 The test runner may return one of the following values:
  34
  35 [table
  36 [[Value][Meaning]]
  37 [[`boost::exit_success`][
  38 * No errors occurred during testing, or
  39 * the success result was forced with command-line argument `--[link boost_test.utf_reference.rt_param_reference.result_code `result_code`]=no`.]]
  40 [[`boost::exit_test_failure`][
  41 * Non-fatal errors detected and no uncaught exceptions were thrown during testing, or
  42 * the initialization of the __UTF__ failed. ]]
  43 [[`boost::exit_exception_failure`][
  44 * Fatal errors were detected, or
  45 * uncaught exceptions thrown during testing. ]]
  46 ]
  47
  48 An advanced test runner may provide additional features, including interactive GUI interfaces, test coverage and profiling support.
  49
  50 [endsect] [/section:test_module_runner_overview]