ceph/src/boost/libs/test/doc/test_organization/nullary_tests.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:test_organization_nullary Test cases without parameters]
   9
  10 The most common scenario is that you want to write test case without any parameters. The __UTF__ provides you with both
  11 automatic and manual registration APIs to declare such test case.
  12
  13 [#ref_BOOST_AUTO_TEST_CASE][h4 Automated registration]
  14
  15 To declare a test case without parameters, which is registered in place of implementation, employ the
  16 macro __BOOST_AUTO_TEST_CASE__.
  17
  18 ``
  19   __BOOST_AUTO_TEST_CASE__(test_case_name);
  20 ``
  21
  22 This API is designed to closely mimic nullary free function declaration syntax.
  23 In comparison with free function all you need to do is to skip result type and brackets and wrap test
  24 case name into BOOST_AUTO_TEST_CASE:
  25
  26 [bt_example example06..Nullary function based test case with automated registration..run]
  27
  28 With this macro you don't need to implement any other registration steps. The macro creates and
  29 registers the test case with the name `free_test_function` automatically.
  30
  31 [#ref_BOOST_TEST_CASE][h4 Manual registration]
  32
  33 The __UTF__ allows to manually create test case without parameters based on nullary free functions, nullary
  34 function objects (including those created with `boost::bind` and nullary `boost::function`
  35 instances). To do this, employ the macro __BOOST_TEST_CASE__:
  36
  37 ``
  38   BOOST_TEST_CASE(test_function);
  39 ``
  40
  41 __BOOST_TEST_CASE__ creates an instance of the class [classref boost::unit_test::test_case] and returns a pointer to the
  42 constructed instance. The test case name is deduced from the macro argument test_function. If you prefer to
  43 assign a different test case name, you have to use the underlying make_test_case interface instead. To
  44 register a new test case, employ the method [memberref boost::unit_test::test_suite::add `test_suite::add`].
  45 Both test case creation and registration are performed in the
  46 [link boost_test.adv_scenarios.test_module_init_overview test module initialization function].
  47
  48 Here is the simplest example of manually registered test case. A single test case is created and registered inside
  49 the test module initialization routine. Note that the free function name is passed by address to the macro __BOOST_TEST_CASE__`.
  50
  51 [#ref_bt_example01]
  52 [bt_example example01..Nullary free function manually registered..run]
  53
  54 A test case can be implemented as a method of a class. In this case a pointer to the class instance has to be
  55 bound to the test method to create a test case. You can use the same instance of the class for multiple test
  56 cases. The __UTF__ doesn't take an ownership of the class instance and you are required to manage the class
  57 instance lifetime yourself.
  58
  59 [warning
  60  The class instance can't be defined in the initialization function scope, since it becomes invalid as
  61  soon as the test execution exits it. It needs to be either defined statically/globally or managed using a
  62  shared pointer.
  63 ]
  64
  65 [bt_example example03..Nullary method of a class bound to shared class instance and manually registered..run-fail]
  66
  67 [endsect]
  68
  69 [/EOF]