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 * 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 * &#064;RunWith(Suite.class)
037 * &#064;SuiteClasses({A.class, B.class, C.class})
038 * public class UsesExternalResource {
039 *     public static Server myServer= new Server();
040 *
041 *     &#064;ClassRule
042 *     public static ExternalResource resource= new ExternalResource() {
043 *       &#064;Override
044 *       protected void before() throws Throwable {
045 *          myServer.connect();
046 *      }
047 *
048 *      &#064;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 * &#064;RunWith(Suite.class)
059 * &#064;SuiteClasses({A.class, B.class, C.class})
060 * public class UsesExternalResource {
061 *     public static Server myServer= new Server();
062 *
063 *     &#064;ClassRule
064 *     public static ExternalResource getResource() {
065 *         return new ExternalResource() {
066 *             &#064;Override
067 *             protected void before() throws Throwable {
068 *                 myServer.connect();
069 *             }
070 *
071 *             &#064;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})
086public @interface ClassRule {
087}