001 package org.junit;
002
003 import java.lang.annotation.ElementType;
004 import java.lang.annotation.Retention;
005 import java.lang.annotation.RetentionPolicy;
006 import 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 fields first, then methods.
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 * before Rules defined by methods. You can use a {@link org.junit.rules.RuleChain} if you want
024 * to have control over the order in which the Rules are applied.
025 * <p>
026 * For example, here is a test class that creates a temporary folder before
027 * each test method, and deletes it after each:
028 * <pre>
029 * public static class HasTempFolder {
030 * @Rule
031 * public TemporaryFolder folder= new TemporaryFolder();
032 *
033 * @Test
034 * public void testUsingTempFolder() throws IOException {
035 * File createdFile= folder.newFile("myfile.txt");
036 * File createdFolder= folder.newFolder("subfolder");
037 * // ...
038 * }
039 * }
040 * </pre>
041 * <p>
042 * And the same using a method.
043 * <pre>
044 * public static class HasTempFolder {
045 * private TemporaryFolder folder= new TemporaryFolder();
046 *
047 * @Rule
048 * public TemporaryFolder getFolder() {
049 * return folder;
050 * }
051 *
052 * @Test
053 * public void testUsingTempFolder() throws IOException {
054 * File createdFile= folder.newFile("myfile.txt");
055 * File createdFolder= folder.newFolder("subfolder");
056 * // ...
057 * }
058 * }
059 * </pre>
060 * <p>
061 * For more information and more examples, see
062 * {@link org.junit.rules.TestRule}.
063 *
064 * @since 4.7
065 */
066 @Retention(RetentionPolicy.RUNTIME)
067 @Target({ElementType.FIELD, ElementType.METHOD})
068 public @interface Rule {
069
070 }