#ifndef CPPUNIT_TESTLISTENER_H    // -*- C++ -*-
#define CPPUNIT_TESTLISTENER_H

#include <cppunit/Portability.h>


CPPUNIT_NS_BEGIN


class Exception;
class Test;
class TestFailure;
class TestResult;


/*! \brief Listener for test progress and result.
 * \ingroup TrackingTestExecution
 *
 * Implementing the Observer pattern a TestListener may be registered
 * to a TestResult to obtain information on the testing progress. Use
 * specialized sub classes of TestListener for text output
 * (TextTestProgressListener). Do not use the Listener for the test
 * result output, use a subclass of Outputter instead.
 *
 * The test framework distinguishes between failures and errors.
 * A failure is anticipated and checked for with assertions. Errors are
 * unanticipated problems signified by exceptions that are not generated
 * by the framework.
 *
 * Here is an example to track test time:
 *
 *
 * \code
 * #include <cppunit/TestListener.h>
 * #include <cppunit/Test.h>
 * #include <time.h>    // for clock()
 *
 * class TimingListener : public CppUnit::TestListener
 * {
 * public:
 *   void startTest( CppUnit::Test *test )
 *   {
 *     _chronometer.start();
 *   }
 *  
 *   void endTest( CppUnit::Test *test )
 *   {
 *     _chronometer.end();
 *     addTest( test, _chronometer.elapsedTime() );
 *   }
 *
 *   // ... (interface to add/read test timing result)
 *
 * private:
 *   Clock _chronometer;
 * };
 * \endcode
 *   
 * And another example that track failure/success at test suite level and captures
 * the TestPath of each suite:
 * \code
 * class SuiteTracker : public CppUnit::TestListener
 * {
 * public:
 *   void startSuite( CppUnit::Test *suite )
 *   {
 *     m_currentPath.add( suite );
 *   }
 *   
 *   void addFailure( const TestFailure &failure )
 *   {
 *     m_suiteFailure.top() = false;
 *   }
 * 
 *   void endSuite( CppUnit::Test *suite )
 *   {
 *     m_suiteStatus.insert( std::make_pair( suite, m_suiteFailure.top() ) );
 *     m_suitePaths.insert( std::make_pair( suite, m_currentPath ) );
 *
 *     m_currentPath.up();
 *     m_suiteFailure.pop();
 *   }
 *
 * private:
 *   std::stack<bool> m_suiteFailure;
 *   CppUnit::TestPath m_currentPath;
 *   std::map<CppUnit::Test *, bool> m_suiteStatus;
 *   std::map<CppUnit::Test *, CppUnit::TestPath> m_suitePaths;
 * };
 * \endcode
 *
 * \see TestResult
 */
class CPPUNIT_API TestListener
{
public:
  virtual ~TestListener() {}
  
  /// Called when just before a TestCase is run.
  virtual void startTest( Test * /*test*/ ) {}

  /*! \brief Called when a failure occurs while running a test.
   * \see TestFailure.
   * \warning \a failure is a temporary object that is destroyed after the 
   *          method call. Use TestFailure::clone() to create a duplicate.
   */
  virtual void addFailure( const TestFailure & /*failure*/ ) {}

  /// Called just after a TestCase was run (even if a failure occured).
  virtual void endTest( Test * /*test*/ ) {}

  /*! \brief Called by a TestComposite just before running its child tests.
   */
  virtual void startSuite( Test * /*suite*/ ) {}

  /*! \brief Called by a TestComposite after running its child tests.
   */
  virtual void endSuite( Test * /*suite*/ ) {}

  /*! \brief Called by a TestRunner before running the test.
   * 
   * You can use this to do some global initialisation. A listener
   * could also use to output a 'prolog' to the test run.
   *
   * \param test Test that is going to be run.
   * \param eventManager Event manager used for the test run.
   */
  virtual void startTestRun( Test * /*test*/, 
                             TestResult * /*eventManager*/ ) {}

  /*! \brief Called by a TestRunner after running the test.
   *
   * TextTestProgressListener use this to emit a line break. You can also use this
   * to do some global uninitialisation.
   *
   * \param test Test that was run.
   * \param eventManager Event manager used for the test run.
   */
  virtual void endTestRun( Test * /*test*/, 
                           TestResult * /*eventManager*/ ) {}
};


CPPUNIT_NS_END

#endif // CPPUNIT_TESTLISTENER_H