001 package org.junit.runner.notification;
002
003 import java.lang.annotation.Documented;
004 import java.lang.annotation.ElementType;
005 import java.lang.annotation.Retention;
006 import java.lang.annotation.RetentionPolicy;
007 import java.lang.annotation.Target;
008
009 import org.junit.runner.Description;
010 import org.junit.runner.Result;
011
012 /**
013 * Register an instance of this class with {@link RunNotifier} to be notified
014 * of events that occur during a test run. All of the methods in this class
015 * are abstract and have no implementation; override one or more methods to
016 * receive events.
017 * <p>
018 * For example, suppose you have a <code>Cowbell</code>
019 * class that you want to make a noise whenever a test fails. You could write:
020 * <pre>
021 * public class RingingListener extends RunListener {
022 * public void testFailure(Failure failure) {
023 * Cowbell.ring();
024 * }
025 * }
026 * </pre>
027 * <p>
028 * To invoke your listener, you need to run your tests through <code>JUnitCore</code>.
029 * <pre>
030 * public void main(String... args) {
031 * JUnitCore core= new JUnitCore();
032 * core.addListener(new RingingListener());
033 * core.run(MyTestClass.class);
034 * }
035 * </pre>
036 * <p>
037 * If a listener throws an exception for a test event, the other listeners will
038 * have their {@link RunListener#testFailure(Failure)} called with a {@code Description}
039 * of {@link Description#TEST_MECHANISM} to indicate the failure.
040 * <p>
041 * By default, JUnit will synchronize calls to your listener. If your listener
042 * is thread-safe and you want to allow JUnit to call your listener from
043 * multiple threads when tests are run in parallel, you can annotate your
044 * test class with {@link RunListener.ThreadSafe}.
045 * <p>
046 * Listener methods will be called from the same thread as is running
047 * the test, unless otherwise indicated by the method Javadoc
048 *
049 * @see org.junit.runner.JUnitCore
050 * @since 4.0
051 */
052 public class RunListener {
053
054 /**
055 * Called before any tests have been run. This may be called on an
056 * arbitrary thread.
057 *
058 * @param description describes the tests to be run
059 */
060 public void testRunStarted(Description description) throws Exception {
061 }
062
063 /**
064 * Called when all tests have finished. This may be called on an
065 * arbitrary thread.
066 *
067 * @param result the summary of the test run, including all the tests that failed
068 */
069 public void testRunFinished(Result result) throws Exception {
070 }
071
072 /**
073 * Called when a test suite is about to be started. If this method is
074 * called for a given {@link Description}, then {@link #testSuiteFinished(Description)}
075 * will also be called for the same {@code Description}.
076 *
077 * <p>Note that not all runners will call this method, so runners should
078 * be prepared to handle {@link #testStarted(Description)} calls for tests
079 * where there was no corresponding {@code testSuiteStarted()} call for
080 * the parent {@code Description}.
081 *
082 * @param description the description of the test suite that is about to be run
083 * (generally a class name)
084 * @since 4.13
085 */
086 public void testSuiteStarted(Description description) throws Exception {
087 }
088
089 /**
090 * Called when a test suite has finished, whether the test suite succeeds or fails.
091 * This method will not be called for a given {@link Description} unless
092 * {@link #testSuiteStarted(Description)} was called for the same @code Description}.
093 *
094 * @param description the description of the test suite that just ran
095 * @since 4.13
096 */
097 public void testSuiteFinished(Description description) throws Exception {
098 }
099
100 /**
101 * Called when an atomic test is about to be started.
102 *
103 * @param description the description of the test that is about to be run
104 * (generally a class and method name)
105 */
106 public void testStarted(Description description) throws Exception {
107 }
108
109 /**
110 * Called when an atomic test has finished, whether the test succeeds or fails.
111 *
112 * @param description the description of the test that just ran
113 */
114 public void testFinished(Description description) throws Exception {
115 }
116
117 /**
118 * Called when an atomic test fails, or when a listener throws an exception.
119 *
120 * <p>In the case of a failure of an atomic test, this method will be called
121 * with the same {@code Description} passed to
122 * {@link #testStarted(Description)}, from the same thread that called
123 * {@link #testStarted(Description)}.
124 *
125 * <p>In the case of a listener throwing an exception, this will be called with
126 * a {@code Description} of {@link Description#TEST_MECHANISM}, and may be called
127 * on an arbitrary thread.
128 *
129 * @param failure describes the test that failed and the exception that was thrown
130 */
131 public void testFailure(Failure failure) throws Exception {
132 }
133
134 /**
135 * Called when an atomic test flags that it assumes a condition that is
136 * false
137 *
138 * @param failure describes the test that failed and the
139 * {@link org.junit.AssumptionViolatedException} that was thrown
140 */
141 public void testAssumptionFailure(Failure failure) {
142 }
143
144 /**
145 * Called when a test will not be run, generally because a test method is annotated
146 * with {@link org.junit.Ignore}.
147 *
148 * @param description describes the test that will not be run
149 */
150 public void testIgnored(Description description) throws Exception {
151 }
152
153
154 /**
155 * Indicates a {@code RunListener} that can have its methods called
156 * concurrently. This implies that the class is thread-safe (i.e. no set of
157 * listener calls can put the listener into an invalid state, even if those
158 * listener calls are being made by multiple threads without
159 * synchronization).
160 *
161 * @since 4.12
162 */
163 @Documented
164 @Target(ElementType.TYPE)
165 @Retention(RetentionPolicy.RUNTIME)
166 public @interface ThreadSafe {
167 }
168 }