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    }