.. index:: ! test runners

Test runners
============

Test runners are responsible for executing the tests in one ore more
test suites. A test application must include at least one test runner
in order to execute any tests.

The ``test_runner`` interface
-----------------------------

.. class:: test_runner

   .. function:: test_runner()

      ::

        test_runner()
        test_runner(test_reporter &r)

      The default constructor will use the :class:`text_reporter` class
      when reporting test results. This can be changed by supplying
      another reporter as the ``test_reporter`` argument at construction
      time.

   .. function:: ~test_runner()
  
   .. function:: use_reporter()

      ::

        void use_reporter(test_reporter &r)

      Set the test reporter to use after construction.

   .. function:: stage<T>()

      ::

        template<typename t_suite>
        void stage();

      Register new suite

   .. function:: run_all()

      ::

        int run_all();
 
      Run all tests in registered test suites. Returns the number of
      failed tests.

   .. function:: run_suite<T>()

      ::

        template<typename t_suite>
        int run_suite();

      Run all tests in a suite. Returns the number of failed tests.


   .. function:: run_test<T>()
      
      ::
 
        template<typename t_suite>
        int run_test(void (t_suite::*test)());

      Run a single test in a single suite. Returns the number of
      failed tests.

Suite registration
------------------

In order to execute a set of test suites each suite has to be
registered with the test runner. This is done with the
:func:`test_runner::stage<T>()` method. E.g. assume that ``my_suite_1``,
``my_suite_2``, ``my_suite_3`` are test suites. Then::

  test_runner tester;

  tester.stage<my_suite_1>();
  tester.stage<my_suite_2>();
  tester.stage<my_suite_3>();

  tester.run_all();

will create a test runner, register the suites and execute all tests
in each one of them.

Running single suites
---------------------

It is possible to execute all tests in a suite directly, then there is
no need to stage the suite first. ::

  test_runner tester;

  tester.run_suite<my_suite>();

Running single tests
--------------------

It is possible to execute a single test in a suite directly. This is
done by invoking the :func:`test_runner::run_test<T>()` method in the test runner class with
a pointer to the test to run. ::

  test_runner tester;

  tester.run_test(&my_suite::test_method);

Here ``my_suite`` is a test suite and ``test_method`` is the name of
the test method to execute.