UnitTests/cppunit/include/cppunit/TestListener.h

   1 #ifndef CPPUNIT_TESTLISTENER_H    // -*- C++ -*-
   2 #define CPPUNIT_TESTLISTENER_H
   3
   4 #include <cppunit/Portability.h>
   5
   6
   7 CPPUNIT_NS_BEGIN
   8
   9
  10 class Exception;
  11 class Test;
  12 class TestFailure;
  13 class TestResult;
  14
  15
  16 /*! \brief Listener for test progress and result.
  17  * \ingroup TrackingTestExecution
  18  *
  19  * Implementing the Observer pattern a TestListener may be registered
  20  * to a TestResult to obtain information on the testing progress. Use
  21  * specialized sub classes of TestListener for text output
  22  * (TextTestProgressListener). Do not use the Listener for the test
  23  * result output, use a subclass of Outputter instead.
  24  *
  25  * The test framework distinguishes between failures and errors.
  26  * A failure is anticipated and checked for with assertions. Errors are
  27  * unanticipated problems signified by exceptions that are not generated
  28  * by the framework.
  29  *
  30  * Here is an example to track test time:
  31  *
  32  *
  33  * \code
  34  * #include <cppunit/TestListener.h>
  35  * #include <cppunit/Test.h>
  36  * #include <time.h>    // for clock()
  37  *
  38  * class TimingListener : public CppUnit::TestListener
  39  * {
  40  * public:
  41  *   void startTest( CppUnit::Test *test )
  42  *   {
  43  *     _chronometer.start();
  44  *   }
  45  *
  46  *   void endTest( CppUnit::Test *test )
  47  *   {
  48  *     _chronometer.end();
  49  *     addTest( test, _chronometer.elapsedTime() );
  50  *   }
  51  *
  52  *   // ... (interface to add/read test timing result)
  53  *
  54  * private:
  55  *   Clock _chronometer;
  56  * };
  57  * \endcode
  58  *
  59  * And another example that track failure/success at test suite level and captures
  60  * the TestPath of each suite:
  61  * \code
  62  * class SuiteTracker : public CppUnit::TestListener
  63  * {
  64  * public:
  65  *   void startSuite( CppUnit::Test *suite )
  66  *   {
  67  *     m_currentPath.add( suite );
  68  *   }
  69  *
  70  *   void addFailure( const TestFailure &failure )
  71  *   {
  72  *     m_suiteFailure.top() = false;
  73  *   }
  74  *
  75  *   void endSuite( CppUnit::Test *suite )
  76  *   {
  77  *     m_suiteStatus.insert( std::make_pair( suite, m_suiteFailure.top() ) );
  78  *     m_suitePaths.insert( std::make_pair( suite, m_currentPath ) );
  79  *
  80  *     m_currentPath.up();
  81  *     m_suiteFailure.pop();
  82  *   }
  83  *
  84  * private:
  85  *   std::stack<bool> m_suiteFailure;
  86  *   CppUnit::TestPath m_currentPath;
  87  *   std::map<CppUnit::Test *, bool> m_suiteStatus;
  88  *   std::map<CppUnit::Test *, CppUnit::TestPath> m_suitePaths;
  89  * };
  90  * \endcode
  91  *
  92  * \see TestResult
  93  */
  94 class CPPUNIT_API TestListener
  95 {
  96 public:
  97   virtual ~TestListener() {}
  98
  99   /// Called when just before a TestCase is run.
 100   virtual void startTest( Test * /*test*/ ) {}
 101
 102   /*! \brief Called when a failure occurs while running a test.
 103    * \see TestFailure.
 104    * \warning \a failure is a temporary object that is destroyed after the
 105    *          method call. Use TestFailure::clone() to create a duplicate.
 106    */
 107   virtual void addFailure( const TestFailure & /*failure*/ ) {}
 108
 109   /// Called just after a TestCase was run (even if a failure occured).
 110   virtual void endTest( Test * /*test*/ ) {}
 111
 112   /*! \brief Called by a TestComposite just before running its child tests.
 113    */
 114   virtual void startSuite( Test * /*suite*/ ) {}
 115
 116   /*! \brief Called by a TestComposite after running its child tests.
 117    */
 118   virtual void endSuite( Test * /*suite*/ ) {}
 119
 120   /*! \brief Called by a TestRunner before running the test.
 121    *
 122    * You can use this to do some global initialisation. A listener
 123    * could also use to output a 'prolog' to the test run.
 124    *
 125    * \param test Test that is going to be run.
 126    * \param eventManager Event manager used for the test run.
 127    */
 128   virtual void startTestRun( Test * /*test*/,
 129                              TestResult * /*eventManager*/ ) {}
 130
 131   /*! \brief Called by a TestRunner after running the test.
 132    *
 133    * TextTestProgressListener use this to emit a line break. You can also use this
 134    * to do some global uninitialisation.
 135    *
 136    * \param test Test that was run.
 137    * \param eventManager Event manager used for the test run.
 138    */
 139   virtual void endTestRun( Test * /*test*/,
 140                            TestResult * /*eventManager*/ ) {}
 141 };
 142
 143
 144 CPPUNIT_NS_END
 145
 146 #endif // CPPUNIT_TESTLISTENER_H
 147
 148