Document context hierarchy support in the TCF
This commit adds examples to the Javadoc for @ContextHierarchy and updates the Javadoc for @ContextConfiguration accordingly. Issue: SPR-10357
This commit is contained in:
Sam Brannen
parent
3eb3610660
commit
4e7098dc63
|
|
@ -287,13 +287,14 @@ public @interface ContextConfiguration {
|
|||
/**
|
||||
* The name of the context hierarchy level represented by this configuration.
|
||||
*
|
||||
* <p>If not specified the name will be inferred based on the numerical level within all
|
||||
* declared contexts within the hierarchy.
|
||||
* <p>If not specified the name will be inferred based on the numerical level
|
||||
* within all declared contexts within the hierarchy.
|
||||
*
|
||||
* <p>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.
|
||||
* <p>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 <em>merging</em> or <em>overriding</em> 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
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -28,6 +28,109 @@ import java.lang.annotation.Target;
|
|||
* a hierarchy of {@link org.springframework.context.ApplicationContext
|
||||
* ApplicationContexts} for integration tests.
|
||||
*
|
||||
* <h2>Examples</h2>
|
||||
* <p>The following JUnit-based examples demonstrate common configuration
|
||||
* scenarios for integration tests that require the use of context hierarchies.
|
||||
*
|
||||
* <h3>Single Test Class with Context Hierarchy</h3>
|
||||
* <p>{@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 <em>root</em> {@code WebApplicationContext}
|
||||
* (with {@code TestAppConfig}) and one for the <em>dispatcher servlet</em>
|
||||
* {@code WebApplicationContext} (with {@code WebConfig}). The {@code
|
||||
* WebApplicationContext} that is <em>autowired</em> into the test instance is
|
||||
* the one for the child context (i.e., the lowest context in the hierarchy).
|
||||
*
|
||||
* <pre class="code">
|
||||
* @RunWith(SpringJUnit4ClassRunner.class)
|
||||
* @WebAppConfiguration
|
||||
* @ContextHierarchy({
|
||||
* @ContextConfiguration(classes = TestAppConfig.class),
|
||||
* @ContextConfiguration(classes = WebConfig.class)
|
||||
* })
|
||||
* public class ControllerIntegrationTests {
|
||||
*
|
||||
* @Autowired
|
||||
* private WebApplicationContext wac;
|
||||
*
|
||||
* // ...
|
||||
* }</pre>
|
||||
*
|
||||
* <h3>Class Hierarchy with Implicit Parent Context</h3>
|
||||
* <p>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.
|
||||
*
|
||||
* <pre class="code">
|
||||
* @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 {}</pre>
|
||||
*
|
||||
* <h3>Class Hierarchy with Merged Context Hierarchy Configuration</h3>
|
||||
* <p>The following classes demonstrate the use of <em>named</em> hierarchy levels
|
||||
* in order to <em>merge</em> 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 <code>{"/user-config.xml",
|
||||
* "/order-config.xml"}</code>. 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 <code>{"/user-config.xml",
|
||||
* "/order-config.xml"}</code>.
|
||||
*
|
||||
* <pre class="code">
|
||||
* @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 {}</pre>
|
||||
*
|
||||
* <h3>Class Hierarchy with Overridden Context Hierarchy Configuration</h3>
|
||||
* <p>In contrast to the previous example, this example demonstrates how to
|
||||
* <em>override</em> 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"}.
|
||||
*
|
||||
* <pre class="code">
|
||||
* @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 {}</pre>
|
||||
*
|
||||
* @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();
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue