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