| package org.junit; |
| |
| import java.lang.annotation.ElementType; |
| import java.lang.annotation.Retention; |
| import java.lang.annotation.RetentionPolicy; |
| import java.lang.annotation.Target; |
| |
| /** |
| * Annotates fields that reference rules or methods that return a rule. A field must be public, not |
| * static, and a subtype of {@link org.junit.rules.TestRule} (preferred) or |
| * {@link org.junit.rules.MethodRule}. A method must be public, not static, |
| * and must return a subtype of {@link org.junit.rules.TestRule} (preferred) or |
| * {@link org.junit.rules.MethodRule}. |
| * <p> |
| * The {@link org.junit.runners.model.Statement} passed |
| * to the {@link org.junit.rules.TestRule} will run any {@link Before} methods, |
| * then the {@link Test} method, and finally any {@link After} methods, |
| * throwing an exception if any of these fail. If there are multiple |
| * annotated {@link Rule}s on a class, they will be applied in order of methods first, then fields. |
| * However, if there are multiple fields (or methods) they will be applied in an order |
| * that depends on your JVM's implementation of the reflection API, which is |
| * undefined, in general. Rules defined by fields will always be applied |
| * after Rules defined by methods, i.e. the Statements returned by the former will |
| * be executed around those returned by the latter. |
| * |
| * <h3>Usage</h3> |
| * <p> |
| * For example, here is a test class that creates a temporary folder before |
| * each test method, and deletes it after each: |
| * <pre> |
| * public static class HasTempFolder { |
| * @Rule |
| * public TemporaryFolder folder= new TemporaryFolder(); |
| * |
| * @Test |
| * public void testUsingTempFolder() throws IOException { |
| * File createdFile= folder.newFile("myfile.txt"); |
| * File createdFolder= folder.newFolder("subfolder"); |
| * // ... |
| * } |
| * } |
| * </pre> |
| * <p> |
| * And the same using a method. |
| * <pre> |
| * public static class HasTempFolder { |
| * private TemporaryFolder folder= new TemporaryFolder(); |
| * |
| * @Rule |
| * public TemporaryFolder getFolder() { |
| * return folder; |
| * } |
| * |
| * @Test |
| * public void testUsingTempFolder() throws IOException { |
| * File createdFile= folder.newFile("myfile.txt"); |
| * File createdFolder= folder.newFolder("subfolder"); |
| * // ... |
| * } |
| * } |
| * </pre> |
| * <p> |
| * For more information and more examples, see |
| * {@link org.junit.rules.TestRule}. |
| * |
| * <h3>Ordering</h3> |
| * <p> |
| * You can use {@link #order()} if you want to have control over the order in |
| * which the Rules are applied. |
| * |
| * <pre> |
| * public class ThreeRules { |
| * @Rule(order = 0) |
| * public LoggingRule outer = new LoggingRule("outer rule"); |
| * |
| * @Rule(order = 1) |
| * public LoggingRule middle = new LoggingRule("middle rule"); |
| * |
| * @Rule(order = 2) |
| * public LoggingRule inner = new LoggingRule("inner rule"); |
| * |
| * // ... |
| * } |
| * </pre> |
| * |
| * @since 4.7 |
| */ |
| @Retention(RetentionPolicy.RUNTIME) |
| @Target({ElementType.FIELD, ElementType.METHOD}) |
| public @interface Rule { |
| |
| int DEFAULT_ORDER = -1; |
| |
| /** |
| * Specifies the order in which rules are applied. The rules with a higher value are inner. |
| * |
| * @since 4.13 |
| */ |
| int order() default DEFAULT_ORDER; |
| |
| } |