org.junit.runner.notification
Class RunListener

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

public class RunListener
extends 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

static interface

RunListener.ThreadSafe Indicates a RunListener that can have its methods called concurrently.

Constructor Summary

RunListener()

Method Summary

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.
void	testSuiteFinished(Description description) Called when a test suite has finished, whether the test suite succeeds or fails.
void	testSuiteStarted(Description description) Called when a test suite 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 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:

Exception

testRunFinished

public void testRunFinished(Result result)
                     throws 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:

Exception

testSuiteStarted

public void testSuiteStarted(Description description)
                      throws Exception

Called when a test suite is about to be started. If this method is called for a given Description, then testSuiteFinished(Description) will also be called for the same Description.

Note that not all runners will call this method, so runners should be prepared to handle testStarted(Description) calls for tests where there was no corresponding testSuiteStarted() call for the parent Description.

Parameters:

description - the description of the test suite that is about to be run (generally a class name)

Throws:

Exception

Since:

4.13

testSuiteFinished

public void testSuiteFinished(Description description)
                       throws Exception

Called when a test suite has finished, whether the test suite succeeds or fails. This method will not be called for a given Description unless testSuiteStarted(Description) was called for the same @code Description}.

Parameters:

description - the description of the test suite that just ran

Throws:

Exception

Since:

4.13

testStarted

public void testStarted(Description description)
                 throws 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:

Exception

testFinished

public void testFinished(Description description)
                  throws 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:

Exception

testFailure

public void testFailure(Failure failure)
                 throws 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:

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 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:

Exception