org.springframework.test.context

Annotation Type ContextHierarchy

@Target(value=TYPE)
 @Retention(value=RUNTIME)
 @Documented
 @Inherited
public @interface ContextHierarchy

@ContextHierarchy is a class-level annotation that is used to define a hierarchy of ApplicationContexts for integration tests.

Examples

The following JUnit-based examples demonstrate common configuration scenarios for integration tests that require the use of context hierarchies.

Single Test Class with Context Hierarchy

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 WebApplicationContext (with TestAppConfig) and one for the dispatcher servlet WebApplicationContext (with WebConfig). The WebApplicationContext that is autowired into the test instance is the one for the child context (i.e., the lowest context in the hierarchy).

 @RunWith(SpringRunner.class)
 @WebAppConfiguration
 @ContextHierarchy({
     @ContextConfiguration(classes = TestAppConfig.class),
     @ContextConfiguration(classes = WebConfig.class)
 })
 public class ControllerIntegrationTests {

     @Autowired
     private WebApplicationContext wac;

     // ...
 }

Class Hierarchy with Implicit Parent Context

The following test classes define a context hierarchy within a test class hierarchy. AbstractWebTests declares the configuration for a root WebApplicationContext in a Spring-powered web application. Note, however, that AbstractWebTests does not declare @ContextHierarchy; consequently, subclasses of AbstractWebTests can optionally participate in a context hierarchy or follow the standard semantics for @ContextConfiguration. SoapWebServiceTests and RestWebServiceTests both extend AbstractWebTests and define a context hierarchy via @ContextHierarchy. The result is that three application contexts will be loaded (one for each declaration of @ContextConfiguration, and the application context loaded based on the configuration in AbstractWebTests will be set as the parent context for each of the contexts loaded for the concrete subclasses.

 @RunWith(SpringRunner.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 {}

Class Hierarchy with Merged Context Hierarchy Configuration

The following classes demonstrate the use of named hierarchy levels in order to merge the configuration for specific levels in a context hierarchy. BaseTests defines two levels in the hierarchy, parent and child. ExtendedTests extends BaseTests and instructs the Spring TestContext Framework to merge the context configuration for the child hierarchy level, simply by ensuring that the names declared via ContextConfiguration.name() are both "child". The result is that three application contexts will be loaded: one for "/app-config.xml", one for "/user-config.xml", and one for {"/user-config.xml", "/order-config.xml"}. As with the previous example, the application context loaded from "/app-config.xml" will be set as the parent context for the contexts loaded from "/user-config.xml" and {"/user-config.xml", "/order-config.xml"}.

 @RunWith(SpringRunner.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 {}

Class Hierarchy with Overridden Context Hierarchy Configuration

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 ContextConfiguration.inheritLocations() flag to false. Consequently, the application context for ExtendedTests will be loaded only from "/test-user-config.xml" and will have its parent set to the context loaded from "/app-config.xml".

 @RunWith(SpringRunner.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 {}

This annotation may be used as a meta-annotation to create custom composed annotations.

As of Spring Framework 5.3, this annotation will be inherited from an enclosing test class by default. See @NestedTestConfiguration for details.

Since:

3.2.2

Author:

Sam Brannen

See Also:

ContextConfiguration, ApplicationContext

Required Element Summary

Required Elements

Modifier and Type	Required Element and Description
ContextConfiguration[]	value A list of @ContextConfiguration instances, each of which defines a level in the context hierarchy.

Element Detail

value

public abstract ContextConfiguration[] value

A list of @ContextConfiguration instances, each of which defines a level in the context hierarchy.

If you need to merge or override the configuration for a given level of the context hierarchy within a test class hierarchy, you must explicitly name that level by supplying the same value to the name attribute in @ContextConfiguration at each level in the class hierarchy. See the class-level Javadoc for examples.