001package org.junit;
002
003import java.lang.annotation.ElementType;
004import java.lang.annotation.Retention;
005import java.lang.annotation.RetentionPolicy;
006import 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 *
034 * <h3>Usage</h3>
035 * <p>
036 * For example, here is a test suite that connects to a server once before
037 * all the test classes run, and disconnects after they are finished:
038 * <pre>
039 * &#064;RunWith(Suite.class)
040 * &#064;SuiteClasses({A.class, B.class, C.class})
041 * public class UsesExternalResource {
042 *     public static Server myServer= new Server();
043 *
044 *     &#064;ClassRule
045 *     public static ExternalResource resource= new ExternalResource() {
046 *       &#064;Override
047 *       protected void before() throws Throwable {
048 *          myServer.connect();
049 *      }
050 *
051 *      &#064;Override
052 *      protected void after() {
053 *              myServer.disconnect();
054 *      }
055 *   };
056 * }
057 * </pre>
058 * <p>
059 * and the same using a method
060 * <pre>
061 * &#064;RunWith(Suite.class)
062 * &#064;SuiteClasses({A.class, B.class, C.class})
063 * public class UsesExternalResource {
064 *     public static Server myServer= new Server();
065 *
066 *     &#064;ClassRule
067 *     public static ExternalResource getResource() {
068 *         return new ExternalResource() {
069 *             &#064;Override
070 *             protected void before() throws Throwable {
071 *                 myServer.connect();
072 *             }
073 *
074 *             &#064;Override
075 *             protected void after() {
076 *                 myServer.disconnect();
077 *             }
078 *         };
079 *     }
080 * }
081 * </pre>
082 * <p>
083 * For more information and more examples, see {@link org.junit.rules.TestRule}.
084 *
085 * <h3>Ordering</h3>
086 * <p>
087 * You can use {@link #order()} if you want to have control over the order in
088 * which the Rules are applied.
089 *
090 * <pre>
091 * public class ThreeClassRules {
092 *     &#064;ClassRule(order = 0)
093 *     public static LoggingRule outer = new LoggingRule("outer rule");
094 *
095 *     &#064;ClassRule(order = 1)
096 *     public static LoggingRule middle = new LoggingRule("middle rule");
097 *
098 *     &#064;ClassRule(order = 2)
099 *     public static LoggingRule inner = new LoggingRule("inner rule");
100 *
101 *     // ...
102 * }
103 * </pre>
104 *
105 * @since 4.9
106 */
107@Retention(RetentionPolicy.RUNTIME)
108@Target({ElementType.FIELD, ElementType.METHOD})
109public @interface ClassRule {
110
111    /**
112     * Specifies the order in which rules are applied. The rules with a higher value are inner.
113     *
114     * @since 4.13
115     */
116    int order() default Rule.DEFAULT_ORDER;
117
118}