Header <boost/test/framework.hpp>

Defines Unit Test Framework mono-state interfaces. The framework interfaces are based on Monostate design pattern.


BOOST_TEST_SETUP_ASSERT(cond, msg)

namespace boost {
  namespace unit_test {
    typedef test_suite *(* init_unit_test_func;
    namespace framework {
      struct context_generator;
      struct internal_error;
      struct nothing_to_test;
      struct setup_error;

      // Unit Test Framework initialization and shutdown
      void init(init_unit_test_func, int, char *);
      void finalize_setup_phase(test_unit_id = INV_TEST_UNIT_ID);

      // This function returns true when testing is in progress (setup is finished). 
      bool test_in_progress();
      void shutdown();

      // Test unit registration
      test_suite & current_auto_test_suite(test_suite * = 0, bool = true);
      void register_test_unit(test_case *);
      void register_test_unit(test_suite *);
      void deregister_test_unit(test_unit *);

      // After this call the framework can be reinitialized to perform a second test run during the same program lifetime. 
      void clear();

      // Test observer registration
      void register_observer(test_observer &);
      void deregister_observer(test_observer &);

      // Global fixtures registration
      void register_global_fixture(global_fixture &);
      void deregister_global_fixture(global_fixture &);

      // Assertion/uncaught exception context support
      int add_context(lazy_ostream const &, bool);
      void clear_context(int = -1);

      // Produces an instance of small "delegate" object, which facilitates access to collected context. 
      context_generator get_context();

      // Access to registered test units.
      master_test_suite_t & master_test_suite();
      test_unit const & current_test_unit();
      test_case const & current_test_case();
      test_unit_id current_test_case_id();
      test_unit & get(test_unit_id, test_unit_type);
      template<typename UnitType> UnitType & get(test_unit_id);

      // Test initiation interface
      void run(test_unit_id = INV_TEST_UNIT_ID, bool = true);

      // Initiates test execution. Same as other overload. 
      void run(test_unit const * tu, bool continue_test = true);

      // Test events dispatchers
      void assertion_result(unit_test::assertion_result ar);

      // Reports uncaught exception to all test observers. 
      void exception_caught(execution_exception const &);

      // Reports aborted test unit to all test observers. 
      void test_unit_aborted(test_unit const &);

      // Reports aborted test module to all test observers. 
      void test_aborted();
      namespace impl {
        struct master_test_suite_name_setter;
        void setup_for_execution(test_unit const &);
        void setup_loggers();
      }
    }
  }
}

Unit Test Framework initialization and shutdown

```
void init(init_unit_test_func init_func, int argc, char * argv);
```
This function performs initialization of the framework mono-state.
It needs to be called every time before the test is started.

Parameters:

init_func

test module initialization routine

argc

command line arguments collection

argv

command line arguments collection
```
void finalize_setup_phase(test_unit_id tu = INV_TEST_UNIT_ID);
```
This function applies all the decorators and figures out default run status. This argument facilitates an ability of the test cases to prepare some other test units (primarily used internally for self testing).

Parameters:

tu

Optional id of the test unit representing root of test tree. If absent, master test suite is used
```
void shutdown();
```
This function shuts down the framework and clears up its mono-state.
It needs to be at the very end of test module execution

Test unit registration

```
test_suite & 
current_auto_test_suite(test_suite * ts = 0, bool push_or_pop = true);
```
Provides both read and write access to current "leaf" auto test suite during the test unit registration phase.
During auto-registration phase the framework maintain a FIFO queue of test units being registered. New test units become children of the current "leaf" test suite and if this is test suite it is pushed back into queue and becomes a new leaf. When test suite registration is completed, a test suite is popped from the back of the queue. Only automatically registered test suites should be added to this queue. Master test suite is always a zero element in this queue, so if no other test suites are registered all test cases are added to master test suite. This function facilitates all three possible actions:
- if no argument are provided it returns the current queue leaf test suite
- if test suite is provided and no second argument are set, test suite is added to the queue
- if no test suite are provided and last argument is false, the semantic of this function is similar to queue pop: last element is popped from the queue
Parameters:

ts

test suite to push back to the queue

push_or_pop

should we push ts to the queue or pop leaf test suite instead
```
void register_test_unit(test_case * tc);
```
This function add new test case into the global collection of test units the framework aware of.
This function also assignes unique test unit id for every test case. Later on one can use this id to locate the test case if necessary. This is the way for the framework to maintain weak references between test units.

Parameters:

tc

test case to register
```
void register_test_unit(test_suite * ts);
```
This function add new test suite into the global collection of test units the framework aware of.
This function also assignes unique test unit id for every test suite. Later on one can use this id to locate the test case if necessary. This is the way for the framework to maintain weak references between test units.

Parameters:

ts

test suite to register
```
void deregister_test_unit(test_unit * tu);
```
This function removes the test unit from the collection of known test units and destroys the test unit object.
This function also assigns unique test unit id for every test case. Later on one can use this id to located the test case if necessary. This is the way for the framework to maintain weak references between test units.

Parameters:

tu

test unit to deregister

Test observer registration

```
void register_observer(test_observer & to);
```
Observer lifetime should exceed the the testing execution timeframe.

Parameters:

to

test observer object to add
```
void deregister_observer(test_observer & to);
```
Excludes the observer object form the framework's list of test observers.

Parameters:

to

test observer object to exclude

Global fixtures registration

```
void register_global_fixture(global_fixture & tuf);
```
Adds a new global fixture to be setup before any other tests starts and tore down after any other tests finished. Test unit fixture lifetime should exceed the testing execution timeframe.

Parameters:

tuf

fixture to add
```
void deregister_global_fixture(global_fixture & tuf);
```
Removes a test global fixture from the framework.
Test unit fixture lifetime should exceed the testing execution timeframe

Parameters:

tuf

fixture to remove

Assertion/uncaught exception context support

```
int add_context(lazy_ostream const & context_descr, bool sticky);
```
Records context frame message.
Some context frames are sticky - they can only explicitly cleared by specifying context id. Other (non sticky) context frames cleared after every assertion.

Parameters:

context_descr

context frame message

sticky

is this sticky frame or not

Returns:

id of the newly created frame
```
void clear_context(int context_id = -1);
```
Erases context frame (when test exits context scope)
If context_id is passed clears that specific context frame identified by this id, otherwise clears all non sticky contexts.

Access to registered test units.

```
master_test_suite_t & master_test_suite();
```
There is only only master test suite per test module.

Returns:

a reference the master test suite instance
```
test_unit const & current_test_unit();
```
This function provides an access to the test unit currently being executed.
The difference with current_test_case is about the time between a test-suite is being set up or torn down (fixtures) and when the test-cases of that suite start. This function is only valid during test execution phase.

See Also: current_test_case_id, current_test_case
```
test_case const & current_test_case();
```
This function provides an access to the test case currently being executed.
This function is only valid during test execution phase.

See Also: current_test_case_id
```
test_unit_id current_test_case_id();
```
This function provides an access to an id of the test case currently being executed.
This function safer than current_test_case, cause if wont throw if no test case is being executed.

See Also: current_test_case
```
test_unit & get(test_unit_id tu_id, test_unit_type tu_type);
```
This function provides access to a test unit by id and type combination. It will throw if no test unit located.

Parameters:

tu_id

id of a test unit to locate

tu_type

type of a test unit to locate

Returns:

located test unit
```
template<typename UnitType> UnitType & get(test_unit_id id);
```
This function template provides access to a typed test unit by id.
It will throw if you specify incorrect test unit type

Parameters:

id

id of test unit to get

Template Parameters:

UnitType

compile time type of test unit to get (test_suite or test_case)

Test initiation interface

void run(test_unit_id tu = INV_TEST_UNIT_ID, bool continue_test = true);

Initiates test execution.

This function is used to start the test execution from a specific "root" test unit. If no root provided, test is started from master test suite. This second argument facilitates an ability of the test cases to start some other test units (primarily used internally for self testing).

Parameters:

`tu`	Optional id of the test unit or test unit itself from which the test is started. If absent, master test suite is used
`continue_test`	true == continue test if it was already started, false == restart the test from scratch regardless

Boost C++ Libraries