A Listener
is a class you can register with Catch that will then be passed events, such as a test case starting or ending, as they happen during a test run. Listeners
are actually types of Reporters
, with a few small differences:
Catch::TestEventListenerBase
, which has default stubs for all the events, so you are not forced to implement events you're not interested in.CATCH_REGISTER_LISTENER
Simply derive a class from Catch::TestEventListenerBase
and implement the methods you are interested in, either in the main source file (i.e. the one that defines CATCH_CONFIG_MAIN
or CATCH_CONFIG_RUNNER
), or in a file that defines CATCH_CONFIG_EXTERNAL_INTERFACES
.
Then register it using CATCH_REGISTER_LISTENER
.
For example (complete source code):
#define CATCH_CONFIG_MAIN #include "catch.hpp" struct MyListener : Catch::TestEventListenerBase { using TestEventListenerBase::TestEventListenerBase; // inherit constructor virtual void testCaseStarting( Catch::TestCaseInfo const& testInfo ) override { // Perform some setup before a test case is run } virtual void testCaseEnded( Catch::TestCaseStats const& testCaseStats ) override { // Tear-down after a test case is run } }; CATCH_REGISTER_LISTENER( MyListener )
Note that you should not use any assertion macros within a Listener!
The following are the methods that can be overridden in the Listener:
// The whole test run, starting and ending virtual void testRunStarting( TestRunInfo const& testRunInfo ); virtual void testRunEnded( TestRunStats const& testRunStats ); // Test cases starting and ending virtual void testCaseStarting( TestCaseInfo const& testInfo ); virtual void testCaseEnded( TestCaseStats const& testCaseStats ); // Sections starting and ending virtual void sectionStarting( SectionInfo const& sectionInfo ); virtual void sectionEnded( SectionStats const& sectionStats ); // Assertions before/ after virtual void assertionStarting( AssertionInfo const& assertionInfo ); virtual bool assertionEnded( AssertionStats const& assertionStats ); // A test is being skipped (because it is "hidden") virtual void skipTest( TestCaseInfo const& testInfo );
More information about the events (e.g. name of the test case) is contained in the structs passed as arguments - just look in the source code to see what fields are available.