2009-03-19 04:00:49 +08:00
<?xml version="1.0" encoding="UTF-8"?>
2009-04-30 12:16:07 +08:00
< !DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
2009-04-15 05:37:40 +08:00
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
2009-03-19 04:00:49 +08:00
<chapter id= "testing" >
<title > Testing</title>
<section id= "testing-introduction" >
<title > Introduction</title>
<para > The Spring team considers developer testing to be an absolutely
integral part of enterprise software development. A thorough treatment of
testing in the enterprise is beyond the scope of this chapter; rather, the
focus here is on the value-add that the adoption of the IoC principle can
bring to <link linkend= "unit-testing" > unit testing</link> and on the
benefits that the Spring Framework provides in <link
linkend="integration-testing">integration testing</link> .</para>
</section>
<section id= "unit-testing" >
<title > Unit testing</title>
<para > One of the main benefits of Dependency Injection is that your code
should really depend far less on the container than in traditional J2EE
2009-04-30 09:04:39 +08:00
development. The POJOs that make up your application should be testable
2009-03-19 04:00:49 +08:00
in JUnit or TestNG tests, with objects simply instantiated using the
<literal > new</literal> operator, <emphasis > without Spring or any other
container</emphasis> . You can use <link linkend= "mock-objects" > mock
objects</link> (in conjunction with many other valuable testing
techniques) to test your code in isolation. If you follow the architecture
recommendations around Spring you will find that the resulting clean
layering and componentization of your codebase will naturally facilitate
<emphasis > easier</emphasis> unit testing. For example, you will be able to
test service layer objects by stubbing or mocking DAO or Repository
interfaces, without any need to access persistent data while running unit
tests.</para>
<para > True unit tests typically will run extremely quickly, as there is no
runtime infrastructure to set up, whether application server, database,
ORM tool, or whatever. Thus emphasizing true unit tests as part of your
development methodology will boost your productivity. The upshot of this
is that you often do not need this section of the testing chapter to help
you write effective <emphasis > unit</emphasis> tests for your IoC-based
applications. For certain unit testing scenarios, however, the Spring
Framework provides the following mock objects and testing support
classes.</para>
<section id= "mock-objects" >
<title > Mock objects</title>
<section id= "mock-objects-jndi" >
<title > JNDI</title>
<para > The <literal > org.springframework.mock.jndi</literal> package
contains an implementation of the JNDI SPI, which is useful for
setting up a simple JNDI environment for test suites or stand-alone
applications. If, for example, JDBC <classname > DataSource</classname> s
get bound to the same JNDI names in test code as within a J2EE
container, both application code and configuration can be reused in
testing scenarios without modification.</para>
</section>
<section id= "mock-objects-servlet" >
<title > Servlet API</title>
<para > The <literal > org.springframework.mock.web</literal> package
contains a comprehensive set of Servlet API mock objects, targeted at
usage with Spring's Web MVC framework, which are useful for testing
web contexts and controllers. These mock objects are generally more
convenient to use than dynamic mock objects (e.g., <ulink
url="http://www.easymock.org">EasyMock</ulink> ) or existing Servlet
API mock objects (e.g., <ulink
url="http://www.mockobjects.com">MockObjects</ulink> ).</para>
</section>
<section id= "mock-objects-portlet" >
<title > Portlet API</title>
<para > The <literal > org.springframework.mock.web.portlet</literal>
package contains a set of Portlet API mock objects, targeted at usage
with Spring's Portlet MVC framework.</para>
</section>
</section>
<section id= "unit-testing-support-classes" >
<title > Unit testing support classes</title>
<section id= "unit-testing-utilities" >
<title > General utilities</title>
<para > The <literal > org.springframework.test.util</literal> package
contains <classname > ReflectionTestUtils</classname> , which is a
collection of reflection-based utility methods for use in unit and
integration testing scenarios in which the developer would benefit
from being able to set a non-<literal > public</literal> field or invoke
a non-<literal > public</literal> setter method when testing application
code involving, for example:</para>
<itemizedlist >
<listitem >
<para > ORM frameworks such as JPA and Hibernate which condone the
usage of <literal > private</literal> or
<literal > protected</literal> field access as opposed to
<literal > public</literal> setter methods for properties in a
domain entity</para>
</listitem>
<listitem >
<para > Spring's support for annotations such as
<interfacename > @Autowired</interfacename> and
<interfacename > @Resource</interfacename> which provides dependency
injection for <literal > private</literal> or
<literal > protected</literal> fields, setter methods, and
configuration methods</para>
</listitem>
</itemizedlist>
</section>
<section id= "unit-testing-spring-mvc" >
<title > Spring MVC</title>
<para > The <literal > org.springframework.test.web</literal> package
contains <classname > AbstractModelAndViewTests</classname> , which
serves as a convenient base class for JUnit 3.8 based unit tests
dealing with Spring MVC <classname > ModelAndView</classname> objects.
When developing against Java 1.4 and higher (e.g., in combination with
JUnit 4+, TestNG, etc.), you have the option of using the
<classname > ModelAndViewAssert</classname> class (in the same package)
to test your <classname > ModelAndView</classname> related
functionality.</para>
<para > Tip: depending on your testing environment, either extend
<classname > AbstractModelAndViewTests</classname> or use
<classname > ModelAndViewAssert</classname> directly and then use
<literal > MockHttpServletRequest</literal> ,
<literal > MockHttpSession</literal> , etc. from the <link
linkend="mock-objects-servlet"><literal > org.springframework.mock.web</literal> </link>
package to test your Spring MVC <literal > Controller</literal> s.</para>
</section>
</section>
</section>
<section id= "integration-testing" >
<title > Integration testing</title>
<section id= "integration-testing-overview" >
<title > Overview</title>
<para > It is important to be able to perform some integration testing
without requiring deployment to your application server or connecting to
other enterprise infrastructure. This will enable you to test things
such as:</para>
<itemizedlist >
<listitem >
<para > The correct wiring of your Spring IoC container
contexts.</para>
</listitem>
<listitem >
<para > Data access using JDBC or an ORM tool. This would include such
things as the correctness of SQL statements, Hibernate queries, JPA
entity mappings, etc.</para>
</listitem>
</itemizedlist>
<para > The Spring Framework provides first class support for integration
testing in the form of the classes that are packaged in the <filename
class="libraryfile">spring-test.jar</filename> library. In this library,
you will find the <literal > org.springframework.test</literal> package
which contains valuable classes for integration testing using a Spring
container, while at the same time not being reliant on an application
server or other deployment environment. Such tests will be slower to run
than unit tests but much faster to run than the equivalent Cactus tests
or remote tests relying on deployment to an application server.</para>
<para > Prior to the 2.5 release of the framework, Spring provided <link
linkend="junit38-legacy-support">integration testing support specific to
JUnit 3.8</link> . As of the 2.5 release, Spring offers support for unit
and integration testing in the form of the <link
linkend="testcontext-framework">Spring TestContext Framework</link> ,
which is agnostic of the actual testing framework in use, thus allowing
instrumentation of tests in various environments including JUnit 3.8,
2009-04-30 09:04:39 +08:00
JUnit 4.5, TestNG, etc. <emphasis > Note that the Spring TestContext
2009-03-19 04:00:49 +08:00
Framework requires Java 5+.</emphasis> </para>
</section>
<section id= "integration-testing-which-framework" >
<title > Which support framework to use</title>
<para > The Spring team recommends using the <link
linkend="testcontext-framework">Spring TestContext Framework</link> for
all new unit testing or integration testing involving
<classname > ApplicationContext</classname> s or requiring transactional
test fixtures; however, if you are developing in a pre-Java 5
environment, you will need to continue to use the <link
linkend="junit38-legacy-support">JUnit 3.8 legacy support</link> . In
addition, explicit <link linkend= "junit38-legacy-jpa-tests" > integration
testing support for JPA</link> which relies on <emphasis > shadow class
loading</emphasis> for JPA class instrumentation is currently only
available with the JUnit 3.8 legacy support. If you are testing against
a JPA provider which does not require class instrumentation, however, it
is recommended that you use the TestContext framework.</para>
</section>
<section id= "integration-testing-common-goals" >
<title > Common goals</title>
<para > The Spring integration testing support frameworks share several
common goals, including:</para>
<itemizedlist >
<listitem >
<para > <link linkend= "testing-ctx-management" > Spring IoC container
caching</link> between test execution.</para>
</listitem>
<listitem >
<para > <link linkend= "testing-fixture-di" > Dependency Injection of
test fixture instances</link> (this is nice).</para>
</listitem>
<listitem >
<para > <link linkend= "testing-tx" > Transaction management</link>
appropriate to integration testing (this is even nicer).</para>
</listitem>
<listitem >
<para > <link linkend= "testing-support-classes" > Spring-specific
support classes</link> that are really useful when writing
integration tests.</para>
</listitem>
</itemizedlist>
<para > The following sections outline each of these goals and provide
direct links to information specific to the particular support
frameworks.</para>
<section id= "testing-ctx-management" >
<title > Context management and caching</title>
<para > Spring integration testing support frameworks provide consistent
loading of Spring <classname > ApplicationContext</classname> s and
caching of those contexts. Support for the caching of loaded contexts
is important, because if you are working on a large project, startup
time may become an issue - not because of the overhead of Spring
itself, but because the objects instantiated by the Spring container
will themselves take time to instantiate. For example, a project with
50-100 Hibernate mapping files might take 10-20 seconds to load the
mapping files, and incurring that cost before running every single
test in every single test fixture will lead to slower overall test
runs that could reduce productivity.</para>
<para > Test classes will generally provide an array containing the
resource locations of XML configuration metadata - typically on the
classpath - used to configure the application. This will be the same,
or nearly the same, as the list of configuration locations specified
in <literal > web.xml</literal> or other deployment
configuration.</para>
<para > By default, once loaded, the configured
<interfacename > ApplicationContext</interfacename> will be reused for
each test. Thus the setup cost will be incurred only once (per test
fixture), and subsequent test execution will be much faster. In the
unlikely case that a test may 'dirty' the application context,
requiring reloading - for example, by changing a bean definition or
the state of an application object - Spring's testing support provides
mechanisms to cause the test fixture to reload the configurations and
rebuild the application context before executing the next test.</para>
<para > Context management and caching with:</para>
<itemizedlist >
<listitem >
<para > <link linkend= "junit38-legacy-ctx-management" > JUnit 3.8
legacy support</link> </para>
</listitem>
<listitem >
<para > <link linkend= "testcontext-ctx-management" > The TestContext
Framework</link> </para>
</listitem>
</itemizedlist>
</section>
<section id= "testing-fixture-di" >
<title > Dependency Injection of test fixtures</title>
<para > When Spring integration testing support frameworks load your
application context, they can optionally configure instances of your
test classes via Dependency Injection. This provides a convenient
mechanism for setting up test fixtures using pre-configured beans from
your application context. A strong benefit here is that you can reuse
application contexts across various testing scenarios (e.g., for
configuring Spring-managed object graphs, transactional proxies,
<classname > DataSource</classname> s, etc.), thus avoiding the need to
duplicate complex test fixture set up for individual test
cases.</para>
<para > As an example, consider the scenario where we have a class,
<classname > HibernateTitleDao</classname> , that performs data access
logic for say, the <classname > Title</classname> domain object. We want
to write integration tests that test all of the following
areas:</para>
<itemizedlist >
<listitem >
<para > The Spring configuration: basically, is everything related
to the configuration of the
<classname > HibernateTitleDao</classname> bean correct and
present?</para>
</listitem>
<listitem >
<para > The Hibernate mapping file configuration: is everything
mapped correctly and are the correct lazy-loading settings in
place?</para>
</listitem>
<listitem >
<para > The logic of the <classname > HibernateTitleDao</classname> :
does the configured instance of this class perform as
anticipated?</para>
</listitem>
</itemizedlist>
<para > Dependency Injection of test fixtures with:</para>
<itemizedlist >
<listitem >
<para > <link linkend= "junit38-legacy-fixture-di" > JUnit 3.8 legacy
support</link> </para>
</listitem>
<listitem >
<para > <link linkend= "testcontext-fixture-di" > The TestContext
Framework</link> </para>
</listitem>
</itemizedlist>
</section>
<section id= "testing-tx" >
<title > Transaction management</title>
<para > One common issue in tests that access a real database is their
affect on the state of the persistence store. Even when you're using a
development database, changes to the state may affect future tests.
Also, many operations - such as inserting to or modifying persistent
data - cannot be performed (or verified) outside a transaction.</para>
<para > The Spring integration testing support frameworks meet this
need. By default, they create and roll back a transaction for each
test. You simply write code that can assume the existence of a
transaction. If you call transactionally proxied objects in your
tests, they will behave correctly, according to their transactional
semantics. In addition, if test methods delete the contents of
selected tables while running within a transaction, the transaction
will roll back by default, and the database will return to its state
prior to execution of the test. Transactional support is provided to
your test class via a
<classname > PlatformTransactionManager</classname> bean defined in the
test's application context.</para>
<para > If you want a transaction to commit - unusual, but occasionally
useful when you want a particular test to populate or modify the
database - the Spring integration testing support frameworks can be
instructed to cause the transaction to commit instead of roll back
either by calling an inherited hook-method or by declaring a specific
annotation.</para>
<para > Transaction management with:</para>
<itemizedlist >
<listitem >
<para > <link linkend= "junit38-legacy-tx" > JUnit 3.8 legacy
support</link> </para>
</listitem>
<listitem >
<para > <link linkend= "testcontext-tx" > The TestContext
Framework</link> </para>
</listitem>
</itemizedlist>
</section>
<section id= "testing-support-classes" >
<title > Integration testing support classes</title>
<para > The Spring integration testing support frameworks provide
several <literal > abstract</literal> support classes that can simplify
writing integration tests. These base test classes provide well
defined hooks into the testing framework as well as convenient
instance variables and methods, allowing access to such things
as:</para>
<itemizedlist >
<listitem >
<para > The <literal > ApplicationContext</literal> : useful for
performing explicit bean lookups or testing the state of the
context as a whole.</para>
</listitem>
<listitem >
<para > A <classname > JdbcTemplate</classname> or
<classname > SimpleJdbcTemplate</classname> : useful for querying to
confirm state. For example, you might query before and after
testing application code that creates an object and persists it
using an ORM tool, to verify that the data appears in the
database. (Spring will ensure that the query runs in the scope of
the same transaction.) You will need to tell your ORM tool to
'flush' its changes for this to work correctly, for example using
the <methodname > flush()</methodname> method on Hibernate's
<interfacename > Session</interfacename> interface.</para>
</listitem>
</itemizedlist>
<para > Often you will provide an application-wide superclass for
integration tests that provides further useful instance variables used
in many tests.</para>
<para > Support classes for:</para>
<itemizedlist >
<listitem >
<para > <link linkend= "junit38-legacy-support-classes" > JUnit 3.8
legacy support</link> </para>
</listitem>
<listitem >
<para > <link linkend= "testcontext-support-classes" > The TestContext
Framework</link> </para>
</listitem>
</itemizedlist>
</section>
</section>
<section id= "integration-testing-support-jdbc" >
<title > JDBC testing support</title>
<para > The <literal > org.springframework.test.jdbc</literal> package
contains <classname > SimpleJdbcTestUtils</classname> , which is a
Java-5-based collection of JDBC related utility functions intended to
simplify standard database testing scenarios. <emphasis > Note that <link
linkend="testcontext-support-classes-junit38"><classname > AbstractTransactionalJUnit38SpringContextTests</classname> </link> ,
<link
2009-04-30 09:04:39 +08:00
linkend="testcontext-support-classes-junit45"><classname > AbstractTransactionalJUnit4SpringContextTests</classname> </link> ,
2009-03-19 04:00:49 +08:00
and <link
linkend="testcontext-support-classes-testng"><classname > AbstractTransactionalTestNGSpringContextTests</classname> </link>
provide convenience methods which delegate to
<classname > SimpleJdbcTestUtils</classname> internally.</emphasis> </para>
</section>
<section id= "integration-testing-common-annotations" >
<title > Common annotations</title>
<para > The Spring Framework provides a common set of
<emphasis > Spring-specific</emphasis> annotations in the
<literal > org.springframework.test.annotation</literal> package that you
can use in your testing if you are developing against Java 5 or
greater.</para>
<itemizedlist >
<listitem >
<para > <emphasis
role="bold"><interfacename > @IfProfileValue</interfacename> </emphasis> </para>
<para > Indicates that the annotated test is enabled for a specific
testing environment. If the configured
<classname > ProfileValueSource</classname> returns a matching
<literal > value</literal> for the provided <literal > name</literal> ,
the test will be enabled. This annotation can be applied to an
entire class or individual methods.</para>
2009-04-08 21:38:36 +08:00
<programlisting language= "java" > @IfProfileValue(name="java.vendor", value="Sun Microsystems Inc.")
2009-03-19 04:00:49 +08:00
public void testProcessWhichRunsOnlyOnSunJvm() {
<lineannotation > // some logic that should run only on Java VMs from Sun Microsystems</lineannotation>
}</programlisting>
<para > Alternatively <interfacename > @IfProfileValue</interfacename>
may be configured with a list of <literal > values</literal> (with
<emphasis > OR</emphasis> semantics) to achieve TestNG-like support
for <emphasis > test groups</emphasis> in a JUnit environment.
Consider the following example:</para>
2009-04-08 21:38:36 +08:00
<programlisting language= "java" > @IfProfileValue(name="test-groups", values={"unit-tests", "integration-tests"})
2009-03-19 04:00:49 +08:00
public void testProcessWhichRunsForUnitOrIntegrationTestGroups() {
<lineannotation > // some logic that should run only for unit and integration test groups</lineannotation>
}</programlisting>
</listitem>
<listitem >
<para > <emphasis
role="bold"><interfacename > @ProfileValueSourceConfiguration</interfacename> </emphasis> </para>
<para > Class-level annotation which is used to specify what type of
<literal > ProfileValueSource</literal> to use when retrieving
<emphasis > profile values</emphasis> configured via the
<interfacename > @IfProfileValue</interfacename> annotation. If
<interfacename > @ProfileValueSourceConfiguration</interfacename> is
not declared for a test,
<classname > SystemProfileValueSource</classname> will be used by
default.</para>
2009-04-08 21:38:36 +08:00
<programlisting language= "java" > @ProfileValueSourceConfiguration(CustomProfileValueSource.class)
2009-03-19 04:00:49 +08:00
public class CustomProfileValueSourceTests {
<lineannotation > // class body...</lineannotation>
}</programlisting>
</listitem>
<listitem >
<para > <emphasis
role="bold"><interfacename > @DirtiesContext</interfacename> </emphasis> </para>
<para > The presence of this annotation on a test method indicates
that the underlying Spring container is 'dirtied' during the
execution of the test method, and thus must be rebuilt after the
test method finishes execution (regardless of whether the test
passed or not).</para>
2009-04-08 21:38:36 +08:00
<programlisting language= "java" > @DirtiesContext
2009-03-19 04:00:49 +08:00
public void testProcessWhichDirtiesAppCtx() {
<lineannotation > // some logic that results in the Spring container being dirtied</lineannotation>
}</programlisting>
</listitem>
<listitem >
<para > <emphasis
role="bold"><interfacename > @ExpectedException</interfacename> </emphasis> </para>
<para > Indicates that the annotated test method is expected to throw
an exception during execution. The type of the expected exception is
provided in the annotation, and if an instance of the exception is
thrown during the test method execution then the test passes.
Likewise if an instance of the exception is <emphasis > not</emphasis>
thrown during the test method execution then the test fails.</para>
2009-04-08 21:38:36 +08:00
<programlisting language= "java" > @ExpectedException(SomeBusinessException.class)
2009-03-19 04:00:49 +08:00
public void testProcessRainyDayScenario() {
<lineannotation > // some logic that should result in an <classname > Exception</classname> being thrown</lineannotation>
}</programlisting>
</listitem>
<listitem >
<para > <emphasis
role="bold"><interfacename > @Timed</interfacename> </emphasis> </para>
<para > Indicates that the annotated test method has to finish
execution in a specified time period (in milliseconds). If the text
execution time takes longer than the specified time period, the test
fails.</para>
<para > Note that the time period includes execution of the test
method itself, any repetitions of the test (see
<interfacename > @Repeat</interfacename> ), as well as any
<emphasis > set up</emphasis> or <emphasis > tear down</emphasis> of the
test fixture.</para>
2009-04-08 21:38:36 +08:00
<programlisting language= "java" > @Timed(millis=1000)
2009-03-19 04:00:49 +08:00
public void testProcessWithOneSecondTimeout() {
<lineannotation > // some logic that should not take longer than 1 second to execute</lineannotation>
}</programlisting>
</listitem>
<listitem >
<para > <emphasis
role="bold"><interfacename > @Repeat</interfacename> </emphasis> </para>
<para > 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.</para>
<para > Note that the scope of execution to be repeated includes
execution of the test method itself as well as any <emphasis > set
up</emphasis> or <emphasis > tear down</emphasis> of the test
fixture.</para>
2009-04-08 21:38:36 +08:00
<programlisting language= "java" > @Repeat(10)
2009-03-19 04:00:49 +08:00
public void testProcessRepeatedly() {
<lineannotation > // ...</lineannotation>
}</programlisting>
</listitem>
<listitem >
<para > <emphasis
role="bold"><interfacename > @Rollback</interfacename> </emphasis> </para>
<para > Indicates whether or not the transaction for the annotated
test method should be <emphasis > rolled back</emphasis> after the
test method has completed. If <literal > true</literal> , the
transaction will be rolled back; otherwise, the transaction will be
committed. Use <interfacename > @Rollback</interfacename> to override
the default rollback flag configured at the class level.</para>
2009-04-08 21:38:36 +08:00
<programlisting language= "java" > @Rollback(false)
2009-03-19 04:00:49 +08:00
public void testProcessWithoutRollback() {
<lineannotation > // ...</lineannotation>
}</programlisting>
</listitem>
<listitem >
<para > <emphasis
role="bold"><interfacename > @NotTransactional</interfacename> </emphasis> </para>
<para > The presence of this annotation indicates that the annotated
test method must <emphasis > not</emphasis> execute in a transactional
context.</para>
2009-04-08 21:38:36 +08:00
<programlisting language= "java" > @NotTransactional
2009-03-19 04:00:49 +08:00
public void testProcessWithoutTransaction() {
<lineannotation > // ...</lineannotation>
}</programlisting>
</listitem>
</itemizedlist>
<para > Annotation support for:</para>
<itemizedlist >
<listitem >
<para > <link linkend= "junit38-legacy-java5-support" > JUnit 3.8 legacy
support</link> : all common annotations listed above are supported
but <emphasis > must</emphasis> be used in conjunction with
<classname > AbstractAnnotationAwareTransactionalTests</classname> in
order for the presence of these annotations to have any
effect.</para>
</listitem>
<listitem >
<para > <link linkend= "testcontext-annotations" > The TestContext
Framework</link> : supports all of the common annotations listed
above while providing additional TestContext-specific and
transactional annotations (e.g.,
<interfacename > @ContextConfiguration</interfacename> ,
<interfacename > @BeforeTransaction</interfacename> , etc.). Note,
however, that some of the common annotations are only supported when
used in conjunction with JUnit (e.g., with the <link
linkend="testcontext-junit4-runner">SpringJUnit4ClassRunner</link>
or the <link linkend= "testcontext-support-classes-junit38" > JUnit
3.8</link> and <link
2009-04-30 09:04:39 +08:00
linkend="testcontext-support-classes-junit45">JUnit 4.5</link> base
2009-03-19 04:00:49 +08:00
test classes). Refer to the documentation in the
<emphasis > TestContext Framework</emphasis> section for further
details.</para>
</listitem>
</itemizedlist>
</section>
<section id= "junit38-legacy-support" >
<title > JUnit 3.8 legacy support</title>
2009-04-30 09:04:39 +08:00
<para > Spring's JUnit 3.8 legacy support consists of the classes
2009-03-19 04:00:49 +08:00
found in the <literal > org.springframework.test</literal> package. This
package provides valuable JUnit <classname > TestCase</classname>
superclasses which can be extended for out-of-container integration
tests involving Spring <classname > ApplicationContext</classname> s or
requiring transactional support at the test method level.</para>
<section id= "junit38-legacy-ctx-management" >
<title > Context management and caching</title>
<para > <classname > AbstractSingleSpringContextTests</classname> provides
context management and caching support for JUnit 3.8 based test cases
and exposes a <literal > protected</literal> method that subclasses can
override to provide the location of context definition files:</para>
2009-04-08 21:38:36 +08:00
<programlisting language= "java" > protected String[] getConfigLocations()</programlisting>
2009-03-19 04:00:49 +08:00
<para > Implementations of this method must provide an array containing
the resource locations of XML configuration metadata - typically on
the classpath - used to configure the application. This will be the
same, or nearly the same, as the list of configuration locations
specified in <literal > web.xml</literal> or other deployment
configuration. As an alternative you may choose to override one of the
following. See the respective JavaDoc for further details.</para>
2009-04-08 21:38:36 +08:00
<programlisting language= "java" > protected String[] getConfigPaths()</programlisting>
2009-03-19 04:00:49 +08:00
2009-04-08 21:38:36 +08:00
<programlisting language= "java" > protected String getConfigPath()</programlisting>
2009-03-19 04:00:49 +08:00
<para > By default, once loaded, the configuration file set will be
reused for each test case. Thus the setup cost will be incurred only
once (per test fixture), and subsequent test execution will be much
faster. In the unlikely case that a test may 'dirty' the application
context, requiring reloading - for example, by changing a bean
definition or the state of an application object - you can call the
<methodname > setDirty()</methodname> method on
<classname > AbstractSingleSpringContextTests</classname> to cause the
test fixture to reload the configurations and rebuild the application
context before executing the next test case. As an alternative, if you
are developing against Java 5 or greater and extending <link
linkend="junit38-legacy-annotation-aware-tests"><classname > AbstractAnnotationAwareTransactionalTests</classname> </link> ,
you may annotate your test method with
<interfacename > @DirtiesContext</interfacename> to achieve the same
effect.</para>
</section>
<section id= "junit38-legacy-fixture-di" >
<title > Dependency Injection of test fixtures</title>
<para > When
<classname > AbstractDependencyInjectionSpringContextTests</classname>
(and subclasses) load your application context, they can optionally
configure instances of your test classes by Setter Injection. All you
need to do is to define instance variables and the corresponding
setter methods.
<classname > AbstractDependencyInjectionSpringContextTests</classname>
will automatically locate the corresponding object in the set of
configuration files specified in the
<methodname > getConfigLocations()</methodname> method.</para>
<para > Consider the scenario where we have a class,
<classname > HibernateTitleDao</classname> (as outlined in the <link
linkend="testing-fixture-di">Common goals</link> section). Let's look
at a JUnit 3.8 based implementation of the test class itself (we will
look at the configuration immediately afterwards).</para>
2009-04-08 21:38:36 +08:00
<programlisting language= "java" > public final class HibernateTitleDaoTests <emphasis
2009-03-19 04:00:49 +08:00
role="bold">extends AbstractDependencyInjectionSpringContextTests</emphasis> {
<lineannotation > // this instance will be (automatically) dependency injected</lineannotation>
private HibernateTitleDao titleDao;
<lineannotation > // a setter method to enable DI of the 'titleDao' instance variable</lineannotation>
public void setTitleDao(HibernateTitleDao titleDao) {
this.titleDao = titleDao;
}
public void testLoadTitle() throws Exception {
Title title = this.titleDao.loadTitle(new Long(10));
assertNotNull(title);
}
<lineannotation > // specifies the Spring configuration to load for this test fixture</lineannotation>
protected String[] getConfigLocations() {
return new String[] { "classpath:com/foo/daos.xml" };
}
}</programlisting>
<para > The file referenced by the
<methodname > getConfigLocations()</methodname> method (i.e.,
<literal > "classpath:com/foo/daos.xml"</literal> ) looks like
this:</para>
2009-04-08 21:38:36 +08:00
<programlisting language= "xml" > < ?xml version="1.0" encoding="UTF-8"?>
2009-03-19 04:00:49 +08:00
< beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-2.5.xsd">
<lineannotation > < !-- this bean will be injected into the <classname > HibernateTitleDaoTests</classname> class --> </lineannotation>
< bean id="<emphasis role= "bold" > titleDao</emphasis> " class="<emphasis
role="bold">com.foo.dao.hibernate.HibernateTitleDao</emphasis> ">
< property name="sessionFactory" ref="sessionFactory"/>
< /bean>
< bean id="sessionFactory" class="org.springframework.orm.hibernate3.LocalSessionFactoryBean">
<lineannotation > < !-- dependencies elided for clarity --> </lineannotation>
< /bean>
< /beans> </programlisting>
<para > The
<classname > AbstractDependencyInjectionSpringContextTests</classname>
classes uses <link linkend= "beans-factory-autowire" > <emphasis > autowire
by type</emphasis> </link> . Thus 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 the inherited
<literal > applicationContext</literal> instance variable and perform
explicit lookups using (for example) a call to
<methodname > applicationContext.getBean("titleDao")</methodname> .</para>
<para > If you don't want dependency injection applied to your test
cases, simply don't declare any <literal > public</literal> setter
methods. Alternatively, you can extend
<classname > AbstractSpringContextTests</classname> - the root of the
JUnit 3.8 integration testing support class hierarchy in the
<literal > org.springframework.test</literal> package - which merely
contains convenience methods to load Spring contexts and performs no
Dependency Injection of the test fixture.</para>
<section id= "junit38-legacy-fixture-di-field" >
<title > Field level injection</title>
<para > If, for whatever reason, you don't fancy having setter methods
in your test fixtures, Spring can inject dependencies into
<literal > protected</literal> fields. Find below a reworking of the
previous example to use field level injection (the Spring XML
configuration does not need to change, merely the test
fixture).</para>
2009-04-08 21:38:36 +08:00
<programlisting language= "java" > public final class HibernateTitleDaoTests <emphasis
2009-03-19 04:00:49 +08:00
role="bold">extends AbstractDependencyInjectionSpringContextTests</emphasis> {
public HibernateTitleDaoTests() {
<lineannotation > // switch on field level injection</lineannotation>
setPopulateProtectedVariables(true);
}
<lineannotation > // this instance will be (automatically) dependency injected</lineannotation>
<lineannotation > <emphasis > protected</emphasis> </lineannotation> HibernateTitleDao <lineannotation > <emphasis > titleDao</emphasis> </lineannotation> ;
public void testLoadTitle() throws Exception {
Title title = this.titleDao.loadTitle(new Long(10));
assertNotNull(title);
}
<lineannotation > // specifies the Spring configuration to load for this test fixture</lineannotation>
protected String[] getConfigLocations() {
return new String[] { "classpath:com/foo/daos.xml" };
}
}</programlisting>
<para > In the case of field injection, there is no autowiring going
on: the name of a <literal > protected</literal> instance variable is
used as the lookup bean name in the configured Spring
container.</para>
</section>
</section>
<section id= "junit38-legacy-tx" >
<title > Transaction management</title>
<para > <classname > AbstractTransactionalSpringContextTests</classname>
depends on a <classname > PlatformTransactionManager</classname> bean
being defined in the application context. The name doesn't matter due
to the use of <link
linkend="beans-factory-autowire"><emphasis > autowire by
type</emphasis> </link> .</para>
<para > Typically you will extend the subclass,
<classname > AbstractTransactionalDataSourceSpringContextTests</classname> .
This class also requires that a <classname > DataSource</classname> bean
definition - again, with any name - be present in the application
context. It creates a <classname > JdbcTemplate</classname> instance
variable, that is useful for convenient querying, and provides handy
methods to delete the contents of selected tables (remember that the
transaction will roll back by default, so this is safe to do).</para>
<para > If you want a transaction to commit
<emphasis > programmatically</emphasis> - unusual, but occasionally
useful when you want a particular test to populate the database - you
can call the <methodname > setComplete()</methodname> method inherited
from <classname > AbstractTransactionalSpringContextTests</classname> .
This will cause the transaction to commit instead of roll back. As an
alternative, if you are developing against Java 5 or greater and
extending <link
linkend="junit38-legacy-annotation-aware-tests"><classname > AbstractAnnotationAwareTransactionalTests</classname> </link> ,
you may annotate your test method with
<interfacename > @Rollback(false)</interfacename> to achieve the same
effect through <emphasis > configuration</emphasis> .</para>
<para > There is also the convenient ability to end a transaction before
the test case ends, by calling the
<methodname > endTransaction()</methodname> method. This will roll back
the transaction by default and commit it only if
<methodname > setComplete()</methodname> had previously been called.
This functionality is useful if you want to test the behavior of
'disconnected' data objects, such as Hibernate-mapped entities that
will be used in a web or remoting tier outside a transaction. Often,
lazy loading errors are discovered only through UI testing; if you
call <methodname > endTransaction()</methodname> you can ensure correct
operation of the UI through your JUnit test suite.</para>
</section>
<section id= "junit38-legacy-support-classes" >
<title > JUnit 3.8 legacy support classes</title>
<para > When you extend the
<classname > AbstractTransactionalDataSourceSpringContextTests</classname>
class you will have access to the following
<literal > protected</literal> instance variables:</para>
<itemizedlist >
<listitem >
<para > <literal > applicationContext</literal> (a
<interfacename > ConfigurableApplicationContext</interfacename> ):
inherited from the
<classname > AbstractSingleSpringContextTests</classname>
superclass. Use this to perform explicit bean lookup or to test
the state of the context as a whole.</para>
</listitem>
<listitem >
<para > <literal > jdbcTemplate</literal> : inherited from
<classname > AbstractTransactionalDataSourceSpringContextTests</classname> .
Useful for querying to confirm state. For example, you might query
before and after testing application code that creates an object
and persists it using an ORM tool, to verify that the data appears
in the database. (Spring will ensure that the query runs in the
scope of the same transaction.) You will need to tell your ORM
tool to 'flush' its changes for this to work correctly, for
example using the <methodname > flush()</methodname> method on
Hibernate's <classname > Session</classname> interface.</para>
</listitem>
</itemizedlist>
</section>
<section id= "junit38-legacy-java5-support" >
<title > Java 5+ specific support</title>
<section id= "junit38-legacy-annotation-aware-tests" >
<title > Annotation aware transactional tests</title>
<para > In addition to the aforementioned <link
linkend="integration-testing-common-annotations">common
annotations</link> , the
<literal > org.springframework.test.annotation</literal> package also
contains an <literal > abstract</literal> JUnit
<classname > TestCase</classname> class which provides
annotation-driven integration testing support.</para>
<para > The
<classname > AbstractAnnotationAwareTransactionalTests</classname>
class extends
<classname > AbstractTransactionalDataSourceSpringContextTests</classname>
and makes text fixtures, which extend it, aware of a number of
(Spring-specific) annotations.
<classname > AbstractAnnotationAwareTransactionalTests</classname>
supports all annotations listed in the <link
linkend="integration-testing-common-annotations">common
annotations</link> section as well as Spring's
<interfacename > @Transactional</interfacename> annotation for
configuring explicit transactional semantics.</para>
</section>
<section id= "junit38-legacy-jpa-tests" >
<title > JPA support classes</title>
<para > The <literal > org.springframework.test.jpa</literal> package
provides support classes for tests based on the Java Persistence API
(JPA).</para>
<itemizedlist >
<listitem >
<para > <classname > AbstractJpaTests</classname> is a convenient
support class for JPA-related tests, which offers the same
contract as
<classname > AbstractTransactionalDataSourceSpringContextTests</classname>
and equally good performance, even when performing the
instrumentation required by the JPA specification. Exposes an
<interfacename > EntityManagerFactory</interfacename> and a shared
<interfacename > EntityManager</interfacename> . Requires an
<interfacename > EntityManagerFactory</interfacename> to be
injected, plus the <interfacename > DataSource</interfacename> and
<interfacename > JpaTransactionManager</interfacename> through the
superclass.</para>
</listitem>
<listitem >
<para > <classname > AbstractAspectjJpaTests</classname> is a
subclass of <classname > AbstractJpaTests</classname> that
activates AspectJ load-time weaving and allows the ability to
specify a custom location for AspectJ's
<literal > aop.xml</literal> file.</para>
</listitem>
</itemizedlist>
</section>
</section>
</section>
<section id= "testcontext-framework" >
<title > Spring TestContext Framework</title>
<para > The <emphasis > Spring <classname > TestContext</classname>
Framework</emphasis> (located in the
<literal > org.springframework.test.context</literal> package) provides
generic, annotation-driven unit and integration testing support that is
agnostic of the testing framework in use, for example JUnit 3.8, JUnit
2009-04-30 09:04:39 +08:00
4.5, TestNG 5.8, etc. The TestContext framework also places a great deal
2009-03-19 04:00:49 +08:00
of importance on <emphasis > convention over configuration</emphasis> with
reasonable defaults that can be overridden via annotation-based
configuration.</para>
<para > In addition to generic testing infrastructure, the TestContext
2009-04-30 09:04:39 +08:00
framework provides explicit support for JUnit 3.8, JUnit 4.5, and TestNG
5.8 in the form of <literal > abstract</literal> support classes. For
JUnit 4.5, the framework also provides a custom
2009-03-19 04:00:49 +08:00
<interfacename > Runner</interfacename> which allows one to write test
classes that are not required to extend a particular class
hierarchy.</para>
<para > The following section provides an overview of the internals of the
TestContext framework. If you are only interested in using the framework
and not necessarily interested in extending it with your own custom
listeners, feel free to skip ahead to the configuration (<link
linkend="testcontext-ctx-management">context management</link> , <link
linkend="testcontext-fixture-di">dependency injection</link> , <link
linkend="testcontext-tx">transaction management</link> ), <link
linkend="testcontext-support-classes">support classes</link> , and <link
linkend="testcontext-annotations">annotation support</link>
sections.</para>
<!-- ================================================================= -->
<section id= "testcontext-key-abstractions" >
<title > Key abstractions</title>
<para > The core of the framework consists of the
<classname > TestContext</classname> and
<classname > TestContextManager</classname> classes and the
<interfacename > TestExecutionListener</interfacename> interface. A
<classname > TestContextManager</classname> is created on a per-test
basis. The <classname > TestContextManager</classname> in turn manages a
<classname > TestContext</classname> which is responsible for holding
the context of the current test. The
<classname > TestContextManager</classname> is also responsible for
updating the state of the <classname > TestContext</classname> as the
test progresses and delegating to
<interfacename > TestExecutionListener</interfacename> s, which
instrument the actual test execution (e.g., providing dependency
injection, managing transactions, etc.). Consult the JavaDoc and the
Spring test suite for further information and examples of various
configurations.</para>
<itemizedlist >
<listitem >
<para > <classname > TestContext</classname> : encapsulates the context
in which a test is executed, agnostic of the actual testing
framework in use.</para>
</listitem>
<listitem >
<para > <classname > TestContextManager</classname> : the main entry
point into the <emphasis > Spring TestContext Framework</emphasis> ,
which is responsible for managing a single
<classname > TestContext</classname> and signaling events to all
registered <interfacename > TestExecutionListener</interfacename> s
at well defined test execution points: test instance preparation,
prior to any <emphasis > before methods</emphasis> of a particular
testing framework, and after any <emphasis > after
methods</emphasis> of a particular testing framework.</para>
</listitem>
<listitem >
<para > <interfacename > TestExecutionListener</interfacename> :
defines a <emphasis > listener</emphasis> API for reacting to test
execution events published by the
<classname > TestContextManager</classname> with which the listener
is registered.</para>
<para > Spring provides three
<interfacename > TestExecutionListener</interfacename>
2009-04-30 09:04:39 +08:00
implementations which are configured by default:
2009-03-19 04:00:49 +08:00
<classname > DependencyInjectionTestExecutionListener</classname> ,
<classname > DirtiesContextTestExecutionListener</classname> , and
<classname > TransactionalTestExecutionListener</classname> , which
provide support for dependency injection of the test instance,
handling of the <interfacename > @DirtiesContext</interfacename>
annotation, and transactional test execution support with default
rollback semantics, respectively.</para>
</listitem>
</itemizedlist>
<para > The following three sections explain how to configure the
<classname > TestContext</classname> framework via annotations and
provide working examples of how to actually write unit and integration
tests with the framework.</para>
</section>
<!-- ================================================================= -->
<section id= "testcontext-ctx-management" >
<title > Context management and caching</title>
<para > Each <classname > TestContext</classname> provides context
management and caching support for the test instance for which it is
responsible. Test instances do not automatically receive access to the
configured <classname > ApplicationContext</classname> ; however, if a
test class implements the
<interfacename > ApplicationContextAware</interfacename> interface, a
reference to the <classname > ApplicationContext</classname> will be
supplied to the test instance (provided the
<classname > DependencyInjectionTestExecutionListener</classname> has
been configured, which is the default). Note that
<classname > AbstractJUnit38SpringContextTests</classname> ,
<classname > AbstractJUnit4SpringContextTests</classname> , and
<classname > AbstractTestNGSpringContextTests</classname> already
implement <interfacename > ApplicationContextAware</interfacename> and
therefore provide this functionality out-of-the-box.</para>
2009-04-30 09:04:39 +08:00
<tip >
<title > @Autowired ApplicationContext</title>
<para >
As an alternative to implementing the
<interfacename > ApplicationContextAware</interfacename> interface,
your test class can have its application context injected via the
<interfacename > @Autowired</interfacename> annotation on either a
field or setter method, for example:
</para>
<programlisting language= "java" > @RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration
public class MyTest {
<emphasis role= "bold" > @Autowired</emphasis>
private ApplicationContext applicationContext;
<lineannotation > // class body...</lineannotation>
}</programlisting>
</tip>
2009-03-19 04:00:49 +08:00
<para > In contrast to the JUnit 3.8 legacy support, test classes which
use the TestContext framework do not need to override any
<literal > protected</literal> instance methods to configure their
application context. Rather, configuration is achieved merely by
declaring the <interfacename > @ContextConfiguration</interfacename>
annotation at the class level. If your test class does not explicitly
declare any application context resource <literal > locations</literal> ,
the configured <interfacename > ContextLoader</interfacename> will
determine how and whether or not to load a context from a default set
of locations. For example,
<classname > GenericXmlContextLoader</classname> - which is the default
<interfacename > ContextLoader</interfacename> - will generate a default
location based on the name of the test class. If your class is named
<literal > com.example.MyTest</literal> ,
<classname > GenericXmlContextLoader</classname> will load your
application context from
<literal > "classpath:/com/example/MyTest-context.xml"</literal> .</para>
2009-04-08 21:38:36 +08:00
<programlisting language= "java" > package com.example;
2009-03-19 04:00:49 +08:00
@RunWith(SpringJUnit4ClassRunner.class)
<lineannotation > // ApplicationContext will be loaded from <literal > "classpath:/com/example/MyTest-context.xml"</literal> </lineannotation>
<emphasis role= "bold" > @ContextConfiguration</emphasis>
public class MyTest {
<lineannotation > // class body...</lineannotation>
}</programlisting>
<para > If the default location does not suit your needs, you are free
to explicitly configure the <literal > locations</literal> attribute of
<interfacename > @ContextConfiguration</interfacename> (see code listing
below) with an array containing the resource locations of XML
configuration metadata (assuming an XML-capable
<interfacename > ContextLoader</interfacename> has been configured) -
typically on the classpath - used to configure the application. This
will be the same, or nearly the same, as the list of configuration
locations specified in <literal > web.xml</literal> or other deployment
configuration. As an alternative you may choose to implement and
configure your own custom
<interfacename > ContextLoader</interfacename> .</para>
2009-04-08 21:38:36 +08:00
<programlisting language= "java" > @RunWith(SpringJUnit4ClassRunner.class)
2009-03-19 04:00:49 +08:00
<lineannotation > // ApplicationContext will be loaded from <literal > "/applicationContext.xml"</literal> and <literal > "/applicationContext-test.xml"</literal> </lineannotation>
<lineannotation > // in the root of the classpath</lineannotation>
<emphasis role= "bold" > @ContextConfiguration(locations={"/applicationContext.xml", "/applicationContext-test.xml"})</emphasis>
public class MyTest {
<lineannotation > // class body...</lineannotation>
}</programlisting>
<para > <interfacename > @ContextConfiguration</interfacename> also
supports a boolean <literal > inheritLocations</literal> attribute which
denotes whether or not resource locations from superclasses should be
<emphasis > inherited</emphasis> . The default value is
<literal > true</literal> , which means that an annotated class will
<emphasis > inherit</emphasis> the resource locations defined by an
annotated superclass. Specifically, the resource locations for an
annotated class will be appended to the list of resource locations
defined by an annotated superclass. Thus, subclasses have the option
of <emphasis > extending</emphasis> the list of resource locations. In
the following example, the
<interfacename > ApplicationContext</interfacename> for
<classname > ExtendedTest</classname> will be loaded from
"/base-context.xml" <emphasis role= "bold" > and</emphasis>
"/extended-context.xml", in that order. Beans defined in
"/extended-context.xml" may therefore override those defined in
"/base-context.xml".</para>
2009-04-08 21:38:36 +08:00
<programlisting language= "java" > @RunWith(SpringJUnit4ClassRunner.class)
2009-03-19 04:00:49 +08:00
<lineannotation > // ApplicationContext will be loaded from <literal > "/base-context.xml"</literal> in the root of the classpath</lineannotation>
<emphasis role= "bold" > @ContextConfiguration(locations={"/base-context.xml"})</emphasis>
public class BaseTest {
<lineannotation > // class body...</lineannotation>
}
<lineannotation > // ApplicationContext will be loaded from <literal > "/base-context.xml"</literal> and <literal > "/extended-context.xml"</literal> </lineannotation>
<lineannotation > // in the root of the classpath</lineannotation>
<emphasis role= "bold" > @ContextConfiguration(locations={"/extended-context.xml"})</emphasis>
public class ExtendedTest extends BaseTest {
<lineannotation > // class body...</lineannotation>
}</programlisting>
<para > If <literal > inheritLocations</literal> is set to
<literal > false</literal> , the resource locations for the annotated
class will <emphasis > shadow</emphasis> and effectively replace any
resource locations defined by a superclass.</para>
<para > By default, once loaded, the configured
<interfacename > ApplicationContext</interfacename> will be reused for
each test. Thus the setup cost will be incurred only once (per test
fixture), and subsequent test execution will be much faster. In the
unlikely case that a test may <emphasis > dirty</emphasis> the
application context, requiring reloading - for example, by changing a
bean definition or the state of an application object - you may
annotate your test method with
<interfacename > @DirtiesContext</interfacename> (assuming
<classname > DirtiesContextTestExecutionListener</classname> has been
configured, which is the default) to cause the test fixture to reload
the configurations and rebuild the application context before
executing the next test.</para>
</section>
<!-- ================================================================= -->
<section id= "testcontext-fixture-di" >
<title > Dependency Injection of test fixtures</title>
<para > When you configure the
<classname > DependencyInjectionTestExecutionListener</classname> -
which is configured by default - via the
<interfacename > @TestExecutionListeners</interfacename> annotation, the
dependencies of your test instances will be
<emphasis > injected</emphasis> from beans in the application context
you configured via
<interfacename > @ContextConfiguration</interfacename> by Setter
Injection, Field Injection, or both, depending on which annotations
you choose and whether you place them on setter methods or fields. For
2009-04-30 09:04:39 +08:00
consistency with the annotation support introduced in Spring 2.5, you
may choose either Spring's <interfacename > @Autowired</interfacename>
annotation or the <interfacename > @Resource</interfacename> annotation
from JSR 250. The semantics for both are consistent throughout the Spring
2009-03-19 04:00:49 +08:00
Framework. For example, if you prefer <link
linkend="beans-factory-autowire"><emphasis > autowiring by
type</emphasis> </link> , annotate your setter methods or fields with
<interfacename > @Autowired</interfacename> . On the other hand, if you
prefer to have your dependencies injected <emphasis > by
name</emphasis> , annotate your setter methods or fields with
<interfacename > @Resource</interfacename> .</para>
<tip >
<para > The TestContext framework does not instrument the manner in
which a test instance is instantiated. Thus the use of
<interfacename > @Autowired</interfacename> for constructors has no
effect for test classes.</para>
</tip>
<para > Since <interfacename > @Autowired</interfacename> performs <link
linkend="beans-factory-autowire"><emphasis > autowiring by
type</emphasis> </link> , 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
<interfacename > @Resource</interfacename> for injection <emphasis > by
2009-04-30 09:04:39 +08:00
name</emphasis> . Alternatively, if your test class has access to its
<classname > ApplicationContext</classname> , you can perform an explicit
lookup using (for example) a call to
<methodname > applicationContext.getBean("titleDao")</methodname> . A
third option is to use <interfacename > @Autowired</interfacename>
in conjunction with <interfacename > @Qualifier</interfacename> .
</para>
2009-03-19 04:00:49 +08:00
<para > If you don't want dependency injection applied to your test
instances, simply don't annotate any fields or setter methods with
<interfacename > @Autowired</interfacename> or
<interfacename > @Resource</interfacename> . Alternatively, you can
disable dependency injection altogether by explicitly configuring your
class with <interfacename > @TestExecutionListeners</interfacename> and
omitting
<literal > DependencyInjectionTestExecutionListener.class</literal> from
the list of listeners.</para>
<para > Consider the scenario where we have a class,
<classname > HibernateTitleDao</classname> (as outlined in the <link
linkend="testing-fixture-di">common goals</link> section). First,
2009-04-30 09:04:39 +08:00
let's look at a JUnit 4.5 based implementation of the test class
2009-03-19 04:00:49 +08:00
itself which uses <interfacename > @Autowired</interfacename> for field
injection (we will look at the application context configuration after
all sample code listings). <emphasis > Note: The dependency injection
behavior in the following code listings is not in any way specific to
2009-04-30 09:04:39 +08:00
JUnit 4.5. The same DI techniques can be used in conjunction with any
2009-03-19 04:00:49 +08:00
testing framework.</emphasis> </para>
2009-04-08 21:38:36 +08:00
<programlisting language= "java" > @RunWith(SpringJUnit4ClassRunner.class)
2009-03-19 04:00:49 +08:00
<lineannotation > // specifies the Spring configuration to load for this test fixture</lineannotation>
<emphasis role= "bold" > @ContextConfiguration(locations={"daos.xml"})</emphasis>
public final class HibernateTitleDaoTests {
<lineannotation > // this instance will be dependency injected <emphasis
role="bold">by type</emphasis> </lineannotation>
<emphasis role= "bold" > @Autowired</emphasis>
private HibernateTitleDao titleDao;
public void testLoadTitle() throws Exception {
Title title = this.titleDao.loadTitle(new Long(10));
assertNotNull(title);
}
}</programlisting>
<!-- =============================================================== -->
<para > Alternatively, we can configure the class to use
<interfacename > @Autowired</interfacename> for setter injection.</para>
2009-04-08 21:38:36 +08:00
<programlisting language= "java" > @RunWith(SpringJUnit4ClassRunner.class)
2009-03-19 04:00:49 +08:00
<lineannotation > // specifies the Spring configuration to load for this test fixture</lineannotation>
<emphasis role= "bold" > @ContextConfiguration(locations={"daos.xml"})</emphasis>
public final class HibernateTitleDaoTests {
<lineannotation > // this instance will be dependency injected <emphasis
role="bold">by type</emphasis> </lineannotation>
private HibernateTitleDao titleDao;
<emphasis role= "bold" > @Autowired</emphasis>
public void setTitleDao(HibernateTitleDao titleDao) {
this.titleDao = titleDao;
}
public void testLoadTitle() throws Exception {
Title title = this.titleDao.loadTitle(new Long(10));
assertNotNull(title);
}
}</programlisting>
<!-- =============================================================== -->
<para > Now let's take a look at an example using
<interfacename > @Resource</interfacename> for field injection.</para>
2009-04-08 21:38:36 +08:00
<programlisting language= "java" > @RunWith(SpringJUnit4ClassRunner.class)
2009-03-19 04:00:49 +08:00
<lineannotation > // specifies the Spring configuration to load for this test fixture</lineannotation>
<emphasis role= "bold" > @ContextConfiguration(locations={"daos.xml"})</emphasis>
public final class HibernateTitleDaoTests {
<lineannotation > // this instance will be dependency injected <emphasis
role="bold">by name</emphasis> </lineannotation>
<emphasis role= "bold" > @Resource</emphasis>
private HibernateTitleDao titleDao;
public void testLoadTitle() throws Exception {
Title title = this.titleDao.loadTitle(new Long(10));
assertNotNull(title);
}
}</programlisting>
<!-- =============================================================== -->
<para > Finally, here is an example using
<interfacename > @Resource</interfacename> for setter injection.</para>
2009-04-08 21:38:36 +08:00
<programlisting language= "java" > @RunWith(SpringJUnit4ClassRunner.class)
2009-03-19 04:00:49 +08:00
<lineannotation > // specifies the Spring configuration to load for this test fixture</lineannotation>
<emphasis role= "bold" > @ContextConfiguration(locations={"daos.xml"})</emphasis>
public final class HibernateTitleDaoTests {
<lineannotation > // this instance will be dependency injected <emphasis
role="bold">by name</emphasis> </lineannotation>
private HibernateTitleDao titleDao;
<emphasis role= "bold" > @Resource</emphasis>
public void setTitleDao(HibernateTitleDao titleDao) {
this.titleDao = titleDao;
}
public void testLoadTitle() throws Exception {
Title title = this.titleDao.loadTitle(new Long(10));
assertNotNull(title);
}
}</programlisting>
<!-- =============================================================== -->
<para > The above code listings use the same XML context file referenced
by the <interfacename > @ContextConfiguration</interfacename> annotation
(i.e., <literal > "daos.xml"</literal> ) which looks like this:</para>
2009-04-08 21:38:36 +08:00
<programlisting language= "xml" > < ?xml version="1.0" encoding="UTF-8"?>
2009-03-19 04:00:49 +08:00
< beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-2.5.xsd">
<lineannotation > < !-- this bean will be injected into the <classname > HibernateTitleDaoTests</classname> class --> </lineannotation>
< bean id="<emphasis role= "bold" > titleDao</emphasis> " class="<emphasis
role="bold">com.foo.dao.hibernate.HibernateTitleDao</emphasis> ">
< property name="sessionFactory" ref="sessionFactory"/>
< /bean>
< bean id="sessionFactory" class="org.springframework.orm.hibernate3.LocalSessionFactoryBean">
<lineannotation > < !-- dependencies elided for clarity --> </lineannotation>
< /bean>
< /beans> </programlisting>
<note >
<para > If you are extending from a Spring-provided test base class that happens
to use <interfacename > @Autowired</interfacename> on one of its setters methods,
you might have multiple beans of the affected type defined in your application context:
e.g. multiple <interfacename > DataSource</interfacename> beans. In such a case,
you may override the setter and use the <interfacename > @Qualifier</interfacename>
annotation to indicate a specific target bean as follows:</para>
2009-04-08 21:38:36 +08:00
<programlisting language= "java" > ...
2009-03-19 04:00:49 +08:00
@Override @Autowired
public void setDataSource(<emphasis role= "bold" > @Qualifier("myDataSource")</emphasis> DataSource dataSource) {
super.setDataSource(dataSource);
}
...</programlisting>
<para > The specified qualifier value indicates the specific
<interfacename > DataSource</interfacename> bean to inject,
narrowing the set of type matches to a specific bean.
Its value is matched against <literal > < qualifier> </literal>
declarations within the corresponding <literal > < bean> </literal>
definitions. The bean name is used as a fallback qualifier value,
so you may effectively also point to a specific bean by name there
(as shown above, assuming that "myDataSource" is the bean id).
If there is only one <interfacename > DataSource</interfacename> bean
to begin with, then the qualifier will simply not have any effect
- independent from the bean name of that single matching bean.</para>
<para > Alternatively, consider using the <interfacename > @Resource</interfacename>
annotation on such an overridden setter methods, defining the
target bean name explicitly - with no type matching semantics.
Note that this always points to a bean with that specific name,
no matter whether there is one or more beans of the given type.</para>
2009-04-08 21:38:36 +08:00
<programlisting language= "java" > ...
2009-03-19 04:00:49 +08:00
@Override <emphasis role= "bold" > @Resource("myDataSource")</emphasis>
public void setDataSource(DataSource dataSource) {
super.setDataSource(dataSource);
}
...</programlisting>
</note>
</section>
<!-- ================================================================= -->
<section id= "testcontext-tx" >
<title > Transaction management</title>
<para > In the TestContext framework, transactions are managed by the
<classname > TransactionalTestExecutionListener</classname> , which is
configured via the
<interfacename > @TestExecutionListeners</interfacename> annotation by
default, even if you do not explicitly declare
<interfacename > @TestExecutionListeners</interfacename> on your test
class. To enable support for transactions, however, you must provide a
<classname > PlatformTransactionManager</classname> bean in the
application context loaded via
<interfacename > @ContextConfiguration</interfacename> semantics. In
addition, you must declare
<interfacename > @Transactional</interfacename> either at the class or
method level.</para>
<para > For class-level transaction configuration (i.e., setting the
bean name for the transaction manager and the default rollback flag),
see the <interfacename > @TransactionConfiguration</interfacename> entry
in the <link linkend= "testcontext-annotations" > TestContext framework
annotation support</link> section.</para>
<para > There are several options for configuring transactions for
individual test methods. If transactions are not enabled for the
entire test class, methods may be explicitly annotated with
<interfacename > @Transactional</interfacename> . Similarly, if
transactions <emphasis > are</emphasis> enabled for the entire test
class, methods may be explicitly flagged not to run within a
transaction by annotating them with
<interfacename > @NotTransactional</interfacename> . To control whether
or not a transaction should commit for a particular test method, you
may use the <interfacename > @Rollback</interfacename> annotation to
override the class-level default rollback setting.</para>
<para > <emphasis > Note that <link
linkend="testcontext-support-classes-junit38"><classname > AbstractTransactionalJUnit38SpringContextTests</classname> </link> ,
<link
2009-04-30 09:04:39 +08:00
linkend="testcontext-support-classes-junit45"><classname > AbstractTransactionalJUnit4SpringContextTests</classname> </link> ,
2009-03-19 04:00:49 +08:00
and <link
linkend="testcontext-support-classes-testng"><classname > AbstractTransactionalTestNGSpringContextTests</classname> </link>
are pre-configured for transactional support at the class level.
</emphasis> </para>
<para > You will occasionally find that you need to execute certain code
before or after a transactional test method but outside the
transactional context, for example to verify the initial database
state prior to execution of your test or to verify expected
transactional commit behavior after test execution (e.g., if the test
was configured not to roll back the transaction).
<classname > TransactionalTestExecutionListener</classname> supports the
<interfacename > @BeforeTransaction</interfacename> and
<interfacename > @AfterTransaction</interfacename> annotations exactly
for such scenarios. Simply annotate any <literal > public void</literal>
method in your test class with one of these annotations, and the
<classname > TransactionalTestExecutionListener</classname> will ensure
that your <emphasis > before transaction method</emphasis> or
<emphasis > after transaction method</emphasis> is executed at the
appropriate time.</para>
<tip >
<para > Any <emphasis > before methods</emphasis> (e.g., methods
annotated with JUnit 4's @Before) and any <emphasis > after
methods</emphasis> (e.g., methods annotated with JUnit 4's @After)
will be executed <emphasis role= "bold" > within</emphasis> a
transaction. In addition, methods annotated with
<interfacename > @BeforeTransaction</interfacename> or
<interfacename > @AfterTransaction</interfacename> will naturally not
be executed for tests annotated with
<interfacename > @NotTransactional</interfacename> .</para>
</tip>
<para > The following JUnit 4 based example displays a fictitious
integration testing scenario highlighting several of the
transaction-related annotations. Consult the <link
linkend="testcontext-annotations">TestContext framework annotation
support</link> section of the reference manual for further information
and configuration examples.</para>
2009-04-08 21:38:36 +08:00
<programlisting language= "java" > @RunWith(SpringJUnit4ClassRunner.class)
2009-03-19 04:00:49 +08:00
@ContextConfiguration
<emphasis role= "bold" > @TransactionConfiguration(transactionManager="txMgr", defaultRollback=false)</emphasis>
<emphasis role= "bold" > @Transactional</emphasis>
public class FictitiousTransactionalTest {
<emphasis role= "bold" > @BeforeTransaction</emphasis>
public void verifyInitialDatabaseState() {
<lineannotation > // logic to verify the initial state before a transaction is started</lineannotation>
}
@Before
public void setUpTestDataWithinTransaction() {
<lineannotation > // set up test data within the transaction</lineannotation>
}
@Test
<lineannotation > // overrides the class-level defaultRollback setting</lineannotation>
<emphasis role= "bold" > @Rollback(true)</emphasis>
public void modifyDatabaseWithinTransaction() {
<lineannotation > // logic which uses the test data and modifies database state</lineannotation>
}
@After
public void tearDownWithinTransaction() {
<lineannotation > // execute "tear down" logic within the transaction</lineannotation>
}
<emphasis role= "bold" > @AfterTransaction</emphasis>
public void verifyFinalDatabaseState() {
<lineannotation > // logic to verify the final state after transaction has rolled back</lineannotation>
}
@Test
<emphasis role= "bold" > @NotTransactional</emphasis>
public void performNonDatabaseRelatedAction() {
<lineannotation > // logic which does not modify database state</lineannotation>
}
}</programlisting>
</section>
<!-- ================================================================= -->
<section id= "testcontext-support-classes" >
<title > TestContext support classes</title>
<section id= "testcontext-support-classes-junit38" >
<title > JUnit 3.8 support classes</title>
<para > The
<literal > org.springframework.test.context.junit38</literal> package
provides support classes for JUnit 3.8 based test cases.</para>
<itemizedlist >
<listitem >
<para > <classname > AbstractJUnit38SpringContextTests</classname> :</para>
<para > Abstract <classname > TestCase</classname> which integrates
the <emphasis > Spring TestContext Framework</emphasis> with
explicit <classname > ApplicationContext</classname> testing
support in a JUnit 3.8 environment. When you extend the
<classname > AbstractJUnit38SpringContextTests</classname> class
you will have access to the following
<literal > protected</literal> instance variables:</para>
<itemizedlist >
<listitem >
<para > <literal > applicationContext</literal> : use this to
perform explicit bean lookups or to test the state of the
context as a whole.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem >
<para > <classname > AbstractTransactionalJUnit38SpringContextTests</classname> :</para>
<para > Abstract <emphasis > transactional</emphasis> extension of
<classname > AbstractJUnit38SpringContextTests</classname> that
also adds some convenience functionality for JDBC access.
Expects a <classname > javax.sql.DataSource</classname> bean and a
<interfacename > PlatformTransactionManager</interfacename> bean
to be defined in the <classname > ApplicationContext</classname> .
When you extend the
<classname > AbstractTransactionalJUnit38SpringContextTests</classname>
class you will have access to the following
<literal > protected</literal> instance variables:</para>
<itemizedlist >
<listitem >
<para > <literal > applicationContext</literal> : inherited from
the <classname > AbstractJUnit38SpringContextTests</classname>
superclass. Use this to perform explicit bean lookups or to
test the state of the context as a whole.</para>
</listitem>
<listitem >
<para > <literal > simpleJdbcTemplate</literal> : useful for
querying to confirm state. For example, you might query
before and after testing application code that creates an
object and persists it using an ORM tool, to verify that the
data appears in the database. (Spring will ensure that the
query runs in the scope of the same transaction.) You will
need to tell your ORM tool to 'flush' its changes for this
to work correctly, for example using the
<methodname > flush()</methodname> method on Hibernate's
<classname > Session</classname> interface.</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</section>
2009-04-30 09:04:39 +08:00
<section id= "testcontext-support-classes-junit45" >
<title > JUnit 4.5 support classes</title>
2009-03-19 04:00:49 +08:00
<para > The <literal > org.springframework.test.context.junit4</literal>
2009-04-30 09:04:39 +08:00
package provides support classes for JUnit 4.5 based test
2009-03-19 04:00:49 +08:00
cases.</para>
<itemizedlist >
<listitem >
<para > <classname > AbstractJUnit4SpringContextTests</classname> :</para>
<para > Abstract base test class which integrates the
<emphasis > Spring TestContext Framework</emphasis> with explicit
<classname > ApplicationContext</classname> testing support in a
2009-04-30 09:04:39 +08:00
JUnit 4.5 environment.</para>
2009-03-19 04:00:49 +08:00
<para > When you extend
<classname > AbstractJUnit4SpringContextTests</classname> you will
have access to the following <literal > protected</literal>
instance variables:</para>
<itemizedlist >
<listitem >
<para > <literal > applicationContext</literal> : use this to
perform explicit bean lookups or to test the state of the
context as a whole.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem >
<para > <classname > AbstractTransactionalJUnit4SpringContextTests</classname> :</para>
<para > Abstract <emphasis > transactional</emphasis> extension of
<classname > AbstractJUnit4SpringContextTests</classname> that
also adds some convenience functionality for JDBC access.
Expects a <classname > javax.sql.DataSource</classname> bean and a
<interfacename > PlatformTransactionManager</interfacename> bean
to be defined in the
<classname > ApplicationContext</classname> .</para>
<para > When you extend
<classname > AbstractTransactionalJUnit4SpringContextTests</classname>
you will have access to the following
<literal > protected</literal> instance variables:</para>
<itemizedlist >
<listitem >
<para > <literal > applicationContext</literal> : inherited from
the <classname > AbstractJUnit4SpringContextTests</classname>
superclass. Use this to perform explicit bean lookups or to
test the state of the context as a whole.</para>
</listitem>
<listitem >
<para > <literal > simpleJdbcTemplate</literal> : useful for
querying to confirm state. For example, you might query
before and after testing application code that creates an
object and persists it using an ORM tool, to verify that the
data appears in the database. (Spring will ensure that the
query runs in the scope of the same transaction.) You will
need to tell your ORM tool to 'flush' its changes for this
to work correctly, for example using the
<methodname > flush()</methodname> method on Hibernate's
<classname > Session</classname> interface.</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<tip >
<para > These classes serve only as a convenience for extension. If
you do not wish for your test classes to be tied to a
Spring-specific class hierarchy - for example, if you wish to
directly extend the class you are testing - you may configure your
own custom test classes by using
<interfacename > @RunWith(SpringJUnit4ClassRunner.class)</interfacename> ,
<interfacename > @ContextConfiguration</interfacename> ,
<interfacename > @TestExecutionListeners</interfacename> ,
etc.</para>
</tip>
</section>
<section id= "testcontext-junit4-runner" >
2009-04-30 09:04:39 +08:00
<title > Custom JUnit 4.5 Runner</title>
2009-03-19 04:00:49 +08:00
<para > The <emphasis > Spring TestContext Framework</emphasis> offers
2009-04-30 09:04:39 +08:00
full integration with JUnit 4.5 via a custom runner. By annotating
2009-03-19 04:00:49 +08:00
test classes with
<literal > @Runwith(SpringJUnit4ClassRunner.class)</literal> ,
2009-04-30 09:04:39 +08:00
developers can implement standard JUnit 4.5 unit and integration
2009-03-19 04:00:49 +08:00
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
execution, etc. The following code listing displays the minimal
requirements for configuring a test class to run with the custom
Spring Runner. <emphasis > Note that
<interfacename > @TestExecutionListeners</interfacename> has been
configured with an empty list in order to disable the default
listeners, which would otherwise require that an
<interfacename > ApplicationContext</interfacename> be configured via
<interfacename > @ContextConfiguration</interfacename> .</emphasis> </para>
2009-04-08 21:38:36 +08:00
<programlisting language= "java" > @RunWith(SpringJUnit4ClassRunner.class)
2009-03-19 04:00:49 +08:00
@TestExecutionListeners({})
public class SimpleTest {
@Test
public void testMethod() {
<lineannotation > // execute test logic...</lineannotation>
}
}</programlisting>
</section>
<section id= "testcontext-support-classes-testng" >
<title > TestNG support classes</title>
<para > The <literal > org.springframework.test.context.testng</literal>
package provides support classes for TestNG based test cases.</para>
<itemizedlist >
<listitem >
<para > <classname > AbstractTestNGSpringContextTests</classname> :</para>
<para > Abstract base test class which integrates the
<emphasis > Spring TestContext Framework</emphasis> with explicit
<classname > ApplicationContext</classname> testing support in a
TestNG environment.</para>
<para > When you extend
<classname > AbstractTestNGSpringContextTests</classname> you will
have access to the following <literal > protected</literal>
instance variables:</para>
<itemizedlist >
<listitem >
<para > <literal > applicationContext</literal> : use this to
perform explicit bean lookups or to test the state of the
context as a whole.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem >
<para > <classname > AbstractTransactionalTestNGSpringContextTests</classname> :</para>
<para > Abstract <emphasis > transactional</emphasis> extension of
<classname > AbstractTestNGSpringContextTests</classname> that
adds some convenience functionality for JDBC access. Expects a
<classname > javax.sql.DataSource</classname> bean and a
<interfacename > PlatformTransactionManager</interfacename> bean
to be defined in the
<classname > ApplicationContext</classname> .</para>
<para > When you extend
<classname > AbstractTransactionalTestNGSpringContextTests</classname>
you will have access to the following
<literal > protected</literal> instance variables:</para>
<itemizedlist >
<listitem >
<para > <literal > applicationContext</literal> : inherited from
the <classname > AbstractTestNGSpringContextTests</classname>
superclass. Use this to perform explicit bean lookups or to
test the state of the context as a whole.</para>
</listitem>
<listitem >
<para > <literal > simpleJdbcTemplate</literal> : useful for
querying to confirm state. For example, you might query
before and after testing application code that creates an
object and persists it using an ORM tool, to verify that the
data appears in the database. (Spring will ensure that the
query runs in the scope of the same transaction.) You will
need to tell your ORM tool to 'flush' its changes for this
to work correctly, for example using the
<methodname > flush()</methodname> method on Hibernate's
<classname > Session</classname> interface.</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<tip >
<para > These classes serve only as a convenience for extension. If
you do not wish for your test classes to be tied to a
Spring-specific class hierarchy - for example, if you wish to
directly extend the class you are testing - you may configure your
own custom test classes by using
<interfacename > @ContextConfiguration</interfacename> ,
<interfacename > @TestExecutionListeners</interfacename> , etc. and
by manually instrumenting your test class with a
<classname > TestContextManager</classname> . See the source code of
<classname > AbstractTestNGSpringContextTests</classname> for an
example of how to instrument your test class.</para>
</tip>
</section>
</section>
<!-- ================================================================= -->
<section id= "testcontext-annotations" >
<title > TestContext framework annotation support</title>
<!-- =============================================================== -->
<para > The Spring TestContext Framework supports all annotations as
outlined in the <link
linkend="integration-testing-common-annotations">common
annotations</link> section. The following annotations, however, are
<emphasis > only supported when used in conjunction with JUnit (e.g.,
with the <link
linkend="testcontext-junit4-runner">SpringJUnit4ClassRunner</link> or
the <link linkend= "testcontext-support-classes-junit38" > JUnit
3.8</link> and <link
2009-04-30 09:04:39 +08:00
linkend="testcontext-support-classes-junit45">JUnit 4.5</link> support
2009-03-19 04:00:49 +08:00
classes.</emphasis> </para>
<itemizedlist >
<listitem >
<para > <interfacename > @IfProfileValue</interfacename> </para>
</listitem>
<listitem >
<para > <interfacename > @ProfileValueSourceConfiguration</interfacename> </para>
</listitem>
<listitem >
<para > <interfacename > @ExpectedException</interfacename> </para>
<para > Using Spring's
<interfacename > @ExpectedException</interfacename> annotation in
conjunction with JUnit 4's
<interfacename > @Test(expected=...)</interfacename> 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.</para>
</listitem>
<listitem >
<para > <interfacename > @Timed</interfacename> </para>
<para > Spring's <interfacename > @Timed</interfacename> annotation
has different semantics than JUnit 4's
<interfacename > @Test(timeout=...)</interfacename> support.
Specifically, due to the manner in which JUnit 4 handles test
execution timeouts (i.e., by executing the test method in a
separate <classname > Thread</classname> ),
<interfacename > @Test(timeout=...)</interfacename> applies to
<emphasis > each iteration</emphasis> in the case of repetitions
and preemptively fails the test if the test takes too long.
Spring's <interfacename > @Timed</interfacename> , on the other hand,
times the <emphasis > total</emphasis> test execution time
(including all repetitions) and does not preemptively fail the test
but rather waits for the test to actually complete before failing.</para>
</listitem>
<listitem >
<para > <interfacename > @Repeat</interfacename> </para>
</listitem>
</itemizedlist>
<!-- =============================================================== -->
<para > The following non-test-specific annotations are also supported
by the Spring TestContext Framework with their standard
semantics.</para>
<itemizedlist >
<listitem >
<para > <interfacename > @Autowired</interfacename> </para>
</listitem>
<listitem >
<para > <interfacename > @Qualifier</interfacename> </para>
</listitem>
<listitem >
<para > <interfacename > @Resource</interfacename> (javax.annotation)
<emphasis > if JSR-250 is present</emphasis> </para>
</listitem>
<listitem >
<para > <interfacename > @PersistenceContext</interfacename>
(javax.persistence) <emphasis > if JPA is present</emphasis> </para>
</listitem>
<listitem >
<para > <interfacename > @PersistenceUnit</interfacename>
(javax.persistence) <emphasis > if JPA is present</emphasis> </para>
</listitem>
<listitem >
<para > <interfacename > @Required</interfacename> </para>
</listitem>
<listitem >
<para > <interfacename > @Transactional</interfacename> </para>
</listitem>
</itemizedlist>
<!-- =============================================================== -->
<para > The following list includes all annotations specific to the
Spring TestContext Framework. Refer to the respective JavaDoc for
further information, including default attribute values, etc.</para>
<itemizedlist >
<listitem >
<para > <emphasis
role="bold"><interfacename > @ContextConfiguration</interfacename> </emphasis> </para>
<para > Defines class-level metadata which is used to determine how
to load and configure an
<interfacename > ApplicationContext</interfacename> . Specifically,
@ContextConfiguration defines the application context resource
<literal > locations</literal> to load as well as the
<interfacename > ContextLoader</interfacename> strategy to use for
loading the context.</para>
2009-04-08 21:38:36 +08:00
<programlisting language= "java" > @ContextConfiguration(locations={"example/test-context.xml"}, loader=CustomContextLoader.class)
2009-03-19 04:00:49 +08:00
public class CustomConfiguredApplicationContextTests {
<lineannotation > // class body...</lineannotation>
}</programlisting>
<para > Note: <interfacename > @ContextConfiguration</interfacename>
provides support for <emphasis > inherited</emphasis> resource
locations by default. See the <link
linkend="testcontext-ctx-management">Context management and
caching</link> section and JavaDoc for an example and further
details.</para>
</listitem>
<listitem >
<para > <emphasis
role="bold"><interfacename > @TestExecutionListeners</interfacename> </emphasis> </para>
<para > Defines class-level metadata for configuring which
<interfacename > TestExecutionListener</interfacename> s should be
registered with a <classname > TestContextManager</classname> .
Typically, <interfacename > @TestExecutionListeners</interfacename>
will be used in conjunction with
<interfacename > @ContextConfiguration</interfacename> .</para>
2009-04-08 21:38:36 +08:00
<programlisting language= "java" > @ContextConfiguration
2009-03-19 04:00:49 +08:00
@TestExecutionListeners({CustomTestExecutionListener.class, AnotherTestExecutionListener.class})
public class CustomTestExecutionListenerTests {
<lineannotation > // class body...</lineannotation>
}</programlisting>
<para > Note: <interfacename > @TestExecutionListeners</interfacename>
provides support for <emphasis > inherited</emphasis> listeners by
default. See the JavaDoc for an example and further
details.</para>
</listitem>
<listitem >
<para > <emphasis
role="bold"><interfacename > @TransactionConfiguration</interfacename> </emphasis> </para>
<para > Defines class-level metadata for configuring transactional
tests. Specifically, the bean name of the
<interfacename > PlatformTransactionManager</interfacename> 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, the
<literal > defaultRollback</literal> flag can optionally be changed
to <literal > false</literal> . Typically,
<interfacename > @TransactionConfiguration</interfacename> will be
used in conjunction with
<interfacename > @ContextConfiguration</interfacename> .</para>
2009-04-08 21:38:36 +08:00
<programlisting language= "java" > @ContextConfiguration
2009-03-19 04:00:49 +08:00
@TransactionConfiguration(transactionManager="txMgr", defaultRollback=false)
public class CustomConfiguredTransactionalTests {
<lineannotation > // class body...</lineannotation>
}</programlisting>
</listitem>
<listitem >
<para > <emphasis
role="bold"><interfacename > @BeforeTransaction</interfacename> </emphasis> </para>
<para > Indicates that the annotated <literal > public void</literal>
method should be executed <emphasis > before</emphasis> a
transaction is started for test methods configured to run within a
transaction via the <interfacename > @Transactional</interfacename>
annotation.</para>
2009-04-08 21:38:36 +08:00
<programlisting language= "java" > @BeforeTransaction
2009-03-19 04:00:49 +08:00
public void beforeTransaction() {
<lineannotation > // logic to be executed before a transaction is started</lineannotation>
}</programlisting>
</listitem>
<listitem >
<para > <emphasis
role="bold"><interfacename > @AfterTransaction</interfacename> </emphasis> </para>
<para > Indicates that the annotated <literal > public void</literal>
method should be executed <emphasis > after</emphasis> a transaction
has been ended for test methods configured to run within a
transaction via the <interfacename > @Transactional</interfacename>
annotation.</para>
2009-04-08 21:38:36 +08:00
<programlisting language= "java" > @AfterTransaction
2009-03-19 04:00:49 +08:00
public void afterTransaction() {
<lineannotation > // logic to be executed after a transaction has ended</lineannotation>
}</programlisting>
</listitem>
</itemizedlist>
</section>
</section>
<!-- === PetClinic Example ================================================= -->
<section id= "testing-examples-petclinic" >
<title > PetClinic example</title>
<para > The PetClinic sample application included with the full Spring
distribution illustrates several features of the <emphasis > Spring
2009-04-30 09:04:39 +08:00
TestContext Framework</emphasis> in a JUnit 4.5 environment. Most test
2009-03-19 04:00:49 +08:00
functionality is included in the
<classname > AbstractClinicTests</classname> , for which a partial listing
is shown below:</para>
2009-04-08 21:38:36 +08:00
<programlisting language= "java" > <emphasis role= "bold" > @ContextConfiguration</emphasis>
2009-03-19 04:00:49 +08:00
public abstract class AbstractClinicTests <emphasis role= "bold" > extends AbstractTransactionalJUnit4SpringContextTests</emphasis> {
<emphasis role= "bold" > @Autowired</emphasis>
protected Clinic clinic;
@Test
public void getVets() {
Collection< Vet> vets = this.clinic.getVets();
assertEquals("JDBC query must show the same number of vets",
<emphasis role= "bold" > super.countRowsInTable("VETS")</emphasis> , vets.size());
Vet v1 = EntityUtils.getById(vets, Vet.class, 2);
assertEquals("Leary", v1.getLastName());
assertEquals(1, v1.getNrOfSpecialties());
assertEquals("radiology", (v1.getSpecialties().get(0)).getName());
<lineannotation > // ...</lineannotation>
}
<lineannotation > // ...</lineannotation>
}</programlisting>
<para > Notes:</para>
<itemizedlist >
<listitem >
<para > This test case extends the
<classname > AbstractTransactionalJUnit4SpringContextTests</classname>
class, from which it inherits configuration for Dependency Injection
(via the
<classname > DependencyInjectionTestExecutionListener</classname> ) and
transactional behavior (via the
<classname > TransactionalTestExecutionListener</classname> ).</para>
</listitem>
<listitem >
<para > The <literal > clinic</literal> instance variable - the
application object being tested - is set by Dependency Injection via
<interfacename > @Autowired</interfacename> semantics.</para>
</listitem>
<listitem >
<para > The <methodname > testGetVets()</methodname> method illustrates
how the inherited <methodname > countRowsInTable()</methodname> method
can be used to easily verify the number of rows in a given table,
thus testing correct behavior of the application code being tested.
This allows for stronger tests and lessens dependency on the exact
test data. For example, you can add additional rows in the database
without breaking tests.</para>
</listitem>
<listitem >
<para > Like many integration tests using a database, most of the
tests in <classname > AbstractClinicTests</classname> depend on a
minimum amount of data already in the database before the test cases
run. You might, however, choose to populate the database in your
test cases also - again, within the same transaction.</para>
</listitem>
</itemizedlist>
<para > The PetClinic application supports three data access technologies
- JDBC, Hibernate, and JPA. By declaring
<interfacename > @ContextConfiguration</interfacename> without any
specific resource locations, the
<classname > AbstractClinicTests</classname> class will have its
application context loaded from the default location,
<literal > "AbstractClinicTests-context.xml"</literal> , which declares a
common <classname > DataSource</classname> . Subclasses specify additional
context locations which must declare a
<interfacename > PlatformTransactionManager</interfacename> and a concrete
implementation of <interfacename > Clinic</interfacename> .</para>
<para > For example, the Hibernate implementation of the PetClinic tests
contains the following implementation. Note that for this example,
<classname > HibernateClinicTests</classname> does not contain a single
line of code: we only need to declare
<interfacename > @ContextConfiguration</interfacename> , and the tests are
inherited from <classname > AbstractClinicTests</classname> . Since
<interfacename > @ContextConfiguration</interfacename> is declared without
any specific resource locations, the <emphasis > Spring TestContext
Framework</emphasis> will load an application context from all the beans
defined in <literal > "AbstractClinicTests-context.xml"</literal> (i.e.,
the inherited locations) and
<literal > "HibernateClinicTests-context.xml"</literal> , with
<literal > "HibernateClinicTests-context.xml"</literal> possibly
overriding beans defined in
<literal > "AbstractClinicTests-context.xml"</literal> .</para>
2009-04-08 21:38:36 +08:00
<programlisting language= "java" > <emphasis role= "bold" > @ContextConfiguration</emphasis>
2009-03-19 04:00:49 +08:00
public class HibernateClinicTests extends AbstractClinicTests { }
</programlisting>
<para > As you can see in the PetClinic application, the Spring
configuration is split across multiple files. As is typical of large
scale applications, configuration locations will often be specified in a
common base class for all application-specific integration tests. Such a
base class may also add useful instance variables - populated by
Dependency Injection, naturally - such as a
<classname > HibernateTemplate</classname> , in the case of an application
using Hibernate.</para>
<para > As far as possible, you should have exactly the same Spring
configuration files in your integration tests as in the deployed
environment. One likely point of difference concerns database connection
pooling and transaction infrastructure. If you are deploying to a
full-blown application server, you will probably use its connection pool
(available through JNDI) and JTA implementation. Thus in production you
will use a <classname > JndiObjectFactoryBean</classname> for the
<classname > DataSource</classname> and
<classname > JtaTransactionManager</classname> . JNDI and JTA will not be
available in out-of-container integration tests, so you should use a
combination like the Commons DBCP <classname > BasicDataSource</classname>
and <classname > DataSourceTransactionManager</classname> or
<classname > HibernateTransactionManager</classname> for them. You can
factor out this variant behavior into a single XML file, having the
choice between application server and 'local' configuration separated
from all other configuration, which will not vary between the test and
production environments. In addition, it is advisable to use properties
files for connection settings: see the PetClinic application for an
example.</para>
</section>
<!-- ======================================================================= -->
</section>
<section id= "testing-resources" >
<title > Further Resources</title>
2009-04-30 09:04:39 +08:00
<para > This section contains links to further resources about testing in general.</para>
2009-03-19 04:00:49 +08:00
<itemizedlist >
<listitem >
2009-04-30 09:04:39 +08:00
<para > <ulink url= "http://www.junit.org/" > JUnit</ulink> :
the Spring Framework's unit and integration test suite is written using
JUnit 3.8 and JUnit 4.5 as the testing framework.</para>
2009-03-19 04:00:49 +08:00
</listitem>
<listitem >
2009-04-30 09:04:39 +08:00
<para > <ulink url= "http://testng.org/" > TestNG</ulink> :
a testing framework inspired by JUnit 3.8 with added support
2009-03-19 04:00:49 +08:00
for Java 5 annotations, test groups, data-driven testing, distributed
testing, etc.</para>
</listitem>
<listitem >
2009-04-30 09:04:39 +08:00
<para > <ulink url= "http://www.mockobjects.com/" > MockObjects.com</ulink> :
a website dedicated to mock objects, a technique for improving the design
of code within Test-Driven Development.</para>
2009-03-19 04:00:49 +08:00
</listitem>
<listitem >
2009-04-30 09:04:39 +08:00
<para > <ulink url= "http://en.wikipedia.org/wiki/Mock_Object" > "Mock Objects"</ulink> :
article at Wikipedia.</para>
2009-03-19 04:00:49 +08:00
</listitem>
<listitem >
2009-04-30 09:04:39 +08:00
<para > <ulink url= "http://www.easymock.org/" > EasyMock</ulink> :
the Spring Framework uses EasyMock extensively in its test suite.</para>
2009-03-19 04:00:49 +08:00
</listitem>
<listitem >
2009-04-30 09:04:39 +08:00
<para > <ulink url= "http://www.jmock.org/" > JMock</ulink> :
a library that supports test-driven development of Java code
2009-03-19 04:00:49 +08:00
with mock objects.</para>
</listitem>
<listitem >
2009-04-30 09:04:39 +08:00
<para > <ulink url= "http://dbunit.sourceforge.net/" > DbUnit</ulink> :
a JUnit extension (also usable with Ant and Maven) targeted for database-driven
projects that, among other things, puts your database into a known state
between test runs.</para>
2009-03-19 04:00:49 +08:00
</listitem>
<listitem >
2009-04-30 09:04:39 +08:00
<para > <ulink url= "http://grinder.sourceforge.net/" > Grinder</ulink> :
a Java load testing framework.</para>
2009-03-19 04:00:49 +08:00
</listitem>
</itemizedlist>
2009-04-30 09:04:39 +08:00
2009-03-19 04:00:49 +08:00
</section>
</chapter>
