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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 }