RunListener (JUnit API)
Date: 2018-08-04

org.junit.runner.notification

## Class RunListener

- java.lang.Object
- - org.junit.runner.notification.RunListener

-     public class RunListener
      extends java.lang.Object

  Register an instance of this class with `RunNotifier` to be notified of events that occur during a test run. All of the methods in this class are abstract and have no implementation; override one or more methods to receive events.

  For example, suppose you have a `Cowbell` class that you want to make a noise whenever a test fails. You could write:

       public class RingingListener extends RunListener {
          public void testFailure(Failure failure) {
             Cowbell.ring();
          }
       }

  To invoke your listener, you need to run your tests through `JUnitCore`.

       public void main(String... args) {
          JUnitCore core= new JUnitCore();
          core.addListener(new RingingListener());
          core.run(MyTestClass.class);
       }

  If a listener throws an exception for a test event, the other listeners will have their `testFailure(Failure)` called with a `Description` of `Description.TEST_MECHANISM` to indicate the failure.

  By default, JUnit will synchronize calls to your listener. If your listener is thread-safe and you want to allow JUnit to call your listener from multiple threads when tests are run in parallel, you can annotate your test class with `RunListener.ThreadSafe`.

  Listener methods will be called from the same thread as is running the test, unless otherwise indicated by the method Javadoc

  Since:
    4.0
  See Also:
    `JUnitCore`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `RunListener.ThreadSafe` Indicates a `RunListener` that can have its methods called concurrently.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `RunListener()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `testAssumptionFailure(Failure failure)` Called when an atomic test flags that it assumes a condition that is false
    `void` | `testFailure(Failure failure)` Called when an atomic test fails, or when a listener throws an exception.
    `void` | `testFinished(Description description)` Called when an atomic test has finished, whether the test succeeds or fails.
    `void` | `testIgnored(Description description)` Called when a test will not be run, generally because a test method is annotated with `Ignore`.
    `void` | `testRunFinished(Result result)` Called when all tests have finished.
    `void` | `testRunStarted(Description description)` Called before any tests have been run.
    `void` | `testStarted(Description description)` Called when an atomic test is about to be started.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### RunListener

          public RunListener()

  - ### Method Detail

    - #### testRunStarted

          public void testRunStarted(Description description)
                              throws java.lang.Exception

      Called before any tests have been run. This may be called on an arbitrary thread.
      Parameters:
        `description` - describes the tests to be run
      Throws:
        `java.lang.Exception`

    - #### testRunFinished

          public void testRunFinished(Result result)
                               throws java.lang.Exception

      Called when all tests have finished. This may be called on an arbitrary thread.
      Parameters:
        `result` - the summary of the test run, including all the tests that failed
      Throws:
        `java.lang.Exception`

    - #### testStarted

          public void testStarted(Description description)
                           throws java.lang.Exception

      Called when an atomic test is about to be started.
      Parameters:
        `description` - the description of the test that is about to be run (generally a class and method name)
      Throws:
        `java.lang.Exception`

    - #### testFinished

          public void testFinished(Description description)
                            throws java.lang.Exception

      Called when an atomic test has finished, whether the test succeeds or fails.
      Parameters:
        `description` - the description of the test that just ran
      Throws:
        `java.lang.Exception`

    - #### testFailure

          public void testFailure(Failure failure)
                           throws java.lang.Exception

      Called when an atomic test fails, or when a listener throws an exception.

      In the case of a failure of an atomic test, this method will be called with the same `Description` passed to `testStarted(Description)`, from the same thread that called `testStarted(Description)`.

      In the case of a listener throwing an exception, this will be called with a `Description` of `Description.TEST_MECHANISM`, and may be called on an arbitrary thread.

      Parameters:
        `failure` - describes the test that failed and the exception that was thrown
      Throws:
        `java.lang.Exception`

    - #### testAssumptionFailure

          public void testAssumptionFailure(Failure failure)

      Called when an atomic test flags that it assumes a condition that is false
      Parameters:
        `failure` - describes the test that failed and the `AssumptionViolatedException` that was thrown

    - #### testIgnored

          public void testIgnored(Description description)
                           throws java.lang.Exception

      Called when a test will not be run, generally because a test method is annotated with `Ignore`.
      Parameters:
        `description` - describes the test that will not be run
      Throws:
        `java.lang.Exception`