From c86bc2671ae95e6dd7d79a2f9cf61365184432c4 Mon Sep 17 00:00:00 2001 From: Sam Brannen Date: Sun, 13 Mar 2011 00:25:58 +0000 Subject: [PATCH] [SPR-8030] Updated reference manual regarding deprecation of JUnit 3.8 base classes. --- spring-framework-reference/src/testing.xml | 212 +++++++-------------- 1 file changed, 70 insertions(+), 142 deletions(-) diff --git a/spring-framework-reference/src/testing.xml b/spring-framework-reference/src/testing.xml index ed111fde55c..23d599a09d4 100644 --- a/spring-framework-reference/src/testing.xml +++ b/spring-framework-reference/src/testing.xml @@ -115,7 +115,8 @@ The org.springframework.test.web package contains ModelAndViewAssert, which you can use - in combination with JUnit 4+, TestNG, and so on for unit tests dealing + in combination with JUnit, TestNG, or any other testing framework + for unit tests dealing with Spring MVC ModelAndView objects. @@ -176,19 +177,28 @@ In Spring 2.5 and later, unit and integration testing support is provided in the form of the annotation-driven Spring TestContext Framework. The - TestContext Framework is agnostic of the actual testing framework in + TestContext framework is agnostic of the actual testing framework in use, thus allowing instrumentation of tests in various environments including JUnit, TestNG, and so on. - Legacy JUnit 3.8 class hierarchy is deprecated + JUnit 3.8 support is deprecated - As of Spring 3.0, the legacy JUnit 3.8 base class hierarchy (for - example, + As of Spring 3.0, the legacy JUnit 3.8 base class hierarchy (i.e., AbstractDependencyInjectionSpringContextTests, AbstractTransactionalDataSourceSpringContextTests, etc.) is officially deprecated and will be removed in a later release. - Migrate this code to the Spring + Any test classes based on this code should be migrated to the + Spring + TestContext Framework. + + As of Spring 3.1, the JUnit 3.8 base classes in the Spring + TestContext Framework (i.e., + AbstractJUnit38SpringContextTests and + AbstractTransactionalJUnit38SpringContextTests) + have been officially deprecated and will be removed in a later release. + Any test classes based on this code should be migrated to the JUnit 4 + or TestNG support provided by the Spring TestContext Framework. @@ -253,12 +263,12 @@ 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 configurations and rebuild the application + to reload the configuration and rebuild the application context before executing the next test. See context management and caching with the TestContext - Framework. + framework.
@@ -302,7 +312,7 @@ See dependency injection of test fixtures with the TestContext Framework. + linkend="testcontext-fixture-di">TestContext framework.
@@ -336,7 +346,7 @@ annotations. See transaction management with the TestContext Framework. + linkend="testcontext-tx">TestContext framework.
@@ -374,7 +384,7 @@ See support classes for the TestContext - Framework. + framework.
@@ -385,9 +395,7 @@ contains SimpleJdbcTestUtils, which is a Java-5-based collection of JDBC related utility functions intended to simplify standard database testing scenarios. Note that AbstractTransactionalJUnit38SpringContextTests, - AbstractTransactionalJUnit4SpringContextTests, + linkend="testcontext-support-classes-junit4">AbstractTransactionalJUnit4SpringContextTests and AbstractTransactionalTestNGSpringContextTests provide convenience methods which delegate to @@ -464,24 +472,7 @@ public class CustomConfiguredApplicationContextTests { example, by replacing a bean definition). Subsequent tests are supplied a new context. - - Limitations of - <interfacename>@DirtiesContext</interfacename> at the class level - - JUnit 4+ and TestNG both support class-level lifecycle - callbacks — for example, via @BeforeClass - and @AfterClass annotations. Consequently, - @DirtiesContext can be used at the class level - with these frameworks. JUnit 3.x, however, does not support - before class or after class - lifecycle callbacks. Thus, in a JUnit 3.x environment - @DirtiesContext is only supported - on methods and not at the class level. - - - If class-level usage of @DirtiesContext - is supported — for example, with JUnit 4.5+ or TestNG — - you can use + 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 @@ -653,11 +644,10 @@ public void testProcessWithoutTransaction() { The following annotations are only supported - when used in conjunction with JUnit (that is, with the SpringJUnit4ClassRunner or - the JUnit - 3.8.2 and JUnit 4.5+ support + the JUnit support classes. @@ -729,12 +719,11 @@ public void testProcessRainyDayScenario() { Using Spring's @ExpectedException annotation in - conjunction with JUnit 4's + conjunction with JUnit's @Test(expected=...) configuration would lead to an unresolvable conflict. Developers must therefore - choose one or the other when integrating with JUnit 4, in which case - it is generally preferable to use the explicit JUnit 4 - configuration. + choose one or the other when integrating with JUnit, in which case + it is generally preferable to use the explicit JUnit configuration. @@ -757,9 +746,9 @@ public void testProcessWithOneSecondTimeout() { } Spring's @Timed annotation has - different semantics than JUnit 4's + different semantics than JUnit's @Test(timeout=...) support. - Specifically, due to the manner in which JUnit 4 handles test + 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 @@ -861,19 +850,19 @@ 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 3.8.2, JUnit - 4.5+, TestNG 5.12, and so on. The TestContext framework also places a + 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. In addition to generic testing infrastructure, the TestContext - framework provides explicit support for JUnit 3.8.2, JUnit 4.5+, and - TestNG 5.12 in the form of abstract support classes. - For JUnit 4.5+, the framework also provides a custom JUnit - Runner that allows one to write test - classes that are not required to extend a particular class - hierarchy. + 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. POJO test classes + are not required to extend a particular class hierarchy. The following section provides an overview of the internals of the TestContext framework. If you are only interested in using the framework @@ -982,8 +971,7 @@ public void testProcessRepeatedly() { to the test instance, if the DependencyInjectionTestExecutionListener is configured, which is the default. - AbstractJUnit38SpringContextTests, - AbstractJUnit4SpringContextTests, and + AbstractJUnit4SpringContextTests and AbstractTestNGSpringContextTests already implement ApplicationContextAware and therefore provide this functionality out-of-the-box. @@ -1008,7 +996,7 @@ public class MyTest { } - In contrast to the now deprecated JUnit 3.8 legacy class + In contrast to the deprecated JUnit 3.8 legacy class hierarchy, test classes that use the TestContext framework do not need to override any protected instance methods to configure their application context. Rather, configuration is achieved @@ -1113,14 +1101,14 @@ public class ExtendedTest extends BaseTest { method with @DirtiesContext (assuming DirtiesContextTestExecutionListener has been configured, which is the default). This instructs Spring to reload - the configurations and rebuild the application context before + the configuration and rebuild the application context before executing the next test.
Dependency Injection of test fixtures - When you configure the + When you use the DependencyInjectionTestExecutionListener — which is configured by default — the dependencies of your test instances are injected from beans in the @@ -1131,11 +1119,13 @@ public class ExtendedTest extends BaseTest { consistency with the annotation support introduced in Spring 2.5, you can use Spring's @Autowired annotation or the @Resource annotation from JSR - 250. The semantics for both are consistent throughout the Spring - Framework. For example, if you prefer @Inject annotation from JSR 330. For + example, if you prefer autowiring by type, annotate your setter methods or fields with - @Autowired. If you prefer to have your + @Autowired or + @Inject. If you prefer to have your dependencies injected by name, annotate your setter methods or fields with @Resource. @@ -1143,7 +1133,8 @@ public class ExtendedTest extends BaseTest { The TestContext framework does not instrument the manner in which a test instance is instantiated. Thus the use of - @Autowired for constructors has no + @Autowired or + @Inject for constructors has no effect for test classes. @@ -1158,11 +1149,15 @@ public class ExtendedTest extends BaseTest { lookup by using (for example) a call to applicationContext.getBean("titleRepository"). A third option is to use @Autowired in - conjunction with @Qualifier. + conjunction with @Qualifier. As of + Spring 3.0 you may also choose to use + @Inject in conjunction with + @Named. If you do not want dependency injection applied to your test instances, simply do not annotate fields or setter methods with - @Autowired or + @Autowired, + @Inject or @Resource. Alternatively, you can disable dependency injection altogether by explicitly configuring your class with @TestExecutionListeners and @@ -1180,7 +1175,7 @@ public class ExtendedTest extends BaseTest { The dependency injection behavior in the following code - listings is not in any way specific to JUnit 4. The same DI + listings is not specific to JUnit. The same DI techniques can be used in conjunction with any testing framework. @@ -1192,7 +1187,7 @@ public class ExtendedTest extends BaseTest { example. - The first code listing shows a JUnit 4-based implementation + The first code listing shows a JUnit-based implementation of the test class that uses @Autowired for field injection. @@ -1389,9 +1384,7 @@ public class HibernateTitleRepositoryTests { the class-level default rollback setting. AbstractTransactionalJUnit38SpringContextTests, - AbstractTransactionalJUnit4SpringContextTests, + linkend="testcontext-support-classes-junit4">AbstractTransactionalJUnit4SpringContextTests and AbstractTransactionalTestNGSpringContextTests are preconfigured for transactional support at the class level. @@ -1414,9 +1407,10 @@ public class HibernateTitleRepositoryTests { time. - Any before methods (e.g., methods - annotated with JUnit 4's @Before) and any after - methods (such as methods annotated with JUnit 4's @After) + Any before methods (such as methods + annotated with JUnit's @Before) + and any after methods (such as methods annotated + with JUnit's @After) are executed within a transaction. In addition, methods annotated with @BeforeTransaction or @@ -1427,7 +1421,7 @@ public class HibernateTitleRepositoryTests { Spring 3.0. - The following JUnit 4 based example displays a fictitious + The following JUnit-based example displays a fictitious integration testing scenario highlighting several transaction-related annotations. Consult the annotation support @@ -1510,74 +1504,8 @@ public void updateWithSessionFlush() {
TestContext support classes -
- JUnit 3.8 support classes - - The - org.springframework.test.context.junit38 package - provides support classes for JUnit 3.8 based test cases. - - - - AbstractJUnit38SpringContextTests: - Abstract TestCase that integrates the - Spring TestContext Framework with explicit - ApplicationContext testing support in a - JUnit 3.8 environment. When you extend - AbstractJUnit38SpringContextTests, - you can access the following protected - instance variable: - - - - applicationContext: - Use this variable to perform explicit bean - lookups or to test the state of the context as a - whole. - - - - - - AbstractTransactionalJUnit38SpringContextTests: - Abstract transactional extension of - AbstractJUnit38SpringContextTests that - also adds some convenience functionality for JDBC access. - Expects a javax.sql.DataSource bean and a - PlatformTransactionManager bean - to be defined in the ApplicationContext. - When you extend - AbstractTransactionalJUnit38SpringContextTests, - you can access the following - protected instance variables: - - - - applicationContext: Inherited from - the AbstractJUnit38SpringContextTests - superclass. Use this variable to perform explicit bean - lookups or to test the state of the context as a - whole. - - - - simpleJdbcTemplate: Use this variable - to execute SQL statements to query the database. - Such queries can be used to confirm database state both - prior to and after - execution of database-related application code, and Spring - ensures that such queries run in the scope of the same - transaction as the application code. When used in conjunction - with an ORM tool, be sure to avoid - false positives. - - - - -
-
- JUnit 4.5+ support classes + JUnit support classes The org.springframework.test.context.junit4 package provides support classes for JUnit 4.5+ based test @@ -1657,13 +1585,13 @@ public void updateWithSessionFlush() {
- Custom JUnit 4.5+ Runner + Spring JUnit Runner The Spring TestContext Framework offers full integration with JUnit 4.5+ through a custom runner (tested on - JUnit 4.5 – 4.8). By annotating test classes with + JUnit 4.5 – 4.8.1). By annotating test classes with @RunWith(SpringJUnit4ClassRunner.class), - developers can implement standard JUnit 4.5+ unit and integration + developers can implement standard JUnit-based unit and integration tests and simultaneously reap the benefits of the TestContext framework such as support for loading application contexts, dependency injection of test instances, transactional test method @@ -1919,9 +1847,9 @@ public class HibernateClinicTests extends AbstractClinicTests { } TestNG: A testing - framework inspired by JUnit 3.8 with added support for Java 5 + framework inspired by JUnit with added support for Java 5 annotations, test groups, data-driven testing, distributed testing, - and so on. + etc.