From 504cdf498ea27f307c1ab7f9e520b700dfdb612f Mon Sep 17 00:00:00 2001 From: Sam Brannen Date: Fri, 18 May 2012 04:33:40 +0200 Subject: [PATCH] Update documentation of 'annotated class' support in the TCF Updated the testing chapter of the reference manual to refer to 'annotated classes' instead of 'configuration classes' where appropriate. Also revised the content and examples in the @ContextConfiguration annotation section, mentioned Gradle, and reformatted the entire text. Issue: SPR-9401 --- src/reference/docbook/testing.xml | 421 ++++++++++++++++++------------ 1 file changed, 257 insertions(+), 164 deletions(-) diff --git a/src/reference/docbook/testing.xml b/src/reference/docbook/testing.xml index dcf6a5c69617..c5196369235d 100644 --- a/src/reference/docbook/testing.xml +++ b/src/reference/docbook/testing.xml @@ -1,8 +1,11 @@ - + Testing
@@ -128,8 +131,9 @@ ModelAndViewAssert combined with MockHttpServletRequest, MockHttpSession, and so on from the org.springframework.mock.web - package. + linkend="mock-objects-servlet"> + org.springframework.mock.web + package.
@@ -254,11 +258,11 @@ every test fixture leads to slower overall test runs that could reduce productivity. - Test classes can provide either an array containing the resource - locations of XML configuration metadata — typically in the classpath — - or an array containing @Configuration - classes that is used to configure the application. These locations or - classes are the same as or similar to those specified in + Test classes can provide either an array of resource + locations for XML configuration metadata — typically in the + classpath — or an array of annotated classes that + is used to configure the application. These locations or classes are + the same as or similar to those specified in web.xml or other deployment configuration files. @@ -267,8 +271,8 @@ test. Thus the setup cost is incurred only once (per test suite), and subsequent test execution is much faster. In this context, the term test suite means all tests run in the same JVM — - for example, all tests run from an Ant or Maven build for a given - project or module. In the unlikely case that a test corrupts the + for example, all tests run from an Ant, Maven, or Gradle build for a + given project or module. In the unlikely case that a test corrupts the application context and requires reloading — for example, by modifying a bean definition or the state of an application object — the TestContext framework can be configured to reload the configuration @@ -350,10 +354,11 @@ useful when you want a particular test to populate or modify the database — the TestContext framework can be instructed to cause the transaction to commit instead of roll back via the @TransactionConfiguration - and @Rollback - annotations. + linkend="integration-testing-annotations"> + @TransactionConfiguration + and + @Rollback + annotations. See transaction management with the TestContext framework. @@ -405,10 +410,11 @@ contains SimpleJdbcTestUtils, which is a collection of JDBC related utility functions intended to simplify standard database testing scenarios. Note that AbstractTransactionalJUnit4SpringContextTests - and AbstractTransactionalTestNGSpringContextTests - provide convenience methods which delegate to + linkend="testcontext-support-classes-junit4"> + AbstractTransactionalJUnit4SpringContextTests + and + AbstractTransactionalTestNGSpringContextTests + provide convenience methods which delegate to SimpleJdbcTestUtils internally. @@ -427,8 +433,11 @@ - @ContextConfiguration + + + @ContextConfiguration + + Defines class-level metadata that is used to determine how to load and configure an @@ -436,28 +445,46 @@ classes. Specifically, @ContextConfiguration declares either the application context resource - locations or the - @Configuration - classes (but not both) to load as well as the - ContextLoader strategy to use for - loading the context. Note, however, that you typically do not need - to explicitly configure the loader since the default loader - supports either resource locations or - configuration classes. + locations or the annotated + classes that will be used to load the + context. + + Resource locations are typically XML configuration files + located in the classpath; whereas, annotated classes are typically + @Configuration classes. However, + resource locations could also refer to files in the file system, + and annotated classes could be component classes, etc. See Context configuration + with XML resources and the Javadoc for + @ContextConfiguration for further + details. - @ContextConfiguration(locations="example/test-context.xml", loader=CustomContextLoader.class) + @ContextConfiguration("/test-config.xml") public class XmlApplicationContextTests { // class body... } @ContextConfiguration(classes=MyConfig.class) + role="bold">classes=TestConfig.class) public class ConfigClassApplicationContextTests { // class body... } + @ContextConfiguration may + optionally be used to declare the + ContextLoader strategy as well. + Note, however, that you typically do not need to explicitly + configure the loader since the default loader supports either + resource locations or annotated + classes. + + @ContextConfiguration(locations="/test-context.xml", loader=CustomContextLoader.class) +public class CustomLoaderXmlApplicationContextTests { + // class body... +} + @ContextConfiguration provides support for inheriting resource @@ -471,8 +498,11 @@ public class ConfigClassApplicationContextTests { - @ActiveProfiles + + + @ActiveProfiles + + A class-level annotation that is used to declare which bean definition profiles should be active @@ -494,8 +524,7 @@ public class DeveloperIntegrationTests { @ActiveProfiles provides support for inheriting active bean - definition profiles declared by superclasses classes by - default. + definition profiles declared by superclasses by default. See - @DirtiesContext + + + @DirtiesContext + + Indicates that the underlying Spring ApplicationContext has been @@ -575,8 +607,11 @@ public void testProcessWhichDirtiesAppCtx() { - @TestExecutionListeners + + + @TestExecutionListeners + + Defines class-level metadata for configuring which TestExecutionListeners should be @@ -597,8 +632,11 @@ public class CustomTestExecutionListenerTests { - @TransactionConfiguration + + + @TransactionConfiguration + + Defines class-level metadata for configuring transactional tests. Specifically, the bean name of the @@ -634,8 +672,11 @@ public class CustomConfiguredTransactionalTests { - @Rollback + + + @Rollback + + Indicates whether the transaction for the annotated test method should be rolled back after the test @@ -652,8 +693,11 @@ public void testProcessWithoutRollback() { - @BeforeTransaction + + + @BeforeTransaction + + Indicates that the annotated public void method should be executed before a @@ -668,8 +712,11 @@ public void testProcessWithoutRollback() { - @AfterTransaction + + + @AfterTransaction + + Indicates that the annotated public void method should be executed after a transaction @@ -684,8 +731,11 @@ public void testProcessWithoutRollback() { - @NotTransactional + + + @NotTransactional + + The presence of this annotation indicates that the annotated test method must not execute in a @@ -728,54 +778,70 @@ public void testProcessWithoutTransaction() { - @Autowired + + + @Autowired + + - @Qualifier + + + @Qualifier + + - @Resource - (javax.annotation) if JSR-250 is + + @Resource + (javax.annotation) if JSR-250 is present - @Inject - (javax.inject) if JSR-330 is present + + @Inject + (javax.inject) if JSR-330 is + present - @Named - (javax.inject) if JSR-330 is present + + @Named + (javax.inject) if JSR-330 is + present - @PersistenceContext - (javax.persistence) if JPA is present + + @PersistenceContext + (javax.persistence) if JPA is + present - @PersistenceUnit - (javax.persistence) if JPA is present + + @PersistenceUnit + (javax.persistence) if JPA is + present - @Required + + + @Required + + - @Transactional + + + @Transactional + + @@ -791,8 +857,11 @@ public void testProcessWithoutTransaction() { - @IfProfileValue + + + @IfProfileValue + + Indicates that the annotated test is enabled for a specific testing environment. If the configured @@ -827,8 +896,11 @@ public void testProcessWhichRunsForUnitOrIntegrationTestGroups() { - @ProfileValueSourceConfiguration + + + @ProfileValueSourceConfiguration + + Class-level annotation that specifies what type of ProfileValueSource to use when retrieving @@ -846,8 +918,11 @@ public class CustomProfileValueSourceTests { - @Timed + + + @Timed + + Indicates that the annotated test method must finish execution in a specified time period (in milliseconds). If the @@ -881,8 +956,11 @@ public void testProcessWithOneSecondTimeout() { - @Repeat + + + @Repeat + + Indicates that the annotated test method must be executed repeatedly. The number of times that the test method is to be @@ -909,17 +987,16 @@ public void testProcessRepeatedly() { Framework (located in the org.springframework.test.context package) provides generic, annotation-driven unit and integration testing support that is - agnostic of the testing framework in use, whether JUnit or TestNG. The - TestContext framework also places a great deal of importance on - convention over configuration with reasonable - defaults that can be overridden through annotation-based - configuration. + agnostic of the testing framework in use. The TestContext framework also + places a great deal of importance on convention over + configuration with reasonable defaults that can be overridden + through annotation-based configuration. In addition to generic testing infrastructure, the TestContext framework provides explicit support for JUnit and TestNG in the form of abstract support classes. For JUnit, Spring also provides a custom JUnit Runner that - allows one to write so called POJO test classes. + allows one to write so-called POJO test classes. POJO test classes are not required to extend a particular class hierarchy. @@ -1037,8 +1114,8 @@ public void testProcessRepeatedly() { As of Spring 3.1, implement SmartContextLoader instead of this - interface in order to provide support for configuration classes - and active bean definition profiles. + interface in order to provide support for annotated classes and + active bean definition profiles. @@ -1050,8 +1127,8 @@ public void testProcessRepeatedly() { supersedes the ContextLoader SPI that was introduced in Spring 2.5. Specifically, a SmartContextLoader can choose to - process either resource locations or - configuration classes. Furthermore, a + process either resource locations or annotated + classes. Furthermore, a SmartContextLoader can set active bean definition profiles in the context that it loads. @@ -1071,13 +1148,14 @@ public void testProcessRepeatedly() { AnnotationConfigContextLoader: - loads an application context from - @Configuration classes. + loads an application context from annotated + classes. GenericXmlContextLoader: loads an - application context from XML resource locations. + application context from XML resource + locations. @@ -1144,16 +1222,16 @@ public class MyTest { achieved simply by declaring the @ContextConfiguration annotation at the class level. If your test class does not explicitly declare - application context resource locations or - configuration classes, the configured + application context resource locations or annotated + classes, the configured ContextLoader determines how to load a context from a default location or default configuration classes. The following sections explain how to configure an ApplicationContext via XML - configuration files or @Configuration - classes using Spring's + configuration files or annotated classes (typically + @Configuration classes) using Spring's @ContextConfiguration annotation. @@ -1224,15 +1302,15 @@ public class MyTest {
- Context configuration with @Configuration classes + Context configuration with annotated classes To load an ApplicationContext - for your tests using @Configuration - classes (see ), annotate your test - class with @ContextConfiguration and - configure the classes attribute with an array - that contains references to configuration classes. Alternatively, - you can implement and configure your own custom + for your tests using annotated classes (see + ), annotate your test class with + @ContextConfiguration and configure + the classes attribute with an array that contains + references to annotated classes. Alternatively, you can implement + and configure your own custom ContextLoader or SmartContextLoader for advanced use cases. @@ -1249,11 +1327,11 @@ public class MyTest { TestContext framework will attempt to detect the presence of default configuration classes. Specifically, AnnotationConfigContextLoader will detect all - static inner classes of the annotated test class that meet the - requirements for configuration class implementations as specified in - the Javadoc for @Configuration. In - the following example, the OrderServiceTest - class declares a static inner configuration class named + static inner classes of the test class that meet the requirements + for configuration class implementations as specified in the Javadoc + for @Configuration. In the following + example, the OrderServiceTest class declares + a static inner configuration class named Config that will be automatically used to load the ApplicationContext for the test class. Note that the name of the configuration class is @@ -1291,10 +1369,11 @@ public class OrderServiceTest {
- Mixing XML resources and @Configuration classes + Mixing XML resources and annotated classes It may sometimes be desirable to mix XML resources and - @Configuration classes to configure + annotated classes (i.e., typically + @Configuration classes) to configure an ApplicationContext for your tests. For example, if you use XML configuration in production, you may decide that you want to use @@ -1330,22 +1409,21 @@ public class OrderServiceTest { @ContextConfiguration supports a boolean inheritLocations attribute that denotes - whether resource locations or configuration classes declared by + whether resource locations or annotated classes declared by superclasses should be inherited. The default - value is true. This means that an annotated class - inherits the resource locations or configuration classes declared by - any annotated superclasses. Specifically, the resource locations or - configuration classes for an annotated test class are appended to - the list of resource locations or configuration classes declared by - annotated superclasses. Thus, subclasses have the option of - extending the list of resource locations or - configuration classes. + value is true. This means that a test class + inherits the resource locations or annotated classes declared by any + superclasses. Specifically, the resource locations or annotated + classes for a test class are appended to the list of resource + locations or annotated classes declared by superclasses. Thus, + subclasses have the option of extending the + list of resource locations or annotated classes. If @ContextConfiguration's inheritLocations attribute is set to - false, the resource locations or configuration - classes for the annotated class shadow and - effectively replace any resource locations or configuration classes + false, the resource locations or annotated + classes for the test class shadow and + effectively replace any resource locations or annotated classes defined by superclasses. In the following example that uses XML resource locations, the @@ -1372,12 +1450,12 @@ public class ExtendedTest extends BaseTest { // class body... } - Similarly, in the following example that uses configuration + Similarly, in the following example that uses annotated classes, the ApplicationContext for ExtendedTest will be loaded from the BaseConfig and ExtendedConfig - configuration classes, in that order. Beans defined in + classes, in that order. Beans defined in ExtendedConfig may therefore override (i.e., replace) those defined in BaseConfig. @@ -1403,7 +1481,7 @@ public class ExtendedTest extends BaseTest { definition profiles), and integration tests can now be configured to activate particular bean definition profiles for various testing scenarios. This is achieved by annotating a test - class with the new @ActiveProfiles + class with the @ActiveProfiles annotation and supplying a list of profiles that should be activated when loading the ApplicationContext for the test. @@ -1626,23 +1704,35 @@ public class TransferServiceTest { - locations (from - @ContextConfiguration) + + locations + + (from @ContextConfiguration) + - classes (from - @ContextConfiguration) + + classes + + (from @ContextConfiguration) + - contextLoader (from - @ContextConfiguration) + + contextLoader + + (from @ContextConfiguration) + - activeProfiles (from - @ActiveProfiles) + + activeProfiles + + (from @ActiveProfiles) + @@ -1677,9 +1767,9 @@ public class TransferServiceTest { To benefit from the caching mechanism, all tests must run within the same process or test suite. This can be achieved by executing all tests as a group within an IDE. Similarly, when - executing tests with a build framework such as Ant or Maven it is - important to make sure that the build framework does not - fork between tests. For example, if the + executing tests with a build framework such as Ant, Maven, or + Gradle it is important to make sure that the build framework does + not fork between tests. For example, if the forkMode for the Maven Surefire plug-in is set to always @@ -1729,13 +1819,13 @@ public class TransferServiceTest { Because @Autowired is used to - perform autowiring by - type, if you have multiple bean definitions of the - same type, you cannot rely on this approach for those particular - beans. In that case, you can use - @Autowired in conjunction with - @Qualifier. As of Spring 3.0 you may - also choose to use @Inject in + perform + autowiring by type + , if you have multiple bean definitions of the same type, you + cannot rely on this approach for those particular beans. In that case, + you can use @Autowired in conjunction + with @Qualifier. As of Spring 3.0 you + may also choose to use @Inject in conjunction with @Named. Alternatively, if your test class has access to its ApplicationContext, you can perform an explicit @@ -1904,12 +1994,14 @@ public class HibernateTitleRepositoryTests { the @Rollback annotation to override the class-level default rollback setting. - AbstractTransactionalJUnit4SpringContextTests - and AbstractTransactionalTestNGSpringContextTests - are preconfigured for transactional support at the class level. - + + + AbstractTransactionalJUnit4SpringContextTests + and + AbstractTransactionalTestNGSpringContextTests + are preconfigured for transactional support at the class + level. + Occasionally you need to execute certain code before or after a transactional test method but outside the transactional context, for @@ -2363,10 +2455,10 @@ public class HibernateClinicTests extends AbstractClinicTests { } - JUnit: - A programmer-oriented testing framework for - Java. Used by the Spring Framework in its test - suite. + JUnit: + A programmer-oriented testing framework for + Java + . Used by the Spring Framework in its test suite. @@ -2389,10 +2481,11 @@ public class HibernateClinicTests extends AbstractClinicTests { } EasyMock: Java - library that provides Mock Objects for interfaces - (and objects through the class extension) by generating them on the - fly using Java's proxy mechanism. Used by the - Spring Framework in its test suite. + library + that provides Mock Objects for interfaces (and objects + through the class extension) by generating them on the fly using + Java's proxy mechanism. + Used by the Spring Framework in its test suite. @@ -2416,8 +2509,8 @@ public class HibernateClinicTests extends AbstractClinicTests { } - The Grinder: - Java load testing framework. + The + Grinder: Java load testing framework.