001package org.junit.runner.notification;
002
003import java.lang.annotation.Documented;
004import java.lang.annotation.ElementType;
005import java.lang.annotation.Retention;
006import java.lang.annotation.RetentionPolicy;
007import java.lang.annotation.Target;
008
009import org.junit.runner.Description;
010import 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 */
052public 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}