001package org.junit.runner.notification;
002
003import org.junit.internal.AssumptionViolatedException;
004import org.junit.runner.Description;
005import org.junit.runner.Result;
006
007/**
008 * <p>If you need to respond to the events during a test run, extend <code>RunListener</code>
009 * and override the appropriate methods. If a listener throws an exception while processing a
010 * test event, it will be removed for the remainder of the test run.</p>
011 *
012 * <p>For example, suppose you have a <code>Cowbell</code>
013 * class that you want to make a noise whenever a test fails. You could write:
014 * <pre>
015 * public class RingingListener extends RunListener {
016 *    public void testFailure(Failure failure) {
017 *       Cowbell.ring();
018 *    }
019 * }
020 * </pre>
021 * </p>
022 *
023 * <p>To invoke your listener, you need to run your tests through <code>JUnitCore</code>.
024 * <pre>
025 * public void main(String... args) {
026 *    JUnitCore core= new JUnitCore();
027 *    core.addListener(new RingingListener());
028 *    core.run(MyTestClass.class);
029 * }
030 * </pre>
031 * </p>
032 *
033 * @see org.junit.runner.JUnitCore
034 * @since 4.0
035 */
036public class RunListener {
037
038    /**
039     * Called before any tests have been run.
040     *
041     * @param description describes the tests to be run
042     */
043    public void testRunStarted(Description description) throws Exception {
044    }
045
046    /**
047     * Called when all tests have finished
048     *
049     * @param result the summary of the test run, including all the tests that failed
050     */
051    public void testRunFinished(Result result) throws Exception {
052    }
053
054    /**
055     * Called when an atomic test is about to be started.
056     *
057     * @param description the description of the test that is about to be run
058     * (generally a class and method name)
059     */
060    public void testStarted(Description description) throws Exception {
061    }
062
063    /**
064     * Called when an atomic test has finished, whether the test succeeds or fails.
065     *
066     * @param description the description of the test that just ran
067     */
068    public void testFinished(Description description) throws Exception {
069    }
070
071    /**
072     * Called when an atomic test fails.
073     *
074     * @param failure describes the test that failed and the exception that was thrown
075     */
076    public void testFailure(Failure failure) throws Exception {
077    }
078
079    /**
080     * Called when an atomic test flags that it assumes a condition that is
081     * false
082     *
083     * @param failure describes the test that failed and the
084     * {@link AssumptionViolatedException} that was thrown
085     */
086    public void testAssumptionFailure(Failure failure) {
087    }
088
089    /**
090     * Called when a test will not be run, generally because a test method is annotated
091     * with {@link org.junit.Ignore}.
092     *
093     * @param description describes the test that will not be run
094     */
095    public void testIgnored(Description description) throws Exception {
096    }
097}
098
099