.. index:: ! test suites

Test suites
===========

Test suites are the containers with tests. Each test is a method in some
test suite. Test suites are derived from the :class:`test_suite\<T>` template
class. The template argument is the name of the class you are about to
define i.e. ::

  class my_test_suite : public test_suite<my_test_suite> {
    ...
  };


Constructor
  Test suites need to be default constructable. 

Data 
  Data common to several tests may be declared as class members and
  initialized in the proper setup method.


The ``test_suite`` base class
-----------------------------

The definition of the ``test_suite`` base class is as follows.

.. class:: test_suite<T>

   ::

     template<typename T>
     class test_suite : public a_test_suite

   The template argument is the name of the derived class.

   .. function:: test_suite()

      ::

        test_suite(const char *suiteDescription)

      The ``suiteDescription`` argument will be used to set data
      members in the test suite that may be used by test runners to
      present a description of the suite.

   .. function:: ~test_suite()

      ::

        virtual ~test_suite();

   .. function:: stage()

      ::

	void stage(void (T::*test_method)(), const char *description);

      This method should be called from within the constructor of the
      derived test suite, once for each test case in the suite. This
      is needed in order to signal the existence of the test and to
      provide a description for it. The description may be used by the
      :ref:`test reporter <test-reporter>`.


   .. function:: suite_setup()

      ::

        virtual void suite_setup()
      
      Override this method with setup code for your tests. This
      method is run before any tests, once for each suite. It is used
      in order to initialize data common to all tests but which does
      not need to be reinitialized before each test, e.g. database
      connections, allocation of expensive resources etc.

   
   .. function:: test_setup()

      ::

        virtual void test_setup()
      
      Override this method with setup code for your tests. This
      method is run before each test. It is used in order to
      initialize data before each test.

   .. function:: test_teardown()

      ::

        virtual void test_teardown()

      Override this method with clean-up code for your tests. This
      method is called after each test in order to give the opertunity
      to clean up e.g. allocations made in the :func:`test_setup()`
      method.

   .. function:: suite_teardown()

      ::

	virtual void suite_teardown()

      Override this method with clean-up code for your tests. This
      method is called once after all tests in a suite have been
      executed. It is used to clean up e.g. allocations made in the
      :func:`suite_setup()` method.


.. index:: writing tests

Writing tests
-------------

Tests are easy to write, just define a new method in the suite and
make sure to add a call to the :func:`stage()` method for that
test. Note that all test methods need to have void return type and an
empty argument list. See :ref:`example <unittest-example>` for a full
example, and the :ref:`constraints <constraints>` section for
different kinds of assertions and tests.