Event Listeners

CharliePoole edited this page Sep 5, 2016 · 2 revisions
Clone this wiki locally

Event Listeners are extensions that respond to specific events occuring during the running of a test. They implement the ITestEventListener interface. NUnit itself makes extensive use of this interface when running tests. By creating an extension, user code may also respond to test events.

The definition of an Event Listener extension will look something like this:

[Extension(EngineVersion="3.4")]
public class MyEventListener : ITestEventListener
{
    ...
}

Note: The EngineVersion property is used to document the fact that the event listener extension point was only added to the engine with version 3.4. It's function here is purely documentary because the EngineVersion property itself was also added in version 3.4. Event listeners should not be installed with earlier versions.

The ITestEventListener interface is defined as follows:

/// <summary>
/// The ITestListener interface is used to receive notices of significant
/// events while a test is running. It's single method accepts an Xml string, 
/// which may represent any event generated by the test framework, the driver
/// or any of the runners internal to the engine. Use of Xml means that
/// any driver and framework may add additional events and the engine will
/// simply pass them on through this interface.
/// </summary>
[TypeExtensionPoint(
    Description = "Allows an extension to process progress reports and other events from the test.")]
public interface ITestEventListener
{
    /// <summary>
    /// Handle a progress report or other event.
    /// </summary>
    /// <param name="report">An XML progress report.</param>
    void OnTestEvent(string report);
}

The argument to OnTestEvent is an XML-formatted string, with a different top-level element for each potential event.

  • Start of run - <start-run...>
  • End of run - <test-run...>
  • Start of a test suite - <start-suite...>
  • End of a test suite - <test-suite...>
  • Start of a test case - <start-test...>
  • End of a test case - <test-case...>

The XML report signalling the end of a test case contains all available information, including the result. The start events only provide basic identifying information. See XML Formats for a full description of each report.