UnitTests/cppunit/include/cppunit/extensions/HelperMacros.h

   1 // //////////////////////////////////////////////////////////////////////////
   2 // Header file HelperMacros.h
   3 // (c)Copyright 2000, Baptiste Lepilleur.
   4 // Created: 2001/04/15
   5 // //////////////////////////////////////////////////////////////////////////
   6 #ifndef CPPUNIT_EXTENSIONS_HELPERMACROS_H
   7 #define CPPUNIT_EXTENSIONS_HELPERMACROS_H
   8
   9 #include <cppunit/TestCaller.h>
  10 #include <cppunit/TestSuite.h>
  11 #include <cppunit/extensions/AutoRegisterSuite.h>
  12 #include <cppunit/extensions/ExceptionTestCaseDecorator.h>
  13 #include <cppunit/extensions/TestFixtureFactory.h>
  14 #include <cppunit/extensions/TestNamer.h>
  15 #include <cppunit/extensions/TestSuiteBuilderContext.h>
  16 #include <memory>
  17
  18
  19 /*! \addtogroup WritingTestFixture Writing test fixture
  20  */
  21 /** @{
  22  */
  23
  24
  25 /** \file
  26  * Macros intended to ease the definition of test suites.
  27  *
  28  * The macros
  29  * CPPUNIT_TEST_SUITE(), CPPUNIT_TEST(), and CPPUNIT_TEST_SUITE_END()
  30  * are designed to facilitate easy creation of a test suite.
  31  * For example,
  32  *
  33  * \code
  34  * #include <cppunit/extensions/HelperMacros.h>
  35  * class MyTest : public CppUnit::TestFixture {
  36  *   CPPUNIT_TEST_SUITE( MyTest );
  37  *   CPPUNIT_TEST( testEquality );
  38  *   CPPUNIT_TEST( testSetName );
  39  *   CPPUNIT_TEST_SUITE_END();
  40  * public:
  41  *   void testEquality();
  42  *   void testSetName();
  43  * };
  44  * \endcode
  45  *
  46  * The effect of these macros is to define two methods in the
  47  * class MyTest.  The first method is an auxiliary function
  48  * named registerTests that you will not need to call directly.
  49  * The second function
  50  * \code static CppUnit::TestSuite *suite()\endcode
  51  * returns a pointer to the suite of tests defined by the CPPUNIT_TEST()
  52  * macros.
  53  *
  54  * Rather than invoking suite() directly,
  55  * the macro CPPUNIT_TEST_SUITE_REGISTRATION() is
  56  * used to create a static variable that automatically
  57  * registers its test suite in a global registry.
  58  * The registry yields a Test instance containing all the
  59  * registered suites.
  60  * \code
  61  * CPPUNIT_TEST_SUITE_REGISTRATION( MyTest );
  62  * CppUnit::Test* tp =
  63  *   CppUnit::TestFactoryRegistry::getRegistry().makeTest();
  64  * \endcode
  65  *
  66  * The test suite macros can even be used with templated test classes.
  67  * For example:
  68  *
  69  * \code
  70  * template<typename CharType>
  71  * class StringTest : public CppUnit::TestFixture {
  72  *   CPPUNIT_TEST_SUITE( StringTest );
  73  *   CPPUNIT_TEST( testAppend );
  74  *   CPPUNIT_TEST_SUITE_END();
  75  * public:
  76  *   ...
  77  * };
  78  * \endcode
  79  *
  80  * You need to add in an implementation file:
  81  *
  82  * \code
  83  * CPPUNIT_TEST_SUITE_REGISTRATION( StringTest<char> );
  84  * CPPUNIT_TEST_SUITE_REGISTRATION( StringTest<wchar_t> );
  85  * \endcode
  86  */
  87
  88
  89 /*! \brief Begin test suite
  90  *
  91  * This macro starts the declaration of a new test suite.
  92  * Use CPPUNIT_TEST_SUB_SUITE() instead, if you wish to include the
  93  * test suite of the parent class.
  94  *
  95  * \param ATestFixtureType Type of the test case class. This type \b MUST
  96  *                         be derived from TestFixture.
  97  * \see CPPUNIT_TEST_SUB_SUITE, CPPUNIT_TEST, CPPUNIT_TEST_SUITE_END,
  98  * \see CPPUNIT_TEST_SUITE_REGISTRATION, CPPUNIT_TEST_EXCEPTION, CPPUNIT_TEST_FAIL.
  99  */
 100 #define CPPUNIT_TEST_SUITE( ATestFixtureType )                              \
 101   public:                                                                   \
 102     typedef ATestFixtureType TestFixtureType;                               \
 103                                                                             \
 104   private:                                                                  \
 105     static const CPPUNIT_NS::TestNamer &getTestNamer__()                    \
 106     {                                                                       \
 107       static CPPUNIT_TESTNAMER_DECL( testNamer, ATestFixtureType );         \
 108       return testNamer;                                                     \
 109     }                                                                       \
 110                                                                             \
 111   public:                                                                   \
 112     typedef CPPUNIT_NS::TestSuiteBuilderContext<TestFixtureType>            \
 113                 TestSuiteBuilderContextType;                                \
 114                                                                             \
 115     static void                                                             \
 116     addTestsToSuite( CPPUNIT_NS::TestSuiteBuilderContextBase &baseContext ) \
 117     {                                                                       \
 118       TestSuiteBuilderContextType context( baseContext )
 119
 120
 121 /*! \brief Begin test suite (includes parent suite)
 122  *
 123  * This macro may only be used in a class whose parent class
 124  * defines a test suite using CPPUNIT_TEST_SUITE() or CPPUNIT_TEST_SUB_SUITE().
 125  *
 126  * This macro begins the declaration of a test suite, in the same
 127  * manner as CPPUNIT_TEST_SUITE().  In addition, the test suite of the
 128  * parent is automatically inserted in the test suite being
 129  * defined.
 130  *
 131  * Here is an example:
 132  *
 133  * \code
 134  * #include <cppunit/extensions/HelperMacros.h>
 135  * class MySubTest : public MyTest {
 136  *   CPPUNIT_TEST_SUB_SUITE( MySubTest, MyTest );
 137  *   CPPUNIT_TEST( testAdd );
 138  *   CPPUNIT_TEST( testSub );
 139  *   CPPUNIT_TEST_SUITE_END();
 140  * public:
 141  *   void testAdd();
 142  *   void testSub();
 143  * };
 144  * \endcode
 145  *
 146  * \param ATestFixtureType Type of the test case class. This type \b MUST
 147  *                         be derived from TestFixture.
 148  * \param ASuperClass   Type of the parent class.
 149  * \see CPPUNIT_TEST_SUITE.
 150  */
 151 #define CPPUNIT_TEST_SUB_SUITE( ATestFixtureType, ASuperClass )  \
 152   public:                                                        \
 153     typedef ASuperClass ParentTestFixtureType;                   \
 154   private:                                                       \
 155     CPPUNIT_TEST_SUITE( ATestFixtureType );                      \
 156       ParentTestFixtureType::addTestsToSuite( baseContext )
 157
 158
 159 /*! \brief End declaration of the test suite.
 160  *
 161  * After this macro, member access is set to "private".
 162  *
 163  * \see  CPPUNIT_TEST_SUITE.
 164  * \see  CPPUNIT_TEST_SUITE_REGISTRATION.
 165  */
 166 #define CPPUNIT_TEST_SUITE_END()                                               \
 167     }                                                                          \
 168                                                                                \
 169     static CPPUNIT_NS::TestSuite *suite()                                      \
 170     {                                                                          \
 171       const CPPUNIT_NS::TestNamer &namer = getTestNamer__();                   \
 172       std::auto_ptr<CPPUNIT_NS::TestSuite> suite(                              \
 173              new CPPUNIT_NS::TestSuite( namer.getFixtureName() ));             \
 174       CPPUNIT_NS::ConcretTestFixtureFactory<TestFixtureType> factory;          \
 175       CPPUNIT_NS::TestSuiteBuilderContextBase context( *suite.get(),           \
 176                                                        namer,                  \
 177                                                        factory );              \
 178       TestFixtureType::addTestsToSuite( context );                             \
 179       return suite.release();                                                  \
 180     }                                                                          \
 181   private: /* dummy typedef so that the macro can still end with ';'*/         \
 182     typedef int CppUnitDummyTypedefForSemiColonEnding__
 183
 184 /*! \brief End declaration of an abstract test suite.
 185  *
 186  * Use this macro to indicate that the %TestFixture is abstract. No
 187  * static suite() method will be declared.
 188  *
 189  * After this macro, member access is set to "private".
 190  *
 191  * Here is an example of usage:
 192  *
 193  * The abstract test fixture:
 194  * \code
 195  * #include <cppunit/extensions/HelperMacros.h>
 196  * class AbstractDocument;
 197  * class AbstractDocumentTest : public CppUnit::TestFixture {
 198  *   CPPUNIT_TEST_SUITE( AbstractDocumentTest );
 199  *   CPPUNIT_TEST( testInsertText );
 200  *   CPPUNIT_TEST_SUITE_END_ABSTRACT();
 201  * public:
 202  *   void testInsertText();
 203  *
 204  *   void setUp()
 205  *   {
 206  *     m_document = makeDocument();
 207  *   }
 208  *
 209  *   void tearDown()
 210  *   {
 211  *     delete m_document;
 212  *   }
 213  * protected:
 214  *   virtual AbstractDocument *makeDocument() =0;
 215  *
 216  *   AbstractDocument *m_document;
 217  * };\endcode
 218  *
 219  * The concret test fixture:
 220  * \code
 221  * class RichTextDocumentTest : public AbstractDocumentTest {
 222  *   CPPUNIT_TEST_SUB_SUITE( RichTextDocumentTest, AbstractDocumentTest );
 223  *   CPPUNIT_TEST( testInsertFormatedText );
 224  *   CPPUNIT_TEST_SUITE_END();
 225  * public:
 226  *   void testInsertFormatedText();
 227  * protected:
 228  *   AbstractDocument *makeDocument()
 229  *   {
 230  *     return new RichTextDocument();
 231  *   }
 232  * };\endcode
 233  *
 234  * \see  CPPUNIT_TEST_SUB_SUITE.
 235  * \see  CPPUNIT_TEST_SUITE_REGISTRATION.
 236  */
 237 #define CPPUNIT_TEST_SUITE_END_ABSTRACT()                                      \
 238     }                                                                          \
 239   private: /* dummy typedef so that the macro can still end with ';'*/         \
 240     typedef int CppUnitDummyTypedefForSemiColonEnding__
 241
 242
 243 /*! \brief Add a test to the suite (for custom test macro).
 244  *
 245  * The specified test will be added to the test suite being declared. This macro
 246  * is intended for \e advanced usage, to extend %CppUnit by creating new macro such
 247  * as CPPUNIT_TEST_EXCEPTION()...
 248  *
 249  * Between macro CPPUNIT_TEST_SUITE() and CPPUNIT_TEST_SUITE_END(), you can assume
 250  * that the following variables can be used:
 251  * \code
 252  * typedef TestSuiteBuilder<TestFixtureType> TestSuiteBuilderType;
 253  * TestSuiteBuilderType &context;
 254  * \endcode
 255  *
 256  * \c context can be used to name test case, create new test fixture instance,
 257  * or add test case to the test fixture suite.
 258  *
 259  * Below is an example that show how to use this macro to create new macro to add
 260  * test to the fixture suite. The macro below show how you would add a new type
 261  * of test case which fails if the execution last more than a given time limit.
 262  * It relies on an imaginary TimeOutTestCaller class which has an interface similar
 263  * to TestCaller.
 264  *
 265  * \code
 266  * #define CPPUNITEX_TEST_TIMELIMIT( testMethod, timeLimit )            \
 267  *      CPPUNIT_TEST_SUITE_ADD_TEST( (new TimeOutTestCaller<TestFixtureType>(  \
 268  *                  namer.getTestNameFor( #testMethod ),                \
 269  *                  &TestFixtureType::testMethod,                   \
 270  *                  factory.makeFixture(),                              \
 271  *                  timeLimit ) ) )
 272  *
 273  * class PerformanceTest : CppUnit::TestFixture
 274  * {
 275  * public:
 276  *   CPPUNIT_TEST_SUITE( PerformanceTest );
 277  *   CPPUNITEX_TEST_TIMELIMIT( testSortReverseOrder, 5.0 );
 278  *   CPPUNIT_TEST_SUITE_END();
 279  *
 280  *   void testSortReverseOrder();
 281  * };
 282  * \endcode
 283  *
 284  * \param test Test to add to the suite. Must be a subclass of Test. The test name
 285  *             should have been obtained using TestNamer::getTestNameFor().
 286  */
 287 #define CPPUNIT_TEST_SUITE_ADD_TEST( test ) \
 288       context.addTest( test )
 289
 290 /*! \brief Add a method to the suite.
 291  * \param testMethod Name of the method of the test case to add to the
 292  *                   suite. The signature of the method must be of
 293  *                   type: void testMethod();
 294  * \see  CPPUNIT_TEST_SUITE.
 295  */
 296 #define CPPUNIT_TEST( testMethod )                        \
 297     CPPUNIT_TEST_SUITE_ADD_TEST(                           \
 298         ( new CPPUNIT_NS::TestCaller<TestFixtureType>(    \
 299                   context.getTestNameFor( #testMethod),   \
 300                   &TestFixtureType::testMethod,           \
 301                   context.makeFixture() ) ) )
 302
 303 /*! \brief Add a test which fail if the specified exception is not caught.
 304  *
 305  * Example:
 306  * \code
 307  * #include <cppunit/extensions/HelperMacros.h>
 308  * #include <vector>
 309  * class MyTest : public CppUnit::TestFixture {
 310  *   CPPUNIT_TEST_SUITE( MyTest );
 311  *   CPPUNIT_TEST_EXCEPTION( testVectorAtThrow, std::invalid_argument );
 312  *   CPPUNIT_TEST_SUITE_END();
 313  * public:
 314  *   void testVectorAtThrow()
 315  *   {
 316  *     std::vector<int> v;
 317  *     v.at( 1 );     // must throw exception std::invalid_argument
 318  *   }
 319  * };
 320  * \endcode
 321  *
 322  * \param testMethod Name of the method of the test case to add to the suite.
 323  * \param ExceptionType Type of the exception that must be thrown by the test
 324  *                      method.
 325  * \deprecated Use the assertion macro CPPUNIT_ASSERT_THROW instead.
 326  */
 327 #define CPPUNIT_TEST_EXCEPTION( testMethod, ExceptionType )          \
 328   CPPUNIT_TEST_SUITE_ADD_TEST(                                        \
 329       (new CPPUNIT_NS::ExceptionTestCaseDecorator< ExceptionType >(  \
 330           new CPPUNIT_NS::TestCaller< TestFixtureType >(             \
 331                                context.getTestNameFor( #testMethod ),  \
 332                                &TestFixtureType::testMethod,         \
 333                                context.makeFixture() ) ) ) )
 334
 335 /*! \brief Adds a test case which is excepted to fail.
 336  *
 337  * The added test case expect an assertion to fail. You usually used that type
 338  * of test case when testing custom assertion macros.
 339  *
 340  * \code
 341  * CPPUNIT_TEST_FAIL( testAssertFalseFail );
 342  *
 343  * void testAssertFalseFail()
 344  * {
 345  *   CPPUNIT_ASSERT( false );
 346  * }
 347  * \endcode
 348  * \see CreatingNewAssertions.
 349  * \deprecated Use the assertion macro CPPUNIT_ASSERT_ASSERTION_FAIL instead.
 350  */
 351 #define CPPUNIT_TEST_FAIL( testMethod ) \
 352               CPPUNIT_TEST_EXCEPTION( testMethod, CPPUNIT_NS::Exception )
 353
 354 /*! \brief Adds some custom test cases.
 355  *
 356  * Use this to add one or more test cases to the fixture suite. The specified
 357  * method is called with a context parameter that can be used to name,
 358  * instantiate fixture, and add instantiated test case to the fixture suite.
 359  * The specified method must have the following signature:
 360  * \code
 361  * static void aMethodName( TestSuiteBuilderContextType &context );
 362  * \endcode
 363  *
 364  * \c TestSuiteBuilderContextType is typedef to
 365  * TestSuiteBuilderContext<TestFixtureType> declared by CPPUNIT_TEST_SUITE().
 366  *
 367  * Here is an example that add two custom tests:
 368  *
 369  * \code
 370  * #include <cppunit/extensions/HelperMacros.h>
 371  *
 372  * class MyTest : public CppUnit::TestFixture {
 373  *   CPPUNIT_TEST_SUITE( MyTest );
 374  *   CPPUNIT_TEST_SUITE_ADD_CUSTOM_TESTS( addTimeOutTests );
 375  *   CPPUNIT_TEST_SUITE_END();
 376  * public:
 377  *   static void addTimeOutTests( TestSuiteBuilderContextType &context )
 378  *   {
 379  *     context.addTest( new TimeOutTestCaller( context.getTestNameFor( "test1" ) ),
 380  *                                             &MyTest::test1,
 381  *                                             context.makeFixture(),
 382  *                                             5.0 );
 383  *     context.addTest( new TimeOutTestCaller( context.getTestNameFor( "test2" ) ),
 384  *                                             &MyTest::test2,
 385  *                                             context.makeFixture(),
 386  *                                             5.0 );
 387  *   }
 388  *
 389  *   void test1()
 390  *   {
 391  *     // Do some test that may never end...
 392  *   }
 393  *
 394  *   void test2()
 395  *   {
 396  *     // Do some test that may never end...
 397  *   }
 398  * };
 399  * \endcode
 400  * @param testAdderMethod Name of the method called to add the test cases.
 401  */
 402 #define CPPUNIT_TEST_SUITE_ADD_CUSTOM_TESTS( testAdderMethod ) \
 403       testAdderMethod( context )
 404
 405 /*! \brief Adds a property to the test suite builder context.
 406  * \param APropertyKey   Key of the property to add.
 407  * \param APropertyValue Value for the added property.
 408  * Example:
 409  * \code
 410  * CPPUNIT_TEST_SUITE_PROPERTY("XmlFileName", "paraTest.xml"); \endcode
 411  */
 412 #define CPPUNIT_TEST_SUITE_PROPERTY( APropertyKey, APropertyValue ) \
 413     context.addProperty( std::string(APropertyKey),                 \
 414                          std::string(APropertyValue) )
 415
 416 /** @}
 417  */
 418
 419
 420 /*! Adds the specified fixture suite to the unnamed registry.
 421  * \ingroup CreatingTestSuite
 422  *
 423  * This macro declares a static variable whose construction
 424  * causes a test suite factory to be inserted in a global registry
 425  * of such factories.  The registry is available by calling
 426  * the static function CppUnit::TestFactoryRegistry::getRegistry().
 427  *
 428  * \param ATestFixtureType Type of the test case class.
 429  * \warning This macro should be used only once per line of code (the line
 430  *          number is used to name a hidden static variable).
 431  * \see CPPUNIT_TEST_SUITE_NAMED_REGISTRATION
 432  * \see CPPUNIT_REGISTRY_ADD_TO_DEFAULT
 433  * \see CPPUNIT_REGISTRY_ADD
 434  * \see CPPUNIT_TEST_SUITE, CppUnit::AutoRegisterSuite,
 435  *      CppUnit::TestFactoryRegistry.
 436  */
 437 #define CPPUNIT_TEST_SUITE_REGISTRATION( ATestFixtureType )      \
 438   static CPPUNIT_NS::AutoRegisterSuite< ATestFixtureType >       \
 439              CPPUNIT_MAKE_UNIQUE_NAME(autoRegisterRegistry__ )
 440
 441
 442 /** Adds the specified fixture suite to the specified registry suite.
 443  * \ingroup CreatingTestSuite
 444  *
 445  * This macro declares a static variable whose construction
 446  * causes a test suite factory to be inserted in the global registry
 447  * suite of the specified name. The registry is available by calling
 448  * the static function CppUnit::TestFactoryRegistry::getRegistry().
 449  *
 450  * For the suite name, use a string returned by a static function rather
 451  * than a hardcoded string. That way, you can know what are the name of
 452  * named registry and you don't risk mistyping the registry name.
 453  *
 454  * \code
 455  * // MySuites.h
 456  * namespace MySuites {
 457  *   std::string math() {
 458  *     return "Math";
 459  *   }
 460  * }
 461  *
 462  * // ComplexNumberTest.cpp
 463  * #include "MySuites.h"
 464  *
 465  * CPPUNIT_TEST_SUITE_NAMED_REGISTRATION( ComplexNumberTest, MySuites::math() );
 466  * \endcode
 467  *
 468  * \param ATestFixtureType Type of the test case class.
 469  * \param suiteName Name of the global registry suite the test suite is
 470  *                  registered into.
 471  * \warning This macro should be used only once per line of code (the line
 472  *          number is used to name a hidden static variable).
 473  * \see CPPUNIT_TEST_SUITE_REGISTRATION
 474  * \see CPPUNIT_REGISTRY_ADD_TO_DEFAULT
 475  * \see CPPUNIT_REGISTRY_ADD
 476  * \see CPPUNIT_TEST_SUITE, CppUnit::AutoRegisterSuite,
 477  *      CppUnit::TestFactoryRegistry..
 478  */
 479 #define CPPUNIT_TEST_SUITE_NAMED_REGISTRATION( ATestFixtureType, suiteName ) \
 480   static CPPUNIT_NS::AutoRegisterSuite< ATestFixtureType >                   \
 481              CPPUNIT_MAKE_UNIQUE_NAME(autoRegisterRegistry__ )(suiteName)
 482
 483 /*! Adds that the specified registry suite to another registry suite.
 484  * \ingroup CreatingTestSuite
 485  *
 486  * Use this macros to automatically create test registry suite hierarchy. For example,
 487  * if you want to create the following hierarchy:
 488  * - Math
 489  *   - IntegerMath
 490  *   - FloatMath
 491  *     - FastFloat
 492  *     - StandardFloat
 493  *
 494  * You can do this automatically with:
 495  * \code
 496  * CPPUNIT_REGISTRY_ADD( "FastFloat", "FloatMath" );
 497  * CPPUNIT_REGISTRY_ADD( "IntegerMath", "Math" );
 498  * CPPUNIT_REGISTRY_ADD( "FloatMath", "Math" );
 499  * CPPUNIT_REGISTRY_ADD( "StandardFloat", "FloatMath" );
 500  * \endcode
 501  *
 502  * There is no specific order of declaration. Think of it as declaring links.
 503  *
 504  * You register the test in each suite using CPPUNIT_TEST_SUITE_NAMED_REGISTRATION.
 505  *
 506  * \param which Name of the registry suite to add to the registry suite named \a to.
 507  * \param to Name of the registry suite \a which is added to.
 508  * \see CPPUNIT_REGISTRY_ADD_TO_DEFAULT, CPPUNIT_TEST_SUITE_NAMED_REGISTRATION.
 509  */
 510 #define CPPUNIT_REGISTRY_ADD( which, to )                                     \
 511   static CPPUNIT_NS::AutoRegisterRegistry                                     \
 512              CPPUNIT_MAKE_UNIQUE_NAME( autoRegisterRegistry__ )( which, to )
 513
 514 /*! Adds that the specified registry suite to the default registry suite.
 515  * \ingroup CreatingTestSuite
 516  *
 517  * This macro is just like CPPUNIT_REGISTRY_ADD except the specified registry
 518  * suite is added to the default suite (root suite).
 519  *
 520  * \param which Name of the registry suite to add to the default registry suite.
 521  * \see CPPUNIT_REGISTRY_ADD.
 522  */
 523 #define CPPUNIT_REGISTRY_ADD_TO_DEFAULT( which )                         \
 524   static CPPUNIT_NS::AutoRegisterRegistry                                \
 525              CPPUNIT_MAKE_UNIQUE_NAME( autoRegisterRegistry__ )( which )
 526
 527 // Backwards compatibility
 528 // (Not tested!)
 529
 530 #if CPPUNIT_ENABLE_CU_TEST_MACROS
 531
 532 #define CU_TEST_SUITE(tc) CPPUNIT_TEST_SUITE(tc)
 533 #define CU_TEST_SUB_SUITE(tc,sc) CPPUNIT_TEST_SUB_SUITE(tc,sc)
 534 #define CU_TEST(tm) CPPUNIT_TEST(tm)
 535 #define CU_TEST_SUITE_END() CPPUNIT_TEST_SUITE_END()
 536 #define CU_TEST_SUITE_REGISTRATION(tc) CPPUNIT_TEST_SUITE_REGISTRATION(tc)
 537
 538 #endif
 539
 540
 541 #endif  // CPPUNIT_EXTENSIONS_HELPERMACROS_H