001 package org.junit.rules;
002
003 import org.junit.runner.Description;
004 import org.junit.runners.model.Statement;
005
006 /**
007 * A TestRule is an alteration in how a test method, or set of test methods,
008 * is run and reported. A {@link TestRule} may add additional checks that cause
009 * a test that would otherwise fail to pass, or it may perform necessary setup or
010 * cleanup for tests, or it may observe test execution to report it elsewhere.
011 * {@link TestRule}s can do everything that could be done previously with
012 * methods annotated with {@link org.junit.Before},
013 * {@link org.junit.After}, {@link org.junit.BeforeClass}, or
014 * {@link org.junit.AfterClass}, but they are more powerful, and more easily
015 * shared
016 * between projects and classes.
017 *
018 * The default JUnit test runners for suites and
019 * individual test cases recognize {@link TestRule}s introduced in two different
020 * ways. {@link org.junit.Rule} annotates method-level
021 * {@link TestRule}s, and {@link org.junit.ClassRule}
022 * annotates class-level {@link TestRule}s. See Javadoc for those annotations
023 * for more information.
024 *
025 * Multiple {@link TestRule}s can be applied to a test or suite execution. The
026 * {@link Statement} that executes the method or suite is passed to each annotated
027 * {@link org.junit.Rule} in turn, and each may return a substitute or modified
028 * {@link Statement}, which is passed to the next {@link org.junit.Rule}, if any. For
029 * examples of how this can be useful, see these provided TestRules,
030 * or write your own:
031 *
032 * <ul>
033 * <li>{@link ErrorCollector}: collect multiple errors in one test method</li>
034 * <li>{@link ExpectedException}: make flexible assertions about thrown exceptions</li>
035 * <li>{@link ExternalResource}: start and stop a server, for example</li>
036 * <li>{@link TemporaryFolder}: create fresh files, and delete after test</li>
037 * <li>{@link TestName}: remember the test name for use during the method</li>
038 * <li>{@link TestWatcher}: add logic at events during method execution</li>
039 * <li>{@link Timeout}: cause test to fail after a set time</li>
040 * <li>{@link Verifier}: fail test if object state ends up incorrect</li>
041 * </ul>
042 *
043 * @since 4.9
044 */
045 public interface TestRule {
046 /**
047 * Modifies the method-running {@link Statement} to implement this
048 * test-running rule.
049 *
050 * @param base The {@link Statement} to be modified
051 * @param description A {@link Description} of the test implemented in {@code base}
052 * @return a new statement, which may be the same as {@code base},
053 * a wrapper around {@code base}, or a completely new Statement.
054 */
055 Statement apply(Statement base, Description description);
056 }