001    package org.junit.rules;
002    
003    import org.junit.Rule;
004    import org.junit.runners.model.FrameworkMethod;
005    import org.junit.runners.model.Statement;
006    
007    /**
008     * A MethodRule is an alteration in how a test method is run and reported.
009     * Multiple {@link MethodRule}s can be applied to a test method. The
010     * {@link Statement} that executes the method is passed to each annotated
011     * {@link Rule} in turn, and each may return a substitute or modified
012     * {@link Statement}, which is passed to the next {@link Rule}, if any. For
013     * examples of how this can be useful, see these provided MethodRules,
014     * or write your own:
015     *
016     * <ul>
017     *   <li>{@link ErrorCollector}: collect multiple errors in one test method</li>
018     *   <li>{@link ExpectedException}: make flexible assertions about thrown exceptions</li>
019     *   <li>{@link ExternalResource}: start and stop a server, for example</li>
020     *   <li>{@link TemporaryFolder}: create fresh files, and delete after test</li>
021     *   <li>{@link TestName}: remember the test name for use during the method</li>
022     *   <li>{@link TestWatchman}: add logic at events during method execution</li>
023     *   <li>{@link Timeout}: cause test to fail after a set time</li>
024     *   <li>{@link Verifier}: fail test if object state ends up incorrect</li>
025     * </ul>
026     *
027     * Note that {@link MethodRule} has been replaced by {@link TestRule},
028     * which has the added benefit of supporting class rules.
029     *
030     * @since 4.7
031     */
032    public interface MethodRule {
033        /**
034         * Modifies the method-running {@link Statement} to implement an additional
035         * test-running rule.
036         *
037         * @param base The {@link Statement} to be modified
038         * @param method The method to be run
039         * @param target The object on which the method will be run.
040         * @return a new statement, which may be the same as {@code base},
041         *         a wrapper around {@code base}, or a completely new Statement.
042         */
043        Statement apply(Statement base, FrameworkMethod method, Object target);
044    }