docs/event-listeners.md

   1 # Event Listeners
   2
   3 A `Listener` is a class you can register with Catch that will then be passed events,
   4 such as a test case starting or ending, as they happen during a test run.
   5 `Listeners` are actually types of `Reporters`, with a few small differences:
   6
   7 1. Once registered in code they are automatically used - you don't need to specify them on the command line
   8 2. They are called in addition to (just before) any reporters, and you can register multiple listeners.
   9 3. They derive from `Catch::TestEventListenerBase`, which has default stubs for all the events,
  10 so you are not forced to implement events you're not interested in.
  11 4. You register a listener with `CATCH_REGISTER_LISTENER`
  12
  13
  14 ## Implementing a Listener
  15
  16 In your main source file (i.e. the one that has the `#define` for `CATCH_CONFIG_MAIN` or `CATCH_CONFIG_RUNNER`),
  17 simply derive a class from `Catch::TestEventListenerBase` and implement the methods you are interested in.
  18 Then register it using `INTERNAL_CATCH_REGISTER_LISTENER`.
  19
  20 For example:
  21
  22 ```c++
  23 #define CATCH_CONFIG_MAIN
  24 #include "catch.hpp"
  25
  26 struct MyListener : Catch::TestEventListenerBase {
  27
  28     using TestEventListenerBase::TestEventListenerBase; // inherit constructor
  29
  30     virtual void testCaseStarting( Catch::TestCaseInfo const& testInfo ) override {
  31         // Perform some setup before a test case is run
  32     }
  33
  34     virtual void testCaseEnded( Catch::TestCaseStats const& testCaseStats ) override {
  35         // Tear-down after a test case is run
  36     }
  37 };
  38 CATCH_REGISTER_LISTENER( MyListener )
  39 ```
  40
  41 _Note that you should not use any assertion macros within a Listener!_
  42
  43 ## Events that can be hooked
  44
  45 The following are the methods that can be overriden in the Listener:
  46
  47 ```c++
  48 // The whole test run, starting and ending
  49 virtual void testRunStarting( TestRunInfo const& testRunInfo );
  50 virtual void testRunEnded( TestRunStats const& testRunStats );
  51
  52 // Test cases starting and ending
  53 virtual void testCaseStarting( TestCaseInfo const& testInfo );
  54 virtual void testCaseEnded( TestCaseStats const& testCaseStats );
  55
  56 // Sections starting and ending
  57 virtual void sectionStarting( SectionInfo const& sectionInfo );
  58 virtual void sectionEnded( SectionStats const& sectionStats );
  59
  60 // Assertions before/ after
  61 virtual void assertionStarting( AssertionInfo const& assertionInfo );
  62 virtual bool assertionEnded( AssertionStats const& assertionStats );
  63
  64 // A test is being skipped (because it is "hidden")
  65 virtual void skipTest( TestCaseInfo const& testInfo );
  66 ```
  67
  68 More information about the events (e.g. name of the test case) is contained in the structs passed as arguments -
  69 just look in the source code to see what fields are available.
  70
  71 ---
  72
  73 [Home](Readme.md)