ceph/src/boost/boost/test/framework.hpp

   1 //  (C) Copyright Gennadiy Rozental 2001.
   2 //  Distributed under the Boost Software License, Version 1.0.
   3 //  (See accompanying file LICENSE_1_0.txt or copy at
   4 //  http://www.boost.org/LICENSE_1_0.txt)
   5
   6 //  See http://www.boost.org/libs/test for the library home page.
   7 //
   8 //!@file
   9 //!@brief Defines Unit Test Framework mono-state interfaces.
  10 //! The framework interfaces are based on Monostate design pattern.
  11 // ***************************************************************************
  12
  13 #ifndef BOOST_TEST_FRAMEWORK_HPP_020805GER
  14 #define BOOST_TEST_FRAMEWORK_HPP_020805GER
  15
  16 // Boost.Test
  17 #include <boost/test/detail/global_typedef.hpp>
  18 #include <boost/test/detail/fwd_decl.hpp>
  19 #include <boost/test/detail/throw_exception.hpp>
  20
  21 #include <boost/test/utils/trivial_singleton.hpp>
  22
  23 #include <boost/test/detail/suppress_warnings.hpp>
  24
  25 // STL
  26 #include <stdexcept>
  27
  28 //____________________________________________________________________________//
  29
  30 namespace boost {
  31
  32 /// Main namespace for the Unit Test Framework interfaces and implementation
  33 namespace unit_test {
  34
  35 // ************************************************************************** //
  36 // **************              init_unit_test_func             ************** //
  37 // ************************************************************************** //
  38
  39 /// Test module initialization routine signature
  40
  41 /// Different depending on whether BOOST_TEST_ALTERNATIVE_INIT_API is defined or not
  42 #ifdef BOOST_TEST_ALTERNATIVE_INIT_API
  43 typedef bool        (*init_unit_test_func)();
  44 #else
  45 typedef test_suite* (*init_unit_test_func)( int, char* [] );
  46 #endif
  47
  48 // ************************************************************************** //
  49 // **************                   framework                  ************** //
  50 // ************************************************************************** //
  51
  52 /// Namespace of the Unit Test Framework mono-state
  53 namespace framework {
  54
  55 /// @name Unit Test Framework initialization and shutdown
  56 /// @{
  57
  58 /// @brief This function performs initialization of the framework mono-state.
  59 ///
  60 /// It needs to be called every time before the test is started.
  61 /// @param[in] init_func test module initialization routine
  62 /// @param[in] argc command line arguments collection
  63 /// @param[in] argv command line arguments collection
  64 BOOST_TEST_DECL void                init( init_unit_test_func init_func, int argc, char* argv[] );
  65
  66 /// This function applies all the decorators and figures out default run status. This argument facilitates an
  67 /// ability of the test cases to prepare some other test units (primarily used internally for self testing).
  68 /// @param[in] tu Optional id of the test unit representing root of test tree. If absent, master test suite is used
  69 BOOST_TEST_DECL void                finalize_setup_phase( test_unit_id tu = INV_TEST_UNIT_ID);
  70
  71 /// This function returns true when testing is in progress (setup is finished).
  72 BOOST_TEST_DECL bool                test_in_progress();
  73
  74 /// This function shuts down the framework and clears up its mono-state.
  75 ///
  76 /// It needs to be at the very end of test module execution
  77 BOOST_TEST_DECL void                shutdown();
  78 /// @}
  79
  80 /// @name Test unit registration
  81 /// @{
  82
  83 /// Provides both read and write access to current "leaf" auto test suite during the test unit registration phase.
  84 ///
  85 /// During auto-registration phase the framework maintain a FIFO queue of test units being registered. New test units become children
  86 /// of the current "leaf" test suite and if this is test suite it is pushed back into queue and becomes a new leaf.
  87 /// When test suite registration is completed, a test suite is popped from the back of the queue. Only automatically registered test suites
  88 /// should be added to this queue. Master test suite is always a zero element in this queue, so if no other test suites are registered
  89 /// all test cases are added to master test suite.
  90
  91 /// This function facilitates all three possible actions:
  92 ///    - if no argument are provided it returns the current queue leaf test suite
  93 ///    - if test suite is provided and no second argument are set, test suite is added to the queue
  94 ///    - if no test suite are provided and last argument is false, the semantic of this function is similar to queue pop: last element is popped from the queue
  95 /// @param[in] ts test suite to push back to the queue
  96 /// @param[in] push_or_pop should we push ts to the queue or pop leaf test suite instead
  97 /// @returns a reference to the currently active/"leaf" test suite
  98 BOOST_TEST_DECL test_suite&         current_auto_test_suite( test_suite* ts = 0, bool push_or_pop = true );
  99
 100 /// This function add new test case into the global collection of test units the framework aware of.
 101
 102 /// This function also assignes unique test unit id for every test case. Later on one can use this id to locate
 103 /// the test case if necessary. This is the way for the framework to maintain weak references between test units.
 104 /// @param[in]  tc  test case to register
 105 BOOST_TEST_DECL void                register_test_unit( test_case* tc );
 106
 107 /// This function add new test suite into the global collection of test units the framework aware of.
 108
 109 /// This function also assignes unique test unit id for every test suite. Later on one can use this id to locate
 110 /// the test case if necessary. This is the way for the framework to maintain weak references between test units.
 111 /// @param[in]  ts  test suite to register
 112 BOOST_TEST_DECL void                register_test_unit( test_suite* ts );
 113
 114 /// This function removes the test unit from the collection of known test units and destroys the test unit object.
 115
 116 /// This function also assigns unique test unit id for every test case. Later on one can use this id to located
 117 /// the test case if necessary. This is the way for the framework to maintain weak references between test units.
 118 /// @param[in]  tu  test unit to deregister
 119 BOOST_TEST_DECL void                deregister_test_unit( test_unit* tu );
 120
 121 // This function clears up the framework mono-state.
 122
 123 /// After this call the framework can be reinitialized to perform a second test run during the same program lifetime.
 124 BOOST_TEST_DECL void                clear();
 125 /// @}
 126
 127 /// @name Test observer registration
 128 /// @{
 129 /// Adds new test execution observer object into the framework's list of test observers.
 130
 131 /// Observer lifetime should exceed the the testing execution timeframe
 132 /// @param[in]  to  test observer object to add
 133 BOOST_TEST_DECL void                register_observer( test_observer& to );
 134
 135 /// Excludes the observer object form the framework's list of test observers
 136 /// @param[in]  to  test observer object to exclude
 137 BOOST_TEST_DECL void                deregister_observer( test_observer& to );
 138
 139 /// @}
 140
 141 /// @name Global fixtures registration
 142 /// @{
 143
 144 /// Adds a new global fixture to be setup before any other tests starts and tore down after
 145 /// any other tests finished.
 146 /// Test unit fixture lifetime should exceed the testing execution timeframe
 147 /// @param[in]  tuf  fixture to add
 148 BOOST_TEST_DECL void                register_global_fixture( test_unit_fixture& tuf );
 149
 150 /// Removes a test global fixture from the framework
 151 ///
 152 /// Test unit fixture lifetime should exceed the testing execution timeframe
 153 /// @param[in]  tuf  fixture to remove
 154 BOOST_TEST_DECL void                deregister_global_fixture( test_unit_fixture& tuf );
 155 /// @}
 156
 157 /// @name Assertion/uncaught exception context support
 158 /// @{
 159 /// Context accessor
 160 struct BOOST_TEST_DECL context_generator {
 161     context_generator() : m_curr_frame( 0 ) {}
 162
 163     /// Is there any context?
 164     bool            is_empty() const;
 165
 166     /// Give me next frame; empty - last frame
 167     const_string    next() const;
 168
 169 private:
 170     // Data members
 171     mutable unsigned m_curr_frame;
 172 };
 173
 174 /// Records context frame message.
 175
 176 /// Some context frames are sticky - they can only explicitly cleared by specifying context id. Other (non sticky) context frames cleared after every assertion.
 177 /// @param[in] context_descr context frame message
 178 /// @param[in] sticky is this sticky frame or not
 179 /// @returns id of the newly created frame
 180 BOOST_TEST_DECL int                 add_context( lazy_ostream const& context_descr, bool sticky );
 181 /// Erases context frame (when test exits context scope)
 182
 183 /// If context_id is passed clears that specific context frame identified by this id, otherwise clears all non sticky contexts.
 184 BOOST_TEST_DECL void                clear_context( int context_id = -1 );
 185 /// Produces an instance of small "delegate" object, which facilitates access to collected context.
 186 BOOST_TEST_DECL context_generator   get_context();
 187 /// @}
 188
 189 /// @name Access to registered test units.
 190 /// @{
 191 /// This function provides access to the master test suite.
 192
 193 /// There is only only master test suite per test module.
 194 /// @returns a reference the master test suite instance
 195 BOOST_TEST_DECL master_test_suite_t& master_test_suite();
 196
 197 /// This function provides an access to the test unit currently being executed.
 198
 199 /// The difference with current_test_case is about the time between a test-suite
 200 /// is being set up or torn down (fixtures) and when the test-cases of that suite start.
 201
 202 /// This function is only valid during test execution phase.
 203 /// @see current_test_case_id, current_test_case
 204 BOOST_TEST_DECL test_unit const&    current_test_unit();
 205
 206 /// This function provides an access to the test case currently being executed.
 207
 208 /// This function is only valid during test execution phase.
 209 /// @see current_test_case_id
 210 BOOST_TEST_DECL test_case const&    current_test_case();
 211
 212 /// This function provides an access to an id of the test case currently being executed.
 213
 214 /// This function safer than current_test_case, cause if wont throw if no test case is being executed.
 215 /// @see current_test_case
 216 BOOST_TEST_DECL test_unit_id        current_test_case_id(); /* safe version of above */
 217
 218 /// This function provides access to a test unit by id and type combination. It will throw if no test unit located.
 219 /// @param[in]  tu_id    id of a test unit to locate
 220 /// @param[in]  tu_type  type of a test unit to locate
 221 /// @returns located test unit
 222 BOOST_TEST_DECL test_unit&          get( test_unit_id tu_id, test_unit_type tu_type );
 223
 224 /// This function template provides access to a typed test unit by id
 225
 226 /// It will throw if you specify incorrect test unit type
 227 /// @tparam UnitType compile time type of test unit to get (test_suite or test_case)
 228 /// @param  id id of test unit to get
 229 template<typename UnitType>
 230 inline UnitType&                    get( test_unit_id id )
 231 {
 232     return static_cast<UnitType&>( get( id, static_cast<test_unit_type>(UnitType::type) ) );
 233 }
 234 ///@}
 235
 236 /// @name Test initiation interface
 237 /// @{
 238
 239 /// Initiates test execution
 240
 241 /// This function is used to start the test execution from a specific "root" test unit.
 242 /// If no root provided, test is started from master test suite. This second argument facilitates an ability of the test cases to
 243 /// start some other test units (primarily used internally for self testing).
 244 /// @param[in] tu Optional id of the test unit or test unit itself from which the test is started. If absent, master test suite is used
 245 /// @param[in] continue_test true == continue test if it was already started, false == restart the test from scratch regardless
 246 BOOST_TEST_DECL void                run( test_unit_id tu = INV_TEST_UNIT_ID, bool continue_test = true );
 247 /// Initiates test execution. Same as other overload
 248 BOOST_TEST_DECL void                run( test_unit const* tu, bool continue_test = true );
 249 /// @}
 250
 251 /// @name Test events dispatchers
 252 /// @{
 253 /// Reports results of assertion to all test observers
 254 BOOST_TEST_DECL void                assertion_result( unit_test::assertion_result ar );
 255 /// Reports uncaught exception to all test observers
 256 BOOST_TEST_DECL void                exception_caught( execution_exception const& );
 257 /// Reports aborted test unit to all test observers
 258 BOOST_TEST_DECL void                test_unit_aborted( test_unit const& );
 259 /// Reports aborted test module to all test observers
 260 BOOST_TEST_DECL void                test_aborted( );
 261 /// @}
 262
 263 namespace impl {
 264 // exclusively for self test
 265 BOOST_TEST_DECL void                setup_for_execution( test_unit const& );
 266 BOOST_TEST_DECL void                setup_loggers( );
 267 } // namespace impl
 268
 269 // ************************************************************************** //
 270 // **************                framework errors              ************** //
 271 // ************************************************************************** //
 272
 273 /// This exception type is used to report internal Boost.Test framework errors.
 274 struct BOOST_TEST_DECL internal_error : public std::runtime_error {
 275     internal_error( const_string m ) : std::runtime_error( std::string( m.begin(), m.size() ) ) {}
 276 };
 277
 278 //____________________________________________________________________________//
 279
 280 /// This exception type is used to report test module setup errors.
 281 struct BOOST_TEST_DECL setup_error : public std::runtime_error {
 282     setup_error( const_string m ) : std::runtime_error( std::string( m.begin(), m.size() ) ) {}
 283 };
 284
 285 #define BOOST_TEST_SETUP_ASSERT( cond, msg ) BOOST_TEST_I_ASSRT( cond, unit_test::framework::setup_error( msg ) )
 286
 287 //____________________________________________________________________________//
 288
 289 struct nothing_to_test {
 290     explicit    nothing_to_test( int rc ) : m_result_code( rc ) {}
 291
 292     int         m_result_code;
 293 };
 294
 295 //____________________________________________________________________________//
 296
 297 } // namespace framework
 298 } // unit_test
 299 } // namespace boost
 300
 301 #include <boost/test/detail/enable_warnings.hpp>
 302
 303 #endif // BOOST_TEST_FRAMEWORK_HPP_020805GER