source: trunk/contrib/cppunit-1.12.2/include/cppunit/extensions/HelperMacros.h @ 876

Last change on this file since 876 was 876, checked in by sam, 9 years ago

contrib: add a precompiled Win32 version of CppUnit and update build system
accordingly.

File size: 20.1 KB
Line 
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
Note: See TracBrowser for help on using the repository browser.