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
14namespace 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