Documentation update for the new macros

- BOOST_TEST_GLOBAL_FIXTURE explained - BOOST_TEST_GLOBAL_INITIALIZATION explained - changed the examples, deprecating BOOST_GLOBAL_FIXTURE - in the logger part, introduced the fact that BOOST_TEST_GLOBAL_INITIALIZATION should be used and no assertion is supported in this case
boostorg · Jun 23, 2017 · e1b211f · e1b211f
1 parent 5757d9c
commit e1b211f
Show file tree

Hide file tree

Showing 17 changed files with 251 additions and 124 deletions.
diff --git a/doc/adv_scenarios/link_reference.qbk b/doc/adv_scenarios/link_reference.qbk
@@ -8,6 +8,7 @@
 
 [section:link_references Build scenarios and behaviors]
 
+[/-----------------------------------------------------------------]
 [section:link_boost_test_main_macro `BOOST_TEST_MAIN`]
 
 When defined, this macro creates a stub for the test module initialization (the main entry part). This
@@ -25,6 +26,7 @@ macro also expands properly into a `main` function in case the shared library va
 
 [endsect]
 
+[/-----------------------------------------------------------------]
 [section:link_boost_test_module_macro `BOOST_TEST_MODULE`]
 Serves the same purpose as the macro __BOOST_TEST_MAIN__ but, in addition, defines the name of the master test suite.
 
@@ -39,21 +41,24 @@ An example may be found [link ref_BOOST_TEST_MODULE here].
 
 [endsect]
 
-
+[/-----------------------------------------------------------------]
 [section:link_boost_test_alternative_init_macro `BOOST_TEST_ALTERNATIVE_INIT_API`]
 
 [endsect]
 
+[/-----------------------------------------------------------------]
 [section:link_boost_test_no_lib `BOOST_TEST_NO_LIB`]
 Define this flag to prevent auto-linking.
 [note The same flag is used for the __UTF__ and the __PEM__ components.]
 [endsect]
 
+[/-----------------------------------------------------------------]
 [section:link_boost_test_dyn_link `BOOST_TEST_DYN_LINK`]
 Define this flag to link against the __UTF__ shared library.
 [note The same flag is used for the __UTF__ and the __PEM__ components.]
 [endsect]
 
+[/-----------------------------------------------------------------]
 [section:link_boost_test_no_main `BOOST_TEST_NO_MAIN`]
 Prevents the auto generation of the test module initialization functions. This macro is particularly relevant for
 manually registered tests in conjunction with dynamic variant of the __UTF__. When defined, a `main` function
@@ -84,6 +89,23 @@ int main(int argc, char* argv[])
 ``
 [endsect]
 
+[/-----------------------------------------------------------------]
+[section:link_boost_test_global_configuration `BOOST_TEST_GLOBAL_CONFIGURATION`]
+Declares a class that will be constructed during the initialization of the test framework, and destructed afterwards.
+The framework will not call any other member function than the constructor and destructor.
+In particular the constructor and destructor will be called prior and after to the [link boost_test.tests_organization.fixtures.global global fixtures]
+setup and teardown.
+
+This facility is provided to perform additional configuration, in particular programmatic configuration
+of the loggers and reporters. See [link boost_test.test_output.logging_api this section] for more details.
+
+[warning No logging or any other call to the framework assertion is allowed in the constructor and destructor, as its purpose is
+ to set-up the loggers/reporters, and the assertions are calling the logging/reporting facility.
+ Any such assertion during the execution of the will result in the abortion of the test module .]
+
+[endsect]
+
+[/-----------------------------------------------------------------]
 [section:config_disable_alt_stack `BOOST_TEST_DISABLE_ALT_STACK`]
 Disables the support of the alternative stack.
 

diff --git a/doc/examples/example20.run.cpp b/doc/examples/example20.run.cpp
@@ -19,7 +19,7 @@ struct MyConfig {
 
 //____________________________________________________________________________//
 
-BOOST_GLOBAL_FIXTURE( MyConfig );
+BOOST_TEST_GLOBAL_FIXTURE( MyConfig );
 
 BOOST_AUTO_TEST_CASE( test_case )
 {

diff --git a/doc/examples/example50.output b/doc/examples/example50.output
@@ -4,5 +4,5 @@
 *** 1 failures is detected in test suite "example"
 > cat example.log
 Running 1 test case...
-test.cpp(20): error in "test_case": check false failed
-//]
+test.cpp(26): error in "test_case": check false failed
+//]
diff --git a/doc/examples/example50.run-fail.cpp b/doc/examples/example50.run-fail.cpp
@@ -10,25 +10,19 @@
 #include <boost/test/included/unit_test.hpp>
 #include <fstream>
 
-struct MyConfig 
-{
-  MyConfig() : test_log( "example.log" )  
-  { 
-    boost::unit_test::unit_test_log.set_stream( test_log ); 
+struct MyConfig {
+  MyConfig() : test_log( "example.log" ) {
+    boost::unit_test::unit_test_log.set_stream( test_log );
   }
-  ~MyConfig()
-  { 
-    boost::unit_test::unit_test_log.set_stream( std::cout ); 
+  ~MyConfig() {
+    boost::unit_test::unit_test_log.set_stream( std::cout );
   }
-
   std::ofstream test_log;
 };
 
-BOOST_GLOBAL_FIXTURE( MyConfig );
+BOOST_TEST_GLOBAL_CONFIGURATION( MyConfig );
 
-BOOST_AUTO_TEST_CASE( test_case )
-{
+BOOST_AUTO_TEST_CASE( test_case ) {
   BOOST_TEST( false );
 }
-
 //]
diff --git a/doc/examples/example52.output b/doc/examples/example52.output
@@ -1,4 +1,4 @@
 //[example_output
 > example --report_level=no
-<TestLog><Error file="test.cpp" line="18">check false failed</Error></TestLog>
-//]
+<TestLog><Error file="test.cpp" line="23">check false failed</Error></TestLog>
+//]
diff --git a/doc/examples/example52.run-fail.cpp b/doc/examples/example52.run-fail.cpp
@@ -11,17 +11,15 @@
 using namespace boost::unit_test;
 
 struct MyConfig {
-  MyConfig()
-  {
+  MyConfig() {
     unit_test_log.set_format( OF_XML );
   }
   ~MyConfig() {}
 };
 
-BOOST_GLOBAL_FIXTURE( MyConfig );
+BOOST_TEST_GLOBAL_CONFIGURATION( MyConfig );
 
-BOOST_AUTO_TEST_CASE( test_case0 )
-{
+BOOST_AUTO_TEST_CASE( test_case0 ) {
   BOOST_TEST( false );
 }
 //]
diff --git a/doc/examples/fixture_04.output b/doc/examples/fixture_04.output
@@ -0,0 +1,13 @@
+//[example_output
+> fixture_04 --log_level=message
+Running 2 test cases...
+ctor fixture i=0
+setup fixture i=0
+running test_case1
+running test_case2
+./fixture_04.run-fail.cpp:42: error: in "test_case2": check MyGlobalFixture::i == 3 has failed [1 != 3]
+teardown fixture i=1
+dtor fixture i=3
+
+*** 1 failure is detected in the test module "fixture_04"
+//]
diff --git a/doc/examples/fixture_04.run-fail.cpp b/doc/examples/fixture_04.run-fail.cpp
@@ -0,0 +1,44 @@
+//  (C) Copyright Raffi Enficiaud 2017.
+//  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)
+
+//  See http://www.boost.org/libs/test for the library home page.
+
+//[example_code
+#define BOOST_TEST_MODULE fixture_04
+#include <boost/test/included/unit_test.hpp>
+
+struct MyGlobalFixture {
+  MyGlobalFixture() {
+      BOOST_TEST_MESSAGE( "ctor fixture i=" << i );
+  }
+  void setup() {
+      BOOST_TEST_MESSAGE( "setup fixture i=" << i );
+      i++;
+  }
+  void teardown() {
+      BOOST_TEST_MESSAGE( "teardown fixture i=" << i );
+      i += 2;
+  }
+  ~MyGlobalFixture() {
+      BOOST_TEST_MESSAGE( "dtor fixture i=" << i );
+  }
+  static int i;
+};
+int MyGlobalFixture::i = 0;
+
+BOOST_TEST_GLOBAL_FIXTURE( MyGlobalFixture );
+
+BOOST_AUTO_TEST_CASE(test_case1)
+{
+  BOOST_TEST_MESSAGE("running test_case1");
+  BOOST_TEST(MyGlobalFixture::i == 1);
+}
+
+BOOST_AUTO_TEST_CASE(test_case2)
+{
+  BOOST_TEST_MESSAGE("running test_case2");
+  BOOST_TEST(MyGlobalFixture::i == 3);
+}
+//]
diff --git a/doc/test.qbk b/doc/test.qbk
@@ -45,6 +45,7 @@
 [def __BOOST_TEST_NO_LIB__                [link boost_test.utf_reference.link_references.link_boost_test_no_lib                 `BOOST_TEST_NO_LIB`]]
 [def __BOOST_TEST_NO_MAIN__               [link boost_test.utf_reference.link_references.link_boost_test_no_main                `BOOST_TEST_NO_MAIN`]]
 [def __BOOST_TEST_MODULE__                [link boost_test.utf_reference.link_references.link_boost_test_module_macro           `BOOST_TEST_MODULE`]]
+[def __BOOST_TEST_GLOBAL_CONFIGURATION__  [link boost_test.utf_reference.link_references.link_boost_test_global_configuration   `BOOST_TEST_GLOBAL_CONFIGURATION`]]
 
 [def __BOOST_TEST_CHECKPOINT__            [link boost_test.utf_reference.testout_reference.test_output_macro_checkpoint   `BOOST_TEST_CHECKPOINT`]]
 [def __BOOST_TEST_PASSPOINT__             [link boost_test.utf_reference.testout_reference.test_output_macro_passpoint    `BOOST_TEST_PASSPOINT`]]
@@ -116,7 +117,8 @@
 [/ fixtures]
 [def __BOOST_FIXTURE_TEST_CASE__                [link boost_test.utf_reference.test_org_reference.test_org_boost_test_case_fixture     `BOOST_FIXTURE_TEST_CASE`]]
 [def __BOOST_FIXTURE_TEST_SUITE__               [link boost_test.utf_reference.test_org_reference.test_org_boost_test_suite_fixture    `BOOST_FIXTURE_TEST_SUITE`]]
-[def __BOOST_GLOBAL_FIXTURE__                   [link boost_test.utf_reference.test_org_reference.test_org_boost_global_fixture   `BOOST_GLOBAL_FIXTURE`]]
+[def __BOOST_GLOBAL_FIXTURE__                   [link boost_test.utf_reference.test_org_reference.test_org_boost_global_fixture        `BOOST_GLOBAL_FIXTURE`]]
+[def __BOOST_TEST_GLOBAL_FIXTURE__              [link boost_test.utf_reference.test_org_reference.test_org_boost_test_global_fixture   `BOOST_TEST_GLOBAL_FIXTURE`]]
 
 [/ log]
 [def __BOOST_TEST_LOG_LEVEL__                   [link boost_test.utf_reference.rt_param_reference.log_level `BOOST_TEST_LOG_LEVEL`]] [/ this is an environment variable]