libs/test/doc/test_organization/test_organization.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:tests_organization Declaring and organizing tests]
   9
  10 If you look at many legacy test modules, big chance is that it's implemented as one big test function that
  11 consists of a mixture of check and output statements. Is there anything wrong with it? Yes. There are various
  12 disadvantages in single test function approach:
  13
  14 * One big function tends to become really difficult to manage if the number of checks exceeds a reasonable limit
  15   (true for any large function). What is tested and where - who knows?
  16 * Many checks require similar preparations. This results in code repetitions within the test function.
  17 * If a fatal error or an exception is caused by any checks within the test function the rest of tests are
  18   skipped and there is no way to prevent this.
  19 * No way to perform only checks for a particular subsystem of the tested unit.
  20 * No summary of how different subsystems of the tested unit performed under in the test.
  21
  22 The above points should make it clear that it's preferable to split a [link ref_test_module test module] into smaller *units*.
  23 These units are the *test cases*, the *test suites* and the *fixtures*.
  24
  25 [variablelist Subjects covered by this section
  26   [
  27     [Declaration]
  28     [The __UTF__ supports several methods for declaring a [link boost_test.tests_organization.test_cases test case].
  29     Test cases can be implemented using free function like syntax or based on actual free function, function object,
  30     that can be defined with or without parameters/data, or as template functions to be run against various types. ]
  31   ]
  32   [
  33     [Organization]
  34     [The __UTF__ provides facilities to group several test cases into [link boost_test.tests_organization.test_tree.test_suite test suites].
  35     The test suites can be nested, and the set of test suites and test cases defines the [link boost_test.tests_organization.test_tree test tree],
  36     where the leaves are the test cases.
  37     Besides hierarchical structure the __UTF__ allows you to organize the test tree using [link boost_test.tests_organization.tests_grouping logical grouping]
  38     and [link boost_test.tests_organization.tests_dependencies dependencies]
  39     and provides you with controls to utilize the defined test tree organization the way you want (eg. from command line).
  40     ]
  41   ]
  42   [
  43     [Attributes]
  44     [It is possible to specify test unit /attributes/ by using [link boost_test.tests_organization.decorators decorators].
  45      Attributes are used for a fine grained control over various aspects of test module execution, such as /logical grouping/,
  46     /dependencies/, /expected failures/, etc.]
  47   ]
  48   [
  49     [Setup/teardown test unit actions]
  50     [When several tests shares the same set-up (environment, test data preparation, etc.), the preparation and cleanup code
  51      may be factorized in [link boost_test.tests_organization.fixtures fixtures].
  52      In the __UTF__, fixtures can be associated to test cases, test suites or globally to the test module.
  53     ]
  54   ]
  55 ]
  56
  57 [include test_cases.qbk]
  58 [include test_tree.qbk]
  59 [include decorators.qbk]
  60 [include fixtures.qbk]
  61 [include managing_tests_dependencies.qbk]
  62 [include logical_grouping.qbk]
  63 [include test_enabling_disabling.qbk]
  64 [include semantic.qbk]
  65 [include testorg_summary.qbk]
  66
  67 [endsect] [/ test organization]
  68
  69 [/EOF]