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 — 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}