1 package org.junit.runner.notification; 2 3 import java.lang.annotation.Documented; 4 import java.lang.annotation.ElementType; 5 import java.lang.annotation.Retention; 6 import java.lang.annotation.RetentionPolicy; 7 import java.lang.annotation.Target; 8 9 import org.junit.runner.Description; 10 import org.junit.runner.Result; 11 12 /** 13 * Register an instance of this class with {@link RunNotifier} to be notified 14 * of events that occur during a test run. All of the methods in this class 15 * are abstract and have no implementation; override one or more methods to 16 * receive events. 17 * <p> 18 * For example, suppose you have a <code>Cowbell</code> 19 * class that you want to make a noise whenever a test fails. You could write: 20 * <pre> 21 * public class RingingListener extends RunListener { 22 * public void testFailure(Failure failure) { 23 * Cowbell.ring(); 24 * } 25 * } 26 * </pre> 27 * <p> 28 * To invoke your listener, you need to run your tests through <code>JUnitCore</code>. 29 * <pre> 30 * public void main(String... args) { 31 * JUnitCore core= new JUnitCore(); 32 * core.addListener(new RingingListener()); 33 * core.run(MyTestClass.class); 34 * } 35 * </pre> 36 * <p> 37 * If a listener throws an exception for a test event, the other listeners will 38 * have their {@link RunListener#testFailure(Failure)} called with a {@code Description} 39 * of {@link Description#TEST_MECHANISM} to indicate the failure. 40 * <p> 41 * By default, JUnit will synchronize calls to your listener. If your listener 42 * is thread-safe and you want to allow JUnit to call your listener from 43 * multiple threads when tests are run in parallel, you can annotate your 44 * test class with {@link RunListener.ThreadSafe}. 45 * <p> 46 * Listener methods will be called from the same thread as is running 47 * the test, unless otherwise indicated by the method Javadoc 48 * 49 * @see org.junit.runner.JUnitCore 50 * @since 4.0 51 */ 52 public class RunListener { 53 54 /** 55 * Called before any tests have been run. This may be called on an 56 * arbitrary thread. 57 * 58 * @param description describes the tests to be run 59 */ testRunStarted(Description description)60 public void testRunStarted(Description description) throws Exception { 61 } 62 63 /** 64 * Called when all tests have finished. This may be called on an 65 * arbitrary thread. 66 * 67 * @param result the summary of the test run, including all the tests that failed 68 */ testRunFinished(Result result)69 public void testRunFinished(Result result) throws Exception { 70 } 71 72 /** 73 * Called when an atomic test is about to be started. 74 * 75 * @param description the description of the test that is about to be run 76 * (generally a class and method name) 77 */ testStarted(Description description)78 public void testStarted(Description description) throws Exception { 79 } 80 81 /** 82 * Called when an atomic test has finished, whether the test succeeds or fails. 83 * 84 * @param description the description of the test that just ran 85 */ testFinished(Description description)86 public void testFinished(Description description) throws Exception { 87 } 88 89 /** 90 * Called when an atomic test fails, or when a listener throws an exception. 91 * 92 * <p>In the case of a failure of an atomic test, this method will be called 93 * with the same {@code Description} passed to 94 * {@link #testStarted(Description)}, from the same thread that called 95 * {@link #testStarted(Description)}. 96 * 97 * <p>In the case of a listener throwing an exception, this will be called with 98 * a {@code Description} of {@link Description#TEST_MECHANISM}, and may be called 99 * on an arbitrary thread. 100 * 101 * @param failure describes the test that failed and the exception that was thrown 102 */ testFailure(Failure failure)103 public void testFailure(Failure failure) throws Exception { 104 } 105 106 /** 107 * Called when an atomic test flags that it assumes a condition that is 108 * false 109 * 110 * @param failure describes the test that failed and the 111 * {@link org.junit.AssumptionViolatedException} that was thrown 112 */ testAssumptionFailure(Failure failure)113 public void testAssumptionFailure(Failure failure) { 114 } 115 116 /** 117 * Called when a test will not be run, generally because a test method is annotated 118 * with {@link org.junit.Ignore}. 119 * 120 * @param description describes the test that will not be run 121 */ testIgnored(Description description)122 public void testIgnored(Description description) throws Exception { 123 } 124 125 126 /** 127 * Indicates a {@code RunListener} that can have its methods called 128 * concurrently. This implies that the class is thread-safe (i.e. no set of 129 * listener calls can put the listener into an invalid state, even if those 130 * listener calls are being made by multiple threads without 131 * synchronization). 132 * 133 * @since 4.12 134 */ 135 @Documented 136 @Target(ElementType.TYPE) 137 @Retention(RetentionPolicy.RUNTIME) 138 public @interface ThreadSafe { 139 } 140 } 141