libs/test/doc/test_organization/testorg_reference.qbk
[/ / Copyright (c) 2003 Boost.Test contributors / / Distributed under the Boost Software License, Version 1.0. (See accompanying / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) /] [section:test_org_reference Tests declaration and organization] [/ Test cases ###############################################################################################] [section:test_org_boost_test_case `BOOST_TEST_CASE` and `BOOST_TEST_CASE_NAME`] Creates a test case for manual registration. The registration in the test tree should be performed manually. See [link ref_BOOST_TEST_CASE here] for more details. [endsect] [/section:test_org_boost_test_case] [section:test_org_boost_auto_test_case `BOOST_AUTO_TEST_CASE`] Declares and registers automatically a test case. See [link ref_BOOST_AUTO_TEST_CASE here] for more details. [endsect] [/section:test_org_boost_auto_test_case] [section:test_org_boost_test_case_auto_template `BOOST_AUTO_TEST_CASE_TEMPLATE`] Declares and registers automatically a typed test case. See [link ref_BOOST_AUTO_TEST_CASE_TEMPLATE here] for more details. [endsect] [/section:test_org_boost_test_case_auto_template] [section:test_org_boost_test_case_template `BOOST_TEST_CASE_TEMPLATE`] Creates a typed test case. The test case should have been declared with the macro __BOOST_TEST_CASE_TEMPLATE_FUNCTION__. The registration in the test tree should be performed manually. See [link ref_BOOST_TEST_CASE_TEMPLATE here] for more details. [endsect] [/section:test_org_boost_test_case_template] [section:test_org_boost_test_case_template_function `BOOST_TEST_CASE_TEMPLATE_FUNCTION`] Declares a typed test case. The registration in the test tree should be performed manually, using the macro __BOOST_TEST_CASE_TEMPLATE__. See [link ref_BOOST_TEST_CASE_TEMPLATE here] for more details. [endsect] [/section:test_org_boost_test_case_template_function] [section:test_org_boost_test_case_parameter `BOOST_PARAM_TEST_CASE`] Declares and registers automatically a test case with one parameter. See [link boost_test.tests_organization.test_cases.param_test here] for more details. [endsect] [/section:test_org_boost_test_case_parameter] [section:test_org_boost_test_dataset `BOOST_DATA_TEST_CASE`] Declares and registers a data-driven test case, using a particular dataset. Several forms of the macro are available. `` BOOST_DATA_TEST_CASE(test_case_name, dataset) { BOOST_TEST(sample != 0); } `` should be used for datasets with arity 1. In the body of the test case, the samples of the dataset are taken by the variable `sample`. `` BOOST_DATA_TEST_CASE(test_case_name, dataset, var1) { BOOST_TEST(var1 != 0); } `` same as the first form, but the samples are taken by the variable `var1` instead of the variable `sample` `` BOOST_DATA_TEST_CASE(test_case_name, dataset, var1, var2..., varN) { BOOST_TEST(var1 != 0); //... BOOST_TEST(varN != 0); } `` same as the second form, but for dataset of arity `N`. For compilers *lacking the variadic template* support, the maximal arity (the maximal value of `N`) is controlled by the macro `BOOST_TEST_DATASET_MAX_ARITY` which is set to `10` by default. If you need a greater value, define `BOOST_TEST_DATASET_MAX_ARITY` to the desired value *before* including the __UTF__ headers. See [link boost_test.tests_organization.test_cases.test_case_generation.datasets_auto_registration here] for more details. [endsect] [/section:test_org_boost_test_dataset] [section:test_org_boost_test_dataset_fixture `BOOST_DATA_TEST_CASE_F`] Declares and registers a data-driven test case, using a particular dataset and a fixture. This is basically the same as __BOOST_DATA_TEST_CASE__ with fixture support added. `` struct my_fixture { my_fixture() : some_string("environment X") { } std::string some_string; }; BOOST_DATA_TEST_CASE_F(my_fixture, test_case_name, dataset, var1, var2..., varN) { BOOST_TEST(var1 != 0); //... BOOST_TEST(varN != 0); } `` The fixture should implement the appropriate [link boost_test.tests_organization.fixtures.models interface]. As any fixture, it is possible to have test assertions in the fixture class. See [link boost_test.tests_organization.fixtures.case here] for more details on fixtures and [link boost_test.tests_organization.test_cases.test_case_generation.datasets_auto_registration here] for more details on datasets declaration. [endsect] [/section:test_org_boost_test_dataset_fixture] [/ Test suites ###############################################################################################] [section:test_org_boost_test_suite `BOOST_TEST_SUITE`] Creates a test suite. The created test suite should be added to the test tree manually. See [link ref_BOOST_TEST_SUITE here] for more details. [endsect] [/section:test_org_boost_test_suite] [section:test_org_boost_auto_test_suite `BOOST_AUTO_TEST_SUITE`] Indicates the beginning of a test suite. Test suites can be nested. See [link ref_BOOST_AUTO_TEST_SUITE here] for more details. [endsect] [/section:test_org_boost_auto_test_suite] [section:test_org_boost_auto_test_suite_end `BOOST_AUTO_TEST_SUITE_END`] Indicates the end of a test suite. Test suites can be nested. This macro should appear as many times as there is a __BOOST_AUTO_TEST_SUITE__. See [link ref_BOOST_AUTO_TEST_SUITE here] for more details. [endsect] [/section:test_org_boost_auto_test_suite_end] [/ Fixtures ###############################################################################################] [/-----------------------------------------------------------------] [section:test_org_boost_test_case_fixture `BOOST_FIXTURE_TEST_CASE`] Declares and registers a test case that uses a fixture. The class implementing the fixture should have the appropriate [link boost_test.tests_organization.fixtures.models interface]. As any fixture, it is possible to have test assertions in the fixture class. See [link boost_test.tests_organization.fixtures.case here] for more details. [endsect] [/section:test_org_boost_test_case_fixture] [/-----------------------------------------------------------------] [section:test_org_boost_test_suite_fixture `BOOST_FIXTURE_TEST_SUITE`] Declares and registers a fixture used by all test cases under a test suite. Each test case in the subtree of the test suite uses the fixture. The class implementing the fixture should have the appropriate [link boost_test.tests_organization.fixtures.models interface]. As any fixture, it is possible to have test assertions in the fixture class. See [link boost_test.tests_organization.fixtures.case here] for more details. [endsect] [/section:test_org_boost_test_case_fixture] [/-----------------------------------------------------------------] [section:test_org_boost_global_fixture `BOOST_GLOBAL_FIXTURE`] This macro is deprecated in favor of __BOOST_TEST_GLOBAL_FIXTURE__ and __BOOST_TEST_GLOBAL_CONFIGURATION__. [endsect] [/section:test_org_boost_test_case_fixture] [/-----------------------------------------------------------------] [section:test_org_boost_test_global_fixture `BOOST_TEST_GLOBAL_FIXTURE`] Declares and registers a global fixture. The global fixture acts exactly as a suite fixture attached to the [link boost_test.tests_organization.test_tree.master_test_suite master test suite], and is called before any of the test case in the test tree is executed. The class implementing the fixture should have the appropriate [link boost_test.tests_organization.fixtures.models interface]. As any fixture, it is possible to have test assertions in the global fixture. See [link boost_test.tests_organization.fixtures.global here] for more details. [endsect] [/section:test_org_boost_test_global_fixture] [/ Decorators ##############################################################################################] [section:test_org_boost_test_decorator `BOOST_TEST_DECORATOR`] Defines ['decorators] for a test unit. See [link boost_test.tests_organization.decorators here] for more details. [endsect] [/section:test_org_boost_test_decorator] [/-----------------------------------------------------------------] [section:decorator_depends_on depends_on (decorator)] `` depends_on(const_string dependent_test_name); `` Indicates a dependency from the decorated test unit (the child) to the designed test unit `dependent_test_name` (the parent). See [link boost_test.tests_organization.tests_dependencies here] for more details. [endsect] [/ section decorator_depends_on] [/-----------------------------------------------------------------] [section:decorator_description description (decorator)] `` description(const_string message); `` Attaches an arbitrary string to the test unit. See [link boost_test.tests_organization.semantic here] for more details. [endsect] [/ decorator description] [/-----------------------------------------------------------------] [section:decorator_enabled enabled / disabled (decorator)] `` enabled(); disabled(); `` Sets the test unit's __default_run_status__ to ['true] or ['false]. See [link boost_test.tests_organization.enabling here] for more details. [endsect] [/ section:decorator_enabled] [/-----------------------------------------------------------------] [section:decorator_enable_if enable_if (decorator)] `` template <bool Condition> enable_if(); `` Sets the test unit's __default_run_status__ to ['true] or ['false], depending on a compilation-time constant. See [link boost_test.tests_organization.enabling here] for more details. [endsect] [/ section enable_if] [/-----------------------------------------------------------------] [section:decorator_fixture fixture (decorator)] `` fixture(const boost::function<void()>& setup, const boost::function<void()>& teardown = {}); template <typename Fx> fixture<Fx>(); template <typename Fx, typename Arg> fixture<Fx>(const Arg& arg); `` Decorator `fixture` specifies a pair of functions (like `set_up` and `tear_down`) to be called before and after the corresponding test unit. At the suite level the `set_up` function is called once -- before the suite execution starts -- and `tear_down` function is called once -- after the suite execution ends. It comes in three forms. First expects two functions for set-up and tear-down (the second one can be skipped). The second expects a `DefaultConstructible` class. Its default constructor will be used as set-up function and its destructor as a tear-down function. The third form requires a class with one-argument public constructor. Argument `arg` is forwarded to the constructor. For the second and third form, the framework detects if there is a `setup` and/or `teardown` function implemented in the class, with the same declaration as described in the [link boost_test.tests_organization.fixtures.models fixture model]. If those member function are declared, they will be called right after construction and just before destruction respectively. [note There is no way to get access to the members of these fixtures from within the test case or test suite.] [bt_example decorator_12..decorator fixture..run] For other ways of using fixtures, see [link boost_test.tests_organization.fixtures here]. [endsect] [/ section fixture] [/-----------------------------------------------------------------] [section:decorator_label label (decorator)] `` label(const_string label_name); `` Associates a test unit with label `label_name`. It is possible to associate more than one label with a test unit. See [link boost_test.tests_organization.tests_grouping here] for more details. [endsect] [/ section label] [/-----------------------------------------------------------------] [section:decorator_precondition precondition (decorator)] [def __class_assertion_result__ [classref boost::test_tools::assertion_result test_tools::assertion_result]] `` typedef boost::function<__class_assertion_result__ (test_unit_id)> predicate_t; precondition(predicate_t predicate); `` Associates a ['predicate] with a test unit that will determine its __default_run_status__ at run-time. See [link boost_test.tests_organization.enabling here] for more details. [endsect] [/ section decorator_precondition] [endsect] [/reference test organization]