    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    }