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 * after Rules defined by methods, i.e. the Statements returned by the former will
032 * be executed around those returned by the latter.
033 * <p>
034 * For example, here is a test suite that connects to a server once before
035 * all the test classes run, and disconnects after they are finished:
036 * <pre>
037 * @RunWith(Suite.class)
038 * @SuiteClasses({A.class, B.class, C.class})
039 * public class UsesExternalResource {
040 * public static Server myServer= new Server();
041 *
042 * @ClassRule
043 * public static ExternalResource resource= new ExternalResource() {
044 * @Override
045 * protected void before() throws Throwable {
046 * myServer.connect();
047 * }
048 *
049 * @Override
050 * protected void after() {
051 * myServer.disconnect();
052 * }
053 * };
054 * }
055 * </pre>
056 * <p>
057 * and the same using a method
058 * <pre>
059 * @RunWith(Suite.class)
060 * @SuiteClasses({A.class, B.class, C.class})
061 * public class UsesExternalResource {
062 * public static Server myServer= new Server();
063 *
064 * @ClassRule
065 * public static ExternalResource getResource() {
066 * return new ExternalResource() {
067 * @Override
068 * protected void before() throws Throwable {
069 * myServer.connect();
070 * }
071 *
072 * @Override
073 * protected void after() {
074 * myServer.disconnect();
075 * }
076 * };
077 * }
078 * }
079 * </pre>
080 * <p>
081 * For more information and more examples, see {@link org.junit.rules.TestRule}.
082 *
083 * @since 4.9
084 */
085 @Retention(RetentionPolicy.RUNTIME)
086 @Target({ElementType.FIELD, ElementType.METHOD})
087 public @interface ClassRule {
088
089 /**
090 * Specifies the order in which rules are applied. The rules with a higher value are inner.
091 *
092 * @since 4.13
093 */
094 int order() default Rule.DEFAULT_ORDER;
095
096 }