<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"

"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">

<chapter id="testing">

<title>Testing</title>

<section id="testing-introduction">

<title>Introduction to Spring Testing</title>

<para>Testing is an integral part of enterprise software development. This

chapter focuses on the value-add of the IoC principle to <link

linkend="unit-testing">unit testing</link> and on the benefits of the

Spring Framework's support for <link

linkend="integration-testing">integration testing</link>. <emphasis>(A

thorough treatment of testing in the enterprise is beyond the scope of

this reference manual.)</emphasis></para>

</section>

<section id="unit-testing">

<title>Unit Testing</title>

<para>Dependency Injection should make your code less dependent on the

container than it would be with traditional Java EE development. The POJOs

that make up your application should be testable 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 other valuable testing techniques) to test your code in isolation. If

you follow the architecture recommendations for Spring, the resulting

clean layering and componentization of your codebase will facilitate

easier unit testing. For example, you can test service layer objects by

stubbing or mocking DAO or Repository interfaces, without needing to

access persistent data while running unit tests.</para>

<para>True unit tests typically run extremely quickly, as there is no

runtime infrastructure to set up. Emphasizing true unit tests as part of

your development methodology will boost your productivity. You may not

need this section of the testing chapter to help you write effective unit

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 you can use to set

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 Java EE

container, you can reuse both application code and configuration 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 such as <ulink

url="http://www.easymock.org">EasyMock</ulink> or existing Servlet API

mock objects such as <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. Developers use these

methods in unit and integration testing scenarios in which they need

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 that condone

<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>,

<interfacename>@Inject</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>ModelAndViewAssert</classname>, which you can use

in combination with JUnit, TestNG, or any other testing framework for

unit tests dealing with Spring MVC <classname>ModelAndView</classname>

objects.</para>

<tip>

<title>Unit testing Spring MVC Controllers</title>

<para>To test your Spring MVC <literal>Controller</literal>s, use

<classname>ModelAndViewAssert</classname> combined with

<literal>MockHttpServletRequest</literal>,

<literal>MockHttpSession</literal>, and so on from the <link

linkend="mock-objects-servlet"><literal>org.springframework.mock.web</literal></link>

package.</para>

</tip>

</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 <filename class="libraryfile">spring-test</filename>

module. The name of the actual JAR file might include the release

version and might also be in the long

<filename>org.springframework.test</filename> form, depending on where

you get it from (see the <link linkend="dependency-management">section

on Dependency Management</link> for an explanation). This library

includes the <literal>org.springframework.test</literal> package, which

contains valuable classes for integration testing with a Spring

container. This testing does not rely on an application server or other

deployment environment. Such tests are slower to run than unit tests but

much faster than the equivalent Cactus tests or remote tests that rely

on deployment to an application server.</para>

<para>In Spring 2.5 and later, unit and integration testing support is

provided in the form of the annotation-driven <link

linkend="testcontext-framework">Spring TestContext Framework</link>. The

TestContext framework is agnostic of the actual testing framework in

use, thus allowing instrumentation of tests in various environments

including JUnit, TestNG, and so on.</para>

<warning>

<title>JUnit 3.8 support is deprecated</title>

<para>As of Spring 3.0, the legacy JUnit 3.8 base class hierarchy

(i.e.,

<classname>AbstractDependencyInjectionSpringContextTests</classname>,

<classname>AbstractTransactionalDataSourceSpringContextTests</classname>,

etc.) is officially deprecated and will be removed in a later release.

Any test classes based on this code should be migrated to the <link

linkend="testcontext-framework">Spring TestContext

Framework</link>.</para>

<para>As of Spring 3.1, the JUnit 3.8 base classes in the Spring

TestContext Framework (i.e.,

<classname>AbstractJUnit38SpringContextTests</classname> and

<classname>AbstractTransactionalJUnit38SpringContextTests</classname>)

and <interfacename>@ExpectedException</interfacename> have been

officially deprecated and will be removed in a later release. Any test

classes based on this code should be migrated to the JUnit 4 or TestNG

support provided by the <link linkend="testcontext-framework">Spring

TestContext Framework</link>. Similarly, any test methods annotated

with <interfacename>@ExpectedException</interfacename> should be

modified to use the built-in support for expected exceptions in JUnit

and TestNG.</para>

</warning>

</section>

<section id="integration-testing-goals">

<title>Goals of Integration Testing</title>

<para>Spring's integration testing support has the following primary

goals:</para>

<itemizedlist>

<listitem>

<para>To manage <link linkend="testing-ctx-management">Spring IoC

container caching</link> between test execution.</para>

</listitem>

<listitem>

<para>To provide <link linkend="testing-fixture-di">Dependency

Injection of test fixture instances</link>.</para>

</listitem>

<listitem>

<para>To provide <link linkend="testing-tx">transaction

management</link> appropriate to integration testing.</para>

</listitem>

<listitem>

<para>To supply <link

linkend="testing-support-classes">Spring-specific base

classes</link> that assist developers in writing integration

tests.</para>

</listitem>

</itemizedlist>

<para>The next few sections describe each goal and provide links to

implementation and configuration details.</para>

<section id="testing-ctx-management">

<title>Context management and caching</title>

<para>The Spring TestContext Framework provides consistent loading of

Spring <classname>ApplicationContext</classname>s and caching of those

contexts. Support for the caching of loaded contexts is important,

because startup time can become an issue — not because of the overhead

of Spring itself, but because the objects instantiated by the Spring

container take time to instantiate. For example, a project with 50 to

100 Hibernate mapping files might take 10 to 20 seconds to load the

mapping files, and incurring that cost before running every test in

every test fixture leads to slower overall test runs that could reduce

productivity.</para>

<para>Test classes can provide either an array containing the resource

locations of XML configuration metadata — typically in the classpath —

or an array containing <interfacename>@Configuration</interfacename>

classes that is used to configure the application. These locations or

classes are the same as or similar to those specified in

<literal>web.xml</literal> or other deployment configuration

files.</para>

<para>By default, once loaded, the configured

<interfacename>ApplicationContext</interfacename> is reused for each

test. Thus the setup cost is incurred only once (per test suite), and

subsequent test execution is much faster. In this context, the term

<emphasis>test suite</emphasis> means all tests run in the same JVM —

for example, all tests run from an Ant or Maven build for a given

project or module. In the unlikely case that a test corrupts the

application context and requires reloading — for example, by modifying

a bean definition or the state of an application object — the

TestContext framework can be configured to reload the configuration

and rebuild the application context before executing the next

test.</para>

<para>See context management and caching with the <link

linkend="testcontext-ctx-management">TestContext

framework</link>.</para>

</section>

<section id="testing-fixture-di">

<title>Dependency Injection of test fixtures</title>

<para>When the TestContext framework loads your application context,

it can optionally configure instances of your test classes via

Dependency Injection. This provides a convenient mechanism for setting

up test fixtures using preconfigured 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>HibernateTitleRepository</classname>, that performs data

access logic for a <classname>Title</classname> domain entity. We want

to write integration tests that test the following areas:</para>

<itemizedlist>

<listitem>

<para>The Spring configuration: basically, is everything related

to the configuration of the

<classname>HibernateTitleRepository</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>HibernateTitleRepository</classname>: does the

configured instance of this class perform as anticipated?</para>

</listitem>

</itemizedlist>

<para>See dependency injection of test fixtures with the <link

linkend="testcontext-fixture-di">TestContext framework</link>.</para>

</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 or modifying persistent data

— cannot be performed (or verified) outside a transaction.</para>

<para>The TestContext framework addresses this issue. By default, the

framework will 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 configured 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 TestContext framework can be instructed to cause the

transaction to commit instead of roll back via the <link

linkend="integration-testing-annotations"><interfacename>@TransactionConfiguration</interfacename></link>

and <link

linkend="integration-testing-annotations"><interfacename>@Rollback</interfacename></link>

annotations.</para>

<para>See transaction management with the <link

linkend="testcontext-tx">TestContext framework</link>.</para>

</section>

<section id="testing-support-classes">

<title>Support classes for integration testing</title>

<para>The Spring TestContext Framework provides several

<literal>abstract</literal> support classes that simplify the writing

of integration tests. These base test classes provide well-defined

hooks into the testing framework as well as convenient instance

variables and methods, which enable you to access:</para>

<itemizedlist>

<listitem>

<para>The <literal>ApplicationContext</literal>, for performing

explicit bean lookups or testing the state of the context as a

whole.</para>

</listitem>

<listitem>

<para>A <classname>SimpleJdbcTemplate</classname>, for executing

SQL statements to query the database. Such queries can be used to

confirm database state both <emphasis>prior to</emphasis> and

<emphasis>after</emphasis> execution of database-related

application code, and Spring ensures that such queries run in the

scope of the same transaction as the application code. When used

in conjunction with an ORM tool, be sure to avoid <link

linkend="testcontext-tx-false-positives">false

positives</link>.</para>

</listitem>

</itemizedlist>

<para>In addition, you may want to create your own custom,

application-wide superclass with instance variables and methods

specific to your project.</para>

<para>See support classes for the <link

linkend="testcontext-support-classes">TestContext

framework</link>.</para>

</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

collection of JDBC related utility functions intended to simplify

standard database testing scenarios. <emphasis>Note that <link

linkend="testcontext-support-classes-junit4"><classname>AbstractTransactionalJUnit4SpringContextTests</classname></link>

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-annotations">

<title>Annotations</title>

<section id="integration-testing-annotations-spring">

<title>Spring Testing Annotations</title>

<para>The Spring Framework provides the following set of

<emphasis>Spring-specific</emphasis> annotations that you can use in

your unit and integration tests in conjunction with the TestContext

framework. Refer to the respective Javadoc for further information,

including default attribute values, attribute aliases, and so

on.</para>

<itemizedlist>

<listitem>

<para><emphasis

role="bold"><interfacename>@ContextConfiguration</interfacename></emphasis></para>

<para>Defines class-level metadata that is used to determine how

to load and configure an

<interfacename>ApplicationContext</interfacename> for test

classes. Specifically,

<interfacename>@ContextConfiguration</interfacename> declares

<emphasis>either</emphasis> the application context resource

<literal>locations</literal> <emphasis>or</emphasis> the

<interfacename>@Configuration</interfacename>

<varname>classes</varname> (but not both) to load as well as the

<interfacename>ContextLoader</interfacename> strategy to use for

loading the context. Note, however, that you typically do not need

to explicitly configure the loader since the default loader

supports either resource <varname>locations</varname> or

configuration <varname>classes</varname>.</para>

<programlisting language="java"><emphasis role="bold">@ContextConfiguration</emphasis>(<emphasis

role="bold">locations</emphasis>="example/test-context.xml", <emphasis

role="bold">loader</emphasis>=CustomContextLoader.class)

public class XmlApplicationContextTests {

<lineannotation>// class body...</lineannotation>

}</programlisting>

<programlisting language="java"><emphasis role="bold">@ContextConfiguration</emphasis>(<emphasis

role="bold">classes</emphasis>=MyConfig.class)

public class ConfigClassApplicationContextTests {

<lineannotation>// class body...</lineannotation>

}</programlisting>

<note>

<para><interfacename>@ContextConfiguration</interfacename>

provides support for <emphasis>inheriting</emphasis> resource

locations or configuration classes declared by superclasses by

default.</para>

</note>

<para>See <link linkend="testcontext-ctx-management">Context

management and caching</link> and Javadoc for examples and further

details.</para>

</listitem>

<listitem>

<para><emphasis

role="bold"><interfacename>@ActiveProfiles</interfacename></emphasis></para>

<para>A class-level annotation that is used to declare which

<emphasis>bean definition profiles</emphasis> should be active

when loading an <interfacename>ApplicationContext</interfacename>

for test classes.</para>

<programlisting language="java">@ContextConfiguration

<emphasis role="bold">@ActiveProfiles</emphasis>("dev")

public class DeveloperTests {

<lineannotation>// class body...</lineannotation>

}</programlisting>

<programlisting language="java">@ContextConfiguration

<emphasis role="bold">@ActiveProfiles</emphasis>({"dev", "integration"})

public class DeveloperIntegrationTests {

<lineannotation>// class body...</lineannotation>

}</programlisting>

<note>

<para><interfacename>@ActiveProfiles</interfacename> provides

support for <emphasis>inheriting</emphasis> active bean

definition profiles declared by superclasses classes by

default.</para>

</note>

<para>See <link

linkend="testcontext-ctx-management-env-profiles">Context

configuration with environment profiles</link> and the Javadoc for

<interfacename>@ActiveProfiles</interfacename> for examples and

further details.</para>

</listitem>

<listitem>

<para><emphasis

role="bold"><interfacename>@DirtiesContext</interfacename></emphasis></para>

<para>Indicates that the underlying Spring

<interfacename>ApplicationContext</interfacename> has been

<emphasis>dirtied</emphasis> (i.e., modified or corrupted in some

manner) during the execution of a test and should be closed,

regardless of whether the test passed.

<interfacename>@DirtiesContext</interfacename> is supported in the

following scenarios:</para>

<itemizedlist>

<listitem>

<para>After the current test class, when declared on a class

with class mode set to <literal>AFTER_CLASS</literal>, which

is the default class mode.</para>

</listitem>

<listitem>

<para>After each test method in the current test class, when

declared on a class with class mode set to

<literal>AFTER_EACH_TEST_METHOD.</literal></para>

</listitem>

<listitem>

<para>After the current test, when declared on a

method.</para>

</listitem>

</itemizedlist>

<para>Use this annotation if a test has modified the context (for

example, by replacing a bean definition). Subsequent tests are

supplied a new context.</para>

<para>With JUnit 4.5+ or TestNG you can use

<interfacename>@DirtiesContext</interfacename> as both a

class-level and method-level annotation within the same test

class. In such scenarios, the

<interfacename>ApplicationContext</interfacename> is marked as

<emphasis>dirty</emphasis> after any such annotated method as well

as after the entire class. If the <classname>ClassMode</classname>

is set to <literal>AFTER_EACH_TEST_METHOD</literal>, the context

is marked dirty after each test method in the class.</para>

<programlisting language="java"><emphasis role="bold">@DirtiesContext</emphasis>

public class ContextDirtyingTests {

<lineannotation>// some tests that result in the Spring container being dirtied</lineannotation>

}</programlisting>

<programlisting language="java"><emphasis role="bold">@DirtiesContext</emphasis>(<emphasis

role="bold">classMode</emphasis> = ClassMode.AFTER_EACH_TEST_METHOD)

public class ContextDirtyingTests {

<lineannotation>// some tests that result in the Spring container being dirtied</lineannotation>

}</programlisting>

<programlisting language="java"><emphasis role="bold">@DirtiesContext</emphasis>

@Test

public void testProcessWhichDirtiesAppCtx() {

<lineannotation>// some logic that results in the Spring container being dirtied</lineannotation>

}</programlisting>

<para>When an application context is marked

<emphasis>dirty</emphasis>, it is removed from the testing

framework's cache and closed; thus the underlying Spring container

is rebuilt for any subsequent test that requires a context with

the same set of resource locations.</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 the <classname>TestContextManager</classname>.

Typically, <interfacename>@TestExecutionListeners</interfacename>

is used in conjunction with

<interfacename>@ContextConfiguration</interfacename>.</para>

<programlisting language="java">@ContextConfiguration

<emphasis role="bold">@TestExecutionListeners</emphasis>({CustomTestExecutionListener.class, AnotherTestExecutionListener.class})

public class CustomTestExecutionListenerTests {

<lineannotation>// class body...</lineannotation>

}</programlisting>

<para><interfacename>@TestExecutionListeners</interfacename>

supports <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

<interfacename>PlatformTransactionManager</interfacename> is not

"transactionManager". In addition, you can change the

<literal>defaultRollback</literal> flag to

<literal>false</literal>. Typically,

<interfacename>@TransactionConfiguration</interfacename> is used

in conjunction with

<interfacename>@ContextConfiguration</interfacename>.</para>

<programlisting language="java">@ContextConfiguration

<emphasis role="bold">@TransactionConfiguration</emphasis>(<emphasis

role="bold">transactionManager</emphasis>="txMgr", <emphasis

role="bold">defaultRollback</emphasis>=false)

public class CustomConfiguredTransactionalTests {

<lineannotation>// class body...</lineannotation>

}</programlisting>

<note>

<para>If the default conventions are sufficient for your test

configuration, you can avoid using

<interfacename>@TransactionConfiguration</interfacename>

altogether. In other words, if your transaction manager bean is

named "transactionManager" and if you want transactions to roll

back automatically, there is no need to annotate your test class

with

<interfacename>@TransactionConfiguration</interfacename>.</para>

</note>

</listitem>

<listitem>

<para><emphasis

role="bold"><interfacename>@Rollback</interfacename></emphasis></para>

<para>Indicates whether 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

is rolled back; otherwise, the transaction is committed. Use

<interfacename>@Rollback</interfacename> to override the default

rollback flag configured at the class level.</para>

<programlisting language="java"><emphasis role="bold">@Rollback</emphasis>(false)

@Test

public void testProcessWithoutRollback() {

<lineannotation>// ...</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>

<programlisting language="java"><emphasis role="bold">@BeforeTransaction

</emphasis>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 ended for test methods configured to run within a transaction

via the <interfacename>@Transactional</interfacename>

annotation.</para>

<programlisting language="java"><emphasis role="bold">@AfterTransaction

</emphasis>public void afterTransaction() {

<lineannotation>// logic to be executed after a transaction has ended</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>

<programlisting language="java"><emphasis role="bold">@NotTransactional</emphasis>

@Test

public void testProcessWithoutTransaction() {

<lineannotation>// ...</lineannotation>

}</programlisting>

<warning>

<title>@NotTransactional is deprecated</title>

<para>As of Spring 3.0,

<interfacename>@NotTransactional</interfacename> is deprecated

in favor of moving the <emphasis>non-transactional</emphasis>

test method to a separate (non-transactional) test class or to a

<interfacename>@BeforeTransaction</interfacename> or

<interfacename>@AfterTransaction</interfacename> method. As an

alternative to annotating an entire class with

<interfacename>@Transactional</interfacename>, consider

annotating individual methods with

<interfacename>@Transactional</interfacename>; doing so allows a

mix of transactional and non-transactional methods in the same

test class without the need for using

<interfacename>@NotTransactional</interfacename>.</para>

</warning>

</listitem>

</itemizedlist>

</section>

<section id="integration-testing-annotations-standard">

<title>Standard Annotation Support</title>

<para>The following annotations are supported with standard semantics

for all configurations of the Spring TestContext Framework. Note that

these annotations are not specific to tests and can be used anywhere

in the Spring Framework.</para>

<itemizedlist>

<listitem>

<para><emphasis

role="bold"><interfacename>@Autowired</interfacename></emphasis></para>

</listitem>

<listitem>

<para><emphasis

role="bold"><interfacename>@Qualifier</interfacename></emphasis></para>

</listitem>

<listitem>

<para><emphasis

role="bold"><interfacename>@Resource</interfacename></emphasis>

(javax.annotation) <emphasis>if JSR-250 is

present</emphasis></para>

</listitem>

<listitem>

<para><emphasis

role="bold"><interfacename>@Inject</interfacename></emphasis>

(javax.inject) <emphasis>if JSR-330 is present</emphasis></para>

</listitem>

<listitem>

<para><emphasis

role="bold"><interfacename>@Named</interfacename></emphasis>

(javax.inject) <emphasis>if JSR-330 is present</emphasis></para>

</listitem>

<listitem>

<para><emphasis

role="bold"><interfacename>@PersistenceContext</interfacename></emphasis>

(javax.persistence) <emphasis>if JPA is present</emphasis></para>

</listitem>

<listitem>

<para><emphasis

role="bold"><interfacename>@PersistenceUnit</interfacename></emphasis>

(javax.persistence) <emphasis>if JPA is present</emphasis></para>

</listitem>

<listitem>

<para><emphasis

role="bold"><interfacename>@Required</interfacename></emphasis></para>

</listitem>

<listitem>

<para><emphasis

role="bold"><interfacename>@Transactional</interfacename></emphasis></para>

</listitem>

</itemizedlist>

</section>

<section id="integration-testing-annotations-junit">

<title>Spring JUnit Testing Annotations</title>

<para>The following annotations are <emphasis>only</emphasis>

supported when used in conjunction with the <link

linkend="testcontext-junit4-runner">SpringJUnit4ClassRunner</link> or

the <link linkend="testcontext-support-classes-junit4">JUnit</link>

support classes.</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 is enabled. This annotation can be applied to an entire

class or to individual methods. Class-level usage overrides

method-level usage.</para>

<programlisting language="java"><emphasis role="bold">@IfProfileValue</emphasis>(<emphasis

role="bold">name</emphasis>="java.vendor", <emphasis

role="bold">value</emphasis>="Sun Microsystems Inc.")

@Test

public void testProcessWhichRunsOnlyOnSunJvm() {

<lineannotation>// some logic that should run only on Java VMs from Sun Microsystems</lineannotation>

}</programlisting>

<para>Alternatively, you can configure

<interfacename>@IfProfileValue</interfacename> 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>

<programlisting language="java"><emphasis role="bold">@IfProfileValue</emphasis>(<emphasis

role="bold">name</emphasis>="test-groups", <emphasis

role="bold">values</emphasis>={"unit-tests", "integration-tests"})

@Test

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 that specifies what type of

<literal>ProfileValueSource</literal> to use when retrieving

<emphasis>profile values</emphasis> configured through the

<interfacename>@IfProfileValue</interfacename> annotation. If

<interfacename>@ProfileValueSourceConfiguration</interfacename> is

not declared for a test,

<classname>SystemProfileValueSource</classname> is used by

default.</para>

<programlisting language="java"><emphasis role="bold">@ProfileValueSourceConfiguration</emphasis>(CustomProfileValueSource.class)

public class CustomProfileValueSourceTests {

<lineannotation>// class body...</lineannotation>

}</programlisting>

</listitem>

<listitem>

<para><emphasis

role="bold"><interfacename>@Timed</interfacename></emphasis></para>

<para>Indicates that the annotated test method must finish

execution in a specified time period (in milliseconds). If the

text execution time exceeds the specified time period, the test

fails.</para>

<para>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>

<programlisting language="java"><emphasis role="bold">@Timed</emphasis>(millis=1000)

public void testProcessWithOneSecondTimeout() {

<lineannotation>// some logic that should not take longer than 1 second to execute</lineannotation>

}</programlisting>

<para>Spring's <interfacename>@Timed</interfacename> annotation

has different semantics than JUnit's

<interfacename>@Test(timeout=...)</interfacename> support.

Specifically, due to the manner in which JUnit handles test

execution timeouts (that is, 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 complete before failing.</para>

</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>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>

<programlisting language="java"><emphasis role="bold">@Repeat</emphasis>(10)

@Test

public void testProcessRepeatedly() {

<lineannotation>// ...</lineannotation>

}</programlisting>

</listitem>

</itemizedlist>

</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, whether JUnit or TestNG. The

TestContext framework also places a great deal of importance on

<emphasis>convention over configuration</emphasis> with reasonable

defaults that can be overridden through annotation-based

configuration.</para>

<para>In addition to generic testing infrastructure, the TestContext

framework provides explicit support for JUnit and TestNG in the form of

<literal>abstract</literal> support classes. For JUnit, Spring also

provides a custom JUnit <interfacename>Runner</interfacename> that

allows one to write so called <emphasis>POJO test classes</emphasis>.

POJO test classes 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 or custom loaders, feel free to go directly 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="integration-testing-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>,

<interfacename>ContextLoader</interfacename>, and

<interfacename>SmartContextLoader</interfacename> interfaces. A

<classname>TestContextManager</classname> is created on a per-test

basis (e.g., for the execution of a single test method in JUnit). The

<classname>TestContextManager</classname> in turn manages a

<classname>TestContext</classname> that holds the context of the

current test. The <classname>TestContextManager</classname> also

updates the state of the <classname>TestContext</classname> as the

test progresses and delegates to

<interfacename>TestExecutionListener</interfacename>s, which

instrument the actual test execution by providing dependency

injection, managing transactions, and so on. A

<interfacename>ContextLoader</interfacename> (or

<interfacename>SmartContextLoader</interfacename>) is responsible for

loading an <interfacename>ApplicationContext</interfacename> for a

given test class. Consult the Javadoc and the Spring test suite for

further information and examples of various implementations.</para>

<itemizedlist>

<listitem>

<para><classname>TestContext</classname>: Encapsulates the context

in which a test is executed, agnostic of the actual testing

framework in use, and provides context management and caching

support for the test instance for which it is responsible. The

<classname>TestContext</classname> also delegates to a

<interfacename>ContextLoader</interfacename> (or

<interfacename>SmartContextLoader</interfacename>) to load an

<interfacename>ApplicationContext</interfacename> if

requested.</para>

</listitem>

<listitem>

<para><classname>TestContextManager</classname>: The main entry

point into the <emphasis>Spring TestContext Framework</emphasis>,

which manages a single <classname>TestContext</classname> and

signals events to all registered

<interfacename>TestExecutionListener</interfacename>s at

well-defined test execution points:</para>

<itemizedlist>

<listitem>

<para>prior to any <emphasis>before class methods</emphasis>

of a particular testing framework</para>

</listitem>

<listitem>

<para>test instance preparation</para>

</listitem>

<listitem>

<para>prior to any <emphasis>before methods</emphasis> of a

particular testing framework</para>

</listitem>

<listitem>

<para>after any <emphasis>after methods</emphasis> of a

particular testing framework</para>