diff options
Diffstat (limited to 'src/main/java/org/junit/Rule.java')
| -rw-r--r-- | src/main/java/org/junit/Rule.java | 69 |
1 files changed, 46 insertions, 23 deletions
diff --git a/src/main/java/org/junit/Rule.java b/src/main/java/org/junit/Rule.java index 9e67c07..711235c 100644 --- a/src/main/java/org/junit/Rule.java +++ b/src/main/java/org/junit/Rule.java @@ -6,42 +6,65 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * Annotates fields that contain rules. Such a field must be public, not - * static, and a subtype of {@link org.junit.rules.TestRule}. - * The {@link org.junit.runners.model.Statement} passed - * to the {@link org.junit.rules.TestRule} will run any {@link Before} methods, + * 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 an order + * annotated {@link Rule}s on a class, they will be applied in order of fields first, then methods. + * 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. - * + * undefined, in general. Rules defined by fields will always be applied + * before Rules defined by methods. You can use a {@link org.junit.rules.RuleChain} if you want + * to have control over the order in which the Rules are applied. + * <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 { - * @Rule - * public TemporaryFolder folder= new TemporaryFolder(); - * - * @Test - * public void testUsingTempFolder() throws IOException { - * File createdFile= folder.newFile("myfile.txt"); - * File createdFolder= folder.newFolder("subfolder"); - * // ... - * } + * 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> - * - * For more information and more examples, see - * {@link org.junit.rules.TestRule}. + * <p> + * For more information and more examples, see + * {@link org.junit.rules.TestRule}. * - * Note: for backwards compatibility, this annotation may also mark - * fields of type {@link org.junit.rules.MethodRule}, which will be honored. However, - * this is a deprecated interface and feature. + * @since 4.7 */ @Retention(RetentionPolicy.RUNTIME) -@Target({ElementType.FIELD}) +@Target({ElementType.FIELD, ElementType.METHOD}) public @interface Rule { }
\ No newline at end of file |