source: trunk/contrib/cppunit-1.12.2/include/cppunit/TestListener.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: 4.0 KB
Line 
1#ifndef CPPUNIT_TESTLISTENER_H    // -*- C++ -*-
2#define CPPUNIT_TESTLISTENER_H
3
4#include <cppunit/Portability.h>
5
6
7CPPUNIT_NS_BEGIN
8
9
10class Exception;
11class Test;
12class TestFailure;
13class 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 */
94class CPPUNIT_API TestListener
95{
96public:
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
144CPPUNIT_NS_END
145
146#endif // CPPUNIT_TESTLISTENER_H
147
148
Note: See TracBrowser for help on using the repository browser.