source: trunk/contrib/cppunit-1.12.2/include/cppunit/extensions/TestFactoryRegistry.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: 6.1 KB
Line 
1#ifndef CPPUNIT_EXTENSIONS_TESTFACTORYREGISTRY_H
2#define CPPUNIT_EXTENSIONS_TESTFACTORYREGISTRY_H
3
4#include <cppunit/Portability.h>
5
6#if CPPUNIT_NEED_DLL_DECL
7#pragma warning( push )
8#pragma warning( disable: 4251)  // X needs to have dll-interface to be used by clients of class Z
9#endif
10
11#include <cppunit/portability/CppUnitSet.h>
12#include <cppunit/extensions/TestFactory.h>
13#include <string>
14
15CPPUNIT_NS_BEGIN
16
17
18class TestSuite;
19
20#if CPPUNIT_NEED_DLL_DECL
21//  template class CPPUNIT_API std::set<TestFactory *>;
22#endif
23
24
25/*! \brief Registry for TestFactory.
26 * \ingroup CreatingTestSuite
27 *
28 * Notes that the registry \b DON'T assumes lifetime control for any registered tests
29 * anymore.
30 *
31 * The <em>default</em> registry is the registry returned by getRegistry() with the
32 * default name parameter value.
33 *
34 * To register tests, use the macros:
35 * - CPPUNIT_TEST_SUITE_REGISTRATION(): to add tests in the default registry.
36 * - CPPUNIT_TEST_SUITE_NAMED_REGISTRATION(): to add tests in a named registry.
37 *
38 * Example 1: retreiving a suite that contains all the test registered with
39 * CPPUNIT_TEST_SUITE_REGISTRATION().
40 * \code
41 * CppUnit::TestFactoryRegistry &registry = CppUnit::TestFactoryRegistry::getRegistry();
42 * CppUnit::TestSuite *suite = registry.makeTest();
43 * \endcode
44 *
45 * Example 2: retreiving a suite that contains all the test registered with
46 * \link CPPUNIT_TEST_SUITE_NAMED_REGISTRATION() CPPUNIT_TEST_SUITE_NAMED_REGISTRATION( ..., "Math" )\endlink.
47 * \code
48 * CppUnit::TestFactoryRegistry &mathRegistry = CppUnit::TestFactoryRegistry::getRegistry( "Math" );
49 * CppUnit::TestSuite *mathSuite = mathRegistry.makeTest();
50 * \endcode
51 *
52 * Example 3: creating a test suite hierarchy composed of unnamed registration and
53 * named registration:
54 * - All Tests
55 *   - tests registered with CPPUNIT_TEST_SUITE_NAMED_REGISTRATION( ..., "Graph" )
56 *   - tests registered with CPPUNIT_TEST_SUITE_NAMED_REGISTRATION( ..., "Math" )
57 *   - tests registered with CPPUNIT_TEST_SUITE_REGISTRATION
58 *
59 * \code
60 * CppUnit::TestSuite *rootSuite = new CppUnit::TestSuite( "All tests" );
61 * rootSuite->addTest( CppUnit::TestFactoryRegistry::getRegistry( "Graph" ).makeTest() );
62 * rootSuite->addTest( CppUnit::TestFactoryRegistry::getRegistry( "Math" ).makeTest() );
63 * CppUnit::TestFactoryRegistry::getRegistry().addTestToSuite( rootSuite );
64 * \endcode
65 *
66 * The same result can be obtained with:
67 * \code
68 * CppUnit::TestFactoryRegistry &registry = CppUnit::TestFactoryRegistry::getRegistry();
69 * registry.addRegistry( "Graph" );
70 * registry.addRegistry( "Math" );
71 * CppUnit::TestSuite *suite = registry.makeTest();
72 * \endcode
73 *
74 * Since a TestFactoryRegistry is a TestFactory, the named registries can be
75 * registered in the unnamed registry, creating the hierarchy links.
76 *
77 * \see TestSuiteFactory, AutoRegisterSuite
78 * \see CPPUNIT_TEST_SUITE_REGISTRATION, CPPUNIT_TEST_SUITE_NAMED_REGISTRATION
79 */
80class CPPUNIT_API TestFactoryRegistry : public TestFactory
81{
82public:
83  /** Constructs the registry with the specified name.
84   * \param name Name of the registry. It is the name of TestSuite returned by
85   *             makeTest().
86   */
87  TestFactoryRegistry( std::string name );
88
89  /// Destructor.
90  virtual ~TestFactoryRegistry();
91
92  /** Returns a new TestSuite that contains the registered test.
93   * \return A new TestSuite which contains all the test added using
94   * registerFactory(TestFactory *).
95   */
96  virtual Test *makeTest();
97
98  /** Returns a named registry.
99   *
100   * If the \a name is left to its default value, then the registry that is returned is
101   * the one used by CPPUNIT_TEST_SUITE_REGISTRATION(): the 'top' level registry.
102   *
103   * \param name Name of the registry to return.
104   * \return Registry. If the registry does not exist, it is created with the
105   *         specified name.
106   */
107  static TestFactoryRegistry &getRegistry( const std::string &name = "All Tests" );
108
109  /** Adds the registered tests to the specified suite.
110   * \param suite Suite the tests are added to.
111   */
112  void addTestToSuite( TestSuite *suite );
113
114  /** Adds the specified TestFactory to the registry.
115   *
116   * \param factory Factory to register.
117   */
118  void registerFactory( TestFactory *factory );
119
120  /*! Removes the specified TestFactory from the registry.
121   *
122   * The specified factory is not destroyed.
123   * \param factory Factory to remove from the registry.
124   * \todo Address case when trying to remove a TestRegistryFactory.
125   */
126  void unregisterFactory( TestFactory *factory );
127
128  /*! Adds a registry to the registry.
129   *
130   * Convenience method to help create test hierarchy. See TestFactoryRegistry detail
131   * for examples of use. Calling this method is equivalent to:
132   * \code
133   * this->registerFactory( TestFactoryRegistry::getRegistry( name ) );
134   * \endcode
135   *
136   * \param name Name of the registry to add.
137   */
138  void addRegistry( const std::string &name );
139
140  /*! Tests if the registry is valid.
141   *
142   * This method should be used when unregistering test factory on static variable
143   * destruction to ensure that the registry has not been already destroyed (in
144   * that case there is no need to unregister the test factory).
145   *
146   * You should not concern yourself with this method unless you are writing a class
147   * like AutoRegisterSuite.
148   *
149   * \return \c true if the specified registry has not been destroyed,
150   *         otherwise returns \c false.
151   * \see AutoRegisterSuite.
152   */
153  static bool isValid();
154
155  /** Adds the specified TestFactory with a specific name (DEPRECATED).
156   * \param name Name associated to the factory.
157   * \param factory Factory to register.
158   * \deprecated Use registerFactory( TestFactory *) instead.
159   */
160  void registerFactory( const std::string &name,
161                        TestFactory *factory );
162
163private:
164  TestFactoryRegistry( const TestFactoryRegistry &copy );
165  void operator =( const TestFactoryRegistry &copy );
166
167private:
168  typedef CppUnitSet<TestFactory *, std::less<TestFactory*> > Factories;
169  Factories m_factories;
170
171  std::string m_name;
172};
173
174
175CPPUNIT_NS_END
176
177#if CPPUNIT_NEED_DLL_DECL
178#pragma warning( pop )
179#endif
180
181
182#endif  // CPPUNIT_EXTENSIONS_TESTFACTORYREGISTRY_H
Note: See TracBrowser for help on using the repository browser.