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 an atomic test is about to be started.
074 *
075 * @param description the description of the test that is about to be run
076 * (generally a class and method name)
077 */
078 public void testStarted(Description description) throws Exception {
079 }
080
081 /**
082 * Called when an atomic test has finished, whether the test succeeds or fails.
083 *
084 * @param description the description of the test that just ran
085 */
086 public void testFinished(Description description) throws Exception {
087 }
088
089 /**
090 * Called when an atomic test fails, or when a listener throws an exception.
091 *
092 * <p>In the case of a failure of an atomic test, this method will be called
093 * with the same {@code Description} passed to
094 * {@link #testStarted(Description)}, from the same thread that called
095 * {@link #testStarted(Description)}.
096 *
097 * <p>In the case of a listener throwing an exception, this will be called with
098 * a {@code Description} of {@link Description#TEST_MECHANISM}, and may be called
099 * 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 }