[SPR-4702] Added support for @DirtiesContext at the test class level.

Author: sbrannen

org.springframework.test/src/main/java/org/springframework/test/annotation/DirtiesContext.java

@@ -23,14 +23,30 @@
 import java.lang.annotation.Target;
 
 /**
- * Test annotation to indicate that a test method <em>dirties</em> the context
- * for the current test.
- *
+ * Test annotation which indicates that the
+ * {@link org.springframework.context.ApplicationContext ApplicationContext}
+ * associated with a test is <em>dirty</em> and should be closed:
+ * <ul>
+ * <li>after the current test, when declared at the method level, or</li>
+ * <li>after the current test class, when declared at the class level.</li>
+ * </ul>
+ * <p>
+ * Use this annotation if a test has modified the context (for example, by
+ * replacing a bean definition). Subsequent tests will be supplied a new
+ * context.
+ * </p>
+ * <p>
+ * <code>&#064;DirtiesContext</code> may be used as a class-level and
+ * method-level annotation within the same class. In such scenarios, the
+ * <code>ApplicationContext</code> will be marked as <em>dirty</em> after any
+ * such annotated method as well as after the entire class.
+ * </p>
+ * 
  * @author Rod Johnson
  * @author Sam Brannen
  * @since 2.0
  */
-@Target({ElementType.METHOD})
+@Target( { ElementType.TYPE, ElementType.METHOD })
 @Retention(RetentionPolicy.RUNTIME)
 @Documented
 public @interface DirtiesContext {

org.springframework.test/src/main/java/org/springframework/test/context/TestContextManager.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2008 the original author or authors.
+ * Copyright 2002-2009 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -236,6 +236,39 @@ protected Set<Class<? extends TestExecutionListener>> getDefaultTestExecutionLis
 		return defaultListenerClasses;
 	}
 
+	/**
+	 * Hook for pre-processing a test class <em>before</em> execution of any
+	 * tests within the class. Should be called prior to any framework-specific
+	 * <em>before class methods</em> (e.g., methods annotated with JUnit's
+	 * {@link org.junit.BeforeClass &#064;BeforeClass}).
+	 * <p>
+	 * An attempt will be made to give each registered
+	 * {@link TestExecutionListener} a chance to pre-process the test class
+	 * execution. If a listener throws an exception, however, the remaining
+	 * registered listeners will <strong>not</strong> be called.
+	 * 
+	 * @throws Exception if a registered TestExecutionListener throws an
+	 * exception
+	 * @see #getTestExecutionListeners()
+	 */
+	public void beforeTestClass() throws Exception {
+		final Class<?> testClass = getTestContext().getTestClass();
+		if (logger.isTraceEnabled()) {
+			logger.trace("beforeTestClass(): class [" + testClass + "]");
+		}
+
+		for (TestExecutionListener testExecutionListener : getTestExecutionListeners()) {
+			try {
+				testExecutionListener.beforeTestClass(getTestContext());
+			}
+			catch (Exception ex) {
+				logger.warn("Caught exception while allowing TestExecutionListener [" + testExecutionListener
+						+ "] to process 'before class' callback for test class [" + testClass + "]", ex);
+				throw ex;
+			}
+		}
+	}
+
 	/**
 	 * Hook for preparing a test instance prior to execution of any individual
 	 * test methods, for example for injecting dependencies, etc. Should be
@@ -279,7 +312,7 @@ public void prepareTestInstance(Object testInstance) throws Exception {
 	 * {@link Method test method}, for example for setting up test fixtures,
 	 * starting a transaction, etc. Should be called prior to any
 	 * framework-specific <em>before methods</em> (e.g., methods annotated with
-	 * JUnit's {@link org.junit.Before &#064;Before} ).
+	 * JUnit's {@link org.junit.Before &#064;Before}).
 	 * <p>
 	 * The managed {@link TestContext} will be updated with the supplied
 	 * <code>testInstance</code> and <code>testMethod</code>.
@@ -377,4 +410,51 @@ public void afterTestMethod(Object testInstance, Method testMethod, Throwable ex
 		}
 	}
 
+	/**
+	 * Hook for post-processing a test class <em>after</em> execution of all
+	 * tests within the class. Should be called after any framework-specific
+	 * <em>after class methods</em> (e.g., methods annotated with JUnit's
+	 * {@link org.junit.AfterClass &#064;AfterClass}).
+	 * <p>
+	 * Each registered {@link TestExecutionListener} will be given a chance to
+	 * post-process the test class. If a listener throws an exception, the
+	 * remaining registered listeners will still be called, but the first
+	 * exception thrown will be tracked and rethrown after all listeners have
+	 * executed. Note that registered listeners will be executed in the opposite
+	 * order in which they were registered.
+	 * 
+	 * @throws Exception if a registered TestExecutionListener throws an
+	 * exception
+	 * @see #getTestExecutionListeners()
+	 */
+	public void afterTestClass() throws Exception {
+		final Class<?> testClass = getTestContext().getTestClass();
+		if (logger.isTraceEnabled()) {
+			logger.trace("afterTestClass(): class [" + testClass + "]");
+		}
+
+		// Traverse the TestExecutionListeners in reverse order to ensure proper
+		// "wrapper"-style execution of listeners.
+		List<TestExecutionListener> listenersReversed = new ArrayList<TestExecutionListener>(
+			getTestExecutionListeners());
+		Collections.reverse(listenersReversed);
+
+		Exception afterTestClassException = null;
+		for (TestExecutionListener testExecutionListener : listenersReversed) {
+			try {
+				testExecutionListener.afterTestClass(getTestContext());
+			}
+			catch (Exception ex) {
+				logger.warn("Caught exception while allowing TestExecutionListener [" + testExecutionListener
+						+ "] to process 'after class' callback for test class [" + testClass + "]", ex);
+				if (afterTestClassException == null) {
+					afterTestClassException = ex;
+				}
+			}
+		}
+		if (afterTestClassException != null) {
+			throw afterTestClassException;
+		}
+	}
+
 }

org.springframework.test/src/main/java/org/springframework/test/context/TestExecutionListener.java

@@ -31,25 +31,43 @@
  * Spring provides the following out-of-the-box implementations:
  * </p>
  * <ul>
- * <li>{@link org.springframework.test.context.support.DependencyInjectionTestExecutionListener DependencyInjectionTestExecutionListener}</li>
- * <li>{@link org.springframework.test.context.support.DirtiesContextTestExecutionListener DirtiesContextTestExecutionListener}</li>
- * <li>{@link org.springframework.test.context.transaction.TransactionalTestExecutionListener TransactionalTestExecutionListener}</li>
+ * <li>
+ * {@link org.springframework.test.context.support.DependencyInjectionTestExecutionListener
+ * DependencyInjectionTestExecutionListener}</li>
+ * <li>
+ * {@link org.springframework.test.context.support.DirtiesContextTestExecutionListener
+ * DirtiesContextTestExecutionListener}</li>
+ * <li>
+ * {@link org.springframework.test.context.transaction.TransactionalTestExecutionListener
+ * TransactionalTestExecutionListener}</li>
  * </ul>
- *
+ * 
  * @author Sam Brannen
  * @author Juergen Hoeller
  * @since 2.5
  */
 public interface TestExecutionListener {
 
+	/**
+	 * Pre-processes a test class <em>before</em> execution of all tests within
+	 * the class.
+	 * <p>
+	 * This method should be called immediately before framework-specific
+	 * <em>before class</em> lifecycle callbacks.
+	 * 
+	 * @param testContext the test context for the test; never <code>null</code>
+	 * @throws Exception allows any exception to propagate
+	 */
+	void beforeTestClass(TestContext testContext) throws Exception;
+
 	/**
 	 * Prepares the {@link Object test instance} of the supplied
-	 * {@link TestContext test context}, for example by injecting
-	 * dependencies.
-	 * <p>This method should be called immediately after instantiation 
-	 * of the test instance but prior to any framework-specific lifecycle
-	 * callbacks.
-	 * @param testContext the test context for the test (never <code>null</code>)
+	 * {@link TestContext test context}, for example by injecting dependencies.
+	 * <p>
+	 * This method should be called immediately after instantiation of the test
+	 * instance but prior to any framework-specific lifecycle callbacks.
+	 * 
+	 * @param testContext the test context for the test; never <code>null</code>
 	 * @throws Exception allows any exception to propagate
 	 */
 	void prepareTestInstance(TestContext testContext) throws Exception;
@@ -59,10 +77,12 @@ public interface TestExecutionListener {
 	 * {@link java.lang.reflect.Method test method} in the supplied
 	 * {@link TestContext test context}, for example by setting up test
 	 * fixtures.
-	 * <p>This method should be called immediately prior to any
-	 * framework-specific <em>before</em> lifecycle callbacks.
+	 * <p>
+	 * This method should be called immediately prior to framework-specific
+	 * <em>before</em> lifecycle callbacks.
+	 * 
 	 * @param testContext the test context in which the test method will be
-	 * executed (never <code>null</code>)
+	 * executed; never <code>null</code>
 	 * @throws Exception allows any exception to propagate
 	 */
 	void beforeTestMethod(TestContext testContext) throws Exception;
@@ -72,12 +92,26 @@ public interface TestExecutionListener {
 	 * {@link java.lang.reflect.Method test method} in the supplied
 	 * {@link TestContext test context}, for example by tearing down test
 	 * fixtures.
-	 * <p>This method should be called immediately after any
-	 * framework-specific <em>after</em> lifecycle callbacks.
+	 * <p>
+	 * This method should be called immediately after framework-specific
+	 * <em>after</em> lifecycle callbacks.
+	 * 
 	 * @param testContext the test context in which the test method was
-	 * executed (never <code>null</code>)
+	 * executed; never <code>null</code>
 	 * @throws Exception allows any exception to propagate
 	 */
 	void afterTestMethod(TestContext testContext) throws Exception;
 
+	/**
+	 * Post-processes a test class <em>after</em> execution of all tests within
+	 * the class.
+	 * <p>
+	 * This method should be called immediately after framework-specific
+	 * <em>after class</em> lifecycle callbacks.
+	 * 
+	 * @param testContext the test context for the test; never <code>null</code>
+	 * @throws Exception allows any exception to propagate
+	 */
+	void afterTestClass(TestContext testContext) throws Exception;
+
 }

org.springframework.test/src/main/java/org/springframework/test/context/junit4/SpringJUnit4ClassRunner.java

@@ -39,8 +39,10 @@
 import org.springframework.test.annotation.Repeat;
 import org.springframework.test.annotation.Timed;
 import org.springframework.test.context.TestContextManager;
-import org.springframework.test.context.junit4.statements.RunSpringTestContextAfters;
-import org.springframework.test.context.junit4.statements.RunSpringTestContextBefores;
+import org.springframework.test.context.junit4.statements.RunAfterTestClassCallbacks;
+import org.springframework.test.context.junit4.statements.RunAfterTestMethodCallbacks;
+import org.springframework.test.context.junit4.statements.RunBeforeTestClassCallbacks;
+import org.springframework.test.context.junit4.statements.RunBeforeTestMethodCallbacks;
 import org.springframework.test.context.junit4.statements.SpringFailOnTimeout;
 import org.springframework.test.context.junit4.statements.SpringRepeat;
 
@@ -142,20 +144,6 @@ protected String getDefaultContextLoaderClassName(Class<?> clazz) {
 		return null;
 	}
 
-	/**
-	 * Delegates to the parent implementation for creating the test instance and
-	 * then allows the {@link #getTestContextManager() TestContextManager} to
-	 * prepare the test instance before returning it.
-	 * 
-	 * @see TestContextManager#prepareTestInstance(Object)
-	 */
-	@Override
-	protected Object createTest() throws Exception {
-		Object testInstance = super.createTest();
-		getTestContextManager().prepareTestInstance(testInstance);
-		return testInstance;
-	}
-
 	/**
 	 * Returns a description suitable for an ignored test class if the test is
 	 * disabled via <code>&#064;IfProfileValue</code> at the class-level, and
@@ -191,6 +179,47 @@ public void run(RunNotifier notifier) {
 		super.run(notifier);
 	}
 
+	/**
+	 * Wraps the {@link Statement} returned by the parent implementation with a
+	 * {@link RunBeforeTestClassCallbacks} statement, thus preserving the
+	 * default functionality but adding support for the Spring TestContext
+	 * Framework.
+	 * 
+	 * @see RunBeforeTestClassCallbacks
+	 */
+	@Override
+	protected Statement withBeforeClasses(Statement statement) {
+		Statement junitBeforeClasses = super.withBeforeClasses(statement);
+		return new RunBeforeTestClassCallbacks(junitBeforeClasses, getTestContextManager());
+	}
+
+	/**
+	 * Wraps the {@link Statement} returned by the parent implementation with a
+	 * {@link RunAfterTestClassCallbacks} statement, thus preserving the default
+	 * functionality but adding support for the Spring TestContext Framework.
+	 * 
+	 * @see RunAfterTestClassCallbacks
+	 */
+	@Override
+	protected Statement withAfterClasses(Statement statement) {
+		Statement junitAfterClasses = super.withAfterClasses(statement);
+		return new RunAfterTestClassCallbacks(junitAfterClasses, getTestContextManager());
+	}
+
+	/**
+	 * Delegates to the parent implementation for creating the test instance and
+	 * then allows the {@link #getTestContextManager() TestContextManager} to
+	 * prepare the test instance before returning it.
+	 * 
+	 * @see TestContextManager#prepareTestInstance(Object)
+	 */
+	@Override
+	protected Object createTest() throws Exception {
+		Object testInstance = super.createTest();
+		getTestContextManager().prepareTestInstance(testInstance);
+		return testInstance;
+	}
+
 	/**
 	 * Performs the same logic as
 	 * {@link BlockJUnit4ClassRunner#runChild(FrameworkMethod, RunNotifier)},
@@ -393,30 +422,31 @@ protected long getSpringTimeout(FrameworkMethod frameworkMethod) {
 
 	/**
 	 * Wraps the {@link Statement} returned by the parent implementation with a
-	 * {@link RunSpringTestContextBefores} statement, thus preserving the
+	 * {@link RunBeforeTestMethodCallbacks} statement, thus preserving the
 	 * default functionality but adding support for the Spring TestContext
 	 * Framework.
 	 * 
-	 * @see RunSpringTestContextBefores
+	 * @see RunBeforeTestMethodCallbacks
 	 */
 	@Override
 	protected Statement withBefores(FrameworkMethod frameworkMethod, Object testInstance, Statement statement) {
 		Statement junitBefores = super.withBefores(frameworkMethod, testInstance, statement);
-		return new RunSpringTestContextBefores(junitBefores, testInstance, frameworkMethod.getMethod(),
+		return new RunBeforeTestMethodCallbacks(junitBefores, testInstance, frameworkMethod.getMethod(),
 			getTestContextManager());
 	}
 
 	/**
 	 * Wraps the {@link Statement} returned by the parent implementation with a
-	 * {@link RunSpringTestContextAfters} statement, thus preserving the default
-	 * functionality but adding support for the Spring TestContext Framework.
+	 * {@link RunAfterTestMethodCallbacks} statement, thus preserving the
+	 * default functionality but adding support for the Spring TestContext
+	 * Framework.
 	 * 
-	 * @see RunSpringTestContextAfters
+	 * @see RunAfterTestMethodCallbacks
 	 */
 	@Override
 	protected Statement withAfters(FrameworkMethod frameworkMethod, Object testInstance, Statement statement) {
 		Statement junitAfters = super.withAfters(frameworkMethod, testInstance, statement);
-		return new RunSpringTestContextAfters(junitAfters, testInstance, frameworkMethod.getMethod(),
+		return new RunAfterTestMethodCallbacks(junitAfters, testInstance, frameworkMethod.getMethod(),
 			getTestContextManager());
 	}