001/*
002 * Copyright 2002-2016 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.test.annotation;
018
019import java.lang.annotation.Documented;
020import java.lang.annotation.ElementType;
021import java.lang.annotation.Inherited;
022import java.lang.annotation.Retention;
023import java.lang.annotation.RetentionPolicy;
024import java.lang.annotation.Target;
025
026/**
027 * Test annotation which indicates that the
028 * {@link org.springframework.context.ApplicationContext ApplicationContext}
029 * associated with a test is <em>dirty</em> and should therefore be closed
030 * and removed from the context cache.
031 *
032 * <p>Use this annotation if a test has modified the context &mdash; for
033 * example, by modifying the state of a singleton bean, modifying the state
034 * of an embedded database, etc. Subsequent tests that request the same
035 * context will be supplied a new context.
036 *
037 * <p>{@code @DirtiesContext} may be used as a class-level and method-level
038 * annotation within the same class or class hierarchy. In such scenarios, the
039 * {@code ApplicationContext} will be marked as <em>dirty</em> before or
040 * after any such annotated method as well as before or after the current test
041 * class, depending on the configured {@link #methodMode} and {@link #classMode}.
042 *
043 * <p>As of Spring Framework 4.0, this annotation may be used as a
044 * <em>meta-annotation</em> to create custom <em>composed annotations</em>.
045 *
046 * <h3>Supported Test Phases</h3>
047 * <ul>
048 * <li><strong>Before current test class</strong>: when declared at the class
049 * level with class mode set to {@link ClassMode#BEFORE_CLASS BEFORE_CLASS}</li>
050 * <li><strong>Before each test method in current test class</strong>: when
051 * declared at the class level with class mode set to
052 * {@link ClassMode#BEFORE_EACH_TEST_METHOD BEFORE_EACH_TEST_METHOD}</li>
053 * <li><strong>Before current test method</strong>: when declared at the
054 * method level with method mode set to
055 * {@link MethodMode#BEFORE_METHOD BEFORE_METHOD}</li>
056 * <li><strong>After current test method</strong>: when declared at the
057 * method level with method mode set to
058 * {@link MethodMode#AFTER_METHOD AFTER_METHOD}</li>
059 * <li><strong>After each test method in current test class</strong>: when
060 * declared at the class level with class mode set to
061 * {@link ClassMode#AFTER_EACH_TEST_METHOD AFTER_EACH_TEST_METHOD}</li>
062 * <li><strong>After current test class</strong>: when declared at the
063 * class level with class mode set to
064 * {@link ClassMode#AFTER_CLASS AFTER_CLASS}</li>
065 * </ul>
066 *
067 * <p>{@code BEFORE_*} modes are supported by the
068 * {@link org.springframework.test.context.support.DirtiesContextBeforeModesTestExecutionListener DirtiesContextBeforeModesTestExecutionListener};
069 * {@code AFTER_*} modes are supported by the
070 * {@link org.springframework.test.context.support.DirtiesContextTestExecutionListener DirtiesContextTestExecutionListener}.
071 *
072 * @author Sam Brannen
073 * @author Rod Johnson
074 * @since 2.0
075 * @see org.springframework.test.context.ContextConfiguration
076 * @see org.springframework.test.context.support.DirtiesContextBeforeModesTestExecutionListener
077 * @see org.springframework.test.context.support.DirtiesContextTestExecutionListener
078 */
079@Target({ElementType.TYPE, ElementType.METHOD})
080@Retention(RetentionPolicy.RUNTIME)
081@Documented
082@Inherited
083public @interface DirtiesContext {
084
085        /**
086         * The <i>mode</i> to use when a test method is annotated with
087         * {@code @DirtiesContext}.
088         * <p>Defaults to {@link MethodMode#AFTER_METHOD AFTER_METHOD}.
089         * <p>Setting the method mode on an annotated test class has no meaning.
090         * For class-level control, use {@link #classMode} instead.
091         * @since 4.2
092         */
093        MethodMode methodMode() default MethodMode.AFTER_METHOD;
094
095        /**
096         * The <i>mode</i> to use when a test class is annotated with
097         * {@code @DirtiesContext}.
098         * <p>Defaults to {@link ClassMode#AFTER_CLASS AFTER_CLASS}.
099         * <p>Setting the class mode on an annotated test method has no meaning.
100         * For method-level control, use {@link #methodMode} instead.
101         * @since 3.0
102         */
103        ClassMode classMode() default ClassMode.AFTER_CLASS;
104
105        /**
106         * The context cache clearing <em>mode</em> to use when a context is
107         * configured as part of a hierarchy via
108         * {@link org.springframework.test.context.ContextHierarchy @ContextHierarchy}.
109         * <p>Defaults to {@link HierarchyMode#EXHAUSTIVE EXHAUSTIVE}.
110         * @since 3.2.2
111         */
112        HierarchyMode hierarchyMode() default HierarchyMode.EXHAUSTIVE;
113
114
115        /**
116         * Defines <i>modes</i> which determine how {@code @DirtiesContext} is
117         * interpreted when used to annotate a test method.
118         * @since 4.2
119         */
120        enum MethodMode {
121
122                /**
123                 * The associated {@code ApplicationContext} will be marked as
124                 * <em>dirty</em> before the corresponding test method.
125                 */
126                BEFORE_METHOD,
127
128                /**
129                 * The associated {@code ApplicationContext} will be marked as
130                 * <em>dirty</em> after the corresponding test method.
131                 */
132                AFTER_METHOD;
133        }
134
135
136        /**
137         * Defines <i>modes</i> which determine how {@code @DirtiesContext} is
138         * interpreted when used to annotate a test class.
139         * @since 3.0
140         */
141        enum ClassMode {
142
143                /**
144                 * The associated {@code ApplicationContext} will be marked as
145                 * <em>dirty</em> before the test class.
146                 *
147                 * @since 4.2
148                 */
149                BEFORE_CLASS,
150
151                /**
152                 * The associated {@code ApplicationContext} will be marked as
153                 * <em>dirty</em> before each test method in the class.
154                 *
155                 * @since 4.2
156                 */
157                BEFORE_EACH_TEST_METHOD,
158
159                /**
160                 * The associated {@code ApplicationContext} will be marked as
161                 * <em>dirty</em> after each test method in the class.
162                 */
163                AFTER_EACH_TEST_METHOD,
164
165                /**
166                 * The associated {@code ApplicationContext} will be marked as
167                 * <em>dirty</em> after the test class.
168                 */
169                AFTER_CLASS;
170        }
171
172
173        /**
174         * Defines <i>modes</i> which determine how the context cache is cleared
175         * when {@code @DirtiesContext} is used in a test whose context is
176         * configured as part of a hierarchy via
177         * {@link org.springframework.test.context.ContextHierarchy @ContextHierarchy}.
178         * @since 3.2.2
179         */
180        enum HierarchyMode {
181
182                /**
183                 * The context cache will be cleared using an <em>exhaustive</em> algorithm
184                 * that includes not only the {@linkplain HierarchyMode#CURRENT_LEVEL current level}
185                 * but also all other context hierarchies that share an ancestor context
186                 * common to the current test.
187                 *
188                 * <p>All {@code ApplicationContexts} that reside in a subhierarchy of
189                 * the common ancestor context will be removed from the context cache and
190                 * closed.
191                 */
192                EXHAUSTIVE,
193
194                /**
195                 * The {@code ApplicationContext} for the <em>current level</em> in the
196                 * context hierarchy and all contexts in subhierarchies of the current
197                 * level will be removed from the context cache and closed.
198                 *
199                 * <p>The <em>current level</em> refers to the {@code ApplicationContext}
200                 * at the lowest level in the context hierarchy that is visible from the
201                 * current test.
202                 */
203                CURRENT_LEVEL;
204        }
205
206}