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 static fields that reference rules or methods that return them. A field must be public,
010 * static, and a subtype of {@link org.junit.rules.TestRule}. A method must be public static, and return
011 * a subtype of {@link org.junit.rules.TestRule}.
012 * <p>
013 * The {@link org.junit.runners.model.Statement} passed
014 * to the {@link org.junit.rules.TestRule} will run any {@link BeforeClass} methods,
015 * then the entire body of the test class (all contained methods, if it is
016 * a standard JUnit test class, or all contained classes, if it is a
017 * {@link org.junit.runners.Suite}), and finally any {@link AfterClass} methods.
018 * <p>
019 * The statement passed to the {@link org.junit.rules.TestRule} will never throw an exception,
020 * and throwing an exception from the {@link org.junit.rules.TestRule} will result in undefined
021 * behavior. This means that some {@link org.junit.rules.TestRule}s, such as
022 * {@link org.junit.rules.ErrorCollector},
023 * {@link org.junit.rules.ExpectedException},
024 * and {@link org.junit.rules.Timeout},
025 * have undefined behavior when used as {@link ClassRule}s.
026 * <p>
027 * If there are multiple
028 * annotated {@link ClassRule}s on a class, they will be applied in an order
029 * that depends on your JVM's implementation of the reflection API, which is
030 * undefined, in general. However, Rules defined by fields will always be applied
031 * before Rules defined by methods.
032 * <p>
033 * For example, here is a test suite that connects to a server once before
034 * all the test classes run, and disconnects after they are finished:
035 * <pre>
036 * @RunWith(Suite.class)
037 * @SuiteClasses({A.class, B.class, C.class})
038 * public class UsesExternalResource {
039 * public static Server myServer= new Server();
040 *
041 * @ClassRule
042 * public static ExternalResource resource= new ExternalResource() {
043 * @Override
044 * protected void before() throws Throwable {
045 * myServer.connect();
046 * }
047 *
048 * @Override
049 * protected void after() {
050 * myServer.disconnect();
051 * }
052 * };
053 * }
054 * </pre>
055 * <p>
056 * and the same using a method
057 * <pre>
058 * @RunWith(Suite.class)
059 * @SuiteClasses({A.class, B.class, C.class})
060 * public class UsesExternalResource {
061 * public static Server myServer= new Server();
062 *
063 * @ClassRule
064 * public static ExternalResource getResource() {
065 * return new ExternalResource() {
066 * @Override
067 * protected void before() throws Throwable {
068 * myServer.connect();
069 * }
070 *
071 * @Override
072 * protected void after() {
073 * myServer.disconnect();
074 * }
075 * };
076 * }
077 * }
078 * </pre>
079 * <p>
080 * For more information and more examples, see {@link org.junit.rules.TestRule}.
081 *
082 * @since 4.9
083 */
084 @Retention(RetentionPolicy.RUNTIME)
085 @Target({ElementType.FIELD, ElementType.METHOD})
086 public @interface ClassRule {
087 }