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}.<p>
012 *
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 *
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 *
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 *
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 *
036 * <pre>
037 * &#064;RunWith(Suite.class)
038 * &#064;SuiteClasses({A.class, B.class, C.class})
039 * public class UsesExternalResource {
040 *     public static Server myServer= new Server();
041 *
042 *     &#064;ClassRule
043 *     public static ExternalResource resource= new ExternalResource() {
044 *       &#064;Override
045 *       protected void before() throws Throwable {
046 *          myServer.connect();
047 *      }
048 *
049 *      &#064;Override
050 *      protected void after() {
051 *              myServer.disconnect();
052 *      }
053 *   };
054 * }
055 * </pre>
056 *
057 * and the same using a method
058 *
059 * <pre>
060 * &#064;RunWith(Suite.class)
061 * &#064;SuiteClasses({A.class, B.class, C.class})
062 * public class UsesExternalResource {
063 *     public static Server myServer= new Server();
064 *
065 *     &#064;ClassRule
066 *     public static ExternalResource getResource() {
067 *         return new ExternalResource() {
068 *             &#064;Override
069 *             protected void before() throws Throwable {
070 *                 myServer.connect();
071 *             }
072 *
073 *             &#064;Override
074 *             protected void after() {
075 *                 myServer.disconnect();
076 *             }
077 *         };
078 *     }
079 * }
080 * </pre>
081 *
082 * For more information and more examples, see {@link org.junit.rules.TestRule}.
083 *
084 * @since 4.9
085 */
086@Retention(RetentionPolicy.RUNTIME)
087@Target({ElementType.FIELD, ElementType.METHOD})
088public @interface ClassRule {
089}