If not specified the name will be inferred based on the numerical level within all - * declared contexts within the hierarchy. + *
If not specified the name will be inferred based on the numerical level + * within all declared contexts within the hierarchy. * - *
This attribute is only applicable when used within a test class hierarchy that is - * configured using {@link ContextHierarchy @ContextHierarchy}, in which case the name - * can be used for merging or overriding this configuration with configuration of the - * same name in hierarchy levels defined in superclasses. + *
This attribute is only applicable when used within a test class hierarchy + * that is configured using {@code @ContextHierarchy}, in which case the name + * can be used for merging or overriding this configuration + * with configuration of the same name in hierarchy levels defined in superclasses. + * See the Javadoc for {@link ContextHierarchy @ContextHierarchy} for details. * * @since 3.2.2 */ diff --git a/spring-test/src/main/java/org/springframework/test/context/ContextHierarchy.java b/spring-test/src/main/java/org/springframework/test/context/ContextHierarchy.java index b7846b7a0d..e9a68af829 100644 --- a/spring-test/src/main/java/org/springframework/test/context/ContextHierarchy.java +++ b/spring-test/src/main/java/org/springframework/test/context/ContextHierarchy.java @@ -28,6 +28,109 @@ import java.lang.annotation.Target; * a hierarchy of {@link org.springframework.context.ApplicationContext * ApplicationContexts} for integration tests. * + *
The following JUnit-based examples demonstrate common configuration + * scenarios for integration tests that require the use of context hierarchies. + * + *
{@code ControllerIntegrationTests} represents a typical integration testing + * scenario for a Spring MVC web application by declaring a context hierarchy + * consisting of two levels, one for the root {@code WebApplicationContext} + * (with {@code TestAppConfig}) and one for the dispatcher servlet + * {@code WebApplicationContext} (with {@code WebConfig}). The {@code + * WebApplicationContext} that is autowired into the test instance is + * the one for the child context (i.e., the lowest context in the hierarchy). + * + *
+ * @RunWith(SpringJUnit4ClassRunner.class)
+ * @WebAppConfiguration
+ * @ContextHierarchy({
+ * @ContextConfiguration(classes = TestAppConfig.class),
+ * @ContextConfiguration(classes = WebConfig.class)
+ * })
+ * public class ControllerIntegrationTests {
+ *
+ * @Autowired
+ * private WebApplicationContext wac;
+ *
+ * // ...
+ * }
+ *
+ * The following test classes define a context hierarchy within a test class + * hierarchy. {@code AbstractWebTests} declares the configuration for a root + * {@code WebApplicationContext} in a Spring-powered web application. Note, + * however, that {@code AbstractWebTests} does not declare {@code @ContextHierarchy}; + * consequently, subclasses of {@code AbstractWebTests} can optionally participate + * in a context hierarchy or follow the standard semantics for {@code @ContextConfiguration}. + * {@code SoapWebServiceTests} and {@code RestWebServiceTests} both extend + * {@code AbstractWebTests} and define a context hierarchy via {@code @ContextHierarchy}. + * The result is that three application contexts will be loaded (one for each + * declaration of {@code @ContextConfiguration}, and the application context + * loaded based on the configuration in {@code AbstractWebTests} will be set as + * the parent context for each of the contexts loaded for the concrete subclasses. + * + *
+ * @RunWith(SpringJUnit4ClassRunner.class)
+ * @WebAppConfiguration
+ * @ContextConfiguration("file:src/main/webapp/WEB-INF/applicationContext.xml")
+ * public abstract class AbstractWebTests {}
+ *
+ * @ContextHierarchy(@ContextConfiguration("/spring/soap-ws-config.xml")
+ * public class SoapWebServiceTests extends AbstractWebTests {}
+ *
+ * @ContextHierarchy(@ContextConfiguration("/spring/rest-ws-config.xml")
+ * public class RestWebServiceTests extends AbstractWebTests {}
+ *
+ * The following classes demonstrate the use of named hierarchy levels
+ * in order to merge the configuration for specific levels in a context
+ * hierarchy. {@code BaseTests} defines two levels in the hierarchy, {@code parent}
+ * and {@code child}. {@code ExtendedTests} extends {@code BaseTests} and instructs
+ * the Spring TestContext Framework to merge the context configuration for the
+ * {@code child} hierarchy level, simply by ensuring that the names declared via
+ * {@link ContextConfiguration#name} are both {@code "child"}. The result is that
+ * three application contexts will be loaded: one for {@code "/app-config.xml"},
+ * one for {@code "/user-config.xml"}, and one for {"/user-config.xml",
+ * "/order-config.xml"}. As with the previous example, the application
+ * context loaded from {@code "/app-config.xml"} will be set as the parent context
+ * for the contexts loaded from {@code "/user-config.xml"} and {"/user-config.xml",
+ * "/order-config.xml"}.
+ *
+ *
+ * @RunWith(SpringJUnit4ClassRunner.class)
+ * @ContextHierarchy({
+ * @ContextConfiguration(name = "parent", locations = "/app-config.xml"),
+ * @ContextConfiguration(name = "child", locations = "/user-config.xml")
+ * })
+ * public class BaseTests {}
+ *
+ * @ContextHierarchy(
+ * @ContextConfiguration(name = "child", locations = "/order-config.xml")
+ * )
+ * public class ExtendedTests extends BaseTests {}
+ *
+ * In contrast to the previous example, this example demonstrates how to + * override the configuration for a given named level in a context hierarchy + * by setting the {@link ContextConfiguration#inheritLocations} flag to {@code false}. + * Consequently, the application context for {@code ExtendedTests} will be loaded + * only from {@code "/test-user-config.xml"} and will have its parent set to the + * context loaded from {@code "/app-config.xml"}. + * + *
+ * @RunWith(SpringJUnit4ClassRunner.class)
+ * @ContextHierarchy({
+ * @ContextConfiguration(name = "parent", locations = "/app-config.xml"),
+ * @ContextConfiguration(name = "child", locations = "/user-config.xml")
+ * })
+ * public class BaseTests {}
+ *
+ * @ContextHierarchy(
+ * @ContextConfiguration(name = "child", locations = "/test-user-config.xml", inheritLocations=false)
+ * )
+ * public class ExtendedTests extends BaseTests {}
+ *
* @author Sam Brannen
* @since 3.2.2
* @see ContextConfiguration
@@ -47,7 +150,7 @@ public @interface ContextHierarchy {
* of the context hierarchy within a test class hierarchy, you must explicitly
* name that level by supplying the same value to the {@link ContextConfiguration#name
* name} attribute in {@code @ContextConfiguration} at each level in the
- * class hierarchy.
+ * class hierarchy. See the class-level Javadoc for examples.
*/
ContextConfiguration[] value();