UnitTests/cppunit/include/cppunit/extensions/TestFactoryRegistry.h

   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
  15 CPPUNIT_NS_BEGIN
  16
  17
  18 class 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  */
  80 class CPPUNIT_API TestFactoryRegistry : public TestFactory
  81 {
  82 public:
  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
 163 private:
 164   TestFactoryRegistry( const TestFactoryRegistry &copy );
 165   void operator =( const TestFactoryRegistry &copy );
 166
 167 private:
 168   typedef CppUnitSet<TestFactory *, std::less<TestFactory*> > Factories;
 169   Factories m_factories;
 170
 171   std::string m_name;
 172 };
 173
 174
 175 CPPUNIT_NS_END
 176
 177 #if CPPUNIT_NEED_DLL_DECL
 178 #pragma warning( pop )
 179 #endif
 180
 181
 182 #endif  // CPPUNIT_EXTENSIONS_TESTFACTORYREGISTRY_H