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/Portability.h> 10 #include <cppunit/extensions/AutoRegisterSuite.h> 11 #include <cppunit/extensions/TestSuiteBuilder.h> 12 #include <string> 13 14 namespace CppUnit 15 { 16 class TestFixture; 17 18 /*! \brief Abstract TestFixture factory. 19 */ 20 class TestFixtureFactory 21 { 22 public: 23 //! Creates a new TestFixture instance. 24 virtual CppUnit::TestFixture *makeFixture() =0; 25 }; 26 } // namespace CppUnit 27 28 29 // The macro __CPPUNIT_SUITE_CTOR_ARGS expand to an expression used to construct 30 // the TestSuiteBuilder with macro CPPUNIT_TEST_SUITE. 31 // 32 // The name of the suite is obtained using RTTI if CPPUNIT_USE_TYPEINFO_NAME 33 // is defined, otherwise it is extracted from the macro parameter 34 // 35 // This macro is for cppunit internal and should not be use otherwise. 36 #if CPPUNIT_USE_TYPEINFO_NAME 37 # define __CPPUNIT_SUITE_CTOR_ARGS( ATestFixtureType ) 38 #else 39 # define __CPPUNIT_SUITE_CTOR_ARGS( ATestFixtureType ) (string(#ATestFixtureType)) 40 #endif 41 42 43 /*! \addtogroup WritingTestFixture Writing test fixture 44 */ 45 /** @{ 46 */ 47 48 49 /** \file 50 * Macros intended to ease the definition of test suites. 51 * 52 * The macros 53 * CPPUNIT_TEST_SUITE(), CPPUNIT_TEST(), and CPPUNIT_TEST_SUITE_END() 54 * are designed to facilitate easy creation of a test suite. 55 * For example, 56 * 57 * \code 58 * #include <cppunit/extensions/HelperMacros.h> 59 * class MyTest : public CppUnit::TestFixture { 60 * CPPUNIT_TEST_SUITE( MyTest ); 61 * CPPUNIT_TEST( testEquality ); 62 * CPPUNIT_TEST( testSetName ); 63 * CPPUNIT_TEST_SUITE_END(); 64 * public: 65 * void testEquality(); 66 * void testSetName(); 67 * }; 68 * \endcode 69 * 70 * The effect of these macros is to define two methods in the 71 * class MyTest. The first method is an auxiliary function 72 * named registerTests that you will not need to call directly. 73 * The second function 74 * \code static CppUnit::TestSuite *suite()\endcode 75 * returns a pointer to the suite of tests defined by the CPPUNIT_TEST() 76 * macros. 77 * 78 * Rather than invoking suite() directly, 79 * the macro CPPUNIT_TEST_SUITE_REGISTRATION() is 80 * used to create a static variable that automatically 81 * registers its test suite in a global registry. 82 * The registry yields a Test instance containing all the 83 * registered suites. 84 * \code 85 * CPPUNIT_TEST_SUITE_REGISTRATION( MyTest ); 86 * CppUnit::Test* tp = 87 * CppUnit::TestFactoryRegistry::getRegistry().makeTest(); 88 * \endcode 89 * 90 * The test suite macros can even be used with templated test classes. 91 * For example: 92 * 93 * \code 94 * template<typename CharType> 95 * class StringTest : public CppUnit::TestFixture { 96 * CPPUNIT_TEST_SUITE( StringTest ); 97 * CPPUNIT_TEST( testAppend ); 98 * CPPUNIT_TEST_SUITE_END(); 99 * public: 100 * ... 101 * }; 102 * \endcode 103 * 104 * You need to add in an implementation file: 105 * 106 * \code 107 * CPPUNIT_TEST_SUITE_REGISTRATION( StringTest<char> ); 108 * CPPUNIT_TEST_SUITE_REGISTRATION( StringTest<wchar_t> ); 109 * \endcode 110 */ 111 112 113 /*! \brief Begin test suite 114 * 115 * This macro starts the declaration of a new test suite. 116 * Use CPPUNIT_TEST_SUB_SUITE() instead, if you wish to include the 117 * test suite of the parent class. 118 * 119 * \param ATestFixtureType Type of the test case class. This type \b MUST 120 * be derived from TestFixture. 121 * \see CPPUNIT_TEST_SUB_SUITE, CPPUNIT_TEST, CPPUNIT_TEST_SUITE_END, 122 * \see CPPUNIT_TEST_SUITE_REGISTRATION, CPPUNIT_TEST_EXCEPTION, CPPUNIT_TEST_FAIL. 123 */ 124 #define CPPUNIT_TEST_SUITE( ATestFixtureType ) \ 125 private: \ 126 typedef ATestFixtureType __ThisTestFixtureType; \ 127 class ThisTestFixtureFactory : public CppUnit::TestFixtureFactory \ 128 { \ 129 virtual CppUnit::TestFixture *makeFixture() \ 130 { \ 131 return new ATestFixtureType(); \ 132 } \ 133 }; \ 134 public: \ 135 static void \ 136 registerTests( CppUnit::TestSuite *suite, \ 137 CppUnit::TestFixtureFactory *factory ) \ 138 { \ 139 CppUnit::TestSuiteBuilder<__ThisTestFixtureType> builder( suite ); 140 141 142 /*! \brief Begin test suite (includes parent suite) 143 * 144 * This macro may only be used in a class whose parent class 145 * defines a test suite using CPPUNIT_TEST_SUITE() or CPPUNIT_TEST_SUB_SUITE(). 146 * 147 * This macro begins the declaration of a test suite, in the same 148 * manner as CPPUNIT_TEST_SUITE(). In addition, the test suite of the 149 * parent is automatically inserted in the test suite being 150 * defined. 151 * 152 * Here is an example: 153 * 154 * \code 155 * #include <cppunit/extensions/HelperMacros.h> 156 * class MySubTest : public MyTest { 157 * CPPUNIT_TEST_SUB_SUITE( MySubTest, MyTest ); 158 * CPPUNIT_TEST( testAdd ); 159 * CPPUNIT_TEST( testSub ); 160 * CPPUNIT_TEST_SUITE_END(); 161 * public: 162 * void testAdd(); 163 * void testSub(); 164 * }; 165 * \endcode 166 * 167 * \param ATestFixtureType Type of the test case class. This type \b MUST 168 * be derived from TestFixture. 169 * \param ASuperClass Type of the parent class. 170 * \see CPPUNIT_TEST_SUITE. 171 */ 172 #define CPPUNIT_TEST_SUB_SUITE( ATestFixtureType, ASuperClass ) \ 173 private: \ 174 typedef ASuperClass __ThisSuperClassType; \ 175 CPPUNIT_TEST_SUITE( ATestFixtureType ); \ 176 __ThisSuperClassType::registerTests( suite, factory ) 177 178 179 /*! \brief Add a method to the suite. 180 * \param testMethod Name of the method of the test case to add to the 181 * suite. The signature of the method must be of 182 * type: void testMethod(); 183 * \see CPPUNIT_TEST_SUITE. 184 */ 185 #define CPPUNIT_TEST( testMethod ) \ 186 builder.addTestCaller( #testMethod, \ 187 &__ThisTestFixtureType::testMethod , \ 188 (__ThisTestFixtureType*)factory->makeFixture() ) 189 190 191 /*! \brief Add a test which fail if the specified exception is not caught. 192 * 193 * Example: 194 * \code 195 * #include <cppunit/extensions/HelperMacros.h> 196 * #include <vector> 197 * class MyTest : public CppUnit::TestFixture { 198 * CPPUNIT_TEST_SUITE( MyTest ); 199 * CPPUNIT_TEST_EXCEPTION( testVectorAtThrow, invalid_argument ); 200 * CPPUNIT_TEST_SUITE_END(); 201 * public: 202 * void testVectorAtThrow() 203 * { 204 * vector<int> v; 205 * v.at( 1 ); // must throw exception invalid_argument 206 * } 207 * }; 208 * \endcode 209 * 210 * \param testMethod Name of the method of the test case to add to the suite. 211 * \param ExceptionType Type of the exception that must be thrown by the test 212 * method. 213 */ 214 #define CPPUNIT_TEST_EXCEPTION( testMethod, ExceptionType ) \ 215 builder.addTestCallerForException( #testMethod, \ 216 &__ThisTestFixtureType::testMethod , \ 217 (__ThisTestFixtureType*)factory->makeFixture(), \ 218 (ExceptionType *)NULL ); 219 220 /*! \brief Adds a test case which is excepted to fail. 221 * 222 * The added test case expect an assertion to fail. You usually used that type 223 * of test case when testing custom assertion macros. 224 * 225 * \code 226 * CPPUNIT_TEST_FAIL( testAssertFalseFail ); 227 * 228 * void testAssertFalseFail() 229 * { 230 * CPPUNIT_ASSERT( false ); 231 * } 232 * \endcode 233 * \see CreatingNewAssertions. 234 */ 235 #define CPPUNIT_TEST_FAIL( testMethod ) \ 236 CPPUNIT_TEST_EXCEPTION( testMethod, CppUnit::Exception ) 237 238 /*! \brief End declaration of the test suite. 239 * 240 * After this macro, member access is set to "private". 241 * 242 * \see CPPUNIT_TEST_SUITE. 243 * \see CPPUNIT_TEST_SUITE_REGISTRATION. 244 */ 245 #define CPPUNIT_TEST_SUITE_END() \ 246 builder.takeSuite(); \ 247 } \ 248 static CppUnit::TestSuite *suite() \ 249 { \ 250 CppUnit::TestSuiteBuilder<__ThisTestFixtureType> \ 251 builder __CPPUNIT_SUITE_CTOR_ARGS( ATestFixtureType ); \ 252 ThisTestFixtureFactory factory; \ 253 __ThisTestFixtureType::registerTests( builder.suite(), &factory ); \ 254 return builder.takeSuite(); \ 255 } \ 256 private: /* dummy typedef so that the macro can still end with ';'*/ \ 257 typedef ThisTestFixtureFactory __ThisTestFixtureFactory 258 259 /** @} 260 */ 261 262 #define __CPPUNIT_CONCATENATE_DIRECT( s1, s2 ) s1##s2 263 #define __CPPUNIT_CONCATENATE( s1, s2 ) __CPPUNIT_CONCATENATE_DIRECT( s1, s2 ) 264 265 /** Decorates the specified string with the line number to obtain a unique name; 266 * @param str String to decorate. 267 */ 268 #define __CPPUNIT_MAKE_UNIQUE_NAME( str ) __CPPUNIT_CONCATENATE( str, __LINE__ ) 269 270 271 /** Adds the specified fixture suite to the unnamed registry. 272 * \ingroup CreatingTestSuite 273 * 274 * This macro declares a static variable whose construction 275 * causes a test suite factory to be inserted in a global registry 276 * of such factories. The registry is available by calling 277 * the static function CppUnit::TestFactoryRegistry::getRegistry(). 278 * 279 * \param ATestFixtureType Type of the test case class. 280 * \warning This macro should be used only once per line of code (the line 281 * number is used to name a hidden static variable). 282 * \see CPPUNIT_TEST_SUITE_NAMED_REGISTRATION 283 * \see CPPUNIT_TEST_SUITE, CppUnit::AutoRegisterSuite, 284 * CppUnit::TestFactoryRegistry. 285 */ 286 #define CPPUNIT_TEST_SUITE_REGISTRATION( ATestFixtureType ) \ 287 static CppUnit::AutoRegisterSuite< ATestFixtureType > \ 288 __CPPUNIT_MAKE_UNIQUE_NAME(__autoRegisterSuite ) 289 290 291 /** Adds the specified fixture suite to the specified registry suite. 292 * \ingroup CreatingTestSuite 293 * 294 * This macro declares a static variable whose construction 295 * causes a test suite factory to be inserted in the global registry 296 * suite of the specified name. The registry is available by calling 297 * the static function CppUnit::TestFactoryRegistry::getRegistry(). 298 * 299 * For the suite name, use a string returned by a static function rather 300 * than a hardcoded string. That way, you can know what are the name of 301 * named registry and you don't risk mistyping the registry name. 302 * 303 * \code 304 * // MySuites.h 305 * namespace MySuites { 306 * string math() { 307 * return "Math"; 308 * } 309 * } 310 * 311 * // ComplexNumberTest.cpp 312 * #include "MySuites.h" 313 * 314 * CPPUNIT_TEST_SUITE_NAMED_REGISTRATION( ComplexNumberTest, MySuites::math() ); 315 * \endcode 316 * 317 * \param ATestFixtureType Type of the test case class. 318 * \param suiteName Name of the global registry suite the test suite is 319 * registered into. 320 * \warning This macro should be used only once per line of code (the line 321 * number is used to name a hidden static variable). 322 * \see CPPUNIT_TEST_SUITE_REGISTRATION 323 * \see CPPUNIT_TEST_SUITE, CppUnit::AutoRegisterSuite, 324 * CppUnit::TestFactoryRegistry.. 325 */ 326 #define CPPUNIT_TEST_SUITE_NAMED_REGISTRATION( ATestFixtureType, suiteName ) \ 327 static CppUnit::AutoRegisterSuite< ATestFixtureType > \ 328 __CPPUNIT_MAKE_UNIQUE_NAME(__autoRegisterSuite )(suiteName) 329 330 331 // Backwards compatibility 332 // (Not tested!) 333 334 #if CPPUNIT_ENABLE_CU_TEST_MACROS 335 336 #define CU_TEST_SUITE(tc) CPPUNIT_TEST_SUITE(tc) 337 #define CU_TEST_SUB_SUITE(tc,sc) CPPUNIT_TEST_SUB_SUITE(tc,sc) 338 #define CU_TEST(tm) CPPUNIT_TEST(tm) 339 #define CU_TEST_SUITE_END() CPPUNIT_TEST_SUITE_END() 340 #define CU_TEST_SUITE_REGISTRATION(tc) CPPUNIT_TEST_SUITE_REGISTRATION(tc) 341 342 #endif 343 344 345 #endif // CPPUNIT_EXTENSIONS_HELPERMACROS_H 346