001package org.junit;
002
003import java.lang.annotation.ElementType;
004import java.lang.annotation.Retention;
005import java.lang.annotation.RetentionPolicy;
006import java.lang.annotation.Target;
007
008/**
009 * Annotates fields that reference rules or methods that return a rule. A field must be public, not
010 * static, and a subtype of {@link org.junit.rules.TestRule} (preferred) or
011 * {@link org.junit.rules.MethodRule}. A method must be public, not static,
012 * and must return a subtype of {@link org.junit.rules.TestRule} (preferred) or
013 * {@link org.junit.rules.MethodRule}.
014 * <p>
015 * The {@link org.junit.runners.model.Statement} passed
016 * to the {@link org.junit.rules.TestRule} will run any {@link Before} methods,
017 * then the {@link Test} method, and finally any {@link After} methods,
018 * throwing an exception if any of these fail.  If there are multiple
019 * annotated {@link Rule}s on a class, they will be applied in order of methods first, then fields.
020 * However, if there are multiple fields (or methods) they will be applied in an order
021 * that depends on your JVM's implementation of the reflection API, which is
022 * undefined, in general. Rules defined by fields will always be applied
023 * after Rules defined by methods, i.e. the Statements returned by the former will
024 * be executed around those returned by the latter.
025 *
026 * <h3>Usage</h3>
027 * <p>
028 * For example, here is a test class that creates a temporary folder before
029 * each test method, and deletes it after each:
030 * <pre>
031 * public static class HasTempFolder {
032 *     &#064;Rule
033 *     public TemporaryFolder folder= new TemporaryFolder();
034 *
035 *     &#064;Test
036 *     public void testUsingTempFolder() throws IOException {
037 *         File createdFile= folder.newFile(&quot;myfile.txt&quot;);
038 *         File createdFolder= folder.newFolder(&quot;subfolder&quot;);
039 *         // ...
040 *     }
041 * }
042 * </pre>
043 * <p>
044 * And the same using a method.
045 * <pre>
046 * public static class HasTempFolder {
047 *     private TemporaryFolder folder= new TemporaryFolder();
048 *
049 *     &#064;Rule
050 *     public TemporaryFolder getFolder() {
051 *         return folder;
052 *     }
053 *
054 *     &#064;Test
055 *     public void testUsingTempFolder() throws IOException {
056 *         File createdFile= folder.newFile(&quot;myfile.txt&quot;);
057 *         File createdFolder= folder.newFolder(&quot;subfolder&quot;);
058 *         // ...
059 *     }
060 * }
061 * </pre>
062 * <p>
063 * For more information and more examples, see
064 * {@link org.junit.rules.TestRule}.
065 *
066 * <h3>Ordering</h3>
067 * <p>
068 * You can use {@link #order()} if you want to have control over the order in
069 * which the Rules are applied.
070 *
071 * <pre>
072 * public class ThreeRules {
073 *     &#064;Rule(order = 0)
074 *     public LoggingRule outer = new LoggingRule("outer rule");
075 *
076 *     &#064;Rule(order = 1)
077 *     public LoggingRule middle = new LoggingRule("middle rule");
078 *
079 *     &#064;Rule(order = 2)
080 *     public LoggingRule inner = new LoggingRule("inner rule");
081 *
082 *     // ...
083 * }
084 * </pre>
085 *
086 * @since 4.7
087 */
088@Retention(RetentionPolicy.RUNTIME)
089@Target({ElementType.FIELD, ElementType.METHOD})
090public @interface Rule {
091
092    int DEFAULT_ORDER = -1;
093
094    /**
095     * Specifies the order in which rules are applied. The rules with a higher value are inner.
096     *
097     * @since 4.13
098     */
099    int order() default DEFAULT_ORDER;
100
101}