diff --git a/spring-framework-reference/src/testing.xml b/spring-framework-reference/src/testing.xml index 3861198bdfe..901e948b44f 100644 --- a/spring-framework-reference/src/testing.xml +++ b/spring-framework-reference/src/testing.xml @@ -414,433 +414,454 @@
Annotations - The Spring Framework provides the following set of - Spring-specific annotations that you can use in - your unit and integration tests in conjunction with the TestContext - framework. Refer to the respective Javadoc for further information, - including default attribute values, attribute aliases, and so on. +
+ Spring Testing Annotations - - - @ContextConfiguration - - Defines class-level metadata that is used to determine how to - load and configure an - ApplicationContext for test classes. - Specifically, @ContextConfiguration - declares either the application context - resource locations or the - @Configuration - classes 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. - - @ContextConfiguration(locations="example/test-context.xml", loader=CustomContextLoader.class) + The Spring Framework provides the following set of + Spring-specific annotations that you can use in + your unit and integration tests in conjunction with the TestContext + framework. Refer to the respective Javadoc for further information, + including default attribute values, attribute aliases, and so + on. + + + + @ContextConfiguration + + Defines class-level metadata that is used to determine how + to load and configure an + ApplicationContext for test + classes. Specifically, + @ContextConfiguration declares + either the application context resource + locations or the + @Configuration + classes 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. + + @ContextConfiguration(locations="example/test-context.xml", loader=CustomContextLoader.class) public class XmlApplicationContextTests { // class body... } - @ContextConfiguration(classes=MyConfig.class) + @ContextConfiguration(classes=MyConfig.class) public class ConfigClassApplicationContextTests { // class body... } - - @ContextConfiguration - provides support for inheriting resource - locations or configuration classes by default. - + + @ContextConfiguration + provides support for inheriting resource + locations or configuration classes by default. + - See Context - management and caching and Javadoc for examples and further - details. - + See Context + management and caching and Javadoc for examples and further + details. + - - @DirtiesContext + + @DirtiesContext - Indicates that the underlying Spring - ApplicationContext has been - dirtied (i.e., modified or corrupted in some - manner) during the execution of a test and should be closed, - regardless of whether the test passed. - @DirtiesContext is supported in the - following scenarios: + Indicates that the underlying Spring + ApplicationContext has been + dirtied (i.e., modified or corrupted in some + manner) during the execution of a test and should be closed, + regardless of whether the test passed. + @DirtiesContext is supported in the + following scenarios: - - - After the current test class, when declared on a class - with class mode set to AFTER_CLASS, which is - the default class mode. - + + + After the current test class, when declared on a class + with class mode set to AFTER_CLASS, which + is the default class mode. + - - After each test method in the current test class, when - declared on a class with class mode set to - AFTER_EACH_TEST_METHOD. - + + After each test method in the current test class, when + declared on a class with class mode set to + AFTER_EACH_TEST_METHOD. + - - After the current test, when declared on a method. - - + + After the current test, when declared on a + method. + + - Use this annotation if a test has modified the context (for - example, by replacing a bean definition). Subsequent tests are - supplied a new context. - - With JUnit 4.5+ or TestNG you can use - @DirtiesContext as both a class-level - and method-level annotation within the same test class. In such - scenarios, the ApplicationContext is - marked as dirty after any such annotated method - as well as after the entire class. If the - ClassMode is set to - AFTER_EACH_TEST_METHOD, the context is marked - dirty after each test method in the class. - - @DirtiesContext + Use this annotation if a test has modified the context (for + example, by replacing a bean definition). Subsequent tests are + supplied a new context. + + With JUnit 4.5+ or TestNG you can use + @DirtiesContext as both a + class-level and method-level annotation within the same test + class. In such scenarios, the + ApplicationContext is marked as + dirty after any such annotated method as well + as after the entire class. If the ClassMode + is set to AFTER_EACH_TEST_METHOD, the context + is marked dirty after each test method in the class. + + @DirtiesContext public class ContextDirtyingTests { // some tests that result in the Spring container being dirtied } - @DirtiesContext(classMode = ClassMode.AFTER_EACH_TEST_METHOD) + @DirtiesContext(classMode = ClassMode.AFTER_EACH_TEST_METHOD) public class ContextDirtyingTests { // some tests that result in the Spring container being dirtied } - @DirtiesContext + @DirtiesContext @Test public void testProcessWhichDirtiesAppCtx() { // some logic that results in the Spring container being dirtied } - When an application context is marked - dirty, it is removed from the testing - framework's cache and closed; thus the underlying Spring container - is rebuilt for any subsequent test that requires a context with the - same set of resource locations. - + When an application context is marked + dirty, it is removed from the testing + framework's cache and closed; thus the underlying Spring container + is rebuilt for any subsequent test that requires a context with + the same set of resource locations. + - - @TestExecutionListeners + + @TestExecutionListeners - Defines class-level metadata for configuring which - TestExecutionListeners should be - registered with the TestContextManager. - Typically, @TestExecutionListeners is - used in conjunction with - @ContextConfiguration. + Defines class-level metadata for configuring which + TestExecutionListeners should be + registered with the TestContextManager. + Typically, @TestExecutionListeners + is used in conjunction with + @ContextConfiguration. - @ContextConfiguration + @ContextConfiguration @TestExecutionListeners({CustomTestExecutionListener.class, AnotherTestExecutionListener.class}) public class CustomTestExecutionListenerTests { // class body... } - @TestExecutionListeners - supports inherited listeners by default. See - the Javadoc for an example and further details. - + @TestExecutionListeners + supports inherited listeners by default. See + the Javadoc for an example and further details. + - - @TransactionConfiguration - - Defines class-level metadata for configuring transactional - tests. Specifically, the bean name of the - PlatformTransactionManager that is to - be used to drive transactions can be explicitly configured if the - bean name of the desired - PlatformTransactionManager is not - "transactionManager". In addition, you can change the - defaultRollback flag to false. - Typically, @TransactionConfiguration - is used in conjunction with - @ContextConfiguration. - - @ContextConfiguration + + @TransactionConfiguration + + Defines class-level metadata for configuring transactional + tests. Specifically, the bean name of the + PlatformTransactionManager that is + to be used to drive transactions can be explicitly configured if + the bean name of the desired + PlatformTransactionManager is not + "transactionManager". In addition, you can change the + defaultRollback flag to + false. Typically, + @TransactionConfiguration is used + in conjunction with + @ContextConfiguration. + + @ContextConfiguration @TransactionConfiguration(transactionManager="txMgr", defaultRollback=false) + role="bold">transactionManager="txMgr", defaultRollback=false) public class CustomConfiguredTransactionalTests { // class body... } - - If the default conventions are sufficient for your test - configuration, you can avoid using - @TransactionConfiguration - altogether. In other words, if your transaction manager bean is - named "transactionManager" and if you want transactions to roll - back automatically, there is no need to annotate your test class - with - @TransactionConfiguration. - - + + If the default conventions are sufficient for your test + configuration, you can avoid using + @TransactionConfiguration + altogether. In other words, if your transaction manager bean is + named "transactionManager" and if you want transactions to roll + back automatically, there is no need to annotate your test class + with + @TransactionConfiguration. + + - - @Rollback + + @Rollback - Indicates whether the transaction for the annotated test - method should be rolled back after the test - method has completed. If true, the transaction is - rolled back; otherwise, the transaction is committed. Use - @Rollback to override the default - rollback flag configured at the class level. + Indicates whether the transaction for the annotated test + method should be rolled back after the test + method has completed. If true, the transaction + is rolled back; otherwise, the transaction is committed. Use + @Rollback to override the default + rollback flag configured at the class level. - @Rollback(false) + @Rollback(false) @Test public void testProcessWithoutRollback() { // ... } - + - - @BeforeTransaction + + @BeforeTransaction - Indicates that the annotated public void - method should be executed before a transaction - is started for test methods configured to run within a transaction - via the @Transactional - annotation. + Indicates that the annotated public void + method should be executed before a + transaction is started for test methods configured to run within a + transaction via the @Transactional + annotation. - @BeforeTransaction + @BeforeTransaction public void beforeTransaction() { // logic to be executed before a transaction is started } - + - - @AfterTransaction + + @AfterTransaction - Indicates that the annotated public void - method should be executed after a transaction - has ended for test methods configured to run within a transaction - via the @Transactional - annotation. + Indicates that the annotated public void + method should be executed after a transaction + has ended for test methods configured to run within a transaction + via the @Transactional + annotation. - @AfterTransaction + @AfterTransaction public void afterTransaction() { // logic to be executed after a transaction has ended } - + - - @NotTransactional + + @NotTransactional - The presence of this annotation indicates that the annotated - test method must not execute in a transactional - context. + The presence of this annotation indicates that the annotated + test method must not execute in a + transactional context. - @NotTransactional + @NotTransactional @Test public void testProcessWithoutTransaction() { // ... } - - @NotTransactional is deprecated - - As of Spring 3.0, - @NotTransactional is deprecated in - favor of moving the non-transactional test - method to a separate (non-transactional) test class or to a - @BeforeTransaction or - @AfterTransaction method. As an - alternative to annotating an entire class with - @Transactional, consider annotating - individual methods with - @Transactional; doing so allows a - mix of transactional and non-transactional methods in the same - test class without the need for using - @NotTransactional. - - - + + @NotTransactional is deprecated + + As of Spring 3.0, + @NotTransactional is deprecated + in favor of moving the non-transactional + test method to a separate (non-transactional) test class or to a + @BeforeTransaction or + @AfterTransaction method. As an + alternative to annotating an entire class with + @Transactional, consider + annotating individual methods with + @Transactional; doing so allows a + mix of transactional and non-transactional methods in the same + test class without the need for using + @NotTransactional. + + + +
- The following annotations are only supported - when used in conjunction with the SpringJUnit4ClassRunner or - the JUnit - support classes. +
+ Standard Annotation Support - - - @IfProfileValue - - Indicates that the annotated test is enabled for a specific - testing environment. If the configured - ProfileValueSource returns a matching - value for the provided name, - the test is enabled. This annotation can be applied to an entire - class or to individual methods. Class-level usage overrides - method-level usage. - - @IfProfileValue(name="java.vendor", value="Sun Microsystems Inc.") + The following non-test-specific annotations are supported with + standard semantics for all configurations of the Spring TestContext + Framework. + + + + @Autowired + + + + @Qualifier + + + + @Resource + (javax.annotation) if JSR-250 is + present + + + + @Inject + (javax.inject) if JSR-330 is present + + + + @Named + (javax.inject) if JSR-330 is present + + + + @PersistenceContext + (javax.persistence) if JPA is present + + + + @PersistenceUnit + (javax.persistence) if JPA is present + + + + @Required + + + + @Transactional + + +
+ +
+ Spring JUnit Testing Annotations + + The following annotations are only + supported when used in conjunction with the SpringJUnit4ClassRunner or + the JUnit + support classes. + + + + @IfProfileValue + + Indicates that the annotated test is enabled for a specific + testing environment. If the configured + ProfileValueSource returns a matching + value for the provided name, + the test is enabled. This annotation can be applied to an entire + class or to individual methods. Class-level usage overrides + method-level usage. + + @IfProfileValue(name="java.vendor", value="Sun Microsystems Inc.") @Test public void testProcessWhichRunsOnlyOnSunJvm() { // some logic that should run only on Java VMs from Sun Microsystems } - Alternatively, you can configure - @IfProfileValue with a list of - values (with OR semantics) - to achieve TestNG-like support for test groups - in a JUnit environment. Consider the following example: + Alternatively, you can configure + @IfProfileValue with a list of + values (with OR semantics) + to achieve TestNG-like support for test + groups in a JUnit environment. Consider the following + example: - @IfProfileValue(name="test-groups", values={"unit-tests", "integration-tests"}) + @IfProfileValue(name="test-groups", values={"unit-tests", "integration-tests"}) @Test public void testProcessWhichRunsForUnitOrIntegrationTestGroups() { // some logic that should run only for unit and integration test groups } - + - - @ProfileValueSourceConfiguration - - Class-level annotation that specifies what type of - ProfileValueSource to use when retrieving - profile values configured through the - @IfProfileValue annotation. If - @ProfileValueSourceConfiguration is - not declared for a test, - SystemProfileValueSource is used by - default. - - @ProfileValueSourceConfiguration(CustomProfileValueSource.class) + + @ProfileValueSourceConfiguration + + Class-level annotation that specifies what type of + ProfileValueSource to use when retrieving + profile values configured through the + @IfProfileValue annotation. If + @ProfileValueSourceConfiguration is + not declared for a test, + SystemProfileValueSource is used by + default. + + @ProfileValueSourceConfiguration(CustomProfileValueSource.class) public class CustomProfileValueSourceTests { // class body... } - + - - @Timed + + @Timed - Indicates that the annotated test method must finish execution - in a specified time period (in milliseconds). If the text execution - time exceeds the specified time period, the test fails. + Indicates that the annotated test method must finish + execution in a specified time period (in milliseconds). If the + text execution time exceeds the specified time period, the test + fails. - The time period includes execution of the test method itself, - any repetitions of the test (see - @Repeat), as well as any - set up or tear down of the - test fixture. + The time period includes execution of the test method + itself, any repetitions of the test (see + @Repeat), as well as any + set up or tear down of + the test fixture. - @Timed(millis=1000) + @Timed(millis=1000) public void testProcessWithOneSecondTimeout() { // some logic that should not take longer than 1 second to execute } - Spring's @Timed annotation has - different semantics than JUnit's - @Test(timeout=...) support. - Specifically, due to the manner in which JUnit handles test - execution timeouts (that is, by executing the test method in a - separate Thread), - @Test(timeout=...) applies to - each iteration in the case of repetitions and - preemptively fails the test if the test takes too long. Spring's - @Timed, on the other hand, times the - total test execution time (including all - repetitions) and does not preemptively fail the test but rather - waits for the test to complete before failing. - + Spring's @Timed annotation + has different semantics than JUnit's + @Test(timeout=...) support. + Specifically, due to the manner in which JUnit handles test + execution timeouts (that is, by executing the test method in a + separate Thread), + @Test(timeout=...) applies to + each iteration in the case of repetitions and + preemptively fails the test if the test takes too long. Spring's + @Timed, on the other hand, times + the total test execution time (including all + repetitions) and does not preemptively fail the test but rather + waits for the test to complete before failing. + - - @Repeat + + @Repeat - Indicates that the annotated test method must be executed - repeatedly. The number of times that the test method is to be - executed is specified in the annotation. + Indicates that the annotated test method must be executed + repeatedly. The number of times that the test method is to be + executed is specified in the annotation. - The scope of execution to be repeated includes execution of - the test method itself as well as any set up or - tear down of the test fixture. + The scope of execution to be repeated includes execution of + the test method itself as well as any set up + or tear down of the test fixture. - @Repeat(10) + @Repeat(10) @Test public void testProcessRepeatedly() { // ... } - - - - The following non-test-specific annotations are supported with - standard semantics for all configurations of the Spring TestContext - Framework. - - - - @Autowired - - - - @Qualifier - - - - @Resource - (javax.annotation) if JSR-250 is present - - - - @Inject - (javax.inject) if JSR-330 is present - - - - @Named - (javax.inject) if JSR-330 is present - - - - @PersistenceContext - (javax.persistence) if JPA is present - - - - @PersistenceUnit - (javax.persistence) if JPA is present - - - - @Required - - - - @Transactional - - + + +