8477 lines
308 KiB
Plaintext
8477 lines
308 KiB
Plaintext
[[testing]]
|
||
= Testing
|
||
:doc-root: https://docs.spring.io
|
||
:api-spring-framework: {doc-root}/spring-framework/docs/{spring-version}/javadoc-api/org/springframework
|
||
:doc-spring-boot: {doc-root}/spring-boot/docs/current/reference
|
||
:toc: left
|
||
:toclevels: 4
|
||
:tabsize: 4
|
||
:docinfo1:
|
||
|
||
This chapter covers Spring's support for integration testing and best practices for unit
|
||
testing. The Spring team advocates test-driven development (TDD). The Spring team has
|
||
found that the correct use of inversion of control (IoC) certainly does make both unit
|
||
and integration testing easier (in that the presence of setter methods and appropriate
|
||
constructors on classes makes them easier to wire together in a test without having to
|
||
set up service locator registries and similar structures).
|
||
|
||
|
||
|
||
|
||
[[testing-introduction]]
|
||
== Introduction to Spring Testing
|
||
|
||
Testing is an integral part of enterprise software development. This chapter focuses on
|
||
the value added by the IoC principle to <<unit-testing, unit testing>> and on the benefits
|
||
of the Spring Framework's support for <<integration-testing, integration testing>>. (A
|
||
thorough treatment of testing in the enterprise is beyond the scope of this reference
|
||
manual.)
|
||
|
||
|
||
|
||
|
||
[[unit-testing]]
|
||
== Unit Testing
|
||
|
||
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 instantiated by using the `new`
|
||
operator, without Spring or any other container. You can use <<mock-objects, mock objects>>
|
||
(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 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.
|
||
|
||
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 can 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 mock objects and testing support classes, which
|
||
are described in this chapter.
|
||
|
||
|
||
|
||
[[mock-objects]]
|
||
=== Mock Objects
|
||
|
||
Spring includes a number of packages dedicated to mocking:
|
||
|
||
* <<mock-objects-env>>
|
||
* <<mock-objects-jndi>>
|
||
* <<mock-objects-servlet>>
|
||
* <<mock-objects-web-reactive>>
|
||
|
||
|
||
[[mock-objects-env]]
|
||
==== Environment
|
||
|
||
The `org.springframework.mock.env` package contains mock implementations of the
|
||
`Environment` and `PropertySource` abstractions (see
|
||
<<core.adoc#beans-definition-profiles, Bean Definition Profiles>>
|
||
and <<core.adoc#beans-property-source-abstraction, `PropertySource` Abstraction>>).
|
||
`MockEnvironment` and `MockPropertySource` are useful for developing
|
||
out-of-container tests for code that depends on environment-specific properties.
|
||
|
||
|
||
[[mock-objects-jndi]]
|
||
==== JNDI
|
||
|
||
The `org.springframework.mock.jndi` package contains a partial 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 `DataSource` instances get bound to the same JNDI
|
||
names in test code as they do in a Java EE container, you can reuse both application code
|
||
and configuration in testing scenarios without modification.
|
||
|
||
WARNING: The mock JNDI support in the `org.springframework.mock.jndi` package is
|
||
officially deprecated as of Spring Framework 5.2 in favor of complete solutions from third
|
||
parties such as https://github.com/h-thurow/Simple-JNDI[Simple-JNDI].
|
||
|
||
|
||
[[mock-objects-servlet]]
|
||
==== Servlet API
|
||
|
||
The `org.springframework.mock.web` package contains a comprehensive set of Servlet API
|
||
mock objects that are useful for testing web contexts, controllers, and filters. These
|
||
mock objects are targeted at usage with Spring's Web MVC framework and are generally more
|
||
convenient to use than dynamic mock objects (such as http://easymock.org/[EasyMock])
|
||
or alternative Servlet API mock objects (such as http://www.mockobjects.com[MockObjects]).
|
||
|
||
TIP: Since Spring Framework 5.0, the mock objects in `org.springframework.mock.web` are
|
||
based on the Servlet 4.0 API.
|
||
|
||
The Spring MVC Test framework builds on the mock Servlet API objects to provide an
|
||
integration testing framework for Spring MVC. See <<spring-mvc-test-framework>>.
|
||
|
||
|
||
[[mock-objects-web-reactive]]
|
||
==== Spring Web Reactive
|
||
|
||
The `org.springframework.mock.http.server.reactive` package contains mock implementations
|
||
of `ServerHttpRequest` and `ServerHttpResponse` for use in WebFlux applications. The
|
||
`org.springframework.mock.web.server` package contains a mock `ServerWebExchange` that
|
||
depends on those mock request and response objects.
|
||
|
||
Both `MockServerHttpRequest` and `MockServerHttpResponse` extend from the same abstract
|
||
base classes as server-specific implementations and share behavior with them. For
|
||
example, a mock request is immutable once created, but you can use the `mutate()` method
|
||
from `ServerHttpRequest` to create a modified instance.
|
||
|
||
In order for the mock response to properly implement the write contract and return a
|
||
write completion handle (that is, `Mono<Void>`), it by default uses a `Flux` with
|
||
`cache().then()`, which buffers the data and makes it available for assertions in tests.
|
||
Applications can set a custom write function (for example, to test an infinite stream).
|
||
|
||
The <<webtestclient>> builds on the mock request and response to provide support for
|
||
testing WebFlux applications without an HTTP server. The client can also be used for
|
||
end-to-end tests with a running server.
|
||
|
||
|
||
|
||
[[unit-testing-support-classes]]
|
||
=== Unit Testing Support Classes
|
||
|
||
Spring includes a number of classes that can help with unit testing. They fall into two
|
||
categories:
|
||
|
||
* <<unit-testing-utilities>>
|
||
* <<unit-testing-spring-mvc>>
|
||
|
||
|
||
[[unit-testing-utilities]]
|
||
==== General Testing Utilities
|
||
|
||
The `org.springframework.test.util` package contains several general purpose utilities
|
||
for use in unit and integration testing.
|
||
|
||
`ReflectionTestUtils` is a collection of reflection-based utility methods. You can use
|
||
these methods in testing scenarios where you need to change the value of a constant, set
|
||
a non-`public` field, invoke a non-`public` setter method, or invoke a non-`public`
|
||
configuration or lifecycle callback method when testing application code for use cases
|
||
such as the following:
|
||
|
||
* ORM frameworks (such as JPA and Hibernate) that condone `private` or `protected` field
|
||
access as opposed to `public` setter methods for properties in a domain entity.
|
||
* Spring's support for annotations (such as `@Autowired`, `@Inject`, and `@Resource`),
|
||
that provide dependency injection for `private` or `protected` fields, setter methods,
|
||
and configuration methods.
|
||
* Use of annotations such as `@PostConstruct` and `@PreDestroy` for lifecycle callback
|
||
methods.
|
||
|
||
{api-spring-framework}/test/util/AopTestUtils.html[`AopTestUtils`] is a collection of
|
||
AOP-related utility methods. You can use these methods to obtain a reference to the
|
||
underlying target object hidden behind one or more Spring proxies. For example, if you
|
||
have configured a bean as a dynamic mock by using a library such as EasyMock or Mockito,
|
||
and the mock is wrapped in a Spring proxy, you may need direct access to the underlying
|
||
mock to configure expectations on it and perform verifications. For Spring's core AOP
|
||
utilities, see {api-spring-framework}/aop/support/AopUtils.html[`AopUtils`] and
|
||
{api-spring-framework}/aop/framework/AopProxyUtils.html[`AopProxyUtils`].
|
||
|
||
|
||
[[unit-testing-spring-mvc]]
|
||
==== Spring MVC Testing Utilities
|
||
|
||
The `org.springframework.test.web` package contains
|
||
{api-spring-framework}/test/web/ModelAndViewAssert.html[`ModelAndViewAssert`], which you
|
||
can use in combination with JUnit, TestNG, or any other testing framework for unit tests
|
||
that deal with Spring MVC `ModelAndView` objects.
|
||
|
||
.Unit testing Spring MVC Controllers
|
||
TIP: To unit test your Spring MVC `Controller` classes as POJOs, use `ModelAndViewAssert`
|
||
combined with `MockHttpServletRequest`, `MockHttpSession`, and so on from Spring's
|
||
<<mock-objects-servlet, Servlet API mocks>>. For thorough integration testing of your
|
||
Spring MVC and REST `Controller` classes in conjunction with your `WebApplicationContext`
|
||
configuration for Spring MVC, use the
|
||
<<spring-mvc-test-framework, Spring MVC Test Framework>> instead.
|
||
|
||
|
||
|
||
|
||
[[integration-testing]]
|
||
== Integration Testing
|
||
|
||
This section (most of the rest of this chapter) covers integration testing for Spring
|
||
applications. It includes the following topics:
|
||
|
||
* <<integration-testing-overview>>
|
||
* <<integration-testing-goals>>
|
||
* <<integration-testing-support-jdbc>>
|
||
* <<integration-testing-annotations>>
|
||
* <<testcontext-framework>>
|
||
* <<spring-mvc-test-framework>>
|
||
|
||
|
||
|
||
[[integration-testing-overview]]
|
||
=== Overview
|
||
|
||
It is important to be able to perform some integration testing without requiring
|
||
deployment to your application server or connecting to other enterprise infrastructure.
|
||
Doing so lets you test things such as:
|
||
|
||
* The correct wiring of your Spring IoC container contexts.
|
||
* Data access using JDBC or an ORM tool. This can include such things as the correctness
|
||
of SQL statements, Hibernate queries, JPA entity mappings, and so forth.
|
||
|
||
The Spring Framework provides first-class support for integration testing in the
|
||
`spring-test` module. The name of the actual JAR file might include the release version
|
||
and might also be in the long `org.springframework.test` form, depending on where you get
|
||
it from (see the <<core.adoc#dependency-management, section on Dependency Management>>
|
||
for an explanation). This library includes the `org.springframework.test` 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 Selenium tests or
|
||
remote tests that rely on deployment to an application server.
|
||
|
||
Unit and integration testing support is provided in the form of the annotation-driven
|
||
<<testcontext-framework, Spring TestContext Framework>>. The TestContext framework is
|
||
agnostic of the actual testing framework in use, which allows instrumentation of tests
|
||
in various environments, including JUnit, TestNG, and others.
|
||
|
||
|
||
|
||
[[integration-testing-goals]]
|
||
=== Goals of Integration Testing
|
||
|
||
Spring's integration testing support has the following primary goals:
|
||
|
||
* To manage <<testing-ctx-management, Spring IoC container caching>> between tests.
|
||
* To provide <<testing-fixture-di, Dependency Injection of test fixture instances>>.
|
||
* To provide <<testing-tx, transaction management>> appropriate to integration testing.
|
||
* To supply <<testing-support-classes, Spring-specific base classes>> that assist
|
||
developers in writing integration tests.
|
||
|
||
The next few sections describe each goal and provide links to implementation and
|
||
configuration details.
|
||
|
||
|
||
[[testing-ctx-management]]
|
||
==== Context Management and Caching
|
||
|
||
The Spring TestContext Framework provides consistent loading of Spring
|
||
`ApplicationContext` instances and `WebApplicationContext` instances as well as 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 reduce developer productivity.
|
||
|
||
Test classes typically declare either an array of resource locations for XML or Groovy
|
||
configuration metadata -- often in the classpath -- or an array of component classes that
|
||
is used to configure the application. These locations or classes are the same as or
|
||
similar to those specified in `web.xml` or other configuration files for production
|
||
deployments.
|
||
|
||
By default, once loaded, the configured `ApplicationContext` 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 "`test suite`" means all tests run in the same
|
||
JVM -- for example, all tests run from an Ant, Maven, or Gradle build for a given project
|
||
or module. In the unlikely case that a test corrupts the application context and requires
|
||
reloading (for example, by modifying a bean definition or the state of an application
|
||
object) the TestContext framework can be configured to reload the configuration and
|
||
rebuild the application context before executing the next test.
|
||
|
||
See <<testcontext-ctx-management>> and <<testcontext-ctx-management-caching>> with the
|
||
TestContext framework.
|
||
|
||
|
||
[[testing-fixture-di]]
|
||
==== Dependency Injection of Test Fixtures
|
||
|
||
When the TestContext framework loads your application context, it can optionally
|
||
configure instances of your test classes by using Dependency Injection. This provides a
|
||
convenient mechanism for setting up test fixtures by using preconfigured beans from your
|
||
application context. A strong benefit here is that you can reuse application contexts
|
||
across various testing scenarios (for example, for configuring Spring-managed object
|
||
graphs, transactional proxies, `DataSource` instances, and others), thus avoiding the
|
||
need to duplicate complex test fixture setup for individual test cases.
|
||
|
||
As an example, consider a scenario where we have a class (`HibernateTitleRepository`)
|
||
that implements data access logic for a `Title` domain entity. We want to write
|
||
integration tests that test the following areas:
|
||
|
||
* The Spring configuration: Basically, is everything related to the configuration of the
|
||
`HibernateTitleRepository` bean correct and present?
|
||
* The Hibernate mapping file configuration: Is everything mapped correctly and are the
|
||
correct lazy-loading settings in place?
|
||
* The logic of the `HibernateTitleRepository`: Does the configured instance of this class
|
||
perform as anticipated?
|
||
|
||
See dependency injection of test fixtures with the
|
||
<<testcontext-fixture-di, TestContext framework>>.
|
||
|
||
|
||
[[testing-tx]]
|
||
==== Transaction Management
|
||
|
||
One common issue in tests that access a real database is their effect on the state of the
|
||
persistence store. Even when you use 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 of a transaction.
|
||
|
||
The TestContext framework addresses this issue. By default, the framework creates and
|
||
rolls back a transaction for each test. You can write code that can assume the existence
|
||
of a transaction. If you call transactionally proxied objects in your tests, they behave
|
||
correctly, according to their configured transactional semantics. In addition, if a test
|
||
method deletes the contents of selected tables while running within the transaction
|
||
managed for the test, the transaction rolls back by default, and the database returns to
|
||
its state prior to execution of the test. Transactional support is provided to a test by
|
||
using a `PlatformTransactionManager` bean defined in the test's application context.
|
||
|
||
If you want a transaction to commit (unusual, but occasionally useful when you want a
|
||
particular test to populate or modify the database), you can tell the TestContext
|
||
framework to cause the transaction to commit instead of roll back by using the
|
||
<<integration-testing-annotations, `@Commit`>> annotation.
|
||
|
||
See transaction management with the <<testcontext-tx, TestContext framework>>.
|
||
|
||
|
||
[[testing-support-classes]]
|
||
==== Support Classes for Integration Testing
|
||
|
||
The Spring TestContext Framework provides several `abstract` 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 let you access:
|
||
|
||
* The `ApplicationContext`, for performing explicit bean lookups or testing the state of
|
||
the context as a whole.
|
||
* A `JdbcTemplate`, for executing SQL statements to query the database. You can use such
|
||
queries to confirm database state both before and after execution of database-related
|
||
application code, and Spring ensures that such queries run in the scope of the same
|
||
transaction as the application code. When used in conjunction with an ORM tool, be sure
|
||
to avoid <<testcontext-tx-false-positives, false positives>>.
|
||
|
||
In addition, you may want to create your own custom, application-wide superclass with
|
||
instance variables and methods specific to your project.
|
||
|
||
See support classes for the <<testcontext-support-classes, TestContext framework>>.
|
||
|
||
|
||
|
||
[[integration-testing-support-jdbc]]
|
||
=== JDBC Testing Support
|
||
|
||
The `org.springframework.test.jdbc` package contains `JdbcTestUtils`, which is a
|
||
collection of JDBC-related utility functions intended to simplify standard database
|
||
testing scenarios. Specifically, `JdbcTestUtils` provides the following static utility
|
||
methods.
|
||
|
||
* `countRowsInTable(..)`: Counts the number of rows in the given table.
|
||
* `countRowsInTableWhere(..)`: Counts the number of rows in the given table by using the
|
||
provided `WHERE` clause.
|
||
* `deleteFromTables(..)`: Deletes all rows from the specified tables.
|
||
* `deleteFromTableWhere(..)`: Deletes rows from the given table by using the provided
|
||
`WHERE` clause.
|
||
* `dropTables(..)`: Drops the specified tables.
|
||
|
||
[TIP]
|
||
====
|
||
<<testcontext-support-classes-junit4, `AbstractTransactionalJUnit4SpringContextTests`>>
|
||
and <<testcontext-support-classes-testng, `AbstractTransactionalTestNGSpringContextTests`>>
|
||
provide convenience methods that delegate to the aforementioned methods in
|
||
`JdbcTestUtils`.
|
||
|
||
The `spring-jdbc` module provides support for configuring and launching an embedded
|
||
database, which you can use in integration tests that interact with a database.
|
||
For details, see <<data-access.adoc#jdbc-embedded-database-support, Embedded Database
|
||
Support>> and <<data-access.adoc#jdbc-embedded-database-dao-testing, Testing Data Access
|
||
Logic with an Embedded Database>>.
|
||
====
|
||
|
||
|
||
|
||
[[integration-testing-annotations]]
|
||
=== Annotations
|
||
|
||
This section covers annotations that you can use when you test Spring applications.
|
||
It includes the following topics:
|
||
|
||
* <<integration-testing-annotations-spring>>
|
||
* <<integration-testing-annotations-standard>>
|
||
* <<integration-testing-annotations-junit4>>
|
||
* <<integration-testing-annotations-junit-jupiter>>
|
||
* <<integration-testing-annotations-meta>>
|
||
|
||
|
||
[[integration-testing-annotations-spring]]
|
||
==== Spring Testing Annotations
|
||
|
||
The Spring Framework provides the following set of Spring-specific annotations that you
|
||
can use in your unit and integration tests in conjunction with the TestContext framework.
|
||
See the corresponding javadoc for further information, including default attribute
|
||
values, attribute aliases, and other details.
|
||
|
||
Spring's testing annotations include the following:
|
||
|
||
* <<spring-testing-annotation-bootstrapwith>>
|
||
* <<spring-testing-annotation-contextconfiguration>>
|
||
* <<spring-testing-annotation-webappconfiguration>>
|
||
* <<spring-testing-annotation-contexthierarchy>>
|
||
* <<spring-testing-annotation-activeprofiles>>
|
||
* <<spring-testing-annotation-testpropertysource>>
|
||
* <<spring-testing-annotation-dynamicpropertysource>>
|
||
* <<spring-testing-annotation-dirtiescontext>>
|
||
* <<spring-testing-annotation-testexecutionlisteners>>
|
||
* <<spring-testing-annotation-commit>>
|
||
* <<spring-testing-annotation-rollback>>
|
||
* <<spring-testing-annotation-beforetransaction>>
|
||
* <<spring-testing-annotation-aftertransaction>>
|
||
* <<spring-testing-annotation-sql>>
|
||
* <<spring-testing-annotation-sqlconfig>>
|
||
* <<spring-testing-annotation-sqlmergemode>>
|
||
* <<spring-testing-annotation-sqlgroup>>
|
||
|
||
[[spring-testing-annotation-bootstrapwith]]
|
||
===== `@BootstrapWith`
|
||
|
||
`@BootstrapWith` is a class-level annotation that you can use to configure how the Spring
|
||
TestContext Framework is bootstrapped. Specifically, you can use `@BootstrapWith` to
|
||
specify a custom `TestContextBootstrapper`. See the section on
|
||
<<testcontext-bootstrapping, bootstrapping the TestContext framework>> for further details.
|
||
|
||
[[spring-testing-annotation-contextconfiguration]]
|
||
===== `@ContextConfiguration`
|
||
|
||
`@ContextConfiguration` defines class-level metadata that is used to determine how to
|
||
load and configure an `ApplicationContext` for integration tests. Specifically,
|
||
`@ContextConfiguration` declares the application context resource `locations` or the
|
||
component `classes` used to load the context.
|
||
|
||
Resource locations are typically XML configuration files or Groovy scripts located in the
|
||
classpath, while component classes are typically `@Configuration` classes. However,
|
||
resource locations can also refer to files and scripts in the file system, and component
|
||
classes can be `@Component` classes, `@Service` classes, and so on. See
|
||
<<testcontext-ctx-management-javaconfig-component-classes>> for further details.
|
||
|
||
The following example shows a `@ContextConfiguration` annotation that refers to an XML
|
||
file:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ContextConfiguration("/test-config.xml") // <1>
|
||
class XmlApplicationContextTests {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Referring to an XML file.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ContextConfiguration("/test-config.xml") // <1>
|
||
class XmlApplicationContextTests {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Referring to an XML file.
|
||
|
||
|
||
The following example shows a `@ContextConfiguration` annotation that refers to a class:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ContextConfiguration(classes = TestConfig.class) // <1>
|
||
class ConfigClassApplicationContextTests {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Referring to a class.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ContextConfiguration(classes = [TestConfig::class]) // <1>
|
||
class ConfigClassApplicationContextTests {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Referring to a class.
|
||
|
||
|
||
As an alternative or in addition to declaring resource locations or component classes,
|
||
you can use `@ContextConfiguration` to declare `ApplicationContextInitializer` classes.
|
||
The following example shows such a case:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ContextConfiguration(initializers = CustomContextIntializer.class) // <1>
|
||
class ContextInitializerTests {
|
||
// class body...
|
||
}
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ContextConfiguration(initializers = [CustomContextIntializer::class]) // <1>
|
||
class ContextInitializerTests {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Declaring an initializer class.
|
||
|
||
|
||
You can optionally use `@ContextConfiguration` to declare the `ContextLoader` strategy as
|
||
well. Note, however, that you typically do not need to explicitly configure the loader,
|
||
since the default loader supports `initializers` and either resource `locations` or
|
||
component `classes`.
|
||
|
||
The following example uses both a location and a loader:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ContextConfiguration(locations = "/test-context.xml", loader = CustomContextLoader.class) // <1>
|
||
class CustomLoaderXmlApplicationContextTests {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Configuring both a location and a custom loader.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ContextConfiguration("/test-context.xml", loader = CustomContextLoader::class) // <1>
|
||
class CustomLoaderXmlApplicationContextTests {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Configuring both a location and a custom loader.
|
||
|
||
|
||
NOTE: `@ContextConfiguration` provides support for inheriting resource locations or
|
||
configuration classes as well as context initializers that are declared by superclasses.
|
||
|
||
See <<testcontext-ctx-management>> and the `@ContextConfiguration` javadocs for further
|
||
details.
|
||
|
||
[[spring-testing-annotation-webappconfiguration]]
|
||
===== `@WebAppConfiguration`
|
||
|
||
`@WebAppConfiguration` is a class-level annotation that you can use to declare that the
|
||
`ApplicationContext` loaded for an integration test should be a `WebApplicationContext`.
|
||
The mere presence of `@WebAppConfiguration` on a test class ensures that a
|
||
`WebApplicationContext` is loaded for the test, using the default value of
|
||
`"file:src/main/webapp"` for the path to the root of the web application (that is, the
|
||
resource base path). The resource base path is used behind the scenes to create a
|
||
`MockServletContext`, which serves as the `ServletContext` for the test's
|
||
`WebApplicationContext`.
|
||
|
||
The following example shows how to use the `@WebAppConfiguration` annotation:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ContextConfiguration
|
||
@WebAppConfiguration // <1>
|
||
class WebAppTests {
|
||
// class body...
|
||
}
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ContextConfiguration
|
||
@WebAppConfiguration // <1>
|
||
class WebAppTests {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> The `@WebAppConfiguration` annotation.
|
||
|
||
|
||
To override the default, you can specify a different base resource path by using the
|
||
implicit `value` attribute. Both `classpath:` and `file:` resource prefixes are
|
||
supported. If no resource prefix is supplied, the path is assumed to be a file system
|
||
resource. The following example shows how to specify a classpath resource:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ContextConfiguration
|
||
@WebAppConfiguration("classpath:test-web-resources") // <1>
|
||
class WebAppTests {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Specifying a classpath resource.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ContextConfiguration
|
||
@WebAppConfiguration("classpath:test-web-resources") // <1>
|
||
class WebAppTests {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Specifying a classpath resource.
|
||
|
||
|
||
Note that `@WebAppConfiguration` must be used in conjunction with
|
||
`@ContextConfiguration`, either within a single test class or within a test class
|
||
hierarchy. See the
|
||
{api-spring-framework}/test/context/web/WebAppConfiguration.html[`@WebAppConfiguration`]
|
||
javadoc for further details.
|
||
|
||
[[spring-testing-annotation-contexthierarchy]]
|
||
===== `@ContextHierarchy`
|
||
|
||
`@ContextHierarchy` is a class-level annotation that is used to define a hierarchy of
|
||
`ApplicationContext` instances for integration tests. `@ContextHierarchy` should be
|
||
declared with a list of one or more `@ContextConfiguration` instances, each of which
|
||
defines a level in the context hierarchy. The following examples demonstrate the use of
|
||
`@ContextHierarchy` within a single test class (`@ContextHierarchy` can also be used
|
||
within a test class hierarchy):
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ContextHierarchy({
|
||
@ContextConfiguration("/parent-config.xml"),
|
||
@ContextConfiguration("/child-config.xml")
|
||
})
|
||
class ContextHierarchyTests {
|
||
// class body...
|
||
}
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ContextHierarchy(
|
||
ContextConfiguration("/parent-config.xml"),
|
||
ContextConfiguration("/child-config.xml"))
|
||
class ContextHierarchyTests {
|
||
// class body...
|
||
}
|
||
----
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@WebAppConfiguration
|
||
@ContextHierarchy({
|
||
@ContextConfiguration(classes = AppConfig.class),
|
||
@ContextConfiguration(classes = WebConfig.class)
|
||
})
|
||
class WebIntegrationTests {
|
||
// class body...
|
||
}
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@WebAppConfiguration
|
||
@ContextHierarchy(
|
||
ContextConfiguration(classes = [AppConfig::class]),
|
||
ContextConfiguration(classes = [WebConfig::class]))
|
||
class WebIntegrationTests {
|
||
// class body...
|
||
}
|
||
----
|
||
|
||
If you need to merge or override the configuration for a given level of the context
|
||
hierarchy within a test class hierarchy, you must explicitly name that level by supplying
|
||
the same value to the `name` attribute in `@ContextConfiguration` at each corresponding
|
||
level in the class hierarchy. See <<testcontext-ctx-management-ctx-hierarchies>> and the
|
||
{api-spring-framework}/test/context/ContextHierarchy.html[`@ContextHierarchy`] javadoc
|
||
for further examples.
|
||
|
||
[[spring-testing-annotation-activeprofiles]]
|
||
===== `@ActiveProfiles`
|
||
|
||
`@ActiveProfiles` is a class-level annotation that is used to declare which bean
|
||
definition profiles should be active when loading an `ApplicationContext` for an
|
||
integration test.
|
||
|
||
The following example indicates that the `dev` profile should be active:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ContextConfiguration
|
||
@ActiveProfiles("dev") // <1>
|
||
class DeveloperTests {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Indicate that the `dev` profile should be active.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ContextConfiguration
|
||
@ActiveProfiles("dev") // <1>
|
||
class DeveloperTests {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Indicate that the `dev` profile should be active.
|
||
|
||
|
||
The following example indicates that both the `dev` and the `integration` profiles should
|
||
be active:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ContextConfiguration
|
||
@ActiveProfiles({"dev", "integration"}) // <1>
|
||
class DeveloperIntegrationTests {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Indicate that the `dev` and `integration` profiles should be active.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ContextConfiguration
|
||
@ActiveProfiles(["dev", "integration"]) // <1>
|
||
class DeveloperIntegrationTests {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Indicate that the `dev` and `integration` profiles should be active.
|
||
|
||
|
||
NOTE: `@ActiveProfiles` provides support for inheriting active bean definition profiles
|
||
declared by superclasses by default. You can also resolve active bean definition profiles
|
||
programmatically by implementing a custom
|
||
<<testcontext-ctx-management-env-profiles-ActiveProfilesResolver, `ActiveProfilesResolver`>>
|
||
and registering it by using the `resolver` attribute of `@ActiveProfiles`.
|
||
|
||
See <<testcontext-ctx-management-env-profiles>> and the
|
||
{api-spring-framework}/test/context/ActiveProfiles.html[`@ActiveProfiles`] javadoc for
|
||
examples and further details.
|
||
|
||
[[spring-testing-annotation-testpropertysource]]
|
||
===== `@TestPropertySource`
|
||
|
||
`@TestPropertySource` is a class-level annotation that you can use to configure the
|
||
locations of properties files and inlined properties to be added to the set of
|
||
`PropertySources` in the `Environment` for an `ApplicationContext` loaded for an
|
||
integration test.
|
||
|
||
The following example demonstrates how to declare a properties file from the classpath:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ContextConfiguration
|
||
@TestPropertySource("/test.properties") // <1>
|
||
class MyIntegrationTests {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Get properties from `test.properties` in the root of the classpath.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ContextConfiguration
|
||
@TestPropertySource("/test.properties") // <1>
|
||
class MyIntegrationTests {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Get properties from `test.properties` in the root of the classpath.
|
||
|
||
|
||
The following example demonstrates how to declare inlined properties:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ContextConfiguration
|
||
@TestPropertySource(properties = { "timezone = GMT", "port: 4242" }) // <1>
|
||
class MyIntegrationTests {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Declare `timezone` and `port` properties.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ContextConfiguration
|
||
@TestPropertySource(properties = ["timezone = GMT", "port: 4242"]) // <1>
|
||
class MyIntegrationTests {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Declare `timezone` and `port` properties.
|
||
|
||
See <<testcontext-ctx-management-property-sources>> for examples and further details.
|
||
|
||
[[spring-testing-annotation-dynamicpropertysource]]
|
||
===== `@DynamicPropertySource`
|
||
|
||
`@DynamicPropertySource` is a method-level annotation that you can use to register
|
||
_dynamic_ properties to be added to the set of `PropertySources` in the `Environment` for
|
||
an `ApplicationContext` loaded for an integration test. Dynamic properties are useful
|
||
when you do not know the value of the properties upfront – for example, if the properties
|
||
are managed by an external resource such as for a container managed by the
|
||
https://www.testcontainers.org/[Testcontainers] project.
|
||
|
||
The following example demonstrates how to register a dynamic property:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ContextConfiguration
|
||
class MyIntegrationTests {
|
||
|
||
static MyExternalServer server = // ...
|
||
|
||
@DynamicPropertySource // <1>
|
||
static void dynamicProperties(DynamicPropertyRegistry registry) { // <2>
|
||
registry.add("server.port", server::getPort); // <3>
|
||
}
|
||
|
||
// tests ...
|
||
}
|
||
----
|
||
<1> Annotate a `static` method with `@DynamicPropertySource`.
|
||
<2> Accept a `DynamicPropertyRegistry` as an argument.
|
||
<3> Register a dynamic `server.port` property to be retrieved lazily from the server.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ContextConfiguration
|
||
class MyIntegrationTests {
|
||
|
||
companion object {
|
||
|
||
@JvmStatic
|
||
val server: MyExternalServer = // ...
|
||
|
||
@DynamicPropertySource // <1>
|
||
@JvmStatic
|
||
fun dynamicProperties(registry: DynamicPropertyRegistry) { // <2>
|
||
registry.add("server.port", server::getPort) // <3>
|
||
}
|
||
}
|
||
|
||
// tests ...
|
||
}
|
||
----
|
||
<1> Annotate a `static` method with `@DynamicPropertySource`.
|
||
<2> Accept a `DynamicPropertyRegistry` as an argument.
|
||
<3> Register a dynamic `server.port` property to be retrieved lazily from the server.
|
||
|
||
See <<testcontext-ctx-management-dynamic-property-sources>> for further details.
|
||
|
||
[[spring-testing-annotation-dirtiescontext]]
|
||
===== `@DirtiesContext`
|
||
|
||
`@DirtiesContext` indicates that the underlying Spring `ApplicationContext` has been
|
||
dirtied during the execution of a test (that is, the test modified or corrupted it in
|
||
some manner -- for example, by changing the state of a singleton bean) and should be
|
||
closed. When an application context is marked as dirty, it is removed from the testing
|
||
framework's cache and closed. As a consequence, the underlying Spring container is
|
||
rebuilt for any subsequent test that requires a context with the same configuration
|
||
metadata.
|
||
|
||
You can use `@DirtiesContext` as both a class-level and a method-level annotation within
|
||
the same class or class hierarchy. In such scenarios, the `ApplicationContext` is marked
|
||
as dirty before or after any such annotated method as well as before or after the current
|
||
test class, depending on the configured `methodMode` and `classMode`.
|
||
|
||
The following examples explain when the context would be dirtied for various
|
||
configuration scenarios:
|
||
|
||
* Before the current test class, when declared on a class with class mode set to
|
||
`BEFORE_CLASS`.
|
||
+
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@DirtiesContext(classMode = BEFORE_CLASS) // <1>
|
||
class FreshContextTests {
|
||
// some tests that require a new Spring container
|
||
}
|
||
----
|
||
<1> Dirty the context before the current test class.
|
||
+
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@DirtiesContext(classMode = BEFORE_CLASS) // <1>
|
||
class FreshContextTests {
|
||
// some tests that require a new Spring container
|
||
}
|
||
----
|
||
<1> Dirty the context before the current test class.
|
||
|
||
* After the current test class, when declared on a class with class mode set to
|
||
`AFTER_CLASS` (i.e., the default class mode).
|
||
+
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@DirtiesContext // <1>
|
||
class ContextDirtyingTests {
|
||
// some tests that result in the Spring container being dirtied
|
||
}
|
||
----
|
||
<1> Dirty the context after the current test class.
|
||
+
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@DirtiesContext // <1>
|
||
class ContextDirtyingTests {
|
||
// some tests that result in the Spring container being dirtied
|
||
}
|
||
----
|
||
<1> Dirty the context after the current test class.
|
||
|
||
|
||
* Before each test method in the current test class, when declared on a class with class
|
||
mode set to `BEFORE_EACH_TEST_METHOD.`
|
||
+
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@DirtiesContext(classMode = BEFORE_EACH_TEST_METHOD) // <1>
|
||
class FreshContextTests {
|
||
// some tests that require a new Spring container
|
||
}
|
||
----
|
||
<1> Dirty the context before each test method.
|
||
+
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@DirtiesContext(classMode = BEFORE_EACH_TEST_METHOD) // <1>
|
||
class FreshContextTests {
|
||
// some tests that require a new Spring container
|
||
}
|
||
----
|
||
<1> Dirty the context before each test method.
|
||
|
||
|
||
* After each test method in the current test class, when declared on a class with class
|
||
mode set to `AFTER_EACH_TEST_METHOD.`
|
||
+
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@DirtiesContext(classMode = AFTER_EACH_TEST_METHOD) // <1>
|
||
class ContextDirtyingTests {
|
||
// some tests that result in the Spring container being dirtied
|
||
}
|
||
----
|
||
<1> Dirty the context after each test method.
|
||
+
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@DirtiesContext(classMode = AFTER_EACH_TEST_METHOD) // <1>
|
||
class ContextDirtyingTests {
|
||
// some tests that result in the Spring container being dirtied
|
||
}
|
||
----
|
||
<1> Dirty the context after each test method.
|
||
|
||
|
||
* Before the current test, when declared on a method with the method mode set to
|
||
`BEFORE_METHOD`.
|
||
+
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@DirtiesContext(methodMode = BEFORE_METHOD) // <1>
|
||
@Test
|
||
void testProcessWhichRequiresFreshAppCtx() {
|
||
// some logic that requires a new Spring container
|
||
}
|
||
----
|
||
<1> Dirty the context before the current test method.
|
||
+
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@DirtiesContext(methodMode = BEFORE_METHOD) // <1>
|
||
@Test
|
||
fun testProcessWhichRequiresFreshAppCtx() {
|
||
// some logic that requires a new Spring container
|
||
}
|
||
----
|
||
<1> Dirty the context before the current test method.
|
||
|
||
* After the current test, when declared on a method with the method mode set to
|
||
`AFTER_METHOD` (i.e., the default method mode).
|
||
+
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@DirtiesContext // <1>
|
||
@Test
|
||
void testProcessWhichDirtiesAppCtx() {
|
||
// some logic that results in the Spring container being dirtied
|
||
}
|
||
----
|
||
<1> Dirty the context after the current test method.
|
||
+
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@DirtiesContext // <1>
|
||
@Test
|
||
fun testProcessWhichDirtiesAppCtx() {
|
||
// some logic that results in the Spring container being dirtied
|
||
}
|
||
----
|
||
<1> Dirty the context after the current test method.
|
||
|
||
|
||
If you use `@DirtiesContext` in a test whose context is configured as part of a context
|
||
hierarchy with `@ContextHierarchy`, you can use the `hierarchyMode` flag to control how
|
||
the context cache is cleared. By default, an exhaustive algorithm is used to clear the
|
||
context cache, including not only the current level but also all other context
|
||
hierarchies that share an ancestor context common to the current test. All
|
||
`ApplicationContext` instances that reside in a sub-hierarchy of the common ancestor
|
||
context are removed from the context cache and closed. If the exhaustive algorithm is
|
||
overkill for a particular use case, you can specify the simpler current level algorithm,
|
||
as the following example shows.
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ContextHierarchy({
|
||
@ContextConfiguration("/parent-config.xml"),
|
||
@ContextConfiguration("/child-config.xml")
|
||
})
|
||
class BaseTests {
|
||
// class body...
|
||
}
|
||
|
||
class ExtendedTests extends BaseTests {
|
||
|
||
@Test
|
||
@DirtiesContext(hierarchyMode = CURRENT_LEVEL) // <1>
|
||
void test() {
|
||
// some logic that results in the child context being dirtied
|
||
}
|
||
}
|
||
----
|
||
<1> Use the current-level algorithm.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ContextHierarchy(
|
||
ContextConfiguration("/parent-config.xml"),
|
||
ContextConfiguration("/child-config.xml"))
|
||
open class BaseTests {
|
||
// class body...
|
||
}
|
||
|
||
class ExtendedTests : BaseTests() {
|
||
|
||
@Test
|
||
@DirtiesContext(hierarchyMode = CURRENT_LEVEL) // <1>
|
||
fun test() {
|
||
// some logic that results in the child context being dirtied
|
||
}
|
||
}
|
||
----
|
||
<1> Use the current-level algorithm.
|
||
|
||
|
||
For further details regarding the `EXHAUSTIVE` and `CURRENT_LEVEL` algorithms, see the
|
||
{api-spring-framework}/test/annotation/DirtiesContext.HierarchyMode.html[`DirtiesContext.HierarchyMode`]
|
||
javadoc.
|
||
|
||
[[spring-testing-annotation-testexecutionlisteners]]
|
||
===== `@TestExecutionListeners`
|
||
|
||
`@TestExecutionListeners` defines class-level metadata for configuring the
|
||
`TestExecutionListener` implementations that should be registered with the
|
||
`TestContextManager`. Typically, `@TestExecutionListeners` is used in conjunction with
|
||
`@ContextConfiguration`.
|
||
|
||
The following example shows how to register two `TestExecutionListener` implementations:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ContextConfiguration
|
||
@TestExecutionListeners({CustomTestExecutionListener.class, AnotherTestExecutionListener.class}) // <1>
|
||
class CustomTestExecutionListenerTests {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Register two `TestExecutionListener` implementations.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ContextConfiguration
|
||
@TestExecutionListeners(CustomTestExecutionListener::class, AnotherTestExecutionListener::class) // <1>
|
||
class CustomTestExecutionListenerTests {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Register two `TestExecutionListener` implementations.
|
||
|
||
|
||
By default, `@TestExecutionListeners` supports inherited listeners. See the
|
||
{api-spring-framework}/test/context/TestExecutionListeners.html[javadoc]
|
||
for an example and further details.
|
||
|
||
[[spring-testing-annotation-commit]]
|
||
===== `@Commit`
|
||
|
||
`@Commit` indicates that the transaction for a transactional test method should be
|
||
committed after the test method has completed. You can use `@Commit` as a direct
|
||
replacement for `@Rollback(false)` to more explicitly convey the intent of the code.
|
||
Analogous to `@Rollback`, `@Commit` can also be declared as a class-level or method-level
|
||
annotation.
|
||
|
||
The following example shows how to use the `@Commit` annotation:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@Commit // <1>
|
||
@Test
|
||
void testProcessWithoutRollback() {
|
||
// ...
|
||
}
|
||
----
|
||
<1> Commit the result of the test to the database.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@Commit // <1>
|
||
@Test
|
||
fun testProcessWithoutRollback() {
|
||
// ...
|
||
}
|
||
----
|
||
<1> Commit the result of the test to the database.
|
||
|
||
|
||
[[spring-testing-annotation-rollback]]
|
||
===== `@Rollback`
|
||
|
||
`@Rollback` indicates whether the transaction for a transactional test method should be
|
||
rolled back after the test method has completed. If `true`, the transaction is rolled
|
||
back. Otherwise, the transaction is committed (see also
|
||
<<spring-testing-annotation-commit>>). Rollback for integration tests in the Spring
|
||
TestContext Framework defaults to `true` even if `@Rollback` is not explicitly declared.
|
||
|
||
When declared as a class-level annotation, `@Rollback` defines the default rollback
|
||
semantics for all test methods within the test class hierarchy. When declared as a
|
||
method-level annotation, `@Rollback` defines rollback semantics for the specific test
|
||
method, potentially overriding class-level `@Rollback` or `@Commit` semantics.
|
||
|
||
The following example causes a test method's result to not be rolled back (that is, the
|
||
result is committed to the database):
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@Rollback(false) // <1>
|
||
@Test
|
||
void testProcessWithoutRollback() {
|
||
// ...
|
||
}
|
||
----
|
||
<1> Do not roll back the result.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@Rollback(false) // <1>
|
||
@Test
|
||
fun testProcessWithoutRollback() {
|
||
// ...
|
||
}
|
||
----
|
||
<1> Do not roll back the result.
|
||
|
||
|
||
[[spring-testing-annotation-beforetransaction]]
|
||
===== `@BeforeTransaction`
|
||
|
||
`@BeforeTransaction` indicates that the annotated `void` method should be run before a
|
||
transaction is started, for test methods that have been configured to run within a
|
||
transaction by using Spring's `@Transactional` annotation. `@BeforeTransaction` methods
|
||
are not required to be `public` and may be declared on Java 8-based interface default
|
||
methods.
|
||
|
||
The following example shows how to use the `@BeforeTransaction` annotation:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@BeforeTransaction // <1>
|
||
void beforeTransaction() {
|
||
// logic to be run before a transaction is started
|
||
}
|
||
----
|
||
<1> Run this method before a transaction.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@BeforeTransaction // <1>
|
||
fun beforeTransaction() {
|
||
// logic to be run before a transaction is started
|
||
}
|
||
----
|
||
<1> Run this method before a transaction.
|
||
|
||
|
||
[[spring-testing-annotation-aftertransaction]]
|
||
===== `@AfterTransaction`
|
||
|
||
`@AfterTransaction` indicates that the annotated `void` method should be run after a
|
||
transaction is ended, for test methods that have been configured to run within a
|
||
transaction by using Spring's `@Transactional` annotation. `@AfterTransaction` methods
|
||
are not required to be `public` and may be declared on Java 8-based interface default
|
||
methods.
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@AfterTransaction // <1>
|
||
void afterTransaction() {
|
||
// logic to be run after a transaction has ended
|
||
}
|
||
----
|
||
<1> Run this method after a transaction.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@AfterTransaction // <1>
|
||
fun afterTransaction() {
|
||
// logic to be run after a transaction has ended
|
||
}
|
||
----
|
||
<1> Run this method after a transaction.
|
||
|
||
|
||
[[spring-testing-annotation-sql]]
|
||
===== `@Sql`
|
||
|
||
`@Sql` is used to annotate a test class or test method to configure SQL scripts to be run
|
||
against a given database during integration tests. The following example shows how to use
|
||
it:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@Test
|
||
@Sql({"/test-schema.sql", "/test-user-data.sql"}) // <1>
|
||
void userTest() {
|
||
// run code that relies on the test schema and test data
|
||
}
|
||
----
|
||
<1> Run two scripts for this test.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@Test
|
||
@Sql("/test-schema.sql", "/test-user-data.sql") // <1>
|
||
fun userTest() {
|
||
// run code that relies on the test schema and test data
|
||
}
|
||
----
|
||
<1> Run two scripts for this test.
|
||
|
||
See <<testcontext-executing-sql-declaratively>> for further details.
|
||
|
||
|
||
[[spring-testing-annotation-sqlconfig]]
|
||
===== `@SqlConfig`
|
||
|
||
`@SqlConfig` defines metadata that is used to determine how to parse and run SQL scripts
|
||
configured with the `@Sql` annotation. The following example shows how to use it:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@Test
|
||
@Sql(
|
||
scripts = "/test-user-data.sql",
|
||
config = @SqlConfig(commentPrefix = "`", separator = "@@") // <1>
|
||
)
|
||
void userTest() {
|
||
// run code that relies on the test data
|
||
}
|
||
----
|
||
<1> Set the comment prefix and the separator in SQL scripts.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@Test
|
||
@Sql("/test-user-data.sql", config = SqlConfig(commentPrefix = "`", separator = "@@")) // <1>
|
||
fun userTest() {
|
||
// run code that relies on the test data
|
||
}
|
||
----
|
||
<1> Set the comment prefix and the separator in SQL scripts.
|
||
|
||
[[spring-testing-annotation-sqlmergemode]]
|
||
===== `@SqlMergeMode`
|
||
|
||
`@SqlMergeMode` is used to annotate a test class or test method to configure whether
|
||
method-level `@Sql` declarations are merged with class-level `@Sql` declarations. If
|
||
`@SqlMergeMode` is not declared on a test class or test method, the `OVERRIDE` merge mode
|
||
will be used by default. With the `OVERRIDE` mode, method-level `@Sql` declarations will
|
||
effectively override class-level `@Sql` declarations.
|
||
|
||
Note that a method-level `@SqlMergeMode` declaration overrides a class-level declaration.
|
||
|
||
The following example shows how to use `@SqlMergeMode` at the class level.
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@SpringJUnitConfig(TestConfig.class)
|
||
@Sql("/test-schema.sql")
|
||
@SqlMergeMode(MERGE) // <1>
|
||
class UserTests {
|
||
|
||
@Test
|
||
@Sql("/user-test-data-001.sql")
|
||
void standardUserProfile() {
|
||
// run code that relies on test data set 001
|
||
}
|
||
}
|
||
----
|
||
<1> Set the `@Sql` merge mode to `MERGE` for all test methods in the class.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@SpringJUnitConfig(TestConfig::class)
|
||
@Sql("/test-schema.sql")
|
||
@SqlMergeMode(MERGE) // <1>
|
||
class UserTests {
|
||
|
||
@Test
|
||
@Sql("/user-test-data-001.sql")
|
||
fun standardUserProfile() {
|
||
// run code that relies on test data set 001
|
||
}
|
||
}
|
||
----
|
||
<1> Set the `@Sql` merge mode to `MERGE` for all test methods in the class.
|
||
|
||
The following example shows how to use `@SqlMergeMode` at the method level.
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@SpringJUnitConfig(TestConfig.class)
|
||
@Sql("/test-schema.sql")
|
||
class UserTests {
|
||
|
||
@Test
|
||
@Sql("/user-test-data-001.sql")
|
||
@SqlMergeMode(MERGE) // <1>
|
||
void standardUserProfile() {
|
||
// run code that relies on test data set 001
|
||
}
|
||
}
|
||
----
|
||
<1> Set the `@Sql` merge mode to `MERGE` for a specific test method.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@SpringJUnitConfig(TestConfig::class)
|
||
@Sql("/test-schema.sql")
|
||
class UserTests {
|
||
|
||
@Test
|
||
@Sql("/user-test-data-001.sql")
|
||
@SqlMergeMode(MERGE) // <1>
|
||
fun standardUserProfile() {
|
||
// run code that relies on test data set 001
|
||
}
|
||
}
|
||
----
|
||
<1> Set the `@Sql` merge mode to `MERGE` for a specific test method.
|
||
|
||
|
||
[[spring-testing-annotation-sqlgroup]]
|
||
===== `@SqlGroup`
|
||
|
||
`@SqlGroup` is a container annotation that aggregates several `@Sql` annotations. You can
|
||
use `@SqlGroup` natively to declare several nested `@Sql` annotations, or you can use it
|
||
in conjunction with Java 8's support for repeatable annotations, where `@Sql` can be
|
||
declared several times on the same class or method, implicitly generating this container
|
||
annotation. The following example shows how to declare an SQL group:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@Test
|
||
@SqlGroup({ // <1>
|
||
@Sql(scripts = "/test-schema.sql", config = @SqlConfig(commentPrefix = "`")),
|
||
@Sql("/test-user-data.sql")
|
||
)}
|
||
void userTest() {
|
||
// run code that uses the test schema and test data
|
||
}
|
||
----
|
||
<1> Declare a group of SQL scripts.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@Test
|
||
@SqlGroup( // <1>
|
||
Sql("/test-schema.sql", config = SqlConfig(commentPrefix = "`")),
|
||
Sql("/test-user-data.sql"))
|
||
fun userTest() {
|
||
// run code that uses the test schema and test data
|
||
}
|
||
----
|
||
<1> Declare a group of SQL scripts.
|
||
|
||
[[integration-testing-annotations-standard]]
|
||
==== Standard Annotation Support
|
||
|
||
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.
|
||
|
||
* `@Autowired`
|
||
* `@Qualifier`
|
||
* `@Value`
|
||
* `@Resource` (javax.annotation) if JSR-250 is present
|
||
* `@ManagedBean` (javax.annotation) if JSR-250 is present
|
||
* `@Inject` (javax.inject) if JSR-330 is present
|
||
* `@Named` (javax.inject) if JSR-330 is present
|
||
* `@PersistenceContext` (javax.persistence) if JPA is present
|
||
* `@PersistenceUnit` (javax.persistence) if JPA is present
|
||
* `@Required`
|
||
* `@Transactional` (org.springframework.transaction.annotation)
|
||
_with <<testcontext-tx-attribute-support, limited attribute support>>_
|
||
|
||
.JSR-250 Lifecycle Annotations
|
||
[NOTE]
|
||
====
|
||
In the Spring TestContext Framework, you can use `@PostConstruct` and `@PreDestroy` with
|
||
standard semantics on any application components configured in the `ApplicationContext`.
|
||
However, these lifecycle annotations have limited usage within an actual test class.
|
||
|
||
If a method within a test class is annotated with `@PostConstruct`, that method runs
|
||
before any before methods of the underlying test framework (for example, methods
|
||
annotated with JUnit Jupiter's `@BeforeEach`), and that applies for every test method in
|
||
the test class. On the other hand, if a method within a test class is annotated with
|
||
`@PreDestroy`, that method never runs. Therefore, within a test class, we recommend that
|
||
you use test lifecycle callbacks from the underlying test framework instead of
|
||
`@PostConstruct` and `@PreDestroy`.
|
||
====
|
||
|
||
|
||
[[integration-testing-annotations-junit4]]
|
||
==== Spring JUnit 4 Testing Annotations
|
||
|
||
The following annotations are supported only when used in conjunction with the
|
||
<<testcontext-junit4-runner, SpringRunner>>, <<testcontext-junit4-rules, Spring's JUnit 4
|
||
rules>>, or <<testcontext-support-classes-junit4, Spring's JUnit 4 support classes>>:
|
||
|
||
* <<integration-testing-annotations-junit4-ifprofilevalue>>
|
||
* <<integration-testing-annotations-junit4-profilevaluesourceconfiguration>>
|
||
* <<integration-testing-annotations-junit4-timed>>
|
||
* <<integration-testing-annotations-junit4-repeat>>
|
||
|
||
[[integration-testing-annotations-junit4-ifprofilevalue]]
|
||
===== `@IfProfileValue`
|
||
|
||
`@IfProfileValue` indicates that the annotated test is enabled for a specific testing
|
||
environment. If the configured `ProfileValueSource` returns a matching `value` for the
|
||
provided `name`, the test is enabled. Otherwise, the test is disabled and, effectively,
|
||
ignored.
|
||
|
||
You can apply `@IfProfileValue` at the class level, the method level, or both.
|
||
Class-level usage of `@IfProfileValue` takes precedence over method-level usage for any
|
||
methods within that class or its subclasses. Specifically, a test is enabled if it is
|
||
enabled both at the class level and at the method level. The absence of `@IfProfileValue`
|
||
means the test is implicitly enabled. This is analogous to the semantics of JUnit 4's
|
||
`@Ignore` annotation, except that the presence of `@Ignore` always disables a test.
|
||
|
||
The following example shows a test that has an `@IfProfileValue` annotation:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@IfProfileValue(name="java.vendor", value="Oracle Corporation") // <1>
|
||
@Test
|
||
public void testProcessWhichRunsOnlyOnOracleJvm() {
|
||
// some logic that should run only on Java VMs from Oracle Corporation
|
||
}
|
||
----
|
||
<1> Run this test only when the Java vendor is "Oracle Corporation".
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@IfProfileValue(name="java.vendor", value="Oracle Corporation") // <1>
|
||
@Test
|
||
fun testProcessWhichRunsOnlyOnOracleJvm() {
|
||
// some logic that should run only on Java VMs from Oracle Corporation
|
||
}
|
||
----
|
||
<1> Run this test only when the Java vendor is "Oracle Corporation".
|
||
|
||
|
||
Alternatively, you can configure `@IfProfileValue` with a list of `values` (with `OR`
|
||
semantics) to achieve TestNG-like support for test groups in a JUnit 4 environment.
|
||
Consider the following example:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@IfProfileValue(name="test-groups", values={"unit-tests", "integration-tests"}) // <1>
|
||
@Test
|
||
public void testProcessWhichRunsForUnitOrIntegrationTestGroups() {
|
||
// some logic that should run only for unit and integration test groups
|
||
}
|
||
----
|
||
<1> Run this test for unit tests and integration tests.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@IfProfileValue(name="test-groups", values=["unit-tests", "integration-tests"]) // <1>
|
||
@Test
|
||
fun testProcessWhichRunsForUnitOrIntegrationTestGroups() {
|
||
// some logic that should run only for unit and integration test groups
|
||
}
|
||
----
|
||
<1> Run this test for unit tests and integration tests.
|
||
|
||
|
||
[[integration-testing-annotations-junit4-profilevaluesourceconfiguration]]
|
||
===== `@ProfileValueSourceConfiguration`
|
||
|
||
`@ProfileValueSourceConfiguration` is a class-level annotation that specifies what type
|
||
of `ProfileValueSource` to use when retrieving profile values configured through the
|
||
`@IfProfileValue` annotation. If `@ProfileValueSourceConfiguration` is not declared for a
|
||
test, `SystemProfileValueSource` is used by default. The following example shows how to
|
||
use `@ProfileValueSourceConfiguration`:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ProfileValueSourceConfiguration(CustomProfileValueSource.class) // <1>
|
||
public class CustomProfileValueSourceTests {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Use a custom profile value source.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ProfileValueSourceConfiguration(CustomProfileValueSource::class) // <1>
|
||
class CustomProfileValueSourceTests {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Use a custom profile value source.
|
||
|
||
|
||
[[integration-testing-annotations-junit4-timed]]
|
||
===== `@Timed`
|
||
|
||
`@Timed` indicates that the annotated test method must finish execution in a specified
|
||
time period (in milliseconds). If the text execution time exceeds the specified time
|
||
period, the test fails.
|
||
|
||
The time period includes running the test method itself, any repetitions of the test (see
|
||
`@Repeat`), as well as any setting up or tearing down of the test fixture. The following
|
||
example shows how to use it:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@Timed(millis = 1000) // <1>
|
||
public void testProcessWithOneSecondTimeout() {
|
||
// some logic that should not take longer than 1 second to run
|
||
}
|
||
----
|
||
<1> Set the time period for the test to one second.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@Timed(millis = 1000) // <1>
|
||
fun testProcessWithOneSecondTimeout() {
|
||
// some logic that should not take longer than 1 second to run
|
||
}
|
||
----
|
||
<1> Set the time period for the test to one second.
|
||
|
||
|
||
Spring's `@Timed` annotation has different semantics than JUnit 4's `@Test(timeout=...)`
|
||
support. Specifically, due to the manner in which JUnit 4 handles test execution timeouts
|
||
(that is, by executing the test method in a separate `Thread`), `@Test(timeout=...)`
|
||
preemptively fails the test if the test takes too long. Spring's `@Timed`, on the other
|
||
hand, does not preemptively fail the test but rather waits for the test to complete
|
||
before failing.
|
||
|
||
[[integration-testing-annotations-junit4-repeat]]
|
||
===== `@Repeat`
|
||
|
||
`@Repeat` indicates that the annotated test method must be run repeatedly. The number of
|
||
times that the test method is to be run is specified in the annotation.
|
||
|
||
The scope of execution to be repeated includes execution of the test method itself as
|
||
well as any setting up or tearing down of the test fixture. The following example shows
|
||
how to use the `@Repeat` annotation:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@Repeat(10) // <1>
|
||
@Test
|
||
public void testProcessRepeatedly() {
|
||
// ...
|
||
}
|
||
----
|
||
<1> Repeat this test ten times.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@Repeat(10) // <1>
|
||
@Test
|
||
fun testProcessRepeatedly() {
|
||
// ...
|
||
}
|
||
----
|
||
<1> Repeat this test ten times.
|
||
|
||
|
||
|
||
[[integration-testing-annotations-junit-jupiter]]
|
||
==== Spring JUnit Jupiter Testing Annotations
|
||
|
||
The following annotations are supported only when used in conjunction with the
|
||
<<testcontext-junit-jupiter-extension, `SpringExtension`>> and JUnit Jupiter
|
||
(that is, the programming model in JUnit 5):
|
||
|
||
* <<integration-testing-annotations-junit-jupiter-springjunitconfig>>
|
||
* <<integration-testing-annotations-junit-jupiter-springjunitwebconfig>>
|
||
* <<integration-testing-annotations-testconstructor>>
|
||
* <<integration-testing-annotations-junit-jupiter-enabledif>>
|
||
* <<integration-testing-annotations-junit-jupiter-disabledif>>
|
||
|
||
[[integration-testing-annotations-junit-jupiter-springjunitconfig]]
|
||
===== `@SpringJUnitConfig`
|
||
|
||
`@SpringJUnitConfig` is a composed annotation that combines
|
||
`@ExtendWith(SpringExtension.class)` from JUnit Jupiter with `@ContextConfiguration` from
|
||
the Spring TestContext Framework. It can be used at the class level as a drop-in
|
||
replacement for `@ContextConfiguration`. With regard to configuration options, the only
|
||
difference between `@ContextConfiguration` and `@SpringJUnitConfig` is that component
|
||
classes may be declared with the `value` attribute in `@SpringJUnitConfig`.
|
||
|
||
The following example shows how to use the `@SpringJUnitConfig` annotation to specify a
|
||
configuration class:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@SpringJUnitConfig(TestConfig.class) // <1>
|
||
class ConfigurationClassJUnitJupiterSpringTests {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Specify the configuration class.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@SpringJUnitConfig(TestConfig::class) // <1>
|
||
class ConfigurationClassJUnitJupiterSpringTests {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Specify the configuration class.
|
||
|
||
|
||
The following example shows how to use the `@SpringJUnitConfig` annotation to specify the
|
||
location of a configuration file:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@SpringJUnitConfig(locations = "/test-config.xml") // <1>
|
||
class XmlJUnitJupiterSpringTests {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Specify the location of a configuration file.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@SpringJUnitConfig(locations = ["/test-config.xml"]) // <1>
|
||
class XmlJUnitJupiterSpringTests {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Specify the location of a configuration file.
|
||
|
||
|
||
See <<testcontext-ctx-management>> as well as the javadoc for
|
||
{api-spring-framework}/test/context/junit/jupiter/SpringJUnitConfig.html[`@SpringJUnitConfig`]
|
||
and `@ContextConfiguration` for further details.
|
||
|
||
[[integration-testing-annotations-junit-jupiter-springjunitwebconfig]]
|
||
===== `@SpringJUnitWebConfig`
|
||
|
||
`@SpringJUnitWebConfig` is a composed annotation that combines
|
||
`@ExtendWith(SpringExtension.class)` from JUnit Jupiter with `@ContextConfiguration` and
|
||
`@WebAppConfiguration` from the Spring TestContext Framework. You can use it at the class
|
||
level as a drop-in replacement for `@ContextConfiguration` and `@WebAppConfiguration`.
|
||
With regard to configuration options, the only difference between `@ContextConfiguration`
|
||
and `@SpringJUnitWebConfig` is that you can declare component classes by using the
|
||
`value` attribute in `@SpringJUnitWebConfig`. In addition, you can override the `value`
|
||
attribute from `@WebAppConfiguration` only by using the `resourcePath` attribute in
|
||
`@SpringJUnitWebConfig`.
|
||
|
||
The following example shows how to use the `@SpringJUnitWebConfig` annotation to specify
|
||
a configuration class:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@SpringJUnitWebConfig(TestConfig.class) // <1>
|
||
class ConfigurationClassJUnitJupiterSpringWebTests {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Specify the configuration class.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@SpringJUnitWebConfig(TestConfig::class) // <1>
|
||
class ConfigurationClassJUnitJupiterSpringWebTests {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Specify the configuration class.
|
||
|
||
|
||
The following example shows how to use the `@SpringJUnitWebConfig` annotation to specify the
|
||
location of a configuration file:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@SpringJUnitWebConfig(locations = "/test-config.xml") // <1>
|
||
class XmlJUnitJupiterSpringWebTests {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Specify the location of a configuration file.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@SpringJUnitWebConfig(locations = ["/test-config.xml"]) // <1>
|
||
class XmlJUnitJupiterSpringWebTests {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Specify the location of a configuration file.
|
||
|
||
|
||
See <<testcontext-ctx-management>> as well as the javadoc for
|
||
{api-spring-framework}/test/context/junit/jupiter/web/SpringJUnitWebConfig.html[`@SpringJUnitWebConfig`],
|
||
{api-spring-framework}/test/context/ContextConfiguration.html[`@ContextConfiguration`], and
|
||
{api-spring-framework}/test/context/web/WebAppConfiguration.html[`@WebAppConfiguration`]
|
||
for further details.
|
||
|
||
[[integration-testing-annotations-testconstructor]]
|
||
===== `@TestConstructor`
|
||
|
||
`@TestConstructor` is a type-level annotation that is used to configure how the parameters
|
||
of a test class constructor are autowired from components in the test's
|
||
`ApplicationContext`.
|
||
|
||
If `@TestConstructor` is not present or meta-present on a test class, the default _test
|
||
constructor autowire mode_ will be used. See the tip below for details on how to change
|
||
the default mode. Note, however, that a local declaration of `@Autowired` on a
|
||
constructor takes precedence over both `@TestConstructor` and the default mode.
|
||
|
||
.Changing the default test constructor autowire mode
|
||
[TIP]
|
||
=====
|
||
The default _test constructor autowire mode_ can be changed by setting the
|
||
`spring.test.constructor.autowire.mode` JVM system property to `all`. Alternatively, the
|
||
default mode may be set via the `SpringProperties` mechanism.
|
||
|
||
As of Spring Framework 5.3, the default mode may also be configured as a
|
||
https://junit.org/junit5/docs/current/user-guide/#running-tests-config-params[JUnit Platform configuration parameter].
|
||
|
||
If the `spring.test.constructor.autowire.mode` property is not set, test class
|
||
constructors will not be automatically autowired.
|
||
=====
|
||
|
||
NOTE: As of Spring Framework 5.2, `@TestConstructor` is only supported in conjunction
|
||
with the `SpringExtension` for use with JUnit Jupiter. Note that the `SpringExtension` is
|
||
often automatically registered for you – for example, when using annotations such as
|
||
`@SpringJUnitConfig` and `@SpringJUnitWebConfig` or various test-related annotations from
|
||
Spring Boot Test.
|
||
|
||
[[integration-testing-annotations-junit-jupiter-enabledif]]
|
||
===== `@EnabledIf`
|
||
|
||
`@EnabledIf` is used to signal that the annotated JUnit Jupiter test class or test method
|
||
is enabled and should be run if the supplied `expression` evaluates to `true`.
|
||
Specifically, if the expression evaluates to `Boolean.TRUE` or a `String` equal to `true`
|
||
(ignoring case), the test is enabled. When applied at the class level, all test methods
|
||
within that class are automatically enabled by default as well.
|
||
|
||
Expressions can be any of the following:
|
||
|
||
* <<core.adoc#expressions, Spring Expression Language>> (SpEL) expression. For example:
|
||
`@EnabledIf("#{systemProperties['os.name'].toLowerCase().contains('mac')}")`
|
||
* Placeholder for a property available in the Spring <<core.adoc#beans-environment, `Environment`>>.
|
||
For example: `@EnabledIf("${smoke.tests.enabled}")`
|
||
* Text literal. For example: `@EnabledIf("true")`
|
||
|
||
Note, however, that a text literal that is not the result of dynamic resolution of a
|
||
property placeholder is of zero practical value, since `@EnabledIf("false")` is
|
||
equivalent to `@Disabled` and `@EnabledIf("true")` is logically meaningless.
|
||
|
||
You can use `@EnabledIf` as a meta-annotation to create custom composed annotations. For
|
||
example, you can create a custom `@EnabledOnMac` annotation as follows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@Target({ElementType.TYPE, ElementType.METHOD})
|
||
@Retention(RetentionPolicy.RUNTIME)
|
||
@EnabledIf(
|
||
expression = "#{systemProperties['os.name'].toLowerCase().contains('mac')}",
|
||
reason = "Enabled on Mac OS"
|
||
)
|
||
public @interface EnabledOnMac {}
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@Target(AnnotationTarget.TYPE, AnnotationTarget.FUNCTION)
|
||
@Retention(AnnotationRetention.RUNTIME)
|
||
@EnabledIf(
|
||
expression = "#{systemProperties['os.name'].toLowerCase().contains('mac')}",
|
||
reason = "Enabled on Mac OS"
|
||
)
|
||
annotation class EnabledOnMac {}
|
||
----
|
||
|
||
[[integration-testing-annotations-junit-jupiter-disabledif]]
|
||
===== `@DisabledIf`
|
||
|
||
`@DisabledIf` is used to signal that the annotated JUnit Jupiter test class or test
|
||
method is disabled and should not be run if the supplied `expression` evaluates to
|
||
`true`. Specifically, if the expression evaluates to `Boolean.TRUE` or a `String` equal
|
||
to `true` (ignoring case), the test is disabled. When applied at the class level, all
|
||
test methods within that class are automatically disabled as well.
|
||
|
||
Expressions can be any of the following:
|
||
|
||
* <<core.adoc#expressions, Spring Expression Language>> (SpEL) expression. For example:
|
||
`@DisabledIf("#{systemProperties['os.name'].toLowerCase().contains('mac')}")`
|
||
* Placeholder for a property available in the Spring <<core.adoc#beans-environment, `Environment`>>.
|
||
For example: `@DisabledIf("${smoke.tests.disabled}")`
|
||
* Text literal. For example: `@DisabledIf("true")`
|
||
|
||
Note, however, that a text literal that is not the result of dynamic resolution of a
|
||
property placeholder is of zero practical value, since `@DisabledIf("true")` is
|
||
equivalent to `@Disabled` and `@DisabledIf("false")` is logically meaningless.
|
||
|
||
You can use `@DisabledIf` as a meta-annotation to create custom composed annotations. For
|
||
example, you can create a custom `@DisabledOnMac` annotation as follows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@Target({ElementType.TYPE, ElementType.METHOD})
|
||
@Retention(RetentionPolicy.RUNTIME)
|
||
@DisabledIf(
|
||
expression = "#{systemProperties['os.name'].toLowerCase().contains('mac')}",
|
||
reason = "Disabled on Mac OS"
|
||
)
|
||
public @interface DisabledOnMac {}
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@Target(AnnotationTarget.TYPE, AnnotationTarget.FUNCTION)
|
||
@Retention(AnnotationRetention.RUNTIME)
|
||
@DisabledIf(
|
||
expression = "#{systemProperties['os.name'].toLowerCase().contains('mac')}",
|
||
reason = "Disabled on Mac OS"
|
||
)
|
||
annotation class DisabledOnMac {}
|
||
----
|
||
|
||
[[integration-testing-annotations-meta]]
|
||
==== Meta-Annotation Support for Testing
|
||
|
||
You can use most test-related annotations as
|
||
<<core.adoc#beans-meta-annotations, meta-annotations>> to create custom composed
|
||
annotations and reduce configuration duplication across a test suite.
|
||
|
||
You can use each of the following as a meta-annotation in conjunction with the
|
||
<<testcontext-framework, TestContext framework>>.
|
||
|
||
* `@BootstrapWith`
|
||
* `@ContextConfiguration`
|
||
* `@ContextHierarchy`
|
||
* `@ActiveProfiles`
|
||
* `@TestPropertySource`
|
||
* `@DirtiesContext`
|
||
* `@WebAppConfiguration`
|
||
* `@TestExecutionListeners`
|
||
* `@Transactional`
|
||
* `@BeforeTransaction`
|
||
* `@AfterTransaction`
|
||
* `@Commit`
|
||
* `@Rollback`
|
||
* `@Sql`
|
||
* `@SqlConfig`
|
||
* `@SqlMergeMode`
|
||
* `@SqlGroup`
|
||
* `@Repeat` _(only supported on JUnit 4)_
|
||
* `@Timed` _(only supported on JUnit 4)_
|
||
* `@IfProfileValue` _(only supported on JUnit 4)_
|
||
* `@ProfileValueSourceConfiguration` _(only supported on JUnit 4)_
|
||
* `@SpringJUnitConfig` _(only supported on JUnit Jupiter)_
|
||
* `@SpringJUnitWebConfig` _(only supported on JUnit Jupiter)_
|
||
* `@TestConstructor` _(only supported on JUnit Jupiter)_
|
||
* `@EnabledIf` _(only supported on JUnit Jupiter)_
|
||
* `@DisabledIf` _(only supported on JUnit Jupiter)_
|
||
|
||
Consider the following example:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@RunWith(SpringRunner.class)
|
||
@ContextConfiguration({"/app-config.xml", "/test-data-access-config.xml"})
|
||
@ActiveProfiles("dev")
|
||
@Transactional
|
||
public class OrderRepositoryTests { }
|
||
|
||
@RunWith(SpringRunner.class)
|
||
@ContextConfiguration({"/app-config.xml", "/test-data-access-config.xml"})
|
||
@ActiveProfiles("dev")
|
||
@Transactional
|
||
public class UserRepositoryTests { }
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@RunWith(SpringRunner::class)
|
||
@ContextConfiguration("/app-config.xml", "/test-data-access-config.xml")
|
||
@ActiveProfiles("dev")
|
||
@Transactional
|
||
class OrderRepositoryTests { }
|
||
|
||
@RunWith(SpringRunner::class)
|
||
@ContextConfiguration("/app-config.xml", "/test-data-access-config.xml")
|
||
@ActiveProfiles("dev")
|
||
@Transactional
|
||
class UserRepositoryTests { }
|
||
----
|
||
|
||
If we discover that we are repeating the preceding configuration across our JUnit 4-based
|
||
test suite, we can reduce the duplication by introducing a custom composed annotation
|
||
that centralizes the common test configuration for Spring, as follows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@Target(ElementType.TYPE)
|
||
@Retention(RetentionPolicy.RUNTIME)
|
||
@ContextConfiguration({"/app-config.xml", "/test-data-access-config.xml"})
|
||
@ActiveProfiles("dev")
|
||
@Transactional
|
||
public @interface TransactionalDevTestConfig { }
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@Target(AnnotationTarget.TYPE)
|
||
@Retention(AnnotationRetention.RUNTIME)
|
||
@ContextConfiguration("/app-config.xml", "/test-data-access-config.xml")
|
||
@ActiveProfiles("dev")
|
||
@Transactional
|
||
annotation class TransactionalDevTestConfig { }
|
||
----
|
||
|
||
Then we can use our custom `@TransactionalDevTestConfig` annotation to simplify the
|
||
configuration of individual JUnit 4 based test classes, as follows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@RunWith(SpringRunner.class)
|
||
@TransactionalDevTestConfig
|
||
public class OrderRepositoryTests { }
|
||
|
||
@RunWith(SpringRunner.class)
|
||
@TransactionalDevTestConfig
|
||
public class UserRepositoryTests { }
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@RunWith(SpringRunner::class)
|
||
@TransactionalDevTestConfig
|
||
class OrderRepositoryTests
|
||
|
||
@RunWith(SpringRunner::class)
|
||
@TransactionalDevTestConfig
|
||
class UserRepositoryTests
|
||
----
|
||
|
||
If we write tests that use JUnit Jupiter, we can reduce code duplication even further,
|
||
since annotations in JUnit 5 can also be used as meta-annotations. Consider the following
|
||
example:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ExtendWith(SpringExtension.class)
|
||
@ContextConfiguration({"/app-config.xml", "/test-data-access-config.xml"})
|
||
@ActiveProfiles("dev")
|
||
@Transactional
|
||
class OrderRepositoryTests { }
|
||
|
||
@ExtendWith(SpringExtension.class)
|
||
@ContextConfiguration({"/app-config.xml", "/test-data-access-config.xml"})
|
||
@ActiveProfiles("dev")
|
||
@Transactional
|
||
class UserRepositoryTests { }
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ExtendWith(SpringExtension::class)
|
||
@ContextConfiguration("/app-config.xml", "/test-data-access-config.xml")
|
||
@ActiveProfiles("dev")
|
||
@Transactional
|
||
class OrderRepositoryTests { }
|
||
|
||
@ExtendWith(SpringExtension::class)
|
||
@ContextConfiguration("/app-config.xml", "/test-data-access-config.xml")
|
||
@ActiveProfiles("dev")
|
||
@Transactional
|
||
class UserRepositoryTests { }
|
||
----
|
||
|
||
If we discover that we are repeating the preceding configuration across our JUnit
|
||
Jupiter-based test suite, we can reduce the duplication by introducing a custom composed
|
||
annotation that centralizes the common test configuration for Spring and JUnit Jupiter,
|
||
as follows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@Target(ElementType.TYPE)
|
||
@Retention(RetentionPolicy.RUNTIME)
|
||
@ExtendWith(SpringExtension.class)
|
||
@ContextConfiguration({"/app-config.xml", "/test-data-access-config.xml"})
|
||
@ActiveProfiles("dev")
|
||
@Transactional
|
||
public @interface TransactionalDevTestConfig { }
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@Target(AnnotationTarget.TYPE)
|
||
@Retention(AnnotationRetention.RUNTIME)
|
||
@ExtendWith(SpringExtension::class)
|
||
@ContextConfiguration("/app-config.xml", "/test-data-access-config.xml")
|
||
@ActiveProfiles("dev")
|
||
@Transactional
|
||
annotation class TransactionalDevTestConfig { }
|
||
----
|
||
|
||
Then we can use our custom `@TransactionalDevTestConfig` annotation to simplify the
|
||
configuration of individual JUnit Jupiter based test classes, as follows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@TransactionalDevTestConfig
|
||
class OrderRepositoryTests { }
|
||
|
||
@TransactionalDevTestConfig
|
||
class UserRepositoryTests { }
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@TransactionalDevTestConfig
|
||
class OrderRepositoryTests { }
|
||
|
||
@TransactionalDevTestConfig
|
||
class UserRepositoryTests { }
|
||
----
|
||
|
||
Since JUnit Jupiter supports the use of `@Test`, `@RepeatedTest`, `ParameterizedTest`,
|
||
and others as meta-annotations, you can also create custom composed annotations at the
|
||
test method level. For example, if we wish to create a composed annotation that combines
|
||
the `@Test` and `@Tag` annotations from JUnit Jupiter with the `@Transactional`
|
||
annotation from Spring, we could create an `@TransactionalIntegrationTest` annotation, as
|
||
follows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@Target(ElementType.METHOD)
|
||
@Retention(RetentionPolicy.RUNTIME)
|
||
@Transactional
|
||
@Tag("integration-test") // org.junit.jupiter.api.Tag
|
||
@Test // org.junit.jupiter.api.Test
|
||
public @interface TransactionalIntegrationTest { }
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@Target(AnnotationTarget.TYPE)
|
||
@Retention(AnnotationRetention.RUNTIME)
|
||
@Transactional
|
||
@Tag("integration-test") // org.junit.jupiter.api.Tag
|
||
@Test // org.junit.jupiter.api.Test
|
||
annotation class TransactionalIntegrationTest { }
|
||
----
|
||
|
||
Then we can use our custom `@TransactionalIntegrationTest` annotation to simplify the
|
||
configuration of individual JUnit Jupiter based test methods, as follows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@TransactionalIntegrationTest
|
||
void saveOrder() { }
|
||
|
||
@TransactionalIntegrationTest
|
||
void deleteOrder() { }
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@TransactionalIntegrationTest
|
||
fun saveOrder() { }
|
||
|
||
@TransactionalIntegrationTest
|
||
fun deleteOrder() { }
|
||
----
|
||
|
||
For further details, see the
|
||
https://github.com/spring-projects/spring-framework/wiki/Spring-Annotation-Programming-Model[Spring Annotation Programming Model]
|
||
wiki page.
|
||
|
||
|
||
|
||
[[testcontext-framework]]
|
||
=== Spring TestContext Framework
|
||
|
||
The Spring TestContext Framework (located in the `org.springframework.test.context`
|
||
package) provides generic, annotation-driven unit and integration testing support that is
|
||
agnostic of the testing framework in use. The TestContext framework also places a great
|
||
deal of importance on convention over configuration, with reasonable defaults that you
|
||
can override through annotation-based configuration.
|
||
|
||
In addition to generic testing infrastructure, the TestContext framework provides
|
||
explicit support for JUnit 4, JUnit Jupiter (AKA JUnit 5), and TestNG. For JUnit 4 and
|
||
TestNG, Spring provides `abstract` support classes. Furthermore, Spring provides a custom
|
||
JUnit `Runner` and custom JUnit `Rules` for JUnit 4 and a custom `Extension` for JUnit
|
||
Jupiter that let you write so-called POJO test classes. POJO test classes are not
|
||
required to extend a particular class hierarchy, such as the `abstract` support classes.
|
||
|
||
The following section provides an overview of the internals of the TestContext framework.
|
||
If you are interested only in using the framework and are not interested in extending it
|
||
with your own custom listeners or custom loaders, feel free to go directly to the
|
||
configuration (<<testcontext-ctx-management, context management>>,
|
||
<<testcontext-fixture-di, dependency injection>>, <<testcontext-tx,transaction
|
||
management>>), <<testcontext-support-classes, support classes>>, and
|
||
<<integration-testing-annotations, annotation support>> sections.
|
||
|
||
|
||
[[testcontext-key-abstractions]]
|
||
==== Key Abstractions
|
||
|
||
The core of the framework consists of the `TestContextManager` class and the
|
||
`TestContext`, `TestExecutionListener`, and `SmartContextLoader` interfaces. A
|
||
`TestContextManager` is created for each test class (for example, for the execution of
|
||
all test methods within a single test class in JUnit Jupiter). The `TestContextManager`,
|
||
in turn, manages a `TestContext` that holds the context of the current test. The
|
||
`TestContextManager` also updates the state of the `TestContext` as the test progresses
|
||
and delegates to `TestExecutionListener` implementations, which instrument the actual
|
||
test execution by providing dependency injection, managing transactions, and so on. A
|
||
`SmartContextLoader` is responsible for loading an `ApplicationContext` for a given test
|
||
class. See the {api-spring-framework}/test/context/package-summary.html[javadoc] and the
|
||
Spring test suite for further information and examples of various implementations.
|
||
|
||
===== `TestContext`
|
||
|
||
`TestContext` encapsulates the context in which a test is run (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 `TestContext` also delegates to a
|
||
`SmartContextLoader` to load an `ApplicationContext` if requested.
|
||
|
||
===== `TestContextManager`
|
||
|
||
`TestContextManager` is the main entry point into the Spring TestContext Framework and is
|
||
responsible for managing a single `TestContext` and signaling events to each registered
|
||
`TestExecutionListener` at well-defined test execution points:
|
||
|
||
* Prior to any "`before class`" or "`before all`" methods of a particular testing framework.
|
||
* Test instance post-processing.
|
||
* Prior to any "`before`" or "`before each`" methods of a particular testing framework.
|
||
* Immediately before execution of the test method but after test setup.
|
||
* Immediately after execution of the test method but before test tear down.
|
||
* After any "`after`" or "`after each`" methods of a particular testing framework.
|
||
* After any "`after class`" or "`after all`" methods of a particular testing framework.
|
||
|
||
===== `TestExecutionListener`
|
||
|
||
`TestExecutionListener` defines the API for reacting to test-execution events published by
|
||
the `TestContextManager` with which the listener is registered. See <<testcontext-tel-config>>.
|
||
|
||
===== Context Loaders
|
||
|
||
`ContextLoader` is a strategy interface for loading an `ApplicationContext` for an
|
||
integration test managed by the Spring TestContext Framework. You should implement
|
||
`SmartContextLoader` instead of this interface to provide support for component classes,
|
||
active bean definition profiles, test property sources, context hierarchies, and
|
||
`WebApplicationContext` support.
|
||
|
||
`SmartContextLoader` is an extension of the `ContextLoader` interface that supersedes the
|
||
original minimal `ContextLoader` SPI. Specifically, a `SmartContextLoader` can choose to
|
||
process resource locations, component classes, or context initializers. Furthermore, a
|
||
`SmartContextLoader` can set active bean definition profiles and test property sources in
|
||
the context that it loads.
|
||
|
||
Spring provides the following implementations:
|
||
|
||
* `DelegatingSmartContextLoader`: One of two default loaders, it delegates internally to
|
||
an `AnnotationConfigContextLoader`, a `GenericXmlContextLoader`, or a
|
||
`GenericGroovyXmlContextLoader`, depending either on the configuration declared for the
|
||
test class or on the presence of default locations or default configuration classes.
|
||
Groovy support is enabled only if Groovy is on the classpath.
|
||
* `WebDelegatingSmartContextLoader`: One of two default loaders, it delegates internally
|
||
to an `AnnotationConfigWebContextLoader`, a `GenericXmlWebContextLoader`, or a
|
||
`GenericGroovyXmlWebContextLoader`, depending either on the configuration declared for
|
||
the test class or on the presence of default locations or default configuration
|
||
classes. A web `ContextLoader` is used only if `@WebAppConfiguration` is present on the
|
||
test class. Groovy support is enabled only if Groovy is on the classpath.
|
||
* `AnnotationConfigContextLoader`: Loads a standard `ApplicationContext` from component
|
||
classes.
|
||
* `AnnotationConfigWebContextLoader`: Loads a `WebApplicationContext` from component
|
||
classes.
|
||
* `GenericGroovyXmlContextLoader`: Loads a standard `ApplicationContext` from resource
|
||
locations that are either Groovy scripts or XML configuration files.
|
||
* `GenericGroovyXmlWebContextLoader`: Loads a `WebApplicationContext` from resource
|
||
locations that are either Groovy scripts or XML configuration files.
|
||
* `GenericXmlContextLoader`: Loads a standard `ApplicationContext` from XML resource
|
||
locations.
|
||
* `GenericXmlWebContextLoader`: Loads a `WebApplicationContext` from XML resource
|
||
locations.
|
||
|
||
|
||
[[testcontext-bootstrapping]]
|
||
==== Bootstrapping the TestContext Framework
|
||
|
||
The default configuration for the internals of the Spring TestContext Framework is
|
||
sufficient for all common use cases. However, there are times when a development team or
|
||
third party framework would like to change the default `ContextLoader`, implement a
|
||
custom `TestContext` or `ContextCache`, augment the default sets of
|
||
`ContextCustomizerFactory` and `TestExecutionListener` implementations, and so on. For
|
||
such low-level control over how the TestContext framework operates, Spring provides a
|
||
bootstrapping strategy.
|
||
|
||
`TestContextBootstrapper` defines the SPI for bootstrapping the TestContext framework. A
|
||
`TestContextBootstrapper` is used by the `TestContextManager` to load the
|
||
`TestExecutionListener` implementations for the current test and to build the
|
||
`TestContext` that it manages. You can configure a custom bootstrapping strategy for a
|
||
test class (or test class hierarchy) by using `@BootstrapWith`, either directly or as a
|
||
meta-annotation. If a bootstrapper is not explicitly configured by using
|
||
`@BootstrapWith`, either the `DefaultTestContextBootstrapper` or the
|
||
`WebTestContextBootstrapper` is used, depending on the presence of `@WebAppConfiguration`.
|
||
|
||
Since the `TestContextBootstrapper` SPI is likely to change in the future (to accommodate
|
||
new requirements), we strongly encourage implementers not to implement this interface
|
||
directly but rather to extend `AbstractTestContextBootstrapper` or one of its concrete
|
||
subclasses instead.
|
||
|
||
|
||
[[testcontext-tel-config]]
|
||
==== `TestExecutionListener` Configuration
|
||
|
||
Spring provides the following `TestExecutionListener` implementations that are registered
|
||
by default, exactly in the following order:
|
||
|
||
* `ServletTestExecutionListener`: Configures Servlet API mocks for a
|
||
`WebApplicationContext`.
|
||
* `DirtiesContextBeforeModesTestExecutionListener`: Handles the `@DirtiesContext`
|
||
annotation for "`before`" modes.
|
||
* `DependencyInjectionTestExecutionListener`: Provides dependency injection for the test
|
||
instance.
|
||
* `DirtiesContextTestExecutionListener`: Handles the `@DirtiesContext` annotation for
|
||
"`after`" modes.
|
||
* `TransactionalTestExecutionListener`: Provides transactional test execution with
|
||
default rollback semantics.
|
||
* `SqlScriptsTestExecutionListener`: Runs SQL scripts configured by using the `@Sql`
|
||
annotation.
|
||
* `EventPublishingTestExecutionListener`: Publishes test execution events to the test's
|
||
`ApplicationContext` (see <<testcontext-test-execution-events>>).
|
||
|
||
[[testcontext-tel-config-registering-tels]]
|
||
===== Registering `TestExecutionListener` Implementations
|
||
|
||
You can register `TestExecutionListener` implementations for a test class and its
|
||
subclasses by using the `@TestExecutionListeners` annotation. See
|
||
<<integration-testing-annotations, annotation support>> and the javadoc for
|
||
{api-spring-framework}/test/context/TestExecutionListeners.html[`@TestExecutionListeners`]
|
||
for details and examples.
|
||
|
||
[[testcontext-tel-config-automatic-discovery]]
|
||
===== Automatic Discovery of Default `TestExecutionListener` Implementations
|
||
|
||
Registering `TestExecutionListener` implementations by using `@TestExecutionListeners` is
|
||
suitable for custom listeners that are used in limited testing scenarios. However, it can
|
||
become cumbersome if a custom listener needs to be used across an entire test suite. This
|
||
issue is addressed through support for automatic discovery of default
|
||
`TestExecutionListener` implementations through the `SpringFactoriesLoader` mechanism.
|
||
|
||
Specifically, the `spring-test` module declares all core default `TestExecutionListener`
|
||
implementations under the `org.springframework.test.context.TestExecutionListener` key in
|
||
its `META-INF/spring.factories` properties file. Third-party frameworks and developers
|
||
can contribute their own `TestExecutionListener` implementations to the list of default
|
||
listeners in the same manner through their own `META-INF/spring.factories` properties
|
||
file.
|
||
|
||
[[testcontext-tel-config-ordering]]
|
||
===== Ordering `TestExecutionListener` Implementations
|
||
|
||
When the TestContext framework discovers default `TestExecutionListener` implementations
|
||
through the <<testcontext-tel-config-automatic-discovery, aforementioned>>
|
||
`SpringFactoriesLoader` mechanism, the instantiated listeners are sorted by using
|
||
Spring's `AnnotationAwareOrderComparator`, which honors Spring's `Ordered` interface and
|
||
`@Order` annotation for ordering. `AbstractTestExecutionListener` and all default
|
||
`TestExecutionListener` implementations provided by Spring implement `Ordered` with
|
||
appropriate values. Third-party frameworks and developers should therefore make sure that
|
||
their default `TestExecutionListener` implementations are registered in the proper order
|
||
by implementing `Ordered` or declaring `@Order`. See the javadoc for the `getOrder()`
|
||
methods of the core default `TestExecutionListener` implementations for details on what
|
||
values are assigned to each core listener.
|
||
|
||
[[testcontext-tel-config-merging]]
|
||
===== Merging `TestExecutionListener` Implementations
|
||
|
||
If a custom `TestExecutionListener` is registered via `@TestExecutionListeners`, the
|
||
default listeners are not registered. In most common testing scenarios, this effectively
|
||
forces the developer to manually declare all default listeners in addition to any custom
|
||
listeners. The following listing demonstrates this style of configuration:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ContextConfiguration
|
||
@TestExecutionListeners({
|
||
MyCustomTestExecutionListener.class,
|
||
ServletTestExecutionListener.class,
|
||
DirtiesContextBeforeModesTestExecutionListener.class,
|
||
DependencyInjectionTestExecutionListener.class,
|
||
DirtiesContextTestExecutionListener.class,
|
||
TransactionalTestExecutionListener.class,
|
||
SqlScriptsTestExecutionListener.class
|
||
})
|
||
class MyTest {
|
||
// class body...
|
||
}
|
||
----
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ContextConfiguration
|
||
@TestExecutionListeners(
|
||
MyCustomTestExecutionListener::class,
|
||
ServletTestExecutionListener::class,
|
||
DirtiesContextBeforeModesTestExecutionListener::class,
|
||
DependencyInjectionTestExecutionListener::class,
|
||
DirtiesContextTestExecutionListener::class,
|
||
TransactionalTestExecutionListener::class,
|
||
SqlScriptsTestExecutionListener::class
|
||
)
|
||
class MyTest {
|
||
// class body...
|
||
}
|
||
----
|
||
|
||
The challenge with this approach is that it requires that the developer know exactly
|
||
which listeners are registered by default. Moreover, the set of default listeners can
|
||
change from release to release -- for example, `SqlScriptsTestExecutionListener` was
|
||
introduced in Spring Framework 4.1, and `DirtiesContextBeforeModesTestExecutionListener`
|
||
was introduced in Spring Framework 4.2. Furthermore, third-party frameworks like Spring
|
||
Boot and Spring Security register their own default `TestExecutionListener`
|
||
implementations by using the aforementioned <<testcontext-tel-config-automatic-discovery,
|
||
automatic discovery mechanism>>.
|
||
|
||
To avoid having to be aware of and re-declare all default listeners, you can set the
|
||
`mergeMode` attribute of `@TestExecutionListeners` to `MergeMode.MERGE_WITH_DEFAULTS`.
|
||
`MERGE_WITH_DEFAULTS` indicates that locally declared listeners should be merged with the
|
||
default listeners. The merging algorithm ensures that duplicates are removed from the
|
||
list and that the resulting set of merged listeners is sorted according to the semantics
|
||
of `AnnotationAwareOrderComparator`, as described in <<testcontext-tel-config-ordering>>.
|
||
If a listener implements `Ordered` or is annotated with `@Order`, it can influence the
|
||
position in which it is merged with the defaults. Otherwise, locally declared listeners
|
||
are appended to the list of default listeners when merged.
|
||
|
||
For example, if the `MyCustomTestExecutionListener` class in the previous example
|
||
configures its `order` value (for example, `500`) to be less than the order of the
|
||
`ServletTestExecutionListener` (which happens to be `1000`), the
|
||
`MyCustomTestExecutionListener` can then be automatically merged with the list of
|
||
defaults in front of the `ServletTestExecutionListener`, and the previous example could
|
||
be replaced with the following:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ContextConfiguration
|
||
@TestExecutionListeners(
|
||
listeners = MyCustomTestExecutionListener.class,
|
||
mergeMode = MERGE_WITH_DEFAULTS
|
||
)
|
||
class MyTest {
|
||
// class body...
|
||
}
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ContextConfiguration
|
||
@TestExecutionListeners(
|
||
listeners = [MyCustomTestExecutionListener::class],
|
||
mergeMode = MERGE_WITH_DEFAULTS
|
||
)
|
||
class MyTest {
|
||
// class body...
|
||
}
|
||
----
|
||
|
||
[[testcontext-test-execution-events]]
|
||
==== Test Execution Events
|
||
|
||
The `EventPublishingTestExecutionListener` introduced in Spring Framework 5.2 offers an
|
||
alternative approach to implementing a custom `TestExecutionListener`. Components in the
|
||
test's `ApplicationContext` can listen to the following events published by the
|
||
`EventPublishingTestExecutionListener`, each of which corresponds to a method in the
|
||
`TestExecutionListener` API.
|
||
|
||
* `BeforeTestClassEvent`
|
||
* `PrepareTestInstanceEvent`
|
||
* `BeforeTestMethodEvent`
|
||
* `BeforeTestExecutionEvent`
|
||
* `AfterTestExecutionEvent`
|
||
* `AfterTestMethodEvent`
|
||
* `AfterTestClassEvent`
|
||
|
||
NOTE: These events are only published if the `ApplicationContext` has already been loaded.
|
||
|
||
These events may be consumed for various reasons, such as resetting mock beans or tracing
|
||
test execution. One advantage of consuming test execution events rather than implementing
|
||
a custom `TestExecutionListener` is that test execution events may be consumed by any
|
||
Spring bean registered in the test `ApplicationContext`, and such beans may benefit
|
||
directly from dependency injection and other features of the `ApplicationContext`. In
|
||
contrast, a `TestExecutionListener` is not a bean in the `ApplicationContext`.
|
||
|
||
In order to listen to test execution events, a Spring bean may choose to implement the
|
||
`org.springframework.context.ApplicationListener` interface. Alternatively, listener
|
||
methods can be annotated with `@EventListener` and configured to listen to one of the
|
||
particular event types listed above (see
|
||
<<core.adoc#context-functionality-events-annotation, Annotation-based Event Listeners>>).
|
||
Due to the popularity of this approach, Spring provides the following dedicated
|
||
`@EventListener` annotations to simplify registration of test execution event listeners.
|
||
These annotations reside in the `org.springframework.test.context.event.annotation`
|
||
package.
|
||
|
||
* `@BeforeTestClass`
|
||
* `@PrepareTestInstance`
|
||
* `@BeforeTestMethod`
|
||
* `@BeforeTestExecution`
|
||
* `@AfterTestExecution`
|
||
* `@AfterTestMethod`
|
||
* `@AfterTestClass`
|
||
|
||
[[testcontext-test-execution-events-exception-handling]]
|
||
===== Exception Handling
|
||
|
||
By default, if a test execution event listener throws an exception while consuming an
|
||
event, that exception will propagate to the underlying testing framework in use (such as
|
||
JUnit or TestNG). For example, if the consumption of a `BeforeTestMethodEvent` results in
|
||
an exception, the corresponding test method will fail as a result of the exception. In
|
||
contrast, if an asynchronous test execution event listener throws an exception, the
|
||
exception will not propagate to the underlying testing framework. For further details on
|
||
asynchronous exception handling, consult the class-level javadoc for `@EventListener`.
|
||
|
||
[[testcontext-test-execution-events-async]]
|
||
===== Asynchronous Listeners
|
||
|
||
If you want a particular test execution event listener to process events asynchronously,
|
||
you can use Spring's <<integration.adoc#scheduling-annotation-support-async,regular
|
||
`@Async` support>>. For further details, consult the class-level javadoc for
|
||
`@EventListener`.
|
||
|
||
|
||
[[testcontext-ctx-management]]
|
||
==== Context Management
|
||
|
||
Each `TestContext` 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 `ApplicationContext`. However, if a test class implements the
|
||
`ApplicationContextAware` interface, a reference to the `ApplicationContext` is supplied
|
||
to the test instance. Note that `AbstractJUnit4SpringContextTests` and
|
||
`AbstractTestNGSpringContextTests` implement `ApplicationContextAware` and, therefore,
|
||
provide access to the `ApplicationContext` automatically.
|
||
|
||
.@Autowired ApplicationContext
|
||
[TIP]
|
||
=====
|
||
As an alternative to implementing the `ApplicationContextAware` interface, you can inject
|
||
the application context for your test class through the `@Autowired` annotation on either
|
||
a field or setter method, as the following example shows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@SpringJUnitConfig
|
||
class MyTest {
|
||
|
||
@Autowired // <1>
|
||
ApplicationContext applicationContext;
|
||
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Injecting the `ApplicationContext`.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@SpringJUnitConfig
|
||
class MyTest {
|
||
|
||
@Autowired // <1>
|
||
lateinit var applicationContext: ApplicationContext
|
||
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Injecting the `ApplicationContext`.
|
||
|
||
|
||
Similarly, if your test is configured to load a `WebApplicationContext`, you can inject
|
||
the web application context into your test, as follows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@SpringJUnitWebConfig // <1>
|
||
class MyWebAppTest {
|
||
|
||
@Autowired // <2>
|
||
WebApplicationContext wac;
|
||
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Configuring the `WebApplicationContext`.
|
||
<2> Injecting the `WebApplicationContext`.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@SpringJUnitWebConfig // <1>
|
||
class MyWebAppTest {
|
||
|
||
@Autowired // <2>
|
||
lateinit var wac: WebApplicationContext
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Configuring the `WebApplicationContext`.
|
||
<2> Injecting the `WebApplicationContext`.
|
||
|
||
|
||
Dependency injection by using `@Autowired` is provided by the
|
||
`DependencyInjectionTestExecutionListener`, which is configured by default
|
||
(see <<testcontext-fixture-di>>).
|
||
=====
|
||
|
||
Test classes that use the TestContext framework do not need to extend any particular
|
||
class or implement a specific interface to configure their application context. Instead,
|
||
configuration is achieved by declaring the `@ContextConfiguration` annotation at the
|
||
class level. If your test class does not explicitly declare application context resource
|
||
locations or component classes, the configured `ContextLoader` determines how to load a
|
||
context from a default location or default configuration classes. In addition to context
|
||
resource locations and component classes, an application context can also be configured
|
||
through application context initializers.
|
||
|
||
The following sections explain how to use Spring's `@ContextConfiguration` annotation to
|
||
configure a test `ApplicationContext` by using XML configuration files, Groovy scripts,
|
||
component classes (typically `@Configuration` classes), or context initializers.
|
||
Alternatively, you can implement and configure your own custom `SmartContextLoader` for
|
||
advanced use cases.
|
||
|
||
* <<testcontext-ctx-management-xml>>
|
||
* <<testcontext-ctx-management-groovy>>
|
||
* <<testcontext-ctx-management-javaconfig>>
|
||
* <<testcontext-ctx-management-mixed-config>>
|
||
* <<testcontext-ctx-management-initializers>>
|
||
* <<testcontext-ctx-management-inheritance>>
|
||
* <<testcontext-ctx-management-env-profiles>>
|
||
* <<testcontext-ctx-management-property-sources>>
|
||
* <<testcontext-ctx-management-dynamic-property-sources>>
|
||
* <<testcontext-ctx-management-web>>
|
||
* <<testcontext-ctx-management-caching>>
|
||
* <<testcontext-ctx-management-ctx-hierarchies>>
|
||
|
||
[[testcontext-ctx-management-xml]]
|
||
===== Context Configuration with XML resources
|
||
|
||
To load an `ApplicationContext` for your tests by using XML configuration files, annotate
|
||
your test class with `@ContextConfiguration` and configure the `locations` attribute with
|
||
an array that contains the resource locations of XML configuration metadata. A plain or
|
||
relative path (for example, `context.xml`) is treated as a classpath resource that is
|
||
relative to the package in which the test class is defined. A path starting with a slash
|
||
is treated as an absolute classpath location (for example, `/org/example/config.xml`). A
|
||
path that represents a resource URL (i.e., a path prefixed with `classpath:`, `file:`,
|
||
`http:`, etc.) is used _as is_.
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ExtendWith(SpringExtension.class)
|
||
// ApplicationContext will be loaded from "/app-config.xml" and
|
||
// "/test-config.xml" in the root of the classpath
|
||
@ContextConfiguration(locations={"/app-config.xml", "/test-config.xml"}) // <1>
|
||
class MyTest {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Setting the locations attribute to a list of XML files.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ExtendWith(SpringExtension::class)
|
||
// ApplicationContext will be loaded from "/app-config.xml" and
|
||
// "/test-config.xml" in the root of the classpath
|
||
@ContextConfiguration("/app-config.xml", "/test-config.xml") // <1>
|
||
class MyTest {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Setting the locations attribute to a list of XML files.
|
||
|
||
|
||
`@ContextConfiguration` supports an alias for the `locations` attribute through the
|
||
standard Java `value` attribute. Thus, if you do not need to declare additional
|
||
attributes in `@ContextConfiguration`, you can omit the declaration of the `locations`
|
||
attribute name and declare the resource locations by using the shorthand format
|
||
demonstrated in the following example:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ExtendWith(SpringExtension.class)
|
||
@ContextConfiguration({"/app-config.xml", "/test-config.xml"}) <1>
|
||
class MyTest {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Specifying XML files without using the `location` attribute.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ExtendWith(SpringExtension::class)
|
||
@ContextConfiguration("/app-config.xml", "/test-config.xml") // <1>
|
||
class MyTest {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Specifying XML files without using the `location` attribute.
|
||
|
||
|
||
If you omit both the `locations` and the `value` attributes from the
|
||
`@ContextConfiguration` annotation, the TestContext framework tries to detect a default
|
||
XML resource location. Specifically, `GenericXmlContextLoader` and
|
||
`GenericXmlWebContextLoader` detect a default location based on the name of the test
|
||
class. If your class is named `com.example.MyTest`, `GenericXmlContextLoader` loads your
|
||
application context from `"classpath:com/example/MyTest-context.xml"`. The following
|
||
example shows how to do so:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ExtendWith(SpringExtension.class)
|
||
// ApplicationContext will be loaded from
|
||
// "classpath:com/example/MyTest-context.xml"
|
||
@ContextConfiguration // <1>
|
||
class MyTest {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Loading configuration from the default location.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ExtendWith(SpringExtension::class)
|
||
// ApplicationContext will be loaded from
|
||
// "classpath:com/example/MyTest-context.xml"
|
||
@ContextConfiguration // <1>
|
||
class MyTest {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Loading configuration from the default location.
|
||
|
||
|
||
[[testcontext-ctx-management-groovy]]
|
||
===== Context Configuration with Groovy Scripts
|
||
|
||
To load an `ApplicationContext` for your tests by using Groovy scripts that use the
|
||
<<core.adoc#groovy-bean-definition-dsl, Groovy Bean Definition DSL>>, you can annotate
|
||
your test class with `@ContextConfiguration` and configure the `locations` or `value`
|
||
attribute with an array that contains the resource locations of Groovy scripts. Resource
|
||
lookup semantics for Groovy scripts are the same as those described for
|
||
<<testcontext-ctx-management-xml, XML configuration files>>.
|
||
|
||
.Enabling Groovy script support
|
||
TIP: Support for using Groovy scripts to load an `ApplicationContext` in the Spring
|
||
TestContext Framework is enabled automatically if Groovy is on the classpath.
|
||
|
||
The following example shows how to specify Groovy configuration files:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ExtendWith(SpringExtension.class)
|
||
// ApplicationContext will be loaded from "/AppConfig.groovy" and
|
||
// "/TestConfig.groovy" in the root of the classpath
|
||
@ContextConfiguration({"/AppConfig.groovy", "/TestConfig.Groovy"}) <1>
|
||
class MyTest {
|
||
// class body...
|
||
}
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ExtendWith(SpringExtension::class)
|
||
// ApplicationContext will be loaded from "/AppConfig.groovy" and
|
||
// "/TestConfig.groovy" in the root of the classpath
|
||
@ContextConfiguration("/AppConfig.groovy", "/TestConfig.Groovy") // <1>
|
||
class MyTest {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Specifying the location of Groovy configuration files.
|
||
|
||
|
||
If you omit both the `locations` and `value` attributes from the `@ContextConfiguration`
|
||
annotation, the TestContext framework tries to detect a default Groovy script.
|
||
Specifically, `GenericGroovyXmlContextLoader` and `GenericGroovyXmlWebContextLoader`
|
||
detect a default location based on the name of the test class. If your class is named
|
||
`com.example.MyTest`, the Groovy context loader loads your application context from
|
||
`"classpath:com/example/MyTestContext.groovy"`. The following example shows how to use
|
||
the default:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ExtendWith(SpringExtension.class)
|
||
// ApplicationContext will be loaded from
|
||
// "classpath:com/example/MyTestContext.groovy"
|
||
@ContextConfiguration // <1>
|
||
class MyTest {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Loading configuration from the default location.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ExtendWith(SpringExtension::class)
|
||
// ApplicationContext will be loaded from
|
||
// "classpath:com/example/MyTestContext.groovy"
|
||
@ContextConfiguration // <1>
|
||
class MyTest {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Loading configuration from the default location.
|
||
|
||
|
||
.Declaring XML configuration and Groovy scripts simultaneously
|
||
[TIP]
|
||
=====
|
||
You can declare both XML configuration files and Groovy scripts simultaneously by using
|
||
the `locations` or `value` attribute of `@ContextConfiguration`. If the path to a
|
||
configured resource location ends with `.xml`, it is loaded by using an
|
||
`XmlBeanDefinitionReader`. Otherwise, it is loaded by using a
|
||
`GroovyBeanDefinitionReader`.
|
||
|
||
The following listing shows how to combine both in an integration test:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ExtendWith(SpringExtension.class)
|
||
// ApplicationContext will be loaded from
|
||
// "/app-config.xml" and "/TestConfig.groovy"
|
||
@ContextConfiguration({ "/app-config.xml", "/TestConfig.groovy" })
|
||
class MyTest {
|
||
// class body...
|
||
}
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ExtendWith(SpringExtension::class)
|
||
// ApplicationContext will be loaded from
|
||
// "/app-config.xml" and "/TestConfig.groovy"
|
||
@ContextConfiguration("/app-config.xml", "/TestConfig.groovy")
|
||
class MyTest {
|
||
// class body...
|
||
}
|
||
----
|
||
=====
|
||
|
||
[[testcontext-ctx-management-javaconfig]]
|
||
===== Context Configuration with Component Classes
|
||
|
||
To load an `ApplicationContext` for your tests by using component classes (see
|
||
<<core.adoc#beans-java, Java-based container configuration>>), you can annotate your test
|
||
class with `@ContextConfiguration` and configure the `classes` attribute with an array
|
||
that contains references to component classes. The following example shows how to do so:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ExtendWith(SpringExtension.class)
|
||
// ApplicationContext will be loaded from AppConfig and TestConfig
|
||
@ContextConfiguration(classes = {AppConfig.class, TestConfig.class}) // <1>
|
||
class MyTest {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Specifying component classes.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ExtendWith(SpringExtension::class)
|
||
// ApplicationContext will be loaded from AppConfig and TestConfig
|
||
@ContextConfiguration(classes = [AppConfig::class, TestConfig::class]) // <1>
|
||
class MyTest {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Specifying component classes.
|
||
|
||
|
||
[[testcontext-ctx-management-javaconfig-component-classes]]
|
||
.Component Classes
|
||
[TIP]
|
||
====
|
||
The term "`component class`" can refer to any of the following:
|
||
|
||
* A class annotated with `@Configuration`.
|
||
* A component (that is, a class annotated with `@Component`, `@Service`, `@Repository`, or other stereotype annotations).
|
||
* A JSR-330 compliant class that is annotated with `javax.inject` annotations.
|
||
* Any class that contains `@Bean`-methods.
|
||
* Any other class that is intended to be registered as a Spring component (i.e., a Spring
|
||
bean in the `ApplicationContext`), potentially taking advantage of automatic autowiring
|
||
of a single constructor without the use of Spring annotations.
|
||
|
||
See the javadoc of
|
||
{api-spring-framework}/context/annotation/Configuration.html[`@Configuration`] and
|
||
{api-spring-framework}/context/annotation/Bean.html[`@Bean`] for further information
|
||
regarding the configuration and semantics of component classes, paying special attention
|
||
to the discussion of `@Bean` Lite Mode.
|
||
====
|
||
|
||
If you omit the `classes` attribute from the `@ContextConfiguration` annotation, the
|
||
TestContext framework tries to detect the presence of default configuration classes.
|
||
Specifically, `AnnotationConfigContextLoader` and `AnnotationConfigWebContextLoader`
|
||
detect all `static` nested classes of the test class that meet the requirements for
|
||
configuration class implementations, as specified in the
|
||
{api-spring-framework}/context/annotation/Configuration.html[`@Configuration`] javadoc.
|
||
Note that the name of the configuration class is arbitrary. In addition, a test class can
|
||
contain more than one `static` nested configuration class if desired. In the following
|
||
example, the `OrderServiceTest` class declares a `static` nested configuration class
|
||
named `Config` that is automatically used to load the `ApplicationContext` for the test
|
||
class:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@SpringJUnitConfig <1>
|
||
// ApplicationContext will be loaded from the
|
||
// static nested Config class
|
||
class OrderServiceTest {
|
||
|
||
@Configuration
|
||
static class Config {
|
||
|
||
// this bean will be injected into the OrderServiceTest class
|
||
@Bean
|
||
OrderService orderService() {
|
||
OrderService orderService = new OrderServiceImpl();
|
||
// set properties, etc.
|
||
return orderService;
|
||
}
|
||
}
|
||
|
||
@Autowired
|
||
OrderService orderService;
|
||
|
||
@Test
|
||
void testOrderService() {
|
||
// test the orderService
|
||
}
|
||
|
||
}
|
||
----
|
||
<1> Loading configuration information from the nested `Config` class.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@SpringJUnitConfig <1>
|
||
// ApplicationContext will be loaded from the nested Config class
|
||
class OrderServiceTest {
|
||
|
||
@Autowired
|
||
lateinit var orderService: OrderService
|
||
|
||
@Configuration
|
||
class Config {
|
||
|
||
// this bean will be injected into the OrderServiceTest class
|
||
@Bean
|
||
fun orderService(): OrderService {
|
||
// set properties, etc.
|
||
return OrderServiceImpl()
|
||
}
|
||
}
|
||
|
||
@Test
|
||
fun testOrderService() {
|
||
// test the orderService
|
||
}
|
||
}
|
||
----
|
||
<1> Loading configuration information from the nested `Config` class.
|
||
|
||
|
||
[[testcontext-ctx-management-mixed-config]]
|
||
===== Mixing XML, Groovy Scripts, and Component Classes
|
||
|
||
It may sometimes be desirable to mix XML configuration files, Groovy scripts, and
|
||
component classes (typically `@Configuration` classes) to configure an
|
||
`ApplicationContext` for your tests. For example, if you use XML configuration in
|
||
production, you may decide that you want to use `@Configuration` classes to configure
|
||
specific Spring-managed components for your tests, or vice versa.
|
||
|
||
Furthermore, some third-party frameworks (such as Spring Boot) provide first-class
|
||
support for loading an `ApplicationContext` from different types of resources
|
||
simultaneously (for example, XML configuration files, Groovy scripts, and
|
||
`@Configuration` classes). The Spring Framework, historically, has not supported this for
|
||
standard deployments. Consequently, most of the `SmartContextLoader` implementations that
|
||
the Spring Framework delivers in the `spring-test` module support only one resource type
|
||
for each test context. However, this does not mean that you cannot use both. One
|
||
exception to the general rule is that the `GenericGroovyXmlContextLoader` and
|
||
`GenericGroovyXmlWebContextLoader` support both XML configuration files and Groovy
|
||
scripts simultaneously. Furthermore, third-party frameworks may choose to support the
|
||
declaration of both `locations` and `classes` through `@ContextConfiguration`, and, with
|
||
the standard testing support in the TestContext framework, you have the following options.
|
||
|
||
If you want to use resource locations (for example, XML or Groovy) and `@Configuration`
|
||
classes to configure your tests, you must pick one as the entry point, and that one must
|
||
include or import the other. For example, in XML or Groovy scripts, you can include
|
||
`@Configuration` classes by using component scanning or defining them as normal Spring
|
||
beans, whereas, in a `@Configuration` class, you can use `@ImportResource` to import XML
|
||
configuration files or Groovy scripts. Note that this behavior is semantically equivalent
|
||
to how you configure your application in production: In production configuration, you
|
||
define either a set of XML or Groovy resource locations or a set of `@Configuration`
|
||
classes from which your production `ApplicationContext` is loaded, but you still have the
|
||
freedom to include or import the other type of configuration.
|
||
|
||
[[testcontext-ctx-management-initializers]]
|
||
===== Context Configuration with Context Initializers
|
||
|
||
To configure an `ApplicationContext` for your tests by using context initializers,
|
||
annotate your test class with `@ContextConfiguration` and configure the `initializers`
|
||
attribute with an array that contains references to classes that implement
|
||
`ApplicationContextInitializer`. The declared context initializers are then used to
|
||
initialize the `ConfigurableApplicationContext` that is loaded for your tests. Note that
|
||
the concrete `ConfigurableApplicationContext` type supported by each declared initializer
|
||
must be compatible with the type of `ApplicationContext` created by the
|
||
`SmartContextLoader` in use (typically a `GenericApplicationContext`). Furthermore, the
|
||
order in which the initializers are invoked depends on whether they implement Spring's
|
||
`Ordered` interface or are annotated with Spring's `@Order` annotation or the standard
|
||
`@Priority` annotation. The following example shows how to use initializers:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ExtendWith(SpringExtension.class)
|
||
// ApplicationContext will be loaded from TestConfig
|
||
// and initialized by TestAppCtxInitializer
|
||
@ContextConfiguration(
|
||
classes = TestConfig.class,
|
||
initializers = TestAppCtxInitializer.class) // <1>
|
||
class MyTest {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Specifying configuration by using a configuration class and an initializer.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ExtendWith(SpringExtension::class)
|
||
// ApplicationContext will be loaded from TestConfig
|
||
// and initialized by TestAppCtxInitializer
|
||
@ContextConfiguration(
|
||
classes = [TestConfig::class],
|
||
initializers = [TestAppCtxInitializer::class]) // <1>
|
||
class MyTest {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Specifying configuration by using a configuration class and an initializer.
|
||
|
||
|
||
You can also omit the declaration of XML configuration files, Groovy scripts, or
|
||
component classes in `@ContextConfiguration` entirely and instead declare only
|
||
`ApplicationContextInitializer` classes, which are then responsible for registering beans
|
||
in the context -- for example, by programmatically loading bean definitions from XML
|
||
files or configuration classes. The following example shows how to do so:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ExtendWith(SpringExtension.class)
|
||
// ApplicationContext will be initialized by EntireAppInitializer
|
||
// which presumably registers beans in the context
|
||
@ContextConfiguration(initializers = EntireAppInitializer.class) <1>
|
||
class MyTest {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Specifying configuration by using only an initializer.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ExtendWith(SpringExtension::class)
|
||
// ApplicationContext will be initialized by EntireAppInitializer
|
||
// which presumably registers beans in the context
|
||
@ContextConfiguration(initializers = [EntireAppInitializer::class]) // <1>
|
||
class MyTest {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Specifying configuration by using only an initializer.
|
||
|
||
|
||
[[testcontext-ctx-management-inheritance]]
|
||
===== Context Configuration Inheritance
|
||
|
||
`@ContextConfiguration` supports boolean `inheritLocations` and `inheritInitializers`
|
||
attributes that denote whether resource locations or component classes and context
|
||
initializers declared by superclasses should be inherited. The default value for both
|
||
flags is `true`. This means that a test class inherits the resource locations or
|
||
component classes as well as the context initializers declared by any superclasses.
|
||
Specifically, the resource locations or component classes for a test class are appended
|
||
to the list of resource locations or annotated classes declared by superclasses.
|
||
Similarly, the initializers for a given test class are added to the set of initializers
|
||
defined by test superclasses. Thus, subclasses have the option of extending the resource
|
||
locations, component classes, or context initializers.
|
||
|
||
If the `inheritLocations` or `inheritInitializers` attribute in `@ContextConfiguration`
|
||
is set to `false`, the resource locations or component classes and the context
|
||
initializers, respectively, for the test class shadow and effectively replace the
|
||
configuration defined by superclasses.
|
||
|
||
In the next example, which uses XML resource locations, the `ApplicationContext` for
|
||
`ExtendedTest` is loaded from `base-config.xml` and `extended-config.xml`, in that order.
|
||
Beans defined in `extended-config.xml` can, therefore, override (that is, replace) those
|
||
defined in `base-config.xml`. The following example shows how one class can extend
|
||
another and use both its own configuration file and the superclass's configuration file:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ExtendWith(SpringExtension.class)
|
||
// ApplicationContext will be loaded from "/base-config.xml"
|
||
// in the root of the classpath
|
||
@ContextConfiguration("/base-config.xml") <1>
|
||
class BaseTest {
|
||
// class body...
|
||
}
|
||
|
||
// ApplicationContext will be loaded from "/base-config.xml" and
|
||
// "/extended-config.xml" in the root of the classpath
|
||
@ContextConfiguration("/extended-config.xml") <2>
|
||
class ExtendedTest extends BaseTest {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Configuration file defined in the superclass.
|
||
<2> Configuration file defined in the subclass.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ExtendWith(SpringExtension::class)
|
||
// ApplicationContext will be loaded from "/base-config.xml"
|
||
// in the root of the classpath
|
||
@ContextConfiguration("/base-config.xml") // <1>
|
||
open class BaseTest {
|
||
// class body...
|
||
}
|
||
|
||
// ApplicationContext will be loaded from "/base-config.xml" and
|
||
// "/extended-config.xml" in the root of the classpath
|
||
@ContextConfiguration("/extended-config.xml") // <2>
|
||
class ExtendedTest : BaseTest() {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Configuration file defined in the superclass.
|
||
<2> Configuration file defined in the subclass.
|
||
|
||
|
||
Similarly, in the next example, which uses component classes, the `ApplicationContext`
|
||
for `ExtendedTest` is loaded from the `BaseConfig` and `ExtendedConfig` classes, in that
|
||
order. Beans defined in `ExtendedConfig` can, therefore, override (that is, replace)
|
||
those defined in `BaseConfig`. The following example shows how one class can extend
|
||
another and use both its own configuration class and the superclass's configuration class:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
// ApplicationContext will be loaded from BaseConfig
|
||
@SpringJUnitConfig(BaseConfig.class) // <1>
|
||
class BaseTest {
|
||
// class body...
|
||
}
|
||
|
||
// ApplicationContext will be loaded from BaseConfig and ExtendedConfig
|
||
@SpringJUnitConfig(ExtendedConfig.class) // <2>
|
||
class ExtendedTest extends BaseTest {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Configuration class defined in the superclass.
|
||
<2> Configuration class defined in the subclass.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
// ApplicationContext will be loaded from BaseConfig
|
||
@SpringJUnitConfig(BaseConfig::class) // <1>
|
||
open class BaseTest {
|
||
// class body...
|
||
}
|
||
|
||
// ApplicationContext will be loaded from BaseConfig and ExtendedConfig
|
||
@SpringJUnitConfig(ExtendedConfig::class) // <2>
|
||
class ExtendedTest : BaseTest() {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Configuration class defined in the superclass.
|
||
<2> Configuration class defined in the subclass.
|
||
|
||
|
||
In the next example, which uses context initializers, the `ApplicationContext` for
|
||
`ExtendedTest` is initialized by using `BaseInitializer` and `ExtendedInitializer`. Note,
|
||
however, that the order in which the initializers are invoked depends on whether they
|
||
implement Spring's `Ordered` interface or are annotated with Spring's `@Order` annotation
|
||
or the standard `@Priority` annotation. The following example shows how one class can
|
||
extend another and use both its own initializer and the superclass's initializer:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
// ApplicationContext will be initialized by BaseInitializer
|
||
@SpringJUnitConfig(initializers = BaseInitializer.class) // <1>
|
||
class BaseTest {
|
||
// class body...
|
||
}
|
||
|
||
// ApplicationContext will be initialized by BaseInitializer
|
||
// and ExtendedInitializer
|
||
@SpringJUnitConfig(initializers = ExtendedInitializer.class) // <2>
|
||
class ExtendedTest extends BaseTest {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Initializer defined in the superclass.
|
||
<2> Initializer defined in the subclass.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
// ApplicationContext will be initialized by BaseInitializer
|
||
@SpringJUnitConfig(initializers = [BaseInitializer::class]) // <1>
|
||
open class BaseTest {
|
||
// class body...
|
||
}
|
||
|
||
// ApplicationContext will be initialized by BaseInitializer
|
||
// and ExtendedInitializer
|
||
@SpringJUnitConfig(initializers = [ExtendedInitializer::class]) // <2>
|
||
class ExtendedTest : BaseTest() {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Initializer defined in the superclass.
|
||
<2> Initializer defined in the subclass.
|
||
|
||
|
||
[[testcontext-ctx-management-env-profiles]]
|
||
===== Context Configuration with Environment Profiles
|
||
|
||
The Spring Framework has first-class support for the notion of environments and profiles
|
||
(AKA "bean definition profiles"), and integration tests can be configured to activate
|
||
particular bean definition profiles for various testing scenarios. This is achieved by
|
||
annotating a test class with the `@ActiveProfiles` annotation and supplying a list of
|
||
profiles that should be activated when loading the `ApplicationContext` for the test.
|
||
|
||
NOTE: You can use `@ActiveProfiles` with any implementation of the `SmartContextLoader`
|
||
SPI, but `@ActiveProfiles` is not supported with implementations of the older
|
||
`ContextLoader` SPI.
|
||
|
||
Consider two examples with XML configuration and `@Configuration` classes:
|
||
|
||
[source,xml,indent=0,subs="verbatim,quotes"]
|
||
----
|
||
<!-- app-config.xml -->
|
||
<beans xmlns="http://www.springframework.org/schema/beans"
|
||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||
xmlns:jdbc="http://www.springframework.org/schema/jdbc"
|
||
xmlns:jee="http://www.springframework.org/schema/jee"
|
||
xsi:schemaLocation="...">
|
||
|
||
<bean id="transferService"
|
||
class="com.bank.service.internal.DefaultTransferService">
|
||
<constructor-arg ref="accountRepository"/>
|
||
<constructor-arg ref="feePolicy"/>
|
||
</bean>
|
||
|
||
<bean id="accountRepository"
|
||
class="com.bank.repository.internal.JdbcAccountRepository">
|
||
<constructor-arg ref="dataSource"/>
|
||
</bean>
|
||
|
||
<bean id="feePolicy"
|
||
class="com.bank.service.internal.ZeroFeePolicy"/>
|
||
|
||
<beans profile="dev">
|
||
<jdbc:embedded-database id="dataSource">
|
||
<jdbc:script
|
||
location="classpath:com/bank/config/sql/schema.sql"/>
|
||
<jdbc:script
|
||
location="classpath:com/bank/config/sql/test-data.sql"/>
|
||
</jdbc:embedded-database>
|
||
</beans>
|
||
|
||
<beans profile="production">
|
||
<jee:jndi-lookup id="dataSource" jndi-name="java:comp/env/jdbc/datasource"/>
|
||
</beans>
|
||
|
||
<beans profile="default">
|
||
<jdbc:embedded-database id="dataSource">
|
||
<jdbc:script
|
||
location="classpath:com/bank/config/sql/schema.sql"/>
|
||
</jdbc:embedded-database>
|
||
</beans>
|
||
|
||
</beans>
|
||
----
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ExtendWith(SpringExtension.class)
|
||
// ApplicationContext will be loaded from "classpath:/app-config.xml"
|
||
@ContextConfiguration("/app-config.xml")
|
||
@ActiveProfiles("dev")
|
||
class TransferServiceTest {
|
||
|
||
@Autowired
|
||
TransferService transferService;
|
||
|
||
@Test
|
||
void testTransferService() {
|
||
// test the transferService
|
||
}
|
||
}
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ExtendWith(SpringExtension::class)
|
||
// ApplicationContext will be loaded from "classpath:/app-config.xml"
|
||
@ContextConfiguration("/app-config.xml")
|
||
@ActiveProfiles("dev")
|
||
class TransferServiceTest {
|
||
|
||
@Autowired
|
||
lateinit var transferService: TransferService
|
||
|
||
@Test
|
||
fun testTransferService() {
|
||
// test the transferService
|
||
}
|
||
}
|
||
----
|
||
|
||
When `TransferServiceTest` is run, its `ApplicationContext` is loaded from the
|
||
`app-config.xml` configuration file in the root of the classpath. If you inspect
|
||
`app-config.xml`, you can see that the `accountRepository` bean has a dependency on a
|
||
`dataSource` bean. However, `dataSource` is not defined as a top-level bean. Instead,
|
||
`dataSource` is defined three times: in the `production` profile, in the `dev` profile,
|
||
and in the `default` profile.
|
||
|
||
By annotating `TransferServiceTest` with `@ActiveProfiles("dev")`, we instruct the Spring
|
||
TestContext Framework to load the `ApplicationContext` with the active profiles set to
|
||
`{"dev"}`. As a result, an embedded database is created and populated with test data, and
|
||
the `accountRepository` bean is wired with a reference to the development `DataSource`.
|
||
That is likely what we want in an integration test.
|
||
|
||
It is sometimes useful to assign beans to a `default` profile. Beans within the default
|
||
profile are included only when no other profile is specifically activated. You can use
|
||
this to define "`fallback`" beans to be used in the application's default state. For
|
||
example, you may explicitly provide a data source for `dev` and `production` profiles,
|
||
but define an in-memory data source as a default when neither of these is active.
|
||
|
||
The following code listings demonstrate how to implement the same configuration and
|
||
integration test with `@Configuration` classes instead of XML:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@Configuration
|
||
@Profile("dev")
|
||
public class StandaloneDataConfig {
|
||
|
||
@Bean
|
||
public DataSource dataSource() {
|
||
return new EmbeddedDatabaseBuilder()
|
||
.setType(EmbeddedDatabaseType.HSQL)
|
||
.addScript("classpath:com/bank/config/sql/schema.sql")
|
||
.addScript("classpath:com/bank/config/sql/test-data.sql")
|
||
.build();
|
||
}
|
||
}
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@Configuration
|
||
@Profile("dev")
|
||
class StandaloneDataConfig {
|
||
|
||
@Bean
|
||
fun dataSource(): DataSource {
|
||
return EmbeddedDatabaseBuilder()
|
||
.setType(EmbeddedDatabaseType.HSQL)
|
||
.addScript("classpath:com/bank/config/sql/schema.sql")
|
||
.addScript("classpath:com/bank/config/sql/test-data.sql")
|
||
.build()
|
||
}
|
||
}
|
||
----
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@Configuration
|
||
@Profile("production")
|
||
public class JndiDataConfig {
|
||
|
||
@Bean(destroyMethod="")
|
||
public DataSource dataSource() throws Exception {
|
||
Context ctx = new InitialContext();
|
||
return (DataSource) ctx.lookup("java:comp/env/jdbc/datasource");
|
||
}
|
||
}
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@Configuration
|
||
@Profile("production")
|
||
class JndiDataConfig {
|
||
|
||
@Bean(destroyMethod = "")
|
||
fun dataSource(): DataSource {
|
||
val ctx = InitialContext()
|
||
return ctx.lookup("java:comp/env/jdbc/datasource") as DataSource
|
||
}
|
||
}
|
||
----
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@Configuration
|
||
@Profile("default")
|
||
public class DefaultDataConfig {
|
||
|
||
@Bean
|
||
public DataSource dataSource() {
|
||
return new EmbeddedDatabaseBuilder()
|
||
.setType(EmbeddedDatabaseType.HSQL)
|
||
.addScript("classpath:com/bank/config/sql/schema.sql")
|
||
.build();
|
||
}
|
||
}
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@Configuration
|
||
@Profile("default")
|
||
class DefaultDataConfig {
|
||
|
||
@Bean
|
||
fun dataSource(): DataSource {
|
||
return EmbeddedDatabaseBuilder()
|
||
.setType(EmbeddedDatabaseType.HSQL)
|
||
.addScript("classpath:com/bank/config/sql/schema.sql")
|
||
.build()
|
||
}
|
||
}
|
||
----
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@Configuration
|
||
public class TransferServiceConfig {
|
||
|
||
@Autowired DataSource dataSource;
|
||
|
||
@Bean
|
||
public TransferService transferService() {
|
||
return new DefaultTransferService(accountRepository(), feePolicy());
|
||
}
|
||
|
||
@Bean
|
||
public AccountRepository accountRepository() {
|
||
return new JdbcAccountRepository(dataSource);
|
||
}
|
||
|
||
@Bean
|
||
public FeePolicy feePolicy() {
|
||
return new ZeroFeePolicy();
|
||
}
|
||
}
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@Configuration
|
||
class TransferServiceConfig {
|
||
|
||
@Autowired
|
||
lateinit var dataSource: DataSource
|
||
|
||
@Bean
|
||
fun transferService(): TransferService {
|
||
return DefaultTransferService(accountRepository(), feePolicy())
|
||
}
|
||
|
||
@Bean
|
||
fun accountRepository(): AccountRepository {
|
||
return JdbcAccountRepository(dataSource)
|
||
}
|
||
|
||
@Bean
|
||
fun feePolicy(): FeePolicy {
|
||
return ZeroFeePolicy()
|
||
}
|
||
}
|
||
----
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@SpringJUnitConfig({
|
||
TransferServiceConfig.class,
|
||
StandaloneDataConfig.class,
|
||
JndiDataConfig.class,
|
||
DefaultDataConfig.class})
|
||
@ActiveProfiles("dev")
|
||
class TransferServiceTest {
|
||
|
||
@Autowired
|
||
TransferService transferService;
|
||
|
||
@Test
|
||
void testTransferService() {
|
||
// test the transferService
|
||
}
|
||
}
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@SpringJUnitConfig(
|
||
TransferServiceConfig::class,
|
||
StandaloneDataConfig::class,
|
||
JndiDataConfig::class,
|
||
DefaultDataConfig::class)
|
||
@ActiveProfiles("dev")
|
||
class TransferServiceTest {
|
||
|
||
@Autowired
|
||
lateinit var transferService: TransferService
|
||
|
||
@Test
|
||
fun testTransferService() {
|
||
// test the transferService
|
||
}
|
||
}
|
||
----
|
||
|
||
In this variation, we have split the XML configuration into four independent
|
||
`@Configuration` classes:
|
||
|
||
* `TransferServiceConfig`: Acquires a `dataSource` through dependency injection by using
|
||
`@Autowired`.
|
||
* `StandaloneDataConfig`: Defines a `dataSource` for an embedded database suitable for
|
||
developer tests.
|
||
* `JndiDataConfig`: Defines a `dataSource` that is retrieved from JNDI in a production
|
||
environment.
|
||
* `DefaultDataConfig`: Defines a `dataSource` for a default embedded database, in case no
|
||
profile is active.
|
||
|
||
As with the XML-based configuration example, we still annotate `TransferServiceTest` with
|
||
`@ActiveProfiles("dev")`, but this time we specify all four configuration classes by
|
||
using the `@ContextConfiguration` annotation. The body of the test class itself remains
|
||
completely unchanged.
|
||
|
||
It is often the case that a single set of profiles is used across multiple test classes
|
||
within a given project. Thus, to avoid duplicate declarations of the `@ActiveProfiles`
|
||
annotation, you can declare `@ActiveProfiles` once on a base class, and subclasses
|
||
automatically inherit the `@ActiveProfiles` configuration from the base class. In the
|
||
following example, the declaration of `@ActiveProfiles` (as well as other annotations)
|
||
has been moved to an abstract superclass, `AbstractIntegrationTest`:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@SpringJUnitConfig({
|
||
TransferServiceConfig.class,
|
||
StandaloneDataConfig.class,
|
||
JndiDataConfig.class,
|
||
DefaultDataConfig.class})
|
||
@ActiveProfiles("dev")
|
||
abstract class AbstractIntegrationTest {
|
||
}
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@SpringJUnitConfig(
|
||
TransferServiceConfig::class,
|
||
StandaloneDataConfig::class,
|
||
JndiDataConfig::class,
|
||
DefaultDataConfig::class)
|
||
@ActiveProfiles("dev")
|
||
abstract class AbstractIntegrationTest {
|
||
}
|
||
----
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
// "dev" profile inherited from superclass
|
||
class TransferServiceTest extends AbstractIntegrationTest {
|
||
|
||
@Autowired
|
||
TransferService transferService;
|
||
|
||
@Test
|
||
void testTransferService() {
|
||
// test the transferService
|
||
}
|
||
}
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
// "dev" profile inherited from superclass
|
||
class TransferServiceTest : AbstractIntegrationTest() {
|
||
|
||
@Autowired
|
||
lateinit var transferService: TransferService
|
||
|
||
@Test
|
||
fun testTransferService() {
|
||
// test the transferService
|
||
}
|
||
}
|
||
----
|
||
|
||
`@ActiveProfiles` also supports an `inheritProfiles` attribute that can be used to
|
||
disable the inheritance of active profiles, as the following example shows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
// "dev" profile overridden with "production"
|
||
@ActiveProfiles(profiles = "production", inheritProfiles = false)
|
||
class ProductionTransferServiceTest extends AbstractIntegrationTest {
|
||
// test body
|
||
}
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
// "dev" profile overridden with "production"
|
||
@ActiveProfiles("production", inheritProfiles = false)
|
||
class ProductionTransferServiceTest : AbstractIntegrationTest() {
|
||
// test body
|
||
}
|
||
----
|
||
|
||
[[testcontext-ctx-management-env-profiles-ActiveProfilesResolver]]
|
||
Furthermore, it is sometimes necessary to resolve active profiles for tests
|
||
programmatically instead of declaratively -- for example, based on:
|
||
|
||
* The current operating system.
|
||
* Whether tests are being run on a continuous integration build server.
|
||
* The presence of certain environment variables.
|
||
* The presence of custom class-level annotations.
|
||
* Other concerns.
|
||
|
||
To resolve active bean definition profiles programmatically, you can implement
|
||
a custom `ActiveProfilesResolver` and register it by using the `resolver`
|
||
attribute of `@ActiveProfiles`. For further information, see the corresponding
|
||
{api-spring-framework}/test/context/ActiveProfilesResolver.html[javadoc].
|
||
The following example demonstrates how to implement and register a custom
|
||
`OperatingSystemActiveProfilesResolver`:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
// "dev" profile overridden programmatically via a custom resolver
|
||
@ActiveProfiles(
|
||
resolver = OperatingSystemActiveProfilesResolver.class,
|
||
inheritProfiles = false)
|
||
class TransferServiceTest extends AbstractIntegrationTest {
|
||
// test body
|
||
}
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
// "dev" profile overridden programmatically via a custom resolver
|
||
@ActiveProfiles(
|
||
resolver = OperatingSystemActiveProfilesResolver::class,
|
||
inheritProfiles = false)
|
||
class TransferServiceTest : AbstractIntegrationTest() {
|
||
// test body
|
||
}
|
||
----
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
public class OperatingSystemActiveProfilesResolver implements ActiveProfilesResolver {
|
||
|
||
@Override
|
||
public String[] resolve(Class<?> testClass) {
|
||
String profile = ...;
|
||
// determine the value of profile based on the operating system
|
||
return new String[] {profile};
|
||
}
|
||
}
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
class OperatingSystemActiveProfilesResolver : ActiveProfilesResolver {
|
||
|
||
override fun resolve(testClass: Class<*>): Array<String> {
|
||
val profile: String = ...
|
||
// determine the value of profile based on the operating system
|
||
return arrayOf(profile)
|
||
}
|
||
}
|
||
----
|
||
|
||
[[testcontext-ctx-management-property-sources]]
|
||
===== Context Configuration with Test Property Sources
|
||
|
||
The Spring Framework has first-class support for the notion of an environment with a
|
||
hierarchy of property sources, and you can configure integration tests with test-specific
|
||
property sources. In contrast to the `@PropertySource` annotation used on
|
||
`@Configuration` classes, you can declare the `@TestPropertySource` annotation on a test
|
||
class to declare resource locations for test properties files or inlined properties.
|
||
These test property sources are added to the set of `PropertySources` in the
|
||
`Environment` for the `ApplicationContext` loaded for the annotated integration test.
|
||
|
||
[NOTE]
|
||
====
|
||
You can use `@TestPropertySource` with any implementation of the `SmartContextLoader`
|
||
SPI, but `@TestPropertySource` is not supported with implementations of the older
|
||
`ContextLoader` SPI.
|
||
|
||
Implementations of `SmartContextLoader` gain access to merged test property source values
|
||
through the `getPropertySourceLocations()` and `getPropertySourceProperties()` methods in
|
||
`MergedContextConfiguration`.
|
||
====
|
||
|
||
====== Declaring Test Property Sources
|
||
|
||
You can configure test properties files by using the `locations` or `value` attribute of
|
||
`@TestPropertySource`.
|
||
|
||
Both traditional and XML-based properties file formats are supported -- for example,
|
||
`"classpath:/com/example/test.properties"` or `"file:///path/to/file.xml"`.
|
||
|
||
Each path is interpreted as a Spring `Resource`. A plain path (for example,
|
||
`"test.properties"`) is treated as a classpath resource that is relative to the package
|
||
in which the test class is defined. A path starting with a slash is treated as an
|
||
absolute classpath resource (for example: `"/org/example/test.xml"`). A path that
|
||
references a URL (for example, a path prefixed with `classpath:`, `file:`, or `http:`) is
|
||
loaded by using the specified resource protocol. Resource location wildcards (such as
|
||
`**/*.properties`) are not permitted: Each location must evaluate to exactly one
|
||
`.properties` or `.xml` resource.
|
||
|
||
The following example uses a test properties file:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ContextConfiguration
|
||
@TestPropertySource("/test.properties") // <1>
|
||
class MyIntegrationTests {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Specifying a properties file with an absolute path.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ContextConfiguration
|
||
@TestPropertySource("/test.properties") // <1>
|
||
class MyIntegrationTests {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Specifying a properties file with an absolute path.
|
||
|
||
|
||
You can configure inlined properties in the form of key-value pairs by using the
|
||
`properties` attribute of `@TestPropertySource`, as shown in the next example. All
|
||
key-value pairs are added to the enclosing `Environment` as a single test
|
||
`PropertySource` with the highest precedence.
|
||
|
||
The supported syntax for key-value pairs is the same as the syntax defined for entries in
|
||
a Java properties file:
|
||
|
||
* `key=value`
|
||
* `key:value`
|
||
* `key value`
|
||
|
||
The following example sets two inlined properties:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ContextConfiguration
|
||
@TestPropertySource(properties = {"timezone = GMT", "port: 4242"}) // <1>
|
||
class MyIntegrationTests {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Setting two properties by using two variations of the key-value syntax.
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ContextConfiguration
|
||
@TestPropertySource(properties = ["timezone = GMT", "port: 4242"]) // <1>
|
||
class MyIntegrationTests {
|
||
// class body...
|
||
}
|
||
----
|
||
<1> Setting two properties by using two variations of the key-value syntax.
|
||
|
||
[NOTE]
|
||
====
|
||
As of Spring Framework 5.2, `@TestPropertySource` can be used as _repeatable annotation_.
|
||
That means that you can have multiple declarations of `@TestPropertySource` on a single
|
||
test class, with the `locations` and `properties` from later `@TestPropertySource`
|
||
annotations overriding those from previous `@TestPropertySource` annotations.
|
||
|
||
In addition, you may declare multiple composed annotations on a test class that are each
|
||
meta-annotated with `@TestPropertySource`, and all of those `@TestPropertySource`
|
||
declarations will contribute to your test property sources.
|
||
|
||
Directly present `@TestPropertySource` annotations always take precedence over
|
||
meta-present `@TestPropertySource` annotations. In other words, `locations` and
|
||
`properties` from a directly present `@TestPropertySource` annotation will override the
|
||
`locations` and `properties` from a `@TestPropertySource` annotation used as a
|
||
meta-annotation.
|
||
====
|
||
|
||
|
||
====== Default Properties File Detection
|
||
|
||
If `@TestPropertySource` is declared as an empty annotation (that is, without explicit
|
||
values for the `locations` or `properties` attributes), an attempt is made to detect a
|
||
default properties file relative to the class that declared the annotation. For example,
|
||
if the annotated test class is `com.example.MyTest`, the corresponding default properties
|
||
file is `classpath:com/example/MyTest.properties`. If the default cannot be detected, an
|
||
`IllegalStateException` is thrown.
|
||
|
||
====== Precedence
|
||
|
||
Test properties have higher precedence than those defined in the operating system's
|
||
environment, Java system properties, or property sources added by the application
|
||
declaratively by using `@PropertySource` or programmatically. Thus, test properties can
|
||
be used to selectively override properties loaded from system and application property
|
||
sources. Furthermore, inlined properties have higher precedence than properties loaded
|
||
from resource locations. Note, however, that properties registered via
|
||
<<testcontext-ctx-management-dynamic-property-sources, `@DynamicPropertySource`>> have
|
||
higher precedence than those loaded via `@TestPropertySource`.
|
||
|
||
In the next example, the `timezone` and `port` properties and any properties defined in
|
||
`"/test.properties"` override any properties of the same name that are defined in system
|
||
and application property sources. Furthermore, if the `"/test.properties"` file defines
|
||
entries for the `timezone` and `port` properties those are overridden by the inlined
|
||
properties declared by using the `properties` attribute. The following example shows how
|
||
to specify properties both in a file and inline:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ContextConfiguration
|
||
@TestPropertySource(
|
||
locations = "/test.properties",
|
||
properties = {"timezone = GMT", "port: 4242"}
|
||
)
|
||
class MyIntegrationTests {
|
||
// class body...
|
||
}
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ContextConfiguration
|
||
@TestPropertySource("/test.properties",
|
||
properties = ["timezone = GMT", "port: 4242"]
|
||
)
|
||
class MyIntegrationTests {
|
||
// class body...
|
||
}
|
||
----
|
||
|
||
====== Inheriting and Overriding Test Property Sources
|
||
|
||
`@TestPropertySource` supports boolean `inheritLocations` and `inheritProperties`
|
||
attributes that denote whether resource locations for properties files and inlined
|
||
properties declared by superclasses should be inherited. The default value for both flags
|
||
is `true`. This means that a test class inherits the locations and inlined properties
|
||
declared by any superclasses. Specifically, the locations and inlined properties for a
|
||
test class are appended to the locations and inlined properties declared by superclasses.
|
||
Thus, subclasses have the option of extending the locations and inlined properties. Note
|
||
that properties that appear later shadow (that is, override) properties of the same name
|
||
that appear earlier. In addition, the aforementioned precedence rules apply for inherited
|
||
test property sources as well.
|
||
|
||
If the `inheritLocations` or `inheritProperties` attribute in `@TestPropertySource` is
|
||
set to `false`, the locations or inlined properties, respectively, for the test class
|
||
shadow and effectively replace the configuration defined by superclasses.
|
||
|
||
In the next example, the `ApplicationContext` for `BaseTest` is loaded by using only the
|
||
`base.properties` file as a test property source. In contrast, the `ApplicationContext`
|
||
for `ExtendedTest` is loaded by using the `base.properties` and `extended.properties`
|
||
files as test property source locations. The following example shows how to define
|
||
properties in both a subclass and its superclass by using `properties` files:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@TestPropertySource("base.properties")
|
||
@ContextConfiguration
|
||
class BaseTest {
|
||
// ...
|
||
}
|
||
|
||
@TestPropertySource("extended.properties")
|
||
@ContextConfiguration
|
||
class ExtendedTest extends BaseTest {
|
||
// ...
|
||
}
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@TestPropertySource("base.properties")
|
||
@ContextConfiguration
|
||
open class BaseTest {
|
||
// ...
|
||
}
|
||
|
||
@TestPropertySource("extended.properties")
|
||
@ContextConfiguration
|
||
class ExtendedTest : BaseTest() {
|
||
// ...
|
||
}
|
||
----
|
||
|
||
In the next example, the `ApplicationContext` for `BaseTest` is loaded by using only the
|
||
inlined `key1` property. In contrast, the `ApplicationContext` for `ExtendedTest` is
|
||
loaded by using the inlined `key1` and `key2` properties. The following example shows how
|
||
to define properties in both a subclass and its superclass by using inline properties:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@TestPropertySource(properties = "key1 = value1")
|
||
@ContextConfiguration
|
||
class BaseTest {
|
||
// ...
|
||
}
|
||
|
||
@TestPropertySource(properties = "key2 = value2")
|
||
@ContextConfiguration
|
||
class ExtendedTest extends BaseTest {
|
||
// ...
|
||
}
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@TestPropertySource(properties = ["key1 = value1"])
|
||
@ContextConfiguration
|
||
open class BaseTest {
|
||
// ...
|
||
}
|
||
|
||
@TestPropertySource(properties = ["key2 = value2"])
|
||
@ContextConfiguration
|
||
class ExtendedTest : BaseTest() {
|
||
// ...
|
||
}
|
||
----
|
||
|
||
[[testcontext-ctx-management-dynamic-property-sources]]
|
||
===== Context Configuration with Dynamic Property Sources
|
||
|
||
As of Spring Framework 5.2.5, the TestContext framework provides support for _dynamic_
|
||
properties via the `@DynamicPropertySource` annotation. This annotation can be used in
|
||
integration tests that need to add properties with dynamic values to the set of
|
||
`PropertySources` in the `Environment` for the `ApplicationContext` loaded for the
|
||
integration test.
|
||
|
||
NOTE: The `@DynamicPropertySource` annotation and its supporting infrastructure were
|
||
originally designed to allow properties from
|
||
https://www.testcontainers.org/[Testcontainers] based tests to be exposed easily to
|
||
Spring integration tests. However, this feature may also be used with any form of
|
||
external resource whose lifecycle is maintained outside the test's `ApplicationContext`.
|
||
|
||
In contrast to the <<testcontext-ctx-management-property-sources,`@TestPropertySource`>>
|
||
annotation that is applied at the class level, `@DynamicPropertySource` must be applied
|
||
to a `static` method that accepts a single `DynamicPropertyRegistry` argument which is
|
||
used to add _name-value_ pairs to the `Environment`. Values are dynamic and provided via
|
||
a `Supplier` which is only invoked when the property is resolved. Typically, method
|
||
references are used to supply values, as can be seen in the following example which uses
|
||
the Testcontainers project to manage a Redis container outside of the Spring
|
||
`ApplicationContext`. The IP address and port of the managed Redis container are made
|
||
available to components within the test's `ApplicationContext` via the `redis.host` and
|
||
`redis.port` properties. These properties can be accessed via Spring's `Environment`
|
||
abstraction or injected directly into Spring-managed components – for example, via
|
||
`@Value("${redis.host}")` and `@Value("${redis.port}")`, respectively.
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@SpringJUnitConfig(/* ... */)
|
||
@Testcontainers
|
||
class ExampleIntegrationTests {
|
||
|
||
@Container
|
||
static RedisContainer redis = new RedisContainer();
|
||
|
||
@DynamicPropertySource
|
||
static void redisProperties(DynamicPropertyRegistry registry) {
|
||
registry.add("redis.host", redis::getContainerIpAddress);
|
||
registry.add("redis.port", redis::getMappedPort);
|
||
}
|
||
|
||
// tests ...
|
||
|
||
}
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@SpringJUnitConfig(/* ... */)
|
||
@Testcontainers
|
||
class ExampleIntegrationTests {
|
||
|
||
companion object {
|
||
|
||
@Container
|
||
@JvmStatic
|
||
val redis: RedisContainer = RedisContainer()
|
||
|
||
@DynamicPropertySource
|
||
@JvmStatic
|
||
fun redisProperties(registry: DynamicPropertyRegistry) {
|
||
registry.add("redis.host", redis::getContainerIpAddress)
|
||
registry.add("redis.port", redis::getMappedPort)
|
||
}
|
||
}
|
||
|
||
// tests ...
|
||
|
||
}
|
||
----
|
||
|
||
====== Precedence
|
||
|
||
Dynamic properties have higher precedence than those loaded from `@TestPropertySource`,
|
||
the operating system's environment, Java system properties, or property sources added by
|
||
the application declaratively by using `@PropertySource` or programmatically. Thus,
|
||
dynamic properties can be used to selectively override properties loaded via
|
||
`@TestPropertySource`, system property sources, and application property sources.
|
||
|
||
[[testcontext-ctx-management-web]]
|
||
===== Loading a `WebApplicationContext`
|
||
|
||
To instruct the TestContext framework to load a `WebApplicationContext` instead of a
|
||
standard `ApplicationContext`, you can annotate the respective test class with
|
||
`@WebAppConfiguration`.
|
||
|
||
The presence of `@WebAppConfiguration` on your test class instructs the TestContext
|
||
framework (TCF) that a `WebApplicationContext` (WAC) should be loaded for your
|
||
integration tests. In the background, the TCF makes sure that a `MockServletContext` is
|
||
created and supplied to your test's WAC. By default, the base resource path for your
|
||
`MockServletContext` is set to `src/main/webapp`. This is interpreted as a path relative
|
||
to the root of your JVM (normally the path to your project). If you are familiar with the
|
||
directory structure of a web application in a Maven project, you know that
|
||
`src/main/webapp` is the default location for the root of your WAR. If you need to
|
||
override this default, you can provide an alternate path to the `@WebAppConfiguration`
|
||
annotation (for example, `@WebAppConfiguration("src/test/webapp")`). If you wish to
|
||
reference a base resource path from the classpath instead of the file system, you can use
|
||
Spring's `classpath:` prefix.
|
||
|
||
Note that Spring's testing support for `WebApplicationContext` implementations is on par
|
||
with its support for standard `ApplicationContext` implementations. When testing with a
|
||
`WebApplicationContext`, you are free to declare XML configuration files, Groovy scripts,
|
||
or `@Configuration` classes by using `@ContextConfiguration`. You are also free to use
|
||
any other test annotations, such as `@ActiveProfiles`, `@TestExecutionListeners`, `@Sql`,
|
||
`@Rollback`, and others.
|
||
|
||
The remaining examples in this section show some of the various configuration options for
|
||
loading a `WebApplicationContext`. The following example shows the TestContext
|
||
framework's support for convention over configuration:
|
||
|
||
.Conventions
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ExtendWith(SpringExtension.class)
|
||
|
||
// defaults to "file:src/main/webapp"
|
||
@WebAppConfiguration
|
||
|
||
// detects "WacTests-context.xml" in the same package
|
||
// or static nested @Configuration classes
|
||
@ContextConfiguration
|
||
class WacTests {
|
||
//...
|
||
}
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ExtendWith(SpringExtension::class)
|
||
|
||
// defaults to "file:src/main/webapp"
|
||
@WebAppConfiguration
|
||
|
||
// detects "WacTests-context.xml" in the same package
|
||
// or static nested @Configuration classes
|
||
@ContextConfiguration
|
||
class WacTests {
|
||
//...
|
||
}
|
||
----
|
||
|
||
If you annotate a test class with `@WebAppConfiguration` without specifying a resource
|
||
base path, the resource path effectively defaults to `file:src/main/webapp`. Similarly,
|
||
if you declare `@ContextConfiguration` without specifying resource `locations`, component
|
||
`classes`, or context `initializers`, Spring tries to detect the presence of your
|
||
configuration by using conventions (that is, `WacTests-context.xml` in the same package
|
||
as the `WacTests` class or static nested `@Configuration` classes).
|
||
|
||
The following example shows how to explicitly declare a resource base path with
|
||
`@WebAppConfiguration` and an XML resource location with `@ContextConfiguration`:
|
||
|
||
.Default resource semantics
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ExtendWith(SpringExtension.class)
|
||
|
||
// file system resource
|
||
@WebAppConfiguration("webapp")
|
||
|
||
// classpath resource
|
||
@ContextConfiguration("/spring/test-servlet-config.xml")
|
||
class WacTests {
|
||
//...
|
||
}
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ExtendWith(SpringExtension::class)
|
||
|
||
// file system resource
|
||
@WebAppConfiguration("webapp")
|
||
|
||
// classpath resource
|
||
@ContextConfiguration("/spring/test-servlet-config.xml")
|
||
class WacTests {
|
||
//...
|
||
}
|
||
----
|
||
|
||
The important thing to note here is the different semantics for paths with these two
|
||
annotations. By default, `@WebAppConfiguration` resource paths are file system based,
|
||
whereas `@ContextConfiguration` resource locations are classpath based.
|
||
|
||
The following example shows that we can override the default resource semantics for both
|
||
annotations by specifying a Spring resource prefix:
|
||
|
||
.Explicit resource semantics
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ExtendWith(SpringExtension.class)
|
||
|
||
// classpath resource
|
||
@WebAppConfiguration("classpath:test-web-resources")
|
||
|
||
// file system resource
|
||
@ContextConfiguration("file:src/main/webapp/WEB-INF/servlet-config.xml")
|
||
class WacTests {
|
||
//...
|
||
}
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ExtendWith(SpringExtension::class)
|
||
|
||
// classpath resource
|
||
@WebAppConfiguration("classpath:test-web-resources")
|
||
|
||
// file system resource
|
||
@ContextConfiguration("file:src/main/webapp/WEB-INF/servlet-config.xml")
|
||
class WacTests {
|
||
//...
|
||
}
|
||
----
|
||
|
||
Contrast the comments in this example with the previous example.
|
||
|
||
.[[testcontext-ctx-management-web-mocks]]Working with Web Mocks
|
||
--
|
||
To provide comprehensive web testing support, the TestContext framework has a
|
||
`ServletTestExecutionListener` that is enabled by default. When testing against a
|
||
`WebApplicationContext`, this <<testcontext-key-abstractions, `TestExecutionListener`>>
|
||
sets up default thread-local state by using Spring Web's `RequestContextHolder` before
|
||
each test method and creates a `MockHttpServletRequest`, a `MockHttpServletResponse`, and
|
||
a `ServletWebRequest` based on the base resource path configured with
|
||
`@WebAppConfiguration`. `ServletTestExecutionListener` also ensures that the
|
||
`MockHttpServletResponse` and `ServletWebRequest` can be injected into the test instance,
|
||
and, once the test is complete, it cleans up thread-local state.
|
||
|
||
Once you have a `WebApplicationContext` loaded for your test, you might find that you
|
||
need to interact with the web mocks -- for example, to set up your test fixture or to
|
||
perform assertions after invoking your web component. The following example shows which
|
||
mocks can be autowired into your test instance. Note that the `WebApplicationContext` and
|
||
`MockServletContext` are both cached across the test suite, whereas the other mocks are
|
||
managed per test method by the `ServletTestExecutionListener`.
|
||
|
||
.Injecting mocks
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@SpringJUnitWebConfig
|
||
class WacTests {
|
||
|
||
@Autowired
|
||
WebApplicationContext wac; // cached
|
||
|
||
@Autowired
|
||
MockServletContext servletContext; // cached
|
||
|
||
@Autowired
|
||
MockHttpSession session;
|
||
|
||
@Autowired
|
||
MockHttpServletRequest request;
|
||
|
||
@Autowired
|
||
MockHttpServletResponse response;
|
||
|
||
@Autowired
|
||
ServletWebRequest webRequest;
|
||
|
||
//...
|
||
}
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@SpringJUnitWebConfig
|
||
class WacTests {
|
||
|
||
@Autowired
|
||
lateinit var wac: WebApplicationContext // cached
|
||
|
||
@Autowired
|
||
lateinit var servletContext: MockServletContext // cached
|
||
|
||
@Autowired
|
||
lateinit var session: MockHttpSession
|
||
|
||
@Autowired
|
||
lateinit var request: MockHttpServletRequest
|
||
|
||
@Autowired
|
||
lateinit var response: MockHttpServletResponse
|
||
|
||
@Autowired
|
||
lateinit var webRequest: ServletWebRequest
|
||
|
||
//...
|
||
}
|
||
----
|
||
--
|
||
|
||
[[testcontext-ctx-management-caching]]
|
||
===== Context Caching
|
||
|
||
Once the TestContext framework loads an `ApplicationContext` (or `WebApplicationContext`)
|
||
for a test, that context is cached and reused for all subsequent tests that declare the
|
||
same unique context configuration within the same test suite. To understand how caching
|
||
works, it is important to understand what is meant by "`unique`" and "`test suite.`"
|
||
|
||
An `ApplicationContext` can be uniquely identified by the combination of configuration
|
||
parameters that is used to load it. Consequently, the unique combination of configuration
|
||
parameters is used to generate a key under which the context is cached. The TestContext
|
||
framework uses the following configuration parameters to build the context cache key:
|
||
|
||
* `locations` (from `@ContextConfiguration`)
|
||
* `classes` (from `@ContextConfiguration`)
|
||
* `contextInitializerClasses` (from `@ContextConfiguration`)
|
||
* `contextCustomizers` (from `ContextCustomizerFactory`) – this includes
|
||
`@DynamicPropertySource` methods as well as various features from Spring Boot's
|
||
testing support such as `@MockBean` and `@SpyBean`.
|
||
* `contextLoader` (from `@ContextConfiguration`)
|
||
* `parent` (from `@ContextHierarchy`)
|
||
* `activeProfiles` (from `@ActiveProfiles`)
|
||
* `propertySourceLocations` (from `@TestPropertySource`)
|
||
* `propertySourceProperties` (from `@TestPropertySource`)
|
||
* `resourceBasePath` (from `@WebAppConfiguration`)
|
||
|
||
For example, if `TestClassA` specifies `{"app-config.xml", "test-config.xml"}` for the
|
||
`locations` (or `value`) attribute of `@ContextConfiguration`, the TestContext framework
|
||
loads the corresponding `ApplicationContext` and stores it in a `static` context cache
|
||
under a key that is based solely on those locations. So, if `TestClassB` also defines
|
||
`{"app-config.xml", "test-config.xml"}` for its locations (either explicitly or
|
||
implicitly through inheritance) but does not define `@WebAppConfiguration`, a different
|
||
`ContextLoader`, different active profiles, different context initializers, different
|
||
test property sources, or a different parent context, then the same `ApplicationContext`
|
||
is shared by both test classes. This means that the setup cost for loading an application
|
||
context is incurred only once (per test suite), and subsequent test execution is much
|
||
faster.
|
||
|
||
.Test suites and forked processes
|
||
[NOTE]
|
||
====
|
||
The Spring TestContext framework stores application contexts in a static cache. This
|
||
means that the context is literally stored in a `static` variable. In other words, if
|
||
tests run in separate processes, the static cache is cleared between each test
|
||
execution, which effectively disables the caching mechanism.
|
||
|
||
To benefit from the caching mechanism, all tests must run within the same process or test
|
||
suite. This can be achieved by executing all tests as a group within an IDE. Similarly,
|
||
when executing tests with a build framework such as Ant, Maven, or Gradle, it is
|
||
important to make sure that the build framework does not fork between tests. For example,
|
||
if the
|
||
https://maven.apache.org/plugins/maven-surefire-plugin/test-mojo.html#forkMode[`forkMode`]
|
||
for the Maven Surefire plug-in is set to `always` or `pertest`, the TestContext framework
|
||
cannot cache application contexts between test classes, and the build process runs
|
||
significantly more slowly as a result.
|
||
====
|
||
|
||
The size of the context cache is bounded with a default maximum size of 32. Whenever the
|
||
maximum size is reached, a least recently used (LRU) eviction policy is used to evict and
|
||
close stale contexts. You can configure the maximum size from the command line or a build
|
||
script by setting a JVM system property named `spring.test.context.cache.maxSize`. As an
|
||
alternative, you can set the same property programmatically by using the
|
||
`SpringProperties` API.
|
||
|
||
Since having a large number of application contexts loaded within a given test suite can
|
||
cause the suite to take an unnecessarily long time to run, it is often beneficial to
|
||
know exactly how many contexts have been loaded and cached. To view the statistics for
|
||
the underlying context cache, you can set the log level for the
|
||
`org.springframework.test.context.cache` logging category to `DEBUG`.
|
||
|
||
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), you
|
||
can annotate your test class or test method with `@DirtiesContext` (see the discussion of
|
||
`@DirtiesContext` in <<spring-testing-annotation-dirtiescontext>>). This instructs Spring
|
||
to remove the context from the cache and rebuild the application context before running
|
||
the next test that requires the same application context. Note that support for the
|
||
`@DirtiesContext` annotation is provided by the
|
||
`DirtiesContextBeforeModesTestExecutionListener` and the
|
||
`DirtiesContextTestExecutionListener`, which are enabled by default.
|
||
|
||
[[testcontext-ctx-management-ctx-hierarchies]]
|
||
===== Context Hierarchies
|
||
|
||
When writing integration tests that rely on a loaded Spring `ApplicationContext`, it is
|
||
often sufficient to test against a single context. However, there are times when it is
|
||
beneficial or even necessary to test against a hierarchy of `ApplicationContext`
|
||
instances. For example, if you are developing a Spring MVC web application, you typically
|
||
have a root `WebApplicationContext` loaded by Spring's `ContextLoaderListener` and a
|
||
child `WebApplicationContext` loaded by Spring's `DispatcherServlet`. This results in a
|
||
parent-child context hierarchy where shared components and infrastructure configuration
|
||
are declared in the root context and consumed in the child context by web-specific
|
||
components. Another use case can be found in Spring Batch applications, where you often
|
||
have a parent context that provides configuration for shared batch infrastructure and a
|
||
child context for the configuration of a specific batch job.
|
||
|
||
You can write integration tests that use context hierarchies by declaring context
|
||
configuration with the `@ContextHierarchy` annotation, either on an individual test class
|
||
or within a test class hierarchy. If a context hierarchy is declared on multiple classes
|
||
within a test class hierarchy, you can also merge or override the context configuration
|
||
for a specific, named level in the context hierarchy. When merging configuration for a
|
||
given level in the hierarchy, the configuration resource type (that is, XML configuration
|
||
files or component classes) must be consistent. Otherwise, it is perfectly acceptable to
|
||
have different levels in a context hierarchy configured using different resource types.
|
||
|
||
The remaining JUnit Jupiter based examples in this section show common configuration
|
||
scenarios for integration tests that require the use of context hierarchies.
|
||
|
||
.Single test class with context hierarchy
|
||
--
|
||
`ControllerIntegrationTests` represents a typical integration testing scenario for a
|
||
Spring MVC web application by declaring a context hierarchy that consists of two levels,
|
||
one for the root `WebApplicationContext` (loaded by using the `TestAppConfig`
|
||
`@Configuration` class) and one for the dispatcher servlet `WebApplicationContext`
|
||
(loaded by using the `WebConfig` `@Configuration` class). The `WebApplicationContext`
|
||
that is autowired into the test instance is the one for the child context (that is, the
|
||
lowest context in the hierarchy). The following listing shows this configuration scenario:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ExtendWith(SpringExtension.class)
|
||
@WebAppConfiguration
|
||
@ContextHierarchy({
|
||
@ContextConfiguration(classes = TestAppConfig.class),
|
||
@ContextConfiguration(classes = WebConfig.class)
|
||
})
|
||
class ControllerIntegrationTests {
|
||
|
||
@Autowired
|
||
WebApplicationContext wac;
|
||
|
||
// ...
|
||
}
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ExtendWith(SpringExtension::class)
|
||
@WebAppConfiguration
|
||
@ContextHierarchy(
|
||
ContextConfiguration(classes = [TestAppConfig::class]),
|
||
ContextConfiguration(classes = [WebConfig::class]))
|
||
class ControllerIntegrationTests {
|
||
|
||
@Autowired
|
||
lateinit var wac: WebApplicationContext
|
||
|
||
// ...
|
||
}
|
||
----
|
||
--
|
||
|
||
|
||
.Class hierarchy with implicit parent context
|
||
--
|
||
The test classes in this example define a context hierarchy within a test class
|
||
hierarchy. `AbstractWebTests` declares the configuration for a root
|
||
`WebApplicationContext` in a Spring-powered web application. Note, however, that
|
||
`AbstractWebTests` does not declare `@ContextHierarchy`. Consequently, subclasses of
|
||
`AbstractWebTests` can optionally participate in a context hierarchy or follow the
|
||
standard semantics for `@ContextConfiguration`. `SoapWebServiceTests` and
|
||
`RestWebServiceTests` both extend `AbstractWebTests` and define a context hierarchy by
|
||
using `@ContextHierarchy`. The result is that three application contexts are loaded (one
|
||
for each declaration of `@ContextConfiguration`), and the application context loaded
|
||
based on the configuration in `AbstractWebTests` is set as the parent context for each of
|
||
the contexts loaded for the concrete subclasses. The following listing shows this
|
||
configuration scenario:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ExtendWith(SpringExtension.class)
|
||
@WebAppConfiguration
|
||
@ContextConfiguration("file:src/main/webapp/WEB-INF/applicationContext.xml")
|
||
public abstract class AbstractWebTests {}
|
||
|
||
@ContextHierarchy(@ContextConfiguration("/spring/soap-ws-config.xml"))
|
||
public class SoapWebServiceTests extends AbstractWebTests {}
|
||
|
||
@ContextHierarchy(@ContextConfiguration("/spring/rest-ws-config.xml"))
|
||
public class RestWebServiceTests extends AbstractWebTests {}
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ExtendWith(SpringExtension::class)
|
||
@WebAppConfiguration
|
||
@ContextConfiguration("file:src/main/webapp/WEB-INF/applicationContext.xml")
|
||
abstract class AbstractWebTests
|
||
|
||
@ContextHierarchy(ContextConfiguration("/spring/soap-ws-config.xml"))
|
||
class SoapWebServiceTests : AbstractWebTests()
|
||
|
||
@ContextHierarchy(ContextConfiguration("/spring/rest-ws-config.xml"))
|
||
class RestWebServiceTests : AbstractWebTests()
|
||
|
||
----
|
||
--
|
||
|
||
.Class hierarchy with merged context hierarchy configuration
|
||
--
|
||
The classes in this example show the use of named hierarchy levels in order to merge the
|
||
configuration for specific levels in a context hierarchy. `BaseTests` defines two levels
|
||
in the hierarchy, `parent` and `child`. `ExtendedTests` extends `BaseTests` and instructs
|
||
the Spring TestContext Framework to merge the context configuration for the `child`
|
||
hierarchy level, by ensuring that the names declared in the `name` attribute in
|
||
`@ContextConfiguration` are both `child`. The result is that three application contexts
|
||
are loaded: one for `/app-config.xml`, one for `/user-config.xml`, and one for
|
||
`{"/user-config.xml", "/order-config.xml"}`. As with the previous example, the
|
||
application context loaded from `/app-config.xml` is set as the parent context for the
|
||
contexts loaded from `/user-config.xml` and `{"/user-config.xml", "/order-config.xml"}`.
|
||
The following listing shows this configuration scenario:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ExtendWith(SpringExtension.class)
|
||
@ContextHierarchy({
|
||
@ContextConfiguration(name = "parent", locations = "/app-config.xml"),
|
||
@ContextConfiguration(name = "child", locations = "/user-config.xml")
|
||
})
|
||
class BaseTests {}
|
||
|
||
@ContextHierarchy(
|
||
@ContextConfiguration(name = "child", locations = "/order-config.xml")
|
||
)
|
||
class ExtendedTests extends BaseTests {}
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ExtendWith(SpringExtension::class)
|
||
@ContextHierarchy(
|
||
ContextConfiguration(name = "parent", locations = ["/app-config.xml"]),
|
||
ContextConfiguration(name = "child", locations = ["/user-config.xml"]))
|
||
open class BaseTests {}
|
||
|
||
@ContextHierarchy(
|
||
ContextConfiguration(name = "child", locations = ["/order-config.xml"])
|
||
)
|
||
class ExtendedTests : BaseTests() {}
|
||
----
|
||
--
|
||
|
||
.Class hierarchy with overridden context hierarchy configuration
|
||
--
|
||
In contrast to the previous example, this example demonstrates how to override the
|
||
configuration for a given named level in a context hierarchy by setting the
|
||
`inheritLocations` flag in `@ContextConfiguration` to `false`. Consequently, the
|
||
application context for `ExtendedTests` is loaded only from `/test-user-config.xml` and
|
||
has its parent set to the context loaded from `/app-config.xml`. The following listing
|
||
shows this configuration scenario:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ExtendWith(SpringExtension.class)
|
||
@ContextHierarchy({
|
||
@ContextConfiguration(name = "parent", locations = "/app-config.xml"),
|
||
@ContextConfiguration(name = "child", locations = "/user-config.xml")
|
||
})
|
||
class BaseTests {}
|
||
|
||
@ContextHierarchy(
|
||
@ContextConfiguration(
|
||
name = "child",
|
||
locations = "/test-user-config.xml",
|
||
inheritLocations = false
|
||
))
|
||
class ExtendedTests extends BaseTests {}
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ExtendWith(SpringExtension::class)
|
||
@ContextHierarchy(
|
||
ContextConfiguration(name = "parent", locations = ["/app-config.xml"]),
|
||
ContextConfiguration(name = "child", locations = ["/user-config.xml"]))
|
||
open class BaseTests {}
|
||
|
||
@ContextHierarchy(
|
||
ContextConfiguration(
|
||
name = "child",
|
||
locations = ["/test-user-config.xml"],
|
||
inheritLocations = false
|
||
))
|
||
class ExtendedTests : BaseTests() {}
|
||
----
|
||
|
||
.Dirtying a context within a context hierarchy
|
||
NOTE: If you use `@DirtiesContext` in a test whose context is configured as part of a
|
||
context hierarchy, you can use the `hierarchyMode` flag to control how the context cache
|
||
is cleared. For further details, see the discussion of `@DirtiesContext` in
|
||
<<spring-testing-annotation-dirtiescontext, Spring Testing Annotations>> and the
|
||
{api-spring-framework}/test/annotation/DirtiesContext.html[`@DirtiesContext`] javadoc.
|
||
--
|
||
|
||
[[testcontext-fixture-di]]
|
||
==== Dependency Injection of Test Fixtures
|
||
|
||
When you use the `DependencyInjectionTestExecutionListener` (which is configured by
|
||
default), the dependencies of your test instances are injected from beans in the
|
||
application context that you configured with `@ContextConfiguration` or related
|
||
annotations. You may use setter injection, field injection, or both, depending on
|
||
which annotations you choose and whether you place them on setter methods or fields.
|
||
If you are using JUnit Jupiter you may also optionally use constructor injection
|
||
(see <<testcontext-junit-jupiter-di>>). For consistency with Spring's annotation-based
|
||
injection support, you may also use Spring's `@Autowired` annotation or the `@Inject`
|
||
annotation from JSR-330 for field and setter injection.
|
||
|
||
TIP: For testing frameworks other than JUnit Jupiter, the TestContext framework does not
|
||
participate in instantiation of the test class. Thus, the use of `@Autowired` or
|
||
`@Inject` for constructors has no effect for test classes.
|
||
|
||
NOTE: Although field injection is discouraged in production code, field injection is
|
||
actually quite natural in test code. The rationale for the difference is that you will
|
||
never instantiate your test class directly. Consequently, there is no need to be able to
|
||
invoke a `public` constructor or setter method on your test class.
|
||
|
||
Because `@Autowired` is used to perform <<core.adoc#beans-factory-autowire, autowiring by
|
||
type>>, if you have multiple bean definitions of the same type, you cannot rely on this
|
||
approach for those particular beans. In that case, you can use `@Autowired` in
|
||
conjunction with `@Qualifier`. You can also choose to use `@Inject` in conjunction with
|
||
`@Named`. Alternatively, if your test class has access to its `ApplicationContext`, you
|
||
can perform an explicit lookup by using (for example) a call to
|
||
`applicationContext.getBean("titleRepository", TitleRepository.class)`.
|
||
|
||
If you do not want dependency injection applied to your test instances, do not annotate
|
||
fields or setter methods with `@Autowired` or `@Inject`. Alternatively, you can disable
|
||
dependency injection altogether by explicitly configuring your class with
|
||
`@TestExecutionListeners` and omitting `DependencyInjectionTestExecutionListener.class`
|
||
from the list of listeners.
|
||
|
||
Consider the scenario of testing a `HibernateTitleRepository` class, as outlined in the
|
||
<<integration-testing-goals, Goals>> section. The next two code listings demonstrate the
|
||
use of `@Autowired` on fields and setter methods. The application context configuration
|
||
is presented after all sample code listings.
|
||
|
||
[NOTE]
|
||
====
|
||
The dependency injection behavior in the following code listings is not specific to JUnit
|
||
Jupiter. The same DI techniques can be used in conjunction with any supported testing
|
||
framework.
|
||
|
||
The following examples make calls to static assertion methods, such as `assertNotNull()`,
|
||
but without prepending the call with `Assertions`. In such cases, assume that the method
|
||
was properly imported through an `import static` declaration that is not shown in the
|
||
example.
|
||
====
|
||
|
||
The first code listing shows a JUnit Jupiter based implementation of the test class that
|
||
uses `@Autowired` for field injection:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ExtendWith(SpringExtension.class)
|
||
// specifies the Spring configuration to load for this test fixture
|
||
@ContextConfiguration("repository-config.xml")
|
||
class HibernateTitleRepositoryTests {
|
||
|
||
// this instance will be dependency injected by type
|
||
@Autowired
|
||
HibernateTitleRepository titleRepository;
|
||
|
||
@Test
|
||
void findById() {
|
||
Title title = titleRepository.findById(new Long(10));
|
||
assertNotNull(title);
|
||
}
|
||
}
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ExtendWith(SpringExtension::class)
|
||
// specifies the Spring configuration to load for this test fixture
|
||
@ContextConfiguration("repository-config.xml")
|
||
class HibernateTitleRepositoryTests {
|
||
|
||
// this instance will be dependency injected by type
|
||
@Autowired
|
||
lateinit var titleRepository: HibernateTitleRepository
|
||
|
||
@Test
|
||
fun findById() {
|
||
val title = titleRepository.findById(10)
|
||
assertNotNull(title)
|
||
}
|
||
}
|
||
----
|
||
|
||
Alternatively, you can configure the class to use `@Autowired` for setter injection, as
|
||
follows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ExtendWith(SpringExtension.class)
|
||
// specifies the Spring configuration to load for this test fixture
|
||
@ContextConfiguration("repository-config.xml")
|
||
class HibernateTitleRepositoryTests {
|
||
|
||
// this instance will be dependency injected by type
|
||
HibernateTitleRepository titleRepository;
|
||
|
||
@Autowired
|
||
void setTitleRepository(HibernateTitleRepository titleRepository) {
|
||
this.titleRepository = titleRepository;
|
||
}
|
||
|
||
@Test
|
||
void findById() {
|
||
Title title = titleRepository.findById(new Long(10));
|
||
assertNotNull(title);
|
||
}
|
||
}
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ExtendWith(SpringExtension::class)
|
||
// specifies the Spring configuration to load for this test fixture
|
||
@ContextConfiguration("repository-config.xml")
|
||
class HibernateTitleRepositoryTests {
|
||
|
||
// this instance will be dependency injected by type
|
||
lateinit var titleRepository: HibernateTitleRepository
|
||
|
||
@Autowired
|
||
fun setTitleRepository(titleRepository: HibernateTitleRepository) {
|
||
this.titleRepository = titleRepository
|
||
}
|
||
|
||
@Test
|
||
fun findById() {
|
||
val title = titleRepository.findById(10)
|
||
assertNotNull(title)
|
||
}
|
||
}
|
||
----
|
||
|
||
The preceding code listings use the same XML context file referenced by the
|
||
`@ContextConfiguration` annotation (that is, `repository-config.xml`). The following
|
||
shows this configuration:
|
||
|
||
[source,xml,indent=0]
|
||
[subs="verbatim,quotes"]
|
||
----
|
||
<?xml version="1.0" encoding="UTF-8"?>
|
||
<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
|
||
https://www.springframework.org/schema/beans/spring-beans.xsd">
|
||
|
||
<!-- this bean will be injected into the HibernateTitleRepositoryTests class -->
|
||
<bean id="titleRepository" class="com.foo.repository.hibernate.HibernateTitleRepository">
|
||
<property name="sessionFactory" ref="sessionFactory"/>
|
||
</bean>
|
||
|
||
<bean id="sessionFactory" class="org.springframework.orm.hibernate5.LocalSessionFactoryBean">
|
||
<!-- configuration elided for brevity -->
|
||
</bean>
|
||
|
||
</beans>
|
||
----
|
||
|
||
[NOTE]
|
||
=====
|
||
If you are extending from a Spring-provided test base class that happens to use
|
||
`@Autowired` on one of its setter methods, you might have multiple beans of the affected
|
||
type defined in your application context (for example, multiple `DataSource` beans). In
|
||
such a case, you can override the setter method and use the `@Qualifier` annotation to
|
||
indicate a specific target bean, as follows (but make sure to delegate to the overridden
|
||
method in the superclass as well):
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
// ...
|
||
|
||
@Autowired
|
||
@Override
|
||
public void setDataSource(@Qualifier("myDataSource") DataSource dataSource) {
|
||
super.setDataSource(dataSource);
|
||
}
|
||
|
||
// ...
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
// ...
|
||
|
||
@Autowired
|
||
override fun setDataSource(@Qualifier("myDataSource") dataSource: DataSource) {
|
||
super.setDataSource(dataSource)
|
||
}
|
||
|
||
// ...
|
||
----
|
||
|
||
The specified qualifier value indicates the specific `DataSource` bean to inject,
|
||
narrowing the set of type matches to a specific bean. Its value is matched against
|
||
`<qualifier>` declarations within the corresponding `<bean>` definitions. The bean name
|
||
is used as a fallback qualifier value, so you can effectively also point to a specific
|
||
bean by name there (as shown earlier, assuming that `myDataSource` is the bean `id`).
|
||
=====
|
||
|
||
|
||
[[testcontext-web-scoped-beans]]
|
||
==== Testing Request- and Session-scoped Beans
|
||
|
||
Spring has supported <<core#beans-factory-scopes-other, Request- and session-scoped
|
||
beans>> since the early years, and you can test your request-scoped and session-scoped
|
||
beans by following these steps:
|
||
|
||
* Ensure that a `WebApplicationContext` is loaded for your test by annotating your test
|
||
class with `@WebAppConfiguration`.
|
||
* Inject the mock request or session into your test instance and prepare your test
|
||
fixture as appropriate.
|
||
* Invoke your web component that you retrieved from the configured
|
||
`WebApplicationContext` (with dependency injection).
|
||
* Perform assertions against the mocks.
|
||
|
||
The next code snippet shows the XML configuration for a login use case. Note that the
|
||
`userService` bean has a dependency on a request-scoped `loginAction` bean. Also, the
|
||
`LoginAction` is instantiated by using <<core.adoc#expressions, SpEL expressions>> that
|
||
retrieve the username and password from the current HTTP request. In our test, we want to
|
||
configure these request parameters through the mock managed by the TestContext framework.
|
||
The following listing shows the configuration for this use case:
|
||
|
||
.Request-scoped bean configuration
|
||
[source,xml,indent=0]
|
||
----
|
||
<beans>
|
||
|
||
<bean id="userService" class="com.example.SimpleUserService"
|
||
c:loginAction-ref="loginAction"/>
|
||
|
||
<bean id="loginAction" class="com.example.LoginAction"
|
||
c:username="#{request.getParameter('user')}"
|
||
c:password="#{request.getParameter('pswd')}"
|
||
scope="request">
|
||
<aop:scoped-proxy/>
|
||
</bean>
|
||
|
||
</beans>
|
||
----
|
||
|
||
In `RequestScopedBeanTests`, we inject both the `UserService` (that is, the subject under
|
||
test) and the `MockHttpServletRequest` into our test instance. Within our
|
||
`requestScope()` test method, we set up our test fixture by setting request parameters in
|
||
the provided `MockHttpServletRequest`. When the `loginUser()` method is invoked on our
|
||
`userService`, we are assured that the user service has access to the request-scoped
|
||
`loginAction` for the current `MockHttpServletRequest` (that is, the one in which we just
|
||
set parameters). We can then perform assertions against the results based on the known
|
||
inputs for the username and password. The following listing shows how to do so:
|
||
|
||
.Request-scoped bean test
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@SpringJUnitWebConfig
|
||
class RequestScopedBeanTests {
|
||
|
||
@Autowired UserService userService;
|
||
@Autowired MockHttpServletRequest request;
|
||
|
||
@Test
|
||
void requestScope() {
|
||
request.setParameter("user", "enigma");
|
||
request.setParameter("pswd", "$pr!ng");
|
||
|
||
LoginResults results = userService.loginUser();
|
||
// assert results
|
||
}
|
||
}
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@SpringJUnitWebConfig
|
||
class RequestScopedBeanTests {
|
||
|
||
@Autowired lateinit var userService: UserService
|
||
@Autowired lateinit var request: MockHttpServletRequest
|
||
|
||
@Test
|
||
fun requestScope() {
|
||
request.setParameter("user", "enigma")
|
||
request.setParameter("pswd", "\$pr!ng")
|
||
|
||
val results = userService.loginUser()
|
||
// assert results
|
||
}
|
||
}
|
||
----
|
||
|
||
The following code snippet is similar to the one we saw earlier for a request-scoped
|
||
bean. However, this time, the `userService` bean has a dependency on a session-scoped
|
||
`userPreferences` bean. Note that the `UserPreferences` bean is instantiated by using a
|
||
SpEL expression that retrieves the theme from the current HTTP session. In our test, we
|
||
need to configure a theme in the mock session managed by the TestContext framework. The
|
||
following example shows how to do so:
|
||
|
||
.Session-scoped bean configuration
|
||
[source,xml,indent=0]
|
||
[subs="verbatim,quotes"]
|
||
----
|
||
<beans>
|
||
|
||
<bean id="userService" class="com.example.SimpleUserService"
|
||
c:userPreferences-ref="userPreferences" />
|
||
|
||
<bean id="userPreferences" class="com.example.UserPreferences"
|
||
c:theme="#{session.getAttribute('theme')}"
|
||
scope="session">
|
||
<aop:scoped-proxy/>
|
||
</bean>
|
||
|
||
</beans>
|
||
----
|
||
|
||
In `SessionScopedBeanTests`, we inject the `UserService` and the `MockHttpSession` into
|
||
our test instance. Within our `sessionScope()` test method, we set up our test fixture by
|
||
setting the expected `theme` attribute in the provided `MockHttpSession`. When the
|
||
`processUserPreferences()` method is invoked on our `userService`, we are assured that
|
||
the user service has access to the session-scoped `userPreferences` for the current
|
||
`MockHttpSession`, and we can perform assertions against the results based on the
|
||
configured theme. The following example shows how to do so:
|
||
|
||
.Session-scoped bean test
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@SpringJUnitWebConfig
|
||
class SessionScopedBeanTests {
|
||
|
||
@Autowired UserService userService;
|
||
@Autowired MockHttpSession session;
|
||
|
||
@Test
|
||
void sessionScope() throws Exception {
|
||
session.setAttribute("theme", "blue");
|
||
|
||
Results results = userService.processUserPreferences();
|
||
// assert results
|
||
}
|
||
}
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@SpringJUnitWebConfig
|
||
class SessionScopedBeanTests {
|
||
|
||
@Autowired lateinit var userService: UserService
|
||
@Autowired lateinit var session: MockHttpSession
|
||
|
||
@Test
|
||
fun sessionScope() {
|
||
session.setAttribute("theme", "blue")
|
||
|
||
val results = userService.processUserPreferences()
|
||
// assert results
|
||
}
|
||
}
|
||
----
|
||
|
||
[[testcontext-tx]]
|
||
==== Transaction Management
|
||
|
||
In the TestContext framework, transactions are managed by the
|
||
`TransactionalTestExecutionListener`, which is configured by default, even if you do not
|
||
explicitly declare `@TestExecutionListeners` on your test class. To enable support for
|
||
transactions, however, you must configure a `PlatformTransactionManager` bean in the
|
||
`ApplicationContext` that is loaded with `@ContextConfiguration` semantics (further
|
||
details are provided later). In addition, you must declare Spring's `@Transactional`
|
||
annotation either at the class or the method level for your tests.
|
||
|
||
[[testcontext-tx-test-managed-transactions]]
|
||
===== Test-managed Transactions
|
||
|
||
Test-managed transactions are transactions that are managed declaratively by using the
|
||
`TransactionalTestExecutionListener` or programmatically by using `TestTransaction`
|
||
(described later). You should not confuse such transactions with Spring-managed
|
||
transactions (those managed directly by Spring within the `ApplicationContext` loaded for
|
||
tests) or application-managed transactions (those managed programmatically within
|
||
application code that is invoked by tests). Spring-managed and application-managed
|
||
transactions typically participate in test-managed transactions. However, you should use
|
||
caution if Spring-managed or application-managed transactions are configured with any
|
||
propagation type other than `REQUIRED` or `SUPPORTS` (see the discussion on
|
||
<<data-access.adoc#tx-propagation, transaction propagation>> for details).
|
||
|
||
.Preemptive timeouts and test-managed transactions
|
||
[WARNING]
|
||
====
|
||
Caution must be taken when using any form of preemptive timeouts from a testing framework
|
||
in conjunction with Spring's test-managed transactions.
|
||
|
||
Specifically, Spring’s testing support binds transaction state to the current thread (via
|
||
a `java.lang.ThreadLocal` variable) _before_ the current test method is invoked. If a
|
||
testing framework invokes the current test method in a new thread in order to support a
|
||
preemptive timeout, any actions performed within the current test method will _not_ be
|
||
invoked within the test-managed transaction. Consequently, the result of any such actions
|
||
will not be rolled back with the test-managed transaction. On the contrary, such actions
|
||
will be committed to the persistent store -- for example, a relational database -- even
|
||
though the test-managed transaction is properly rolled back by Spring.
|
||
|
||
Situations in which this can occur include but are not limited to the following.
|
||
|
||
* JUnit 4's `@Test(timeout = ...)` support and `TimeOut` rule
|
||
* JUnit Jupiter's `assertTimeoutPreemptively(...)` methods in the
|
||
`org.junit.jupiter.api.Assertions` class
|
||
* TestNG's `@Test(timeOut = ...)` support
|
||
====
|
||
|
||
[[testcontext-tx-enabling-transactions]]
|
||
===== Enabling and Disabling Transactions
|
||
|
||
Annotating a test method with `@Transactional` causes the test to be run within a
|
||
transaction that is, by default, automatically rolled back after completion of the test.
|
||
If a test class is annotated with `@Transactional`, each test method within that class
|
||
hierarchy runs within a transaction. Test methods that are not annotated with
|
||
`@Transactional` (at the class or method level) are not run within a transaction. Note
|
||
that `@Transactional` is not supported on test lifecycle methods — for example, methods
|
||
annotated with JUnit Jupiter's `@BeforeAll`, `@BeforeEach`, etc. Furthermore, tests that
|
||
are annotated with `@Transactional` but have the `propagation` attribute set to
|
||
`NOT_SUPPORTED` are not run within a transaction.
|
||
|
||
[[testcontext-tx-attribute-support]]
|
||
.`@Transactional` attribute support
|
||
|===
|
||
|Attribute |Supported for test-managed transactions
|
||
|
||
|`value` and `transactionManager` |yes
|
||
|
||
|`propagation` |only `Propagation.NOT_SUPPORTED` is supported
|
||
|
||
|`isolation` |no
|
||
|
||
|`timeout` |no
|
||
|
||
|`readOnly` |no
|
||
|
||
|`rollbackFor` and `rollbackForClassName` |no: use `TestTransaction.flagForRollback()` instead
|
||
|
||
|`noRollbackFor` and `noRollbackForClassName` |no: use `TestTransaction.flagForCommit()` instead
|
||
|===
|
||
|
||
[TIP]
|
||
====
|
||
Method-level lifecycle methods — for example, methods annotated with JUnit Jupiter's
|
||
`@BeforeEach` or `@AfterEach` — are run within a test-managed transaction. On the other
|
||
hand, suite-level and class-level lifecycle methods — for example, methods annotated with
|
||
JUnit Jupiter's `@BeforeAll` or `@AfterAll` and methods annotated with TestNG's
|
||
`@BeforeSuite`, `@AfterSuite`, `@BeforeClass`, or `@AfterClass` — are _not_ run within a
|
||
test-managed transaction.
|
||
|
||
If you need to run code in a suite-level or class-level lifecycle method within a
|
||
transaction, you may wish to inject a corresponding `PlatformTransactionManager` into
|
||
your test class and then use that with a `TransactionTemplate` for programmatic
|
||
transaction management.
|
||
====
|
||
|
||
Note that <<testcontext-support-classes-junit4,
|
||
`AbstractTransactionalJUnit4SpringContextTests`>> and
|
||
<<testcontext-support-classes-testng, `AbstractTransactionalTestNGSpringContextTests`>>
|
||
are preconfigured for transactional support at the class level.
|
||
|
||
The following example demonstrates a common scenario for writing an integration test for
|
||
a Hibernate-based `UserRepository`:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@SpringJUnitConfig(TestConfig.class)
|
||
@Transactional
|
||
class HibernateUserRepositoryTests {
|
||
|
||
@Autowired
|
||
HibernateUserRepository repository;
|
||
|
||
@Autowired
|
||
SessionFactory sessionFactory;
|
||
|
||
JdbcTemplate jdbcTemplate;
|
||
|
||
@Autowired
|
||
void setDataSource(DataSource dataSource) {
|
||
this.jdbcTemplate = new JdbcTemplate(dataSource);
|
||
}
|
||
|
||
@Test
|
||
void createUser() {
|
||
// track initial state in test database:
|
||
final int count = countRowsInTable("user");
|
||
|
||
User user = new User(...);
|
||
repository.save(user);
|
||
|
||
// Manual flush is required to avoid false positive in test
|
||
sessionFactory.getCurrentSession().flush();
|
||
assertNumUsers(count + 1);
|
||
}
|
||
|
||
private int countRowsInTable(String tableName) {
|
||
return JdbcTestUtils.countRowsInTable(this.jdbcTemplate, tableName);
|
||
}
|
||
|
||
private void assertNumUsers(int expected) {
|
||
assertEquals("Number of rows in the [user] table.", expected, countRowsInTable("user"));
|
||
}
|
||
}
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@SpringJUnitConfig(TestConfig::class)
|
||
@Transactional
|
||
class HibernateUserRepositoryTests {
|
||
|
||
@Autowired
|
||
lateinit var repository: HibernateUserRepository
|
||
|
||
@Autowired
|
||
lateinit var sessionFactory: SessionFactory
|
||
|
||
lateinit var jdbcTemplate: JdbcTemplate
|
||
|
||
@Autowired
|
||
fun setDataSource(dataSource: DataSource) {
|
||
this.jdbcTemplate = JdbcTemplate(dataSource)
|
||
}
|
||
|
||
@Test
|
||
fun createUser() {
|
||
// track initial state in test database:
|
||
val count = countRowsInTable("user")
|
||
|
||
val user = User()
|
||
repository.save(user)
|
||
|
||
// Manual flush is required to avoid false positive in test
|
||
sessionFactory.getCurrentSession().flush()
|
||
assertNumUsers(count + 1)
|
||
}
|
||
|
||
private fun countRowsInTable(tableName: String): Int {
|
||
return JdbcTestUtils.countRowsInTable(jdbcTemplate, tableName)
|
||
}
|
||
|
||
private fun assertNumUsers(expected: Int) {
|
||
assertEquals("Number of rows in the [user] table.", expected, countRowsInTable("user"))
|
||
}
|
||
}
|
||
----
|
||
|
||
As explained in <<testcontext-tx-rollback-and-commit-behavior>>, there is no need to
|
||
clean up the database after the `createUser()` method runs, since any changes made to the
|
||
database are automatically rolled back by the `TransactionalTestExecutionListener`.
|
||
|
||
[[testcontext-tx-rollback-and-commit-behavior]]
|
||
===== Transaction Rollback and Commit Behavior
|
||
|
||
By default, test transactions will be automatically rolled back after completion of the
|
||
test; however, transactional commit and rollback behavior can be configured declaratively
|
||
via the `@Commit` and `@Rollback` annotations. See the corresponding entries in the
|
||
<<integration-testing-annotations, annotation support>> section for further details.
|
||
|
||
[[testcontext-tx-programmatic-tx-mgt]]
|
||
===== Programmatic Transaction Management
|
||
|
||
You can interact with test-managed transactions programmatically by using the static
|
||
methods in `TestTransaction`. For example, you can use `TestTransaction` within test
|
||
methods, before methods, and after methods to start or end the current test-managed
|
||
transaction or to configure the current test-managed transaction for rollback or commit.
|
||
Support for `TestTransaction` is automatically available whenever the
|
||
`TransactionalTestExecutionListener` is enabled.
|
||
|
||
The following example demonstrates some of the features of `TestTransaction`. See the
|
||
javadoc for {api-spring-framework}/test/context/transaction/TestTransaction.html[`TestTransaction`]
|
||
for further details.
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@ContextConfiguration(classes = TestConfig.class)
|
||
public class ProgrammaticTransactionManagementTests extends
|
||
AbstractTransactionalJUnit4SpringContextTests {
|
||
|
||
@Test
|
||
public void transactionalTest() {
|
||
// assert initial state in test database:
|
||
assertNumUsers(2);
|
||
|
||
deleteFromTables("user");
|
||
|
||
// changes to the database will be committed!
|
||
TestTransaction.flagForCommit();
|
||
TestTransaction.end();
|
||
assertFalse(TestTransaction.isActive());
|
||
assertNumUsers(0);
|
||
|
||
TestTransaction.start();
|
||
// perform other actions against the database that will
|
||
// be automatically rolled back after the test completes...
|
||
}
|
||
|
||
protected void assertNumUsers(int expected) {
|
||
assertEquals("Number of rows in the [user] table.", expected, countRowsInTable("user"));
|
||
}
|
||
}
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@ContextConfiguration(classes = [TestConfig::class])
|
||
class ProgrammaticTransactionManagementTests : AbstractTransactionalJUnit4SpringContextTests() {
|
||
|
||
@Test
|
||
fun transactionalTest() {
|
||
// assert initial state in test database:
|
||
assertNumUsers(2)
|
||
|
||
deleteFromTables("user")
|
||
|
||
// changes to the database will be committed!
|
||
TestTransaction.flagForCommit()
|
||
TestTransaction.end()
|
||
assertFalse(TestTransaction.isActive())
|
||
assertNumUsers(0)
|
||
|
||
TestTransaction.start()
|
||
// perform other actions against the database that will
|
||
// be automatically rolled back after the test completes...
|
||
}
|
||
|
||
protected fun assertNumUsers(expected: Int) {
|
||
assertEquals("Number of rows in the [user] table.", expected, countRowsInTable("user"))
|
||
}
|
||
}
|
||
----
|
||
|
||
[[testcontext-tx-before-and-after-tx]]
|
||
===== Running Code Outside of a Transaction
|
||
|
||
Occasionally, you may need to run certain code before or after a transactional test
|
||
method but outside the transactional context -- for example, to verify the initial
|
||
database state prior to running your test or to verify expected transactional commit
|
||
behavior after your test runs (if the test was configured to commit the transaction).
|
||
`TransactionalTestExecutionListener` supports the `@BeforeTransaction` and
|
||
`@AfterTransaction` annotations for exactly such scenarios. You can annotate any `void`
|
||
method in a test class or any `void` default method in a test interface with one of these
|
||
annotations, and the `TransactionalTestExecutionListener` ensures that your before
|
||
transaction method or after transaction method runs at the appropriate time.
|
||
|
||
TIP: Any before methods (such as methods annotated with JUnit Jupiter's `@BeforeEach`)
|
||
and any after methods (such as methods annotated with JUnit Jupiter's `@AfterEach`) are
|
||
run within a transaction. In addition, methods annotated with `@BeforeTransaction` or
|
||
`@AfterTransaction` are not run for test methods that are not configured to run within a
|
||
transaction.
|
||
|
||
[[testcontext-tx-mgr-config]]
|
||
===== Configuring a Transaction Manager
|
||
|
||
`TransactionalTestExecutionListener` expects a `PlatformTransactionManager` bean to be
|
||
defined in the Spring `ApplicationContext` for the test. If there are multiple instances
|
||
of `PlatformTransactionManager` within the test's `ApplicationContext`, you can declare a
|
||
qualifier by using `@Transactional("myTxMgr")` or `@Transactional(transactionManager =
|
||
"myTxMgr")`, or `TransactionManagementConfigurer` can be implemented by an
|
||
`@Configuration` class. Consult the
|
||
{api-spring-framework}/test/context/transaction/TestContextTransactionUtils.html#retrieveTransactionManager-org.springframework.test.context.TestContext-java.lang.String-[javadoc
|
||
for `TestContextTransactionUtils.retrieveTransactionManager()`] for details on the
|
||
algorithm used to look up a transaction manager in the test's `ApplicationContext`.
|
||
|
||
[[testcontext-tx-annotation-demo]]
|
||
===== Demonstration of All Transaction-related Annotations
|
||
|
||
The following JUnit Jupiter based example displays a fictitious integration testing
|
||
scenario that highlights all transaction-related annotations. The example is not intended
|
||
to demonstrate best practices but rather to demonstrate how these annotations can be
|
||
used. See the <<integration-testing-annotations, annotation support>> section for further
|
||
information and configuration examples. <<testcontext-executing-sql-declaratively-tx,
|
||
Transaction management for `@Sql`>> contains an additional example that uses `@Sql` for
|
||
declarative SQL script execution with default transaction rollback semantics. The
|
||
following example shows the relevant annotations:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@SpringJUnitConfig
|
||
@Transactional(transactionManager = "txMgr")
|
||
@Commit
|
||
class FictitiousTransactionalTest {
|
||
|
||
@BeforeTransaction
|
||
void verifyInitialDatabaseState() {
|
||
// logic to verify the initial state before a transaction is started
|
||
}
|
||
|
||
@BeforeEach
|
||
void setUpTestDataWithinTransaction() {
|
||
// set up test data within the transaction
|
||
}
|
||
|
||
@Test
|
||
// overrides the class-level @Commit setting
|
||
@Rollback
|
||
void modifyDatabaseWithinTransaction() {
|
||
// logic which uses the test data and modifies database state
|
||
}
|
||
|
||
@AfterEach
|
||
void tearDownWithinTransaction() {
|
||
// run "tear down" logic within the transaction
|
||
}
|
||
|
||
@AfterTransaction
|
||
void verifyFinalDatabaseState() {
|
||
// logic to verify the final state after transaction has rolled back
|
||
}
|
||
|
||
}
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@SpringJUnitConfig
|
||
@Transactional(transactionManager = "txMgr")
|
||
@Commit
|
||
class FictitiousTransactionalTest {
|
||
|
||
@BeforeTransaction
|
||
fun verifyInitialDatabaseState() {
|
||
// logic to verify the initial state before a transaction is started
|
||
}
|
||
|
||
@BeforeEach
|
||
fun setUpTestDataWithinTransaction() {
|
||
// set up test data within the transaction
|
||
}
|
||
|
||
@Test
|
||
// overrides the class-level @Commit setting
|
||
@Rollback
|
||
fun modifyDatabaseWithinTransaction() {
|
||
// logic which uses the test data and modifies database state
|
||
}
|
||
|
||
@AfterEach
|
||
fun tearDownWithinTransaction() {
|
||
// run "tear down" logic within the transaction
|
||
}
|
||
|
||
@AfterTransaction
|
||
fun verifyFinalDatabaseState() {
|
||
// logic to verify the final state after transaction has rolled back
|
||
}
|
||
|
||
}
|
||
----
|
||
|
||
[[testcontext-tx-false-positives]]
|
||
.Avoid false positives when testing ORM code
|
||
|
||
[NOTE]
|
||
=====
|
||
When you test application code that manipulates the state of a Hibernate session or JPA
|
||
persistence context, make sure to flush the underlying unit of work within test methods
|
||
that run that code. Failing to flush the underlying unit of work can produce false
|
||
positives: Your test passes, but the same code throws an exception in a live, production
|
||
environment. Note that this applies to any ORM framework that maintains an in-memory unit
|
||
of work. In the following Hibernate-based example test case, one method demonstrates a
|
||
false positive, and the other method correctly exposes the results of flushing the
|
||
session:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
// ...
|
||
|
||
@Autowired
|
||
SessionFactory sessionFactory;
|
||
|
||
@Transactional
|
||
@Test // no expected exception!
|
||
public void falsePositive() {
|
||
updateEntityInHibernateSession();
|
||
// False positive: an exception will be thrown once the Hibernate
|
||
// Session is finally flushed (i.e., in production code)
|
||
}
|
||
|
||
@Transactional
|
||
@Test(expected = ...)
|
||
public void updateWithSessionFlush() {
|
||
updateEntityInHibernateSession();
|
||
// Manual flush is required to avoid false positive in test
|
||
sessionFactory.getCurrentSession().flush();
|
||
}
|
||
|
||
// ...
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
// ...
|
||
|
||
@Autowired
|
||
lateinit var sessionFactory: SessionFactory
|
||
|
||
@Transactional
|
||
@Test // no expected exception!
|
||
fun falsePositive() {
|
||
updateEntityInHibernateSession()
|
||
// False positive: an exception will be thrown once the Hibernate
|
||
// Session is finally flushed (i.e., in production code)
|
||
}
|
||
|
||
@Transactional
|
||
@Test(expected = ...)
|
||
fun updateWithSessionFlush() {
|
||
updateEntityInHibernateSession()
|
||
// Manual flush is required to avoid false positive in test
|
||
sessionFactory.getCurrentSession().flush()
|
||
}
|
||
|
||
// ...
|
||
----
|
||
|
||
The following example shows matching methods for JPA:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
// ...
|
||
|
||
@PersistenceContext
|
||
EntityManager entityManager;
|
||
|
||
@Transactional
|
||
@Test // no expected exception!
|
||
public void falsePositive() {
|
||
updateEntityInJpaPersistenceContext();
|
||
// False positive: an exception will be thrown once the JPA
|
||
// EntityManager is finally flushed (i.e., in production code)
|
||
}
|
||
|
||
@Transactional
|
||
@Test(expected = ...)
|
||
public void updateWithEntityManagerFlush() {
|
||
updateEntityInJpaPersistenceContext();
|
||
// Manual flush is required to avoid false positive in test
|
||
entityManager.flush();
|
||
}
|
||
|
||
// ...
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
// ...
|
||
|
||
@PersistenceContext
|
||
lateinit var entityManager:EntityManager
|
||
|
||
@Transactional
|
||
@Test // no expected exception!
|
||
fun falsePositive() {
|
||
updateEntityInJpaPersistenceContext()
|
||
// False positive: an exception will be thrown once the JPA
|
||
// EntityManager is finally flushed (i.e., in production code)
|
||
}
|
||
|
||
@Transactional
|
||
@Test(expected = ...)
|
||
void updateWithEntityManagerFlush() {
|
||
updateEntityInJpaPersistenceContext()
|
||
// Manual flush is required to avoid false positive in test
|
||
entityManager.flush()
|
||
}
|
||
|
||
// ...
|
||
----
|
||
=====
|
||
|
||
|
||
[[testcontext-executing-sql]]
|
||
==== Executing SQL Scripts
|
||
|
||
When writing integration tests against a relational database, it is often beneficial to
|
||
run SQL scripts to modify the database schema or insert test data into tables. The
|
||
`spring-jdbc` module provides support for _initializing_ an embedded or existing database
|
||
by executing SQL scripts when the Spring `ApplicationContext` is loaded. See
|
||
<<data-access.adoc#jdbc-embedded-database-support, Embedded database support>> and
|
||
<<data-access.adoc#jdbc-embedded-database-dao-testing, Testing data access logic with an
|
||
embedded database>> for details.
|
||
|
||
Although it is very useful to initialize a database for testing _once_ when the
|
||
`ApplicationContext` is loaded, sometimes it is essential to be able to modify the
|
||
database _during_ integration tests. The following sections explain how to run SQL
|
||
scripts programmatically and declaratively during integration tests.
|
||
|
||
[[testcontext-executing-sql-programmatically]]
|
||
===== Executing SQL scripts programmatically
|
||
|
||
Spring provides the following options for executing SQL scripts programmatically within
|
||
integration test methods.
|
||
|
||
* `org.springframework.jdbc.datasource.init.ScriptUtils`
|
||
* `org.springframework.jdbc.datasource.init.ResourceDatabasePopulator`
|
||
* `org.springframework.test.context.junit4.AbstractTransactionalJUnit4SpringContextTests`
|
||
* `org.springframework.test.context.testng.AbstractTransactionalTestNGSpringContextTests`
|
||
|
||
`ScriptUtils` provides a collection of static utility methods for working with SQL
|
||
scripts and is mainly intended for internal use within the framework. However, if you
|
||
require full control over how SQL scripts are parsed and run, `ScriptUtils` may suit
|
||
your needs better than some of the other alternatives described later. See the
|
||
{api-spring-framework}/jdbc/datasource/init/ScriptUtils.html[javadoc] for individual
|
||
methods in `ScriptUtils` for further details.
|
||
|
||
`ResourceDatabasePopulator` provides an object-based API for programmatically populating,
|
||
initializing, or cleaning up a database by using SQL scripts defined in external
|
||
resources. `ResourceDatabasePopulator` provides options for configuring the character
|
||
encoding, statement separator, comment delimiters, and error handling flags used when
|
||
parsing and running the scripts. Each of the configuration options has a reasonable
|
||
default value. See the
|
||
{api-spring-framework}/jdbc/datasource/init/ResourceDatabasePopulator.html[javadoc] for
|
||
details on default values. To run the scripts configured in a
|
||
`ResourceDatabasePopulator`, you can invoke either the `populate(Connection)` method to
|
||
run the populator against a `java.sql.Connection` or the `execute(DataSource)` method
|
||
to run the populator against a `javax.sql.DataSource`. The following example
|
||
specifies SQL scripts for a test schema and test data, sets the statement separator to
|
||
`@@`, and run the scripts against a `DataSource`:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@Test
|
||
void databaseTest() {
|
||
ResourceDatabasePopulator populator = new ResourceDatabasePopulator();
|
||
populator.addScripts(
|
||
new ClassPathResource("test-schema.sql"),
|
||
new ClassPathResource("test-data.sql"));
|
||
populator.setSeparator("@@");
|
||
populator.execute(this.dataSource);
|
||
// run code that uses the test schema and data
|
||
}
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@Test
|
||
fun databaseTest() {
|
||
val populator = ResourceDatabasePopulator()
|
||
populator.addScripts(
|
||
ClassPathResource("test-schema.sql"),
|
||
ClassPathResource("test-data.sql"))
|
||
populator.setSeparator("@@")
|
||
populator.execute(dataSource)
|
||
// run code that uses the test schema and data
|
||
}
|
||
----
|
||
|
||
Note that `ResourceDatabasePopulator` internally delegates to `ScriptUtils` for parsing
|
||
and running SQL scripts. Similarly, the `executeSqlScript(..)` methods in
|
||
<<testcontext-support-classes-junit4, `AbstractTransactionalJUnit4SpringContextTests`>>
|
||
and <<testcontext-support-classes-testng, `AbstractTransactionalTestNGSpringContextTests`>>
|
||
internally use a `ResourceDatabasePopulator` to run SQL scripts. See the Javadoc for the
|
||
various `executeSqlScript(..)` methods for further details.
|
||
|
||
[[testcontext-executing-sql-declaratively]]
|
||
===== Executing SQL scripts declaratively with @Sql
|
||
|
||
In addition to the aforementioned mechanisms for running SQL scripts programmatically,
|
||
you can declaratively configure SQL scripts in the Spring TestContext Framework.
|
||
Specifically, you can declare the `@Sql` annotation on a test class or test method to
|
||
configure individual SQL statements or the resource paths to SQL scripts that should be
|
||
run against a given database before or after an integration test method. Support for
|
||
`@Sql` is provided by the `SqlScriptsTestExecutionListener`, which is enabled by default.
|
||
|
||
NOTE: Method-level `@Sql` declarations override class-level declarations by default. As
|
||
of Spring Framework 5.2, however, this behavior may be configured per test class or per
|
||
test method via `@SqlMergeMode`. See
|
||
<<testcontext-executing-sql-declaratively-script-merging>> for further details.
|
||
|
||
[[testcontext-executing-sql-declaratively-script-resources]]
|
||
====== Path Resource Semantics
|
||
|
||
Each path is interpreted as a Spring `Resource`. A plain path (for example,
|
||
`"schema.sql"`) is treated as a classpath resource that is relative to the package in
|
||
which the test class is defined. A path starting with a slash is treated as an absolute
|
||
classpath resource (for example, `"/org/example/schema.sql"`). A path that references a
|
||
URL (for example, a path prefixed with `classpath:`, `file:`, `http:`) is loaded by using
|
||
the specified resource protocol.
|
||
|
||
The following example shows how to use `@Sql` at the class level and at the method level
|
||
within a JUnit Jupiter based integration test class:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@SpringJUnitConfig
|
||
@Sql("/test-schema.sql")
|
||
class DatabaseTests {
|
||
|
||
@Test
|
||
void emptySchemaTest() {
|
||
// run code that uses the test schema without any test data
|
||
}
|
||
|
||
@Test
|
||
@Sql({"/test-schema.sql", "/test-user-data.sql"})
|
||
void userTest() {
|
||
// run code that uses the test schema and test data
|
||
}
|
||
}
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@SpringJUnitConfig
|
||
@Sql("/test-schema.sql")
|
||
class DatabaseTests {
|
||
|
||
@Test
|
||
fun emptySchemaTest() {
|
||
// run code that uses the test schema without any test data
|
||
}
|
||
|
||
@Test
|
||
@Sql("/test-schema.sql", "/test-user-data.sql")
|
||
fun userTest() {
|
||
// run code that uses the test schema and test data
|
||
}
|
||
}
|
||
----
|
||
|
||
[[testcontext-executing-sql-declaratively-script-detection]]
|
||
====== Default Script Detection
|
||
|
||
If no SQL scripts or statements are specified, an attempt is made to detect a `default`
|
||
script, depending on where `@Sql` is declared. If a default cannot be detected, an
|
||
`IllegalStateException` is thrown.
|
||
|
||
* Class-level declaration: If the annotated test class is `com.example.MyTest`, the
|
||
corresponding default script is `classpath:com/example/MyTest.sql`.
|
||
* Method-level declaration: If the annotated test method is named `testMethod()` and is
|
||
defined in the class `com.example.MyTest`, the corresponding default script is
|
||
`classpath:com/example/MyTest.testMethod.sql`.
|
||
|
||
[[testcontext-executing-sql-declaratively-multiple-annotations]]
|
||
====== Declaring Multiple `@Sql` Sets
|
||
|
||
If you need to configure multiple sets of SQL scripts for a given test class or test
|
||
method but with different syntax configuration, different error handling rules, or
|
||
different execution phases per set, you can declare multiple instances of `@Sql`. With
|
||
Java 8, you can use `@Sql` as a repeatable annotation. Otherwise, you can use the
|
||
`@SqlGroup` annotation as an explicit container for declaring multiple instances of
|
||
`@Sql`.
|
||
|
||
The following example shows how to use `@Sql` as a repeatable annotation with Java 8:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@Test
|
||
@Sql(scripts = "/test-schema.sql", config = @SqlConfig(commentPrefix = "`"))
|
||
@Sql("/test-user-data.sql")
|
||
void userTest() {
|
||
// run code that uses the test schema and test data
|
||
}
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
// Repeatable annotations with non-SOURCE retention are not yet supported by Kotlin
|
||
----
|
||
|
||
In the scenario presented in the preceding example, the `test-schema.sql` script uses a
|
||
different syntax for single-line comments.
|
||
|
||
The following example is identical to the preceding example, except that the `@Sql`
|
||
declarations are grouped together within `@SqlGroup`. With Java 8 and above, the use of
|
||
`@SqlGroup` is optional, but you may need to use `@SqlGroup` for compatibility with
|
||
other JVM languages such as Kotlin.
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@Test
|
||
@SqlGroup({
|
||
@Sql(scripts = "/test-schema.sql", config = @SqlConfig(commentPrefix = "`")),
|
||
@Sql("/test-user-data.sql")
|
||
)}
|
||
void userTest() {
|
||
// run code that uses the test schema and test data
|
||
}
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@Test
|
||
@SqlGroup(
|
||
Sql("/test-schema.sql", config = SqlConfig(commentPrefix = "`")),
|
||
Sql("/test-user-data.sql"))
|
||
fun userTest() {
|
||
// Run code that uses the test schema and test data
|
||
}
|
||
----
|
||
|
||
[[testcontext-executing-sql-declaratively-script-execution-phases]]
|
||
====== Script Execution Phases
|
||
|
||
By default, SQL scripts are run before the corresponding test method. However, if
|
||
you need to run a particular set of scripts after the test method (for example, to clean
|
||
up database state), you can use the `executionPhase` attribute in `@Sql`, as the
|
||
following example shows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@Test
|
||
@Sql(
|
||
scripts = "create-test-data.sql",
|
||
config = @SqlConfig(transactionMode = ISOLATED)
|
||
)
|
||
@Sql(
|
||
scripts = "delete-test-data.sql",
|
||
config = @SqlConfig(transactionMode = ISOLATED),
|
||
executionPhase = AFTER_TEST_METHOD
|
||
)
|
||
void userTest() {
|
||
// run code that needs the test data to be committed
|
||
// to the database outside of the test's transaction
|
||
}
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@Test
|
||
@SqlGroup(
|
||
Sql("create-test-data.sql",
|
||
config = SqlConfig(transactionMode = ISOLATED)),
|
||
Sql("delete-test-data.sql",
|
||
config = SqlConfig(transactionMode = ISOLATED),
|
||
executionPhase = AFTER_TEST_METHOD))
|
||
fun userTest() {
|
||
// run code that needs the test data to be committed
|
||
// to the database outside of the test's transaction
|
||
}
|
||
----
|
||
|
||
Note that `ISOLATED` and `AFTER_TEST_METHOD` are statically imported from
|
||
`Sql.TransactionMode` and `Sql.ExecutionPhase`, respectively.
|
||
|
||
[[testcontext-executing-sql-declaratively-script-configuration]]
|
||
====== Script Configuration with `@SqlConfig`
|
||
|
||
You can configure script parsing and error handling by using the `@SqlConfig` annotation.
|
||
When declared as a class-level annotation on an integration test class, `@SqlConfig`
|
||
serves as global configuration for all SQL scripts within the test class hierarchy. When
|
||
declared directly by using the `config` attribute of the `@Sql` annotation, `@SqlConfig`
|
||
serves as local configuration for the SQL scripts declared within the enclosing `@Sql`
|
||
annotation. Every attribute in `@SqlConfig` has an implicit default value, which is
|
||
documented in the javadoc of the corresponding attribute. Due to the rules defined for
|
||
annotation attributes in the Java Language Specification, it is, unfortunately, not
|
||
possible to assign a value of `null` to an annotation attribute. Thus, in order to
|
||
support overrides of inherited global configuration, `@SqlConfig` attributes have an
|
||
explicit default value of either `""` (for Strings), `{}` (for arrays), or `DEFAULT` (for
|
||
enumerations). This approach lets local declarations of `@SqlConfig` selectively override
|
||
individual attributes from global declarations of `@SqlConfig` by providing a value other
|
||
than `""`, `{}`, or `DEFAULT`. Global `@SqlConfig` attributes are inherited whenever
|
||
local `@SqlConfig` attributes do not supply an explicit value other than `""`, `{}`, or
|
||
`DEFAULT`. Explicit local configuration, therefore, overrides global configuration.
|
||
|
||
The configuration options provided by `@Sql` and `@SqlConfig` are equivalent to those
|
||
supported by `ScriptUtils` and `ResourceDatabasePopulator` but are a superset of those
|
||
provided by the `<jdbc:initialize-database/>` XML namespace element. See the javadoc of
|
||
individual attributes in {api-spring-framework}/test/context/jdbc/Sql.html[`@Sql`] and
|
||
{api-spring-framework}/test/context/jdbc/SqlConfig.html[`@SqlConfig`] for details.
|
||
|
||
[[testcontext-executing-sql-declaratively-tx]]
|
||
*Transaction management for `@Sql`*
|
||
|
||
By default, the `SqlScriptsTestExecutionListener` infers the desired transaction
|
||
semantics for scripts configured by using `@Sql`. Specifically, SQL scripts are run
|
||
without a transaction, within an existing Spring-managed transaction (for example, a
|
||
transaction managed by the `TransactionalTestExecutionListener` for a test annotated with
|
||
`@Transactional`), or within an isolated transaction, depending on the configured value
|
||
of the `transactionMode` attribute in `@SqlConfig` and the presence of a
|
||
`PlatformTransactionManager` in the test's `ApplicationContext`. As a bare minimum,
|
||
however, a `javax.sql.DataSource` must be present in the test's `ApplicationContext`.
|
||
|
||
If the algorithms used by `SqlScriptsTestExecutionListener` to detect a `DataSource` and
|
||
`PlatformTransactionManager` and infer the transaction semantics do not suit your needs,
|
||
you can specify explicit names by setting the `dataSource` and `transactionManager`
|
||
attributes of `@SqlConfig`. Furthermore, you can control the transaction propagation
|
||
behavior by setting the `transactionMode` attribute of `@SqlConfig` (for example, whether
|
||
scripts should be run in an isolated transaction). Although a thorough discussion of all
|
||
supported options for transaction management with `@Sql` is beyond the scope of this
|
||
reference manual, the javadoc for
|
||
{api-spring-framework}/test/context/jdbc/SqlConfig.html[`@SqlConfig`] and
|
||
{api-spring-framework}/test/context/jdbc/SqlScriptsTestExecutionListener.html[`SqlScriptsTestExecutionListener`]
|
||
provide detailed information, and the following example shows a typical testing scenario
|
||
that uses JUnit Jupiter and transactional tests with `@Sql`:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@SpringJUnitConfig(TestDatabaseConfig.class)
|
||
@Transactional
|
||
class TransactionalSqlScriptsTests {
|
||
|
||
final JdbcTemplate jdbcTemplate;
|
||
|
||
@Autowired
|
||
TransactionalSqlScriptsTests(DataSource dataSource) {
|
||
this.jdbcTemplate = new JdbcTemplate(dataSource);
|
||
}
|
||
|
||
@Test
|
||
@Sql("/test-data.sql")
|
||
void usersTest() {
|
||
// verify state in test database:
|
||
assertNumUsers(2);
|
||
// run code that uses the test data...
|
||
}
|
||
|
||
int countRowsInTable(String tableName) {
|
||
return JdbcTestUtils.countRowsInTable(this.jdbcTemplate, tableName);
|
||
}
|
||
|
||
void assertNumUsers(int expected) {
|
||
assertEquals(expected, countRowsInTable("user"),
|
||
"Number of rows in the [user] table.");
|
||
}
|
||
}
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@SpringJUnitConfig(TestDatabaseConfig::class)
|
||
@Transactional
|
||
class TransactionalSqlScriptsTests @Autowired constructor(dataSource: DataSource) {
|
||
|
||
val jdbcTemplate: JdbcTemplate = JdbcTemplate(dataSource)
|
||
|
||
@Test
|
||
@Sql("/test-data.sql")
|
||
fun usersTest() {
|
||
// verify state in test database:
|
||
assertNumUsers(2)
|
||
// run code that uses the test data...
|
||
}
|
||
|
||
fun countRowsInTable(tableName: String): Int {
|
||
return JdbcTestUtils.countRowsInTable(jdbcTemplate, tableName)
|
||
}
|
||
|
||
fun assertNumUsers(expected: Int) {
|
||
assertEquals(expected, countRowsInTable("user"),
|
||
"Number of rows in the [user] table.")
|
||
}
|
||
}
|
||
----
|
||
|
||
Note that there is no need to clean up the database after the `usersTest()` method is
|
||
run, since any changes made to the database (either within the test method or within the
|
||
`/test-data.sql` script) are automatically rolled back by the
|
||
`TransactionalTestExecutionListener` (see <<testcontext-tx,transaction management>> for
|
||
details).
|
||
|
||
[[testcontext-executing-sql-declaratively-script-merging]]
|
||
====== Merging and Overriding Configuration with `@SqlMergeMode`
|
||
|
||
As of Spring Framework 5.2, it is possible to merge method-level `@Sql` declarations with
|
||
class-level declarations. For example, this allows you to provide the configuration for a
|
||
database schema or some common test data once per test class and then provide additional,
|
||
use case specific test data per test method. To enable `@Sql` merging, annotate either
|
||
your test class or test method with `@SqlMergeMode(MERGE)`. To disable merging for a
|
||
specific test method (or specific test subclass), you can switch back to the default mode
|
||
via `@SqlMergeMode(OVERRIDE)`. Consult the <<spring-testing-annotation-sqlmergemode,
|
||
`@SqlMergeMode` annotation documentation section>> for examples and further details.
|
||
|
||
|
||
[[testcontext-parallel-test-execution]]
|
||
==== Parallel Test Execution
|
||
|
||
Spring Framework 5.0 introduced basic support for executing tests in parallel within a
|
||
single JVM when using the Spring TestContext Framework. In general, this means that most
|
||
test classes or test methods can be run in parallel without any changes to test code
|
||
or configuration.
|
||
|
||
TIP: For details on how to set up parallel test execution, see the documentation for your
|
||
testing framework, build tool, or IDE.
|
||
|
||
Keep in mind that the introduction of concurrency into your test suite can result in
|
||
unexpected side effects, strange runtime behavior, and tests that fail intermittently or
|
||
seemingly randomly. The Spring Team therefore provides the following general guidelines
|
||
for when not to run tests in parallel.
|
||
|
||
Do not run tests in parallel if the tests:
|
||
|
||
* Use Spring Framework's `@DirtiesContext` support.
|
||
* Use Spring Boot's `@MockBean` or `@SpyBean` support.
|
||
* Use JUnit 4's `@FixMethodOrder` support or any testing framework feature
|
||
that is designed to ensure that test methods run in a particular order. Note,
|
||
however, that this does not apply if entire test classes are run in parallel.
|
||
* Change the state of shared services or systems such as a database, message broker,
|
||
filesystem, and others. This applies to both embedded and external systems.
|
||
|
||
[TIP]
|
||
====
|
||
If parallel test execution fails with an exception stating that the `ApplicationContext`
|
||
for the current test is no longer active, this typically means that the
|
||
`ApplicationContext` was removed from the `ContextCache` in a different thread.
|
||
|
||
This may be due to the use of `@DirtiesContext` or due to automatic eviction from the
|
||
`ContextCache`. If `@DirtiesContext` is the culprit, you either need to find a way to
|
||
avoid using `@DirtiesContext` or exclude such tests from parallel execution. If the
|
||
maximum size of the `ContextCache` has been exceeded, you can increase the maximum size
|
||
of the cache. See the discussion on <<testcontext-ctx-management-caching, context caching>>
|
||
for details.
|
||
====
|
||
|
||
WARNING: Parallel test execution in the Spring TestContext Framework is only possible if
|
||
the underlying `TestContext` implementation provides a copy constructor, as explained in
|
||
the javadoc for {api-spring-framework}/test/context/TestContext.html[`TestContext`]. The
|
||
`DefaultTestContext` used in Spring provides such a constructor. However, if you use a
|
||
third-party library that provides a custom `TestContext` implementation, you need to
|
||
verify that it is suitable for parallel test execution.
|
||
|
||
|
||
[[testcontext-support-classes]]
|
||
==== TestContext Framework Support Classes
|
||
|
||
This section describes the various classes that support the Spring TestContext Framework.
|
||
|
||
[[testcontext-junit4-runner]]
|
||
===== Spring JUnit 4 Runner
|
||
|
||
The Spring TestContext Framework offers full integration with JUnit 4 through a custom
|
||
runner (supported on JUnit 4.12 or higher). By annotating test classes with
|
||
`@RunWith(SpringJUnit4ClassRunner.class)` or the shorter `@RunWith(SpringRunner.class)`
|
||
variant, developers can implement standard JUnit 4-based unit and integration tests and
|
||
simultaneously reap the benefits of the TestContext framework, such as support for
|
||
loading application contexts, dependency injection of test instances, transactional test
|
||
method execution, and so on. If you want to use the Spring TestContext Framework with an
|
||
alternative runner (such as JUnit 4's `Parameterized` runner) or third-party runners
|
||
(such as the `MockitoJUnitRunner`), you can, optionally, use
|
||
<<testcontext-junit4-rules, Spring's support for JUnit rules>> instead.
|
||
|
||
The following code listing shows the minimal requirements for configuring a test class to
|
||
run with the custom Spring `Runner`:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@RunWith(SpringRunner.class)
|
||
@TestExecutionListeners({})
|
||
public class SimpleTest {
|
||
|
||
@Test
|
||
public void testMethod() {
|
||
// test logic...
|
||
}
|
||
}
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@RunWith(SpringRunner::class)
|
||
@TestExecutionListeners
|
||
class SimpleTest {
|
||
|
||
@Test
|
||
fun testMethod() {
|
||
// test logic...
|
||
}
|
||
}
|
||
----
|
||
|
||
In the preceding example, `@TestExecutionListeners` is configured with an empty list, to
|
||
disable the default listeners, which otherwise would require an `ApplicationContext` to
|
||
be configured through `@ContextConfiguration`.
|
||
|
||
[[testcontext-junit4-rules]]
|
||
===== Spring JUnit 4 Rules
|
||
|
||
The `org.springframework.test.context.junit4.rules` package provides the following JUnit
|
||
4 rules (supported on JUnit 4.12 or higher):
|
||
|
||
* `SpringClassRule`
|
||
* `SpringMethodRule`
|
||
|
||
`SpringClassRule` is a JUnit `TestRule` that supports class-level features of the Spring
|
||
TestContext Framework, whereas `SpringMethodRule` is a JUnit `MethodRule` that supports
|
||
instance-level and method-level features of the Spring TestContext Framework.
|
||
|
||
In contrast to the `SpringRunner`, Spring's rule-based JUnit support has the advantage of
|
||
being independent of any `org.junit.runner.Runner` implementation and can, therefore, be
|
||
combined with existing alternative runners (such as JUnit 4's `Parameterized`) or
|
||
third-party runners (such as the `MockitoJUnitRunner`).
|
||
|
||
To support the full functionality of the TestContext framework, you must combine a
|
||
`SpringClassRule` with a `SpringMethodRule`. The following example shows the proper way
|
||
to declare these rules in an integration test:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
// Optionally specify a non-Spring Runner via @RunWith(...)
|
||
@ContextConfiguration
|
||
public class IntegrationTest {
|
||
|
||
@ClassRule
|
||
public static final SpringClassRule springClassRule = new SpringClassRule();
|
||
|
||
@Rule
|
||
public final SpringMethodRule springMethodRule = new SpringMethodRule();
|
||
|
||
@Test
|
||
public void testMethod() {
|
||
// test logic...
|
||
}
|
||
}
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
// Optionally specify a non-Spring Runner via @RunWith(...)
|
||
@ContextConfiguration
|
||
class IntegrationTest {
|
||
|
||
@Rule
|
||
val springMethodRule = SpringMethodRule()
|
||
|
||
@Test
|
||
fun testMethod() {
|
||
// test logic...
|
||
}
|
||
|
||
companion object {
|
||
@ClassRule
|
||
val springClassRule = SpringClassRule()
|
||
}
|
||
}
|
||
----
|
||
|
||
[[testcontext-support-classes-junit4]]
|
||
===== JUnit 4 Support Classes
|
||
|
||
The `org.springframework.test.context.junit4` package provides the following support
|
||
classes for JUnit 4-based test cases (supported on JUnit 4.12 or higher):
|
||
|
||
* `AbstractJUnit4SpringContextTests`
|
||
* `AbstractTransactionalJUnit4SpringContextTests`
|
||
|
||
`AbstractJUnit4SpringContextTests` is an abstract base test class that integrates the
|
||
Spring TestContext Framework with explicit `ApplicationContext` testing support in a
|
||
JUnit 4 environment. When you extend `AbstractJUnit4SpringContextTests`, you can access a
|
||
`protected` `applicationContext` instance variable that you can use to perform explicit
|
||
bean lookups or to test the state of the context as a whole.
|
||
|
||
`AbstractTransactionalJUnit4SpringContextTests` is an abstract transactional extension of
|
||
`AbstractJUnit4SpringContextTests` that adds some convenience functionality for JDBC
|
||
access. This class expects a `javax.sql.DataSource` bean and a
|
||
`PlatformTransactionManager` bean to be defined in the `ApplicationContext`. When you
|
||
extend `AbstractTransactionalJUnit4SpringContextTests`, you can access a `protected`
|
||
`jdbcTemplate` instance variable that you can use to run SQL statements to query the
|
||
database. You can use such queries to confirm database state both before and after
|
||
running 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 <<testcontext-tx-false-positives, false positives>>.
|
||
As mentioned in <<integration-testing-support-jdbc>>,
|
||
`AbstractTransactionalJUnit4SpringContextTests` also provides convenience methods that
|
||
delegate to methods in `JdbcTestUtils` by using the aforementioned `jdbcTemplate`.
|
||
Furthermore, `AbstractTransactionalJUnit4SpringContextTests` provides an
|
||
`executeSqlScript(..)` method for running SQL scripts against the configured `DataSource`.
|
||
|
||
TIP: These classes are a convenience for extension. If you do not want your test classes
|
||
to be tied to a Spring-specific class hierarchy, you can configure your own custom test
|
||
classes by using `@RunWith(SpringRunner.class)` or <<testcontext-junit4-rules, Spring's
|
||
JUnit rules>>.
|
||
|
||
[[testcontext-junit-jupiter-extension]]
|
||
===== SpringExtension for JUnit Jupiter
|
||
|
||
The Spring TestContext Framework offers full integration with the JUnit Jupiter testing
|
||
framework, introduced in JUnit 5. By annotating test classes with
|
||
`@ExtendWith(SpringExtension.class)`, you can implement standard JUnit Jupiter-based unit
|
||
and integration tests and simultaneously reap the benefits of the TestContext framework,
|
||
such as support for loading application contexts, dependency injection of test instances,
|
||
transactional test method execution, and so on.
|
||
|
||
Furthermore, thanks to the rich extension API in JUnit Jupiter, Spring provides the
|
||
following features above and beyond the feature set that Spring supports for JUnit 4 and
|
||
TestNG:
|
||
|
||
* Dependency injection for test constructors, test methods, and test lifecycle callback
|
||
methods. See <<testcontext-junit-jupiter-di>> for further details.
|
||
* Powerful support for link:https://junit.org/junit5/docs/current/user-guide/#extensions-conditions[conditional
|
||
test execution] based on SpEL expressions, environment variables, system properties,
|
||
and so on. See the documentation for `@EnabledIf` and `@DisabledIf` in
|
||
<<integration-testing-annotations-junit-jupiter>> for further details and examples.
|
||
* Custom composed annotations that combine annotations from Spring and JUnit Jupiter. See
|
||
the `@TransactionalDevTestConfig` and `@TransactionalIntegrationTest` examples in
|
||
<<integration-testing-annotations-meta>> for further details.
|
||
|
||
The following code listing shows how to configure a test class to use the
|
||
`SpringExtension` in conjunction with `@ContextConfiguration`:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
// Instructs JUnit Jupiter to extend the test with Spring support.
|
||
@ExtendWith(SpringExtension.class)
|
||
// Instructs Spring to load an ApplicationContext from TestConfig.class
|
||
@ContextConfiguration(classes = TestConfig.class)
|
||
class SimpleTests {
|
||
|
||
@Test
|
||
void testMethod() {
|
||
// test logic...
|
||
}
|
||
}
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
// Instructs JUnit Jupiter to extend the test with Spring support.
|
||
@ExtendWith(SpringExtension::class)
|
||
// Instructs Spring to load an ApplicationContext from TestConfig::class
|
||
@ContextConfiguration(classes = [TestConfig::class])
|
||
class SimpleTests {
|
||
|
||
@Test
|
||
fun testMethod() {
|
||
// test logic...
|
||
}
|
||
}
|
||
----
|
||
|
||
Since you can also use annotations in JUnit 5 as meta-annotations, Spring provides the
|
||
`@SpringJUnitConfig` and `@SpringJUnitWebConfig` composed annotations to simplify the
|
||
configuration of the test `ApplicationContext` and JUnit Jupiter.
|
||
|
||
The following example uses `@SpringJUnitConfig` to reduce the amount of configuration
|
||
used in the previous example:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
// Instructs Spring to register the SpringExtension with JUnit
|
||
// Jupiter and load an ApplicationContext from TestConfig.class
|
||
@SpringJUnitConfig(TestConfig.class)
|
||
class SimpleTests {
|
||
|
||
@Test
|
||
void testMethod() {
|
||
// test logic...
|
||
}
|
||
}
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
// Instructs Spring to register the SpringExtension with JUnit
|
||
// Jupiter and load an ApplicationContext from TestConfig.class
|
||
@SpringJUnitConfig(TestConfig::class)
|
||
class SimpleTests {
|
||
|
||
@Test
|
||
fun testMethod() {
|
||
// test logic...
|
||
}
|
||
}
|
||
----
|
||
|
||
Similarly, the following example uses `@SpringJUnitWebConfig` to create a
|
||
`WebApplicationContext` for use with JUnit Jupiter:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
// Instructs Spring to register the SpringExtension with JUnit
|
||
// Jupiter and load a WebApplicationContext from TestWebConfig.class
|
||
@SpringJUnitWebConfig(TestWebConfig.class)
|
||
class SimpleWebTests {
|
||
|
||
@Test
|
||
void testMethod() {
|
||
// test logic...
|
||
}
|
||
}
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
// Instructs Spring to register the SpringExtension with JUnit
|
||
// Jupiter and load a WebApplicationContext from TestWebConfig::class
|
||
@SpringJUnitWebConfig(TestWebConfig::class)
|
||
class SimpleWebTests {
|
||
|
||
@Test
|
||
fun testMethod() {
|
||
// test logic...
|
||
}
|
||
}
|
||
----
|
||
|
||
See the documentation for `@SpringJUnitConfig` and `@SpringJUnitWebConfig` in
|
||
<<integration-testing-annotations-junit-jupiter>> for further details.
|
||
|
||
[[testcontext-junit-jupiter-di]]
|
||
===== Dependency Injection with `SpringExtension`
|
||
|
||
`SpringExtension` implements the
|
||
link:https://junit.org/junit5/docs/current/user-guide/#extensions-parameter-resolution[`ParameterResolver`]
|
||
extension API from JUnit Jupiter, which lets Spring provide dependency injection for test
|
||
constructors, test methods, and test lifecycle callback methods.
|
||
|
||
Specifically, `SpringExtension` can inject dependencies from the test's
|
||
`ApplicationContext` into test constructors and methods that are annotated with
|
||
`@BeforeAll`, `@AfterAll`, `@BeforeEach`, `@AfterEach`, `@Test`, `@RepeatedTest`,
|
||
`@ParameterizedTest`, and others.
|
||
|
||
[[testcontext-junit-jupiter-di-constructor]]
|
||
====== Constructor Injection
|
||
|
||
If a specific parameter in a constructor for a JUnit Jupiter test class is of type
|
||
`ApplicationContext` (or a sub-type thereof) or is annotated or meta-annotated with
|
||
`@Autowired`, `@Qualifier`, or `@Value`, Spring injects the value for that specific
|
||
parameter with the corresponding bean or value from the test's `ApplicationContext`.
|
||
|
||
Spring can also be configured to autowire all arguments for a test class constructor if
|
||
the constructor is considered to be _autowirable_. A constructor is considered to be
|
||
autowirable if one of the following conditions is met (in order of precedence).
|
||
|
||
* The constructor is annotated with `@Autowired`.
|
||
* `@TestConstructor` is present or meta-present on the test class with the `autowireMode`
|
||
attribute set to `ALL`.
|
||
* The default _test constructor autowire mode_ has been changed to `ALL`.
|
||
|
||
See <<integration-testing-annotations-testconstructor>> for details on the use of
|
||
`@TestConstructor` and how to change the global _test constructor autowire mode_.
|
||
|
||
WARNING: If the constructor for a test class is considered to be _autowirable_, Spring
|
||
assumes the responsibility for resolving arguments for all parameters in the constructor.
|
||
Consequently, no other `ParameterResolver` registered with JUnit Jupiter can resolve
|
||
parameters for such a constructor.
|
||
|
||
[WARNING]
|
||
====
|
||
Constructor injection for test classes must not be used in conjunction with JUnit
|
||
Jupiter's `@TestInstance(PER_CLASS)` support if `@DirtiesContext` is used to close the
|
||
test's `ApplicationContext` before or after test methods.
|
||
|
||
The reason is that `@TestInstance(PER_CLASS)` instructs JUnit Jupiter to cache the test
|
||
instance between test method invocations. Consequently, the test instance will retain
|
||
references to beans that were originally injected from an `ApplicationContext` that has
|
||
been subsequently closed. Since the constructor for the test class will only be invoked
|
||
once in such scenarios, dependency injection will not occur again, and subsequent tests
|
||
will interact with beans from the closed `ApplicationContext` which may result in errors.
|
||
|
||
To use `@DirtiesContext` with "before test method" or "after test method" modes in
|
||
conjunction with `@TestInstance(PER_CLASS)`, one must configure dependencies from Spring
|
||
to be supplied via field or setter injection so that they can be re-injected between test
|
||
method invocations.
|
||
====
|
||
|
||
In the following example, Spring injects the `OrderService` bean from the
|
||
`ApplicationContext` loaded from `TestConfig.class` into the
|
||
`OrderServiceIntegrationTests` constructor.
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@SpringJUnitConfig(TestConfig.class)
|
||
class OrderServiceIntegrationTests {
|
||
|
||
private final OrderService orderService;
|
||
|
||
@Autowired
|
||
OrderServiceIntegrationTests(OrderService orderService) {
|
||
this.orderService = orderService;
|
||
}
|
||
|
||
// tests that use the injected OrderService
|
||
}
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@SpringJUnitConfig(TestConfig::class)
|
||
class OrderServiceIntegrationTests @Autowired constructor(private val orderService: OrderService){
|
||
// tests that use the injected OrderService
|
||
}
|
||
|
||
----
|
||
|
||
Note that this feature lets test dependencies be `final` and therefore immutable.
|
||
|
||
If the `spring.test.constructor.autowire.mode` property is to `all` (see
|
||
<<integration-testing-annotations-testconstructor>>), we can omit the declaration of
|
||
`@Autowired` on the constructor in the previous example, resulting in the following.
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@SpringJUnitConfig(TestConfig.class)
|
||
class OrderServiceIntegrationTests {
|
||
|
||
private final OrderService orderService;
|
||
|
||
OrderServiceIntegrationTests(OrderService orderService) {
|
||
this.orderService = orderService;
|
||
}
|
||
|
||
// tests that use the injected OrderService
|
||
}
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@SpringJUnitConfig(TestConfig::class)
|
||
class OrderServiceIntegrationTests(val orderService:OrderService) {
|
||
// tests that use the injected OrderService
|
||
}
|
||
----
|
||
|
||
[[testcontext-junit-jupiter-di-method]]
|
||
====== Method Injection
|
||
|
||
If a parameter in a JUnit Jupiter test method or test lifecycle callback method is of
|
||
type `ApplicationContext` (or a sub-type thereof) or is annotated or meta-annotated with
|
||
`@Autowired`, `@Qualifier`, or `@Value`, Spring injects the value for that specific
|
||
parameter with the corresponding bean from the test's `ApplicationContext`.
|
||
|
||
In the following example, Spring injects the `OrderService` from the `ApplicationContext`
|
||
loaded from `TestConfig.class` into the `deleteOrder()` test method:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@SpringJUnitConfig(TestConfig.class)
|
||
class OrderServiceIntegrationTests {
|
||
|
||
@Test
|
||
void deleteOrder(@Autowired OrderService orderService) {
|
||
// use orderService from the test's ApplicationContext
|
||
}
|
||
}
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@SpringJUnitConfig(TestConfig::class)
|
||
class OrderServiceIntegrationTests {
|
||
|
||
@Test
|
||
fun deleteOrder(@Autowired orderService: OrderService) {
|
||
// use orderService from the test's ApplicationContext
|
||
}
|
||
}
|
||
----
|
||
|
||
Due to the robustness of the `ParameterResolver` support in JUnit Jupiter, you can also
|
||
have multiple dependencies injected into a single method, not only from Spring but also
|
||
from JUnit Jupiter itself or other third-party extensions.
|
||
|
||
The following example shows how to have both Spring and JUnit Jupiter inject dependencies
|
||
into the `placeOrderRepeatedly()` test method simultaneously.
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@SpringJUnitConfig(TestConfig.class)
|
||
class OrderServiceIntegrationTests {
|
||
|
||
@RepeatedTest(10)
|
||
void placeOrderRepeatedly(RepetitionInfo repetitionInfo,
|
||
@Autowired OrderService orderService) {
|
||
|
||
// use orderService from the test's ApplicationContext
|
||
// and repetitionInfo from JUnit Jupiter
|
||
}
|
||
}
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@SpringJUnitConfig(TestConfig::class)
|
||
class OrderServiceIntegrationTests {
|
||
|
||
@RepeatedTest(10)
|
||
fun placeOrderRepeatedly(repetitionInfo:RepetitionInfo, @Autowired orderService:OrderService) {
|
||
|
||
// use orderService from the test's ApplicationContext
|
||
// and repetitionInfo from JUnit Jupiter
|
||
}
|
||
}
|
||
----
|
||
|
||
Note that the use of `@RepeatedTest` from JUnit Jupiter lets the test method gain access
|
||
to the `RepetitionInfo`.
|
||
|
||
[[testcontext-support-classes-testng]]
|
||
===== TestNG Support Classes
|
||
|
||
The `org.springframework.test.context.testng` package provides the following support
|
||
classes for TestNG based test cases:
|
||
|
||
* `AbstractTestNGSpringContextTests`
|
||
* `AbstractTransactionalTestNGSpringContextTests`
|
||
|
||
`AbstractTestNGSpringContextTests` is an abstract base test class that integrates the
|
||
Spring TestContext Framework with explicit `ApplicationContext` testing support in a
|
||
TestNG environment. When you extend `AbstractTestNGSpringContextTests`, you can access a
|
||
`protected` `applicationContext` instance variable that you can use to perform explicit
|
||
bean lookups or to test the state of the context as a whole.
|
||
|
||
`AbstractTransactionalTestNGSpringContextTests` is an abstract transactional extension of
|
||
`AbstractTestNGSpringContextTests` that adds some convenience functionality for JDBC
|
||
access. This class expects a `javax.sql.DataSource` bean and a
|
||
`PlatformTransactionManager` bean to be defined in the `ApplicationContext`. When you
|
||
extend `AbstractTransactionalTestNGSpringContextTests`, you can access a `protected`
|
||
`jdbcTemplate` instance variable that you can use to run SQL statements to query the
|
||
database. You can use such queries to confirm database state both before and after
|
||
running 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 <<testcontext-tx-false-positives, false positives>>.
|
||
As mentioned in <<integration-testing-support-jdbc>>,
|
||
`AbstractTransactionalTestNGSpringContextTests` also provides convenience methods that
|
||
delegate to methods in `JdbcTestUtils` by using the aforementioned `jdbcTemplate`.
|
||
Furthermore, `AbstractTransactionalTestNGSpringContextTests` provides an
|
||
`executeSqlScript(..)` method for running SQL scripts against the configured `DataSource`.
|
||
|
||
TIP: These classes are a convenience for extension. If you do not want your test classes
|
||
to be tied to a Spring-specific class hierarchy, you can configure your own custom test
|
||
classes by using `@ContextConfiguration`, `@TestExecutionListeners`, and so on and by
|
||
manually instrumenting your test class with a `TestContextManager`. See the source code
|
||
of `AbstractTestNGSpringContextTests` for an example of how to instrument your test class.
|
||
|
||
|
||
|
||
include::testing/testing-webtestclient.adoc[leveloffset=+2]
|
||
|
||
|
||
|
||
[[spring-mvc-test-framework]]
|
||
=== MockMvc
|
||
|
||
The Spring MVC Test framework, also known as MockMvc, provides support for testing Spring
|
||
MVC applications. It performs full Spring MVC request handling but via mock request and
|
||
response objects instead of a running server.
|
||
|
||
MockMvc can be used on its own to perform requests and verify responses. It can also be
|
||
used through the <<webtestclient>> where MockMvc is plugged in as the server to handle
|
||
requests with. The advantage of `WebTestClient` is the option to work with higher level
|
||
objects instead of raw data as well as the ability to switch to full, end-to-end HTTP
|
||
tests against a live server and use the same test API.
|
||
|
||
|
||
[[spring-mvc-test-server]]
|
||
==== Overview
|
||
|
||
You can write plain unit tests for Spring MVC by instantiating a controller, injecting it
|
||
with dependencies, and calling its methods. However such tests do not verify request
|
||
mappings, data binding, message conversion, type conversion, validation, and nor
|
||
do they involve any of the supporting `@InitBinder`, `@ModelAttribute`, or
|
||
`@ExceptionHandler` methods.
|
||
|
||
The Spring MVC Test framework, also known as `MockMvc`, aims to provide more complete
|
||
testing for Spring MVC controllers without a running server. It does that by invoking
|
||
the `DispacherServlet` and passing
|
||
<<mock-objects-servlet, "`mock`" implementations of the Servlet API>> from the
|
||
`spring-test` module which replicates the full Spring MVC request handling without
|
||
a running server.
|
||
|
||
MockMvc is a server side test framework that lets you verify most of the functionality
|
||
of a Spring MVC application using lightweight and targeted tests. You can use it on
|
||
its own to perform requests and to verify responses, or you can also use it through
|
||
the <<webtestclient>> API with MockMvc plugged in as the server to handle requests
|
||
with.
|
||
|
||
|
||
[[spring-mvc-test-server-static-imports]]
|
||
===== Static Imports
|
||
|
||
When using MockMvc directly to perform requests, you'll need static imports for:
|
||
|
||
- `MockMvcBuilders.{asterisk}`
|
||
- `MockMvcRequestBuilders.{asterisk}`
|
||
- `MockMvcResultMatchers.{asterisk}`
|
||
- `MockMvcResultHandlers.{asterisk}`
|
||
|
||
An easy way to remember that is search for `MockMvc*`. If using Eclipse be sure to also
|
||
add the above as "`favorite static members`" in the Eclipse preferences.
|
||
|
||
When using MockMvc through the <<webtestclient>> you do not need static imports.
|
||
The `WebTestClient` provides a fluent API without static imports.
|
||
|
||
|
||
[[spring-mvc-test-server-setup-options]]
|
||
===== Setup Choices
|
||
|
||
MockMvc can be setup in one of two ways. One is to point directly to the controllers you
|
||
want to test and programmatically configure Spring MVC infrastructure. The second is to
|
||
point to Spring configuration with Spring MVC and controller infrastructure in it.
|
||
|
||
To set up MockMvc for testing a specific controller, use the following:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
class MyWebTests {
|
||
|
||
MockMvc mockMvc;
|
||
|
||
@BeforeEach
|
||
void setup() {
|
||
this.mockMvc = MockMvcBuilders.standaloneSetup(new AccountController()).build();
|
||
}
|
||
|
||
// ...
|
||
|
||
}
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
class MyWebTests {
|
||
|
||
lateinit var mockMvc : MockMvc
|
||
|
||
@BeforeEach
|
||
fun setup() {
|
||
mockMvc = MockMvcBuilders.standaloneSetup(AccountController()).build()
|
||
}
|
||
|
||
// ...
|
||
|
||
}
|
||
----
|
||
|
||
Or you can also use this setup when testing through the
|
||
<<webtestclient-controller-config, WebTestClient>> which delegates to the same builder
|
||
as shown above.
|
||
|
||
To set up MockMvc through Spring configuration, use the following:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@SpringJUnitWebConfig(locations = "my-servlet-context.xml")
|
||
class MyWebTests {
|
||
|
||
MockMvc mockMvc;
|
||
|
||
@BeforeEach
|
||
void setup(WebApplicationContext wac) {
|
||
this.mockMvc = MockMvcBuilders.webAppContextSetup(this.wac).build();
|
||
}
|
||
|
||
// ...
|
||
|
||
}
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@SpringJUnitWebConfig(locations = ["my-servlet-context.xml"])
|
||
class MyWebTests {
|
||
|
||
lateinit var mockMvc: MockMvc
|
||
|
||
@BeforeEach
|
||
fun setup(wac: WebApplicationContext) {
|
||
mockMvc = MockMvcBuilders.webAppContextSetup(wac).build()
|
||
}
|
||
|
||
// ...
|
||
|
||
}
|
||
----
|
||
|
||
Or you can also use this setup when testing through the
|
||
<<webtestclient-context-config, WebTestClient>> which delegates to the same builder
|
||
as shown above.
|
||
|
||
|
||
|
||
Which setup option should you use?
|
||
|
||
The `webAppContextSetup` loads your actual Spring MVC configuration, resulting in a more
|
||
complete integration test. Since the TestContext framework caches the loaded Spring
|
||
configuration, it helps keep tests running fast, even as you introduce more tests in your
|
||
test suite. Furthermore, you can inject mock services into controllers through Spring
|
||
configuration to remain focused on testing the web layer. The following example declares
|
||
a mock service with Mockito:
|
||
|
||
[source,xml,indent=0,subs="verbatim,quotes"]
|
||
----
|
||
<bean id="accountService" class="org.mockito.Mockito" factory-method="mock">
|
||
<constructor-arg value="org.example.AccountService"/>
|
||
</bean>
|
||
----
|
||
|
||
You can then inject the mock service into the test to set up and verify your
|
||
expectations, as the following example shows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@SpringJUnitWebConfig(locations = "test-servlet-context.xml")
|
||
class AccountTests {
|
||
|
||
@Autowired
|
||
AccountService accountService;
|
||
|
||
MockMvc mockMvc;
|
||
|
||
@BeforeEach
|
||
void setup(WebApplicationContext wac) {
|
||
this.mockMvc = MockMvcBuilders.webAppContextSetup(wac).build();
|
||
}
|
||
|
||
// ...
|
||
|
||
}
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@SpringJUnitWebConfig(locations = ["test-servlet-context.xml"])
|
||
class AccountTests {
|
||
|
||
@Autowired
|
||
lateinit var accountService: AccountService
|
||
|
||
lateinit mockMvc: MockMvc
|
||
|
||
@BeforeEach
|
||
fun setup(wac: WebApplicationContext) {
|
||
mockMvc = MockMvcBuilders.webAppContextSetup(wac).build()
|
||
}
|
||
|
||
// ...
|
||
|
||
}
|
||
----
|
||
|
||
The `standaloneSetup`, on the other hand, is a little closer to a unit test. It tests one
|
||
controller at a time. You can manually inject the controller with mock dependencies, and
|
||
it does not involve loading Spring configuration. Such tests are more focused on style
|
||
and make it easier to see which controller is being tested, whether any specific Spring
|
||
MVC configuration is required to work, and so on. The `standaloneSetup` is also a very
|
||
convenient way to write ad-hoc tests to verify specific behavior or to debug an issue.
|
||
|
||
As with most "`integration versus unit testing`" debates, there is no right or wrong
|
||
answer. However, using the `standaloneSetup` does imply the need for additional
|
||
`webAppContextSetup` tests in order to verify your Spring MVC configuration.
|
||
Alternatively, you can write all your tests with `webAppContextSetup`, in order to always
|
||
test against your actual Spring MVC configuration.
|
||
|
||
[[spring-mvc-test-server-setup-steps]]
|
||
===== Setup Features
|
||
|
||
No matter which MockMvc builder you use, all `MockMvcBuilder` implementations provide
|
||
some common and very useful features. For example, you can declare an `Accept` header for
|
||
all requests and expect a status of 200 as well as a `Content-Type` header in all
|
||
responses, as follows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
// static import of MockMvcBuilders.standaloneSetup
|
||
|
||
MockMvc mockMvc = standaloneSetup(new MusicController())
|
||
.defaultRequest(get("/").accept(MediaType.APPLICATION_JSON))
|
||
.alwaysExpect(status().isOk())
|
||
.alwaysExpect(content().contentType("application/json;charset=UTF-8"))
|
||
.build();
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
// Not possible in Kotlin until https://youtrack.jetbrains.com/issue/KT-22208 is fixed
|
||
----
|
||
|
||
In addition, third-party frameworks (and applications) can pre-package setup
|
||
instructions, such as those in a `MockMvcConfigurer`. The Spring Framework has one such
|
||
built-in implementation that helps to save and re-use the HTTP session across requests.
|
||
You can use it as follows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
// static import of SharedHttpSessionConfigurer.sharedHttpSession
|
||
|
||
MockMvc mockMvc = MockMvcBuilders.standaloneSetup(new TestController())
|
||
.apply(sharedHttpSession())
|
||
.build();
|
||
|
||
// Use mockMvc to perform requests...
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
// Not possible in Kotlin until https://youtrack.jetbrains.com/issue/KT-22208 is fixed
|
||
----
|
||
|
||
See the javadoc for
|
||
{api-spring-framework}/test/web/servlet/setup/ConfigurableMockMvcBuilder.html[`ConfigurableMockMvcBuilder`]
|
||
for a list of all MockMvc builder features or use the IDE to explore the available options.
|
||
|
||
[[spring-mvc-test-server-performing-requests]]
|
||
===== Performing Requests
|
||
|
||
This section shows how to use MockMvc on its own to perform requests and verify responses.
|
||
If using MockMvc through the `WebTestClient` please see the corresponding section on
|
||
<<webtestclient-tests>> instead.
|
||
|
||
To perform requests that use any HTTP method, as the following example shows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
mockMvc.perform(post("/hotels/{id}", 42).accept(MediaType.APPLICATION_JSON));
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
import org.springframework.test.web.servlet.post
|
||
|
||
mockMvc.post("/hotels/{id}", 42) {
|
||
accept = MediaType.APPLICATION_JSON
|
||
}
|
||
----
|
||
|
||
You can also perform file upload requests that internally use
|
||
`MockMultipartHttpServletRequest` so that there is no actual parsing of a multipart
|
||
request. Rather, you have to set it up to be similar to the following example:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
mockMvc.perform(multipart("/doc").file("a1", "ABC".getBytes("UTF-8")));
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
import org.springframework.test.web.servlet.multipart
|
||
|
||
mockMvc.multipart("/doc") {
|
||
file("a1", "ABC".toByteArray(charset("UTF8")))
|
||
}
|
||
----
|
||
|
||
You can specify query parameters in URI template style, as the following example shows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
mockMvc.perform(get("/hotels?thing={thing}", "somewhere"));
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
mockMvc.get("/hotels?thing={thing}", "somewhere")
|
||
----
|
||
|
||
You can also add Servlet request parameters that represent either query or form
|
||
parameters, as the following example shows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
mockMvc.perform(get("/hotels").param("thing", "somewhere"));
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
import org.springframework.test.web.servlet.get
|
||
|
||
mockMvc.get("/hotels") {
|
||
param("thing", "somewhere")
|
||
}
|
||
----
|
||
|
||
If application code relies on Servlet request parameters and does not check the query
|
||
string explicitly (as is most often the case), it does not matter which option you use.
|
||
Keep in mind, however, that query parameters provided with the URI template are decoded
|
||
while request parameters provided through the `param(...)` method are expected to already
|
||
be decoded.
|
||
|
||
In most cases, it is preferable to leave the context path and the Servlet path out of the
|
||
request URI. If you must test with the full request URI, be sure to set the `contextPath`
|
||
and `servletPath` accordingly so that request mappings work, as the following example
|
||
shows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
mockMvc.perform(get("/app/main/hotels/{id}").contextPath("/app").servletPath("/main"))
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
import org.springframework.test.web.servlet.get
|
||
|
||
mockMvc.get("/app/main/hotels/{id}") {
|
||
contextPath = "/app"
|
||
servletPath = "/main"
|
||
}
|
||
----
|
||
|
||
In the preceding example, it would be cumbersome to set the `contextPath` and
|
||
`servletPath` with every performed request. Instead, you can set up default request
|
||
properties, as the following example shows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
class MyWebTests {
|
||
|
||
MockMvc mockMvc;
|
||
|
||
@BeforeEach
|
||
void setup() {
|
||
mockMvc = standaloneSetup(new AccountController())
|
||
.defaultRequest(get("/")
|
||
.contextPath("/app").servletPath("/main")
|
||
.accept(MediaType.APPLICATION_JSON)).build();
|
||
}
|
||
}
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
// Not possible in Kotlin until https://youtrack.jetbrains.com/issue/KT-22208 is fixed
|
||
----
|
||
|
||
The preceding properties affect every request performed through the `MockMvc` instance.
|
||
If the same property is also specified on a given request, it overrides the default
|
||
value. That is why the HTTP method and URI in the default request do not matter, since
|
||
they must be specified on every request.
|
||
|
||
[[spring-mvc-test-server-defining-expectations]]
|
||
===== Defining Expectations
|
||
|
||
You can define expectations by appending one or more `.andExpect(..)` calls after
|
||
performing a request, as the following example shows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
mockMvc.perform(get("/accounts/1")).andExpect(status().isOk());
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
import org.springframework.test.web.servlet.get
|
||
|
||
mockMvc.get("/accounts/1").andExpect {
|
||
status().isOk()
|
||
}
|
||
----
|
||
|
||
`MockMvcResultMatchers.*` provides a number of expectations, some of which are further
|
||
nested with more detailed expectations.
|
||
|
||
Expectations fall in two general categories. The first category of assertions verifies
|
||
properties of the response (for example, the response status, headers, and content).
|
||
These are the most important results to assert.
|
||
|
||
The second category of assertions goes beyond the response. These assertions let you
|
||
inspect Spring MVC specific aspects, such as which controller method processed the
|
||
request, whether an exception was raised and handled, what the content of the model is,
|
||
what view was selected, what flash attributes were added, and so on. They also let you
|
||
inspect Servlet specific aspects, such as request and session attributes.
|
||
|
||
The following test asserts that binding or validation failed:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
mockMvc.perform(post("/persons"))
|
||
.andExpect(status().isOk())
|
||
.andExpect(model().attributeHasErrors("person"));
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
import org.springframework.test.web.servlet.post
|
||
|
||
mockMvc.post("/persons").andExpect {
|
||
status().isOk()
|
||
model {
|
||
attributeHasErrors("person")
|
||
}
|
||
}
|
||
----
|
||
|
||
Many times, when writing tests, it is useful to dump the results of the performed
|
||
request. You can do so as follows, where `print()` is a static import from
|
||
`MockMvcResultHandlers`:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
mockMvc.perform(post("/persons"))
|
||
.andDo(print())
|
||
.andExpect(status().isOk())
|
||
.andExpect(model().attributeHasErrors("person"));
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
import org.springframework.test.web.servlet.post
|
||
|
||
mockMvc.post("/persons").andDo {
|
||
print()
|
||
}.andExpect {
|
||
status().isOk()
|
||
model {
|
||
attributeHasErrors("person")
|
||
}
|
||
}
|
||
----
|
||
|
||
As long as request processing does not cause an unhandled exception, the `print()` method
|
||
prints all the available result data to `System.out`. There is also a `log()` method and
|
||
two additional variants of the `print()` method, one that accepts an `OutputStream` and
|
||
one that accepts a `Writer`. For example, invoking `print(System.err)` prints the result
|
||
data to `System.err`, while invoking `print(myWriter)` prints the result data to a custom
|
||
writer. If you want to have the result data logged instead of printed, you can invoke the
|
||
`log()` method, which logs the result data as a single `DEBUG` message under the
|
||
`org.springframework.test.web.servlet.result` logging category.
|
||
|
||
In some cases, you may want to get direct access to the result and verify something that
|
||
cannot be verified otherwise. This can be achieved by appending `.andReturn()` after all
|
||
other expectations, as the following example shows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
MvcResult mvcResult = mockMvc.perform(post("/persons")).andExpect(status().isOk()).andReturn();
|
||
// ...
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
var mvcResult = mockMvc.post("/persons").andExpect { status().isOk() }.andReturn()
|
||
// ...
|
||
----
|
||
|
||
If all tests repeat the same expectations, you can set up common expectations once when
|
||
building the `MockMvc` instance, as the following example shows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
standaloneSetup(new SimpleController())
|
||
.alwaysExpect(status().isOk())
|
||
.alwaysExpect(content().contentType("application/json;charset=UTF-8"))
|
||
.build()
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
// Not possible in Kotlin until https://youtrack.jetbrains.com/issue/KT-22208 is fixed
|
||
----
|
||
|
||
Note that common expectations are always applied and cannot be overridden without
|
||
creating a separate `MockMvc` instance.
|
||
|
||
When a JSON response content contains hypermedia links created with
|
||
https://github.com/spring-projects/spring-hateoas[Spring HATEOAS], you can verify the
|
||
resulting links by using JsonPath expressions, as the following example shows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
mockMvc.perform(get("/people").accept(MediaType.APPLICATION_JSON))
|
||
.andExpect(jsonPath("$.links[?(@.rel == 'self')].href").value("http://localhost:8080/people"));
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
mockMvc.get("/people") {
|
||
accept(MediaType.APPLICATION_JSON)
|
||
}.andExpect {
|
||
jsonPath("$.links[?(@.rel == 'self')].href") {
|
||
value("http://localhost:8080/people")
|
||
}
|
||
}
|
||
----
|
||
|
||
When XML response content contains hypermedia links created with
|
||
https://github.com/spring-projects/spring-hateoas[Spring HATEOAS], you can verify the
|
||
resulting links by using XPath expressions:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
Map<String, String> ns = Collections.singletonMap("ns", "http://www.w3.org/2005/Atom");
|
||
mockMvc.perform(get("/handle").accept(MediaType.APPLICATION_XML))
|
||
.andExpect(xpath("/person/ns:link[@rel='self']/@href", ns).string("http://localhost:8080/people"));
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
val ns = mapOf("ns" to "http://www.w3.org/2005/Atom")
|
||
mockMvc.get("/handle") {
|
||
accept(MediaType.APPLICATION_XML)
|
||
}.andExpect {
|
||
xpath("/person/ns:link[@rel='self']/@href", ns) {
|
||
string("http://localhost:8080/people")
|
||
}
|
||
}
|
||
----
|
||
|
||
[[spring-mvc-test-async-requests]]
|
||
===== Async Requests
|
||
|
||
This section shows how to use MockMvc on its own to test asynchronous request handling.
|
||
If using MockMvc through the <<webtestclient>>, there is nothing special to do to make
|
||
asynchronous requests work as the `WebTestClient` automatically does what is described
|
||
in this section.
|
||
|
||
Servlet 3.0 asynchronous requests,
|
||
<<web.adoc#mvc-ann-async,supported in Spring MVC>>, work by exiting the Servlet container
|
||
thread and allowing the application to compute the response asynchronously, after which
|
||
an async dispatch is made to complete processing on a Servlet container thread.
|
||
|
||
In Spring MVC Test, async requests can be tested by asserting the produced async value
|
||
first, then manually performing the async dispatch, and finally verifying the response.
|
||
Below is an example test for controller methods that return `DeferredResult`, `Callable`,
|
||
or reactive type such as Reactor `Mono`:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@Test
|
||
void test() throws Exception {
|
||
MvcResult mvcResult = this.mockMvc.perform(get("/path"))
|
||
.andExpect(status().isOk()) <1>
|
||
.andExpect(request().asyncStarted()) <2>
|
||
.andExpect(request().asyncResult("body")) <3>
|
||
.andReturn();
|
||
|
||
this.mockMvc.perform(asyncDispatch(mvcResult)) <4>
|
||
.andExpect(status().isOk()) <5>
|
||
.andExpect(content().string("body"));
|
||
}
|
||
----
|
||
<1> Check response status is still unchanged
|
||
<2> Async processing must have started
|
||
<3> Wait and assert the async result
|
||
<4> Manually perform an ASYNC dispatch (as there is no running container)
|
||
<5> Verify the final response
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@Test
|
||
fun test() {
|
||
var mvcResult = mockMvc.get("/path").andExpect {
|
||
status().isOk() // <1>
|
||
request { asyncStarted() } // <2>
|
||
// TODO Remove unused generic parameter
|
||
request { asyncResult<Nothing>("body") } // <3>
|
||
}.andReturn()
|
||
|
||
|
||
mockMvc.perform(asyncDispatch(mvcResult)) // <4>
|
||
.andExpect {
|
||
status().isOk() // <5>
|
||
content().string("body")
|
||
}
|
||
}
|
||
----
|
||
<1> Check response status is still unchanged
|
||
<2> Async processing must have started
|
||
<3> Wait and assert the async result
|
||
<4> Manually perform an ASYNC dispatch (as there is no running container)
|
||
<5> Verify the final response
|
||
|
||
|
||
[[spring-mvc-test-vs-streaming-response]]
|
||
===== Streaming Responses
|
||
|
||
There are no options built into Spring MVC Test for container-less testing of streaming
|
||
responses. However you can test streaming requests through the <<WebTestClient>>.
|
||
This is also supported in Spring Boot where you can
|
||
{doc-spring-boot}/html/spring-boot-features.html#boot-features-testing-spring-boot-applications-testing-with-running-server[test a running server]
|
||
with `WebTestClient`. One extra advantage is the ability to use the `StepVerifier` from
|
||
project Reactor that allows declaring expectations on a stream of data.
|
||
|
||
|
||
[[spring-mvc-test-server-filters]]
|
||
===== Filter Registrations
|
||
|
||
When setting up a `MockMvc` instance, you can register one or more Servlet `Filter`
|
||
instances, as the following example shows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
mockMvc = standaloneSetup(new PersonController()).addFilters(new CharacterEncodingFilter()).build();
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
// Not possible in Kotlin until https://youtrack.jetbrains.com/issue/KT-22208 is fixed
|
||
----
|
||
|
||
Registered filters are invoked through the `MockFilterChain` from `spring-test`, and the
|
||
last filter delegates to the `DispatcherServlet`.
|
||
|
||
|
||
[[spring-mvc-test-vs-end-to-end-integration-tests]]
|
||
===== MockMvc vs End-to-End Tests
|
||
|
||
MockMVc is built on Servlet API mock implementations from the
|
||
`spring-test` module and does not rely on a running container. Therefore, there are
|
||
some differences when compared to full end-to-end integration tests with an actual
|
||
client and a live server running.
|
||
|
||
The easiest way to think about this is by starting with a blank `MockHttpServletRequest`.
|
||
Whatever you add to it is what the request becomes. Things that may catch you by surprise
|
||
are that there is no context path by default; no `jsessionid` cookie; no forwarding,
|
||
error, or async dispatches; and, therefore, no actual JSP rendering. Instead,
|
||
"`forwarded`" and "`redirected`" URLs are saved in the `MockHttpServletResponse` and can
|
||
be asserted with expectations.
|
||
|
||
This means that, if you use JSPs, you can verify the JSP page to which the request was
|
||
forwarded, but no HTML is rendered. In other words, the JSP is not invoked. Note,
|
||
however, that all other rendering technologies that do not rely on forwarding, such as
|
||
Thymeleaf and Freemarker, render HTML to the response body as expected. The same is true
|
||
for rendering JSON, XML, and other formats through `@ResponseBody` methods.
|
||
|
||
Alternatively, you may consider the full end-to-end integration testing support from
|
||
Spring Boot with `@SpringBootTest`. See the
|
||
{doc-spring-boot}/html/spring-boot-features.html#boot-features-testing[Spring Boot Reference Guide].
|
||
|
||
There are pros and cons for each approach. The options provided in Spring MVC Test are
|
||
different stops on the scale from classic unit testing to full integration testing. To be
|
||
certain, none of the options in Spring MVC Test fall under the category of classic unit
|
||
testing, but they are a little closer to it. For example, you can isolate the web layer
|
||
by injecting mocked services into controllers, in which case you are testing the web
|
||
layer only through the `DispatcherServlet` but with actual Spring configuration, as you
|
||
might test the data access layer in isolation from the layers above it. Also, you can use
|
||
the stand-alone setup, focusing on one controller at a time and manually providing the
|
||
configuration required to make it work.
|
||
|
||
Another important distinction when using Spring MVC Test is that, conceptually, such
|
||
tests are the server-side, so you can check what handler was used, if an exception was
|
||
handled with a HandlerExceptionResolver, what the content of the model is, what binding
|
||
errors there were, and other details. That means that it is easier to write expectations,
|
||
since the server is not an opaque box, as it is when testing it through an actual HTTP
|
||
client. This is generally an advantage of classic unit testing: It is easier to write,
|
||
reason about, and debug but does not replace the need for full integration tests. At the
|
||
same time, it is important not to lose sight of the fact that the response is the most
|
||
important thing to check. In short, there is room here for multiple styles and strategies
|
||
of testing even within the same project.
|
||
|
||
[[spring-mvc-test-server-resources]]
|
||
===== Further Examples
|
||
|
||
The framework's own tests include
|
||
https://github.com/spring-projects/spring-framework/tree/master/spring-test/src/test/java/org/springframework/test/web/servlet/samples[
|
||
many sample tests] intended to show how to use MockMvc on its own or through the
|
||
https://github.com/spring-projects/spring-framework/tree/master/spring-test/src/test/java/org/springframework/test/web/servlet/samples/client[
|
||
WebTestClient]. Browse these examples for further ideas.
|
||
|
||
|
||
[[spring-mvc-test-server-htmlunit]]
|
||
==== HtmlUnit Integration
|
||
|
||
Spring provides integration between <<spring-mvc-test-server, MockMvc>> and
|
||
http://htmlunit.sourceforge.net/[HtmlUnit]. This simplifies performing end-to-end testing
|
||
when using HTML-based views. This integration lets you:
|
||
|
||
* Easily test HTML pages by using tools such as
|
||
http://htmlunit.sourceforge.net/[HtmlUnit],
|
||
https://www.seleniumhq.org[WebDriver], and
|
||
http://www.gebish.org/manual/current/#spock-junit-testng[Geb] without the need to
|
||
deploy to a Servlet container.
|
||
* Test JavaScript within pages.
|
||
* Optionally, test using mock services to speed up testing.
|
||
* Share logic between in-container end-to-end tests and out-of-container integration tests.
|
||
|
||
NOTE: MockMvc works with templating technologies that do not rely on a Servlet Container
|
||
(for example, Thymeleaf, FreeMarker, and others), but it does not work with JSPs, since
|
||
they rely on the Servlet container.
|
||
|
||
[[spring-mvc-test-server-htmlunit-why]]
|
||
===== Why HtmlUnit Integration?
|
||
|
||
The most obvious question that comes to mind is "`Why do I need this?`" The answer is
|
||
best found by exploring a very basic sample application. Assume you have a Spring MVC web
|
||
application that supports CRUD operations on a `Message` object. The application also
|
||
supports paging through all messages. How would you go about testing it?
|
||
|
||
With Spring MVC Test, we can easily test if we are able to create a `Message`, as follows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
MockHttpServletRequestBuilder createMessage = post("/messages/")
|
||
.param("summary", "Spring Rocks")
|
||
.param("text", "In case you didn't know, Spring Rocks!");
|
||
|
||
mockMvc.perform(createMessage)
|
||
.andExpect(status().is3xxRedirection())
|
||
.andExpect(redirectedUrl("/messages/123"));
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@Test
|
||
fun test() {
|
||
mockMvc.post("/messages/") {
|
||
param("summary", "Spring Rocks")
|
||
param("text", "In case you didn't know, Spring Rocks!")
|
||
}.andExpect {
|
||
status().is3xxRedirection()
|
||
redirectedUrl("/messages/123")
|
||
}
|
||
}
|
||
----
|
||
|
||
What if we want to test the form view that lets us create the message? For example,
|
||
assume our form looks like the following snippet:
|
||
|
||
[source,xml,indent=0]
|
||
----
|
||
<form id="messageForm" action="/messages/" method="post">
|
||
<div class="pull-right"><a href="/messages/">Messages</a></div>
|
||
|
||
<label for="summary">Summary</label>
|
||
<input type="text" class="required" id="summary" name="summary" value="" />
|
||
|
||
<label for="text">Message</label>
|
||
<textarea id="text" name="text"></textarea>
|
||
|
||
<div class="form-actions">
|
||
<input type="submit" value="Create" />
|
||
</div>
|
||
</form>
|
||
----
|
||
|
||
How do we ensure that our form produce the correct request to create a new message? A
|
||
naive attempt might resemble the following:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
mockMvc.perform(get("/messages/form"))
|
||
.andExpect(xpath("//input[@name='summary']").exists())
|
||
.andExpect(xpath("//textarea[@name='text']").exists());
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
mockMvc.get("/messages/form").andExpect {
|
||
xpath("//input[@name='summary']") { exists() }
|
||
xpath("//textarea[@name='text']") { exists() }
|
||
}
|
||
----
|
||
|
||
This test has some obvious drawbacks. If we update our controller to use the parameter
|
||
`message` instead of `text`, our form test continues to pass, even though the HTML form
|
||
is out of synch with the controller. To resolve this we can combine our two tests, as
|
||
follows:
|
||
|
||
[[spring-mvc-test-server-htmlunit-mock-mvc-test]]
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
String summaryParamName = "summary";
|
||
String textParamName = "text";
|
||
mockMvc.perform(get("/messages/form"))
|
||
.andExpect(xpath("//input[@name='" + summaryParamName + "']").exists())
|
||
.andExpect(xpath("//textarea[@name='" + textParamName + "']").exists());
|
||
|
||
MockHttpServletRequestBuilder createMessage = post("/messages/")
|
||
.param(summaryParamName, "Spring Rocks")
|
||
.param(textParamName, "In case you didn't know, Spring Rocks!");
|
||
|
||
mockMvc.perform(createMessage)
|
||
.andExpect(status().is3xxRedirection())
|
||
.andExpect(redirectedUrl("/messages/123"));
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
val summaryParamName = "summary";
|
||
val textParamName = "text";
|
||
mockMvc.get("/messages/form").andExpect {
|
||
xpath("//input[@name='$summaryParamName']") { exists() }
|
||
xpath("//textarea[@name='$textParamName']") { exists() }
|
||
}
|
||
mockMvc.post("/messages/") {
|
||
param(summaryParamName, "Spring Rocks")
|
||
param(textParamName, "In case you didn't know, Spring Rocks!")
|
||
}.andExpect {
|
||
status().is3xxRedirection()
|
||
redirectedUrl("/messages/123")
|
||
}
|
||
----
|
||
|
||
This would reduce the risk of our test incorrectly passing, but there are still some
|
||
problems:
|
||
|
||
* What if we have multiple forms on our page? Admittedly, we could update our XPath
|
||
expressions, but they get more complicated as we take more factors into account: Are
|
||
the fields the correct type? Are the fields enabled? And so on.
|
||
* Another issue is that we are doing double the work we would expect. We must first
|
||
verify the view, and then we submit the view with the same parameters we just verified.
|
||
Ideally, this could be done all at once.
|
||
* Finally, we still cannot account for some things. For example, what if the form has
|
||
JavaScript validation that we wish to test as well?
|
||
|
||
The overall problem is that testing a web page does not involve a single interaction.
|
||
Instead, it is a combination of how the user interacts with a web page and how that web
|
||
page interacts with other resources. For example, the result of a form view is used as
|
||
the input to a user for creating a message. In addition, our form view can potentially
|
||
use additional resources that impact the behavior of the page, such as JavaScript
|
||
validation.
|
||
|
||
[[spring-mvc-test-server-htmlunit-why-integration]]
|
||
====== Integration Testing to the Rescue?
|
||
|
||
To resolve the issues mentioned earlier, we could perform end-to-end integration testing,
|
||
but this has some drawbacks. Consider testing the view that lets us page through the
|
||
messages. We might need the following tests:
|
||
|
||
* Does our page display a notification to the user to indicate that no results are
|
||
available when the messages are empty?
|
||
* Does our page properly display a single message?
|
||
* Does our page properly support paging?
|
||
|
||
To set up these tests, we need to ensure our database contains the proper messages. This
|
||
leads to a number of additional challenges:
|
||
|
||
* Ensuring the proper messages are in the database can be tedious. (Consider foreign key
|
||
constraints.)
|
||
* Testing can become slow, since each test would need to ensure that the database is in
|
||
the correct state.
|
||
* Since our database needs to be in a specific state, we cannot run tests in parallel.
|
||
* Performing assertions on such items as auto-generated ids, timestamps, and others can
|
||
be difficult.
|
||
|
||
These challenges do not mean that we should abandon end-to-end integration testing
|
||
altogether. Instead, we can reduce the number of end-to-end integration tests by
|
||
refactoring our detailed tests to use mock services that run much faster, more reliably,
|
||
and without side effects. We can then implement a small number of true end-to-end
|
||
integration tests that validate simple workflows to ensure that everything works together
|
||
properly.
|
||
|
||
[[spring-mvc-test-server-htmlunit-why-mockmvc]]
|
||
====== Enter HtmlUnit Integration
|
||
|
||
So how can we achieve a balance between testing the interactions of our pages and still
|
||
retain good performance within our test suite? The answer is: "`By integrating MockMvc
|
||
with HtmlUnit.`"
|
||
|
||
[[spring-mvc-test-server-htmlunit-options]]
|
||
====== HtmlUnit Integration Options
|
||
|
||
You have a number of options when you want to integrate MockMvc with HtmlUnit:
|
||
|
||
* <<spring-mvc-test-server-htmlunit-mah,MockMvc and HtmlUnit>>: Use this option if you
|
||
want to use the raw HtmlUnit libraries.
|
||
* <<spring-mvc-test-server-htmlunit-webdriver,MockMvc and WebDriver>>: Use this option to
|
||
ease development and reuse code between integration and end-to-end testing.
|
||
* <<spring-mvc-test-server-htmlunit-geb,MockMvc and Geb>>: Use this option if you want to
|
||
use Groovy for testing, ease development, and reuse code between integration and
|
||
end-to-end testing.
|
||
|
||
[[spring-mvc-test-server-htmlunit-mah]]
|
||
===== MockMvc and HtmlUnit
|
||
|
||
This section describes how to integrate MockMvc and HtmlUnit. Use this option if you want
|
||
to use the raw HtmlUnit libraries.
|
||
|
||
[[spring-mvc-test-server-htmlunit-mah-setup]]
|
||
====== MockMvc and HtmlUnit Setup
|
||
|
||
First, make sure that you have included a test dependency on
|
||
`net.sourceforge.htmlunit:htmlunit`. In order to use HtmlUnit with Apache HttpComponents
|
||
4.5+, you need to use HtmlUnit 2.18 or higher.
|
||
|
||
We can easily create an HtmlUnit `WebClient` that integrates with MockMvc by using the
|
||
`MockMvcWebClientBuilder`, as follows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
WebClient webClient;
|
||
|
||
@BeforeEach
|
||
void setup(WebApplicationContext context) {
|
||
webClient = MockMvcWebClientBuilder
|
||
.webAppContextSetup(context)
|
||
.build();
|
||
}
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
lateinit var webClient: WebClient
|
||
|
||
@BeforeEach
|
||
fun setup(context: WebApplicationContext) {
|
||
webClient = MockMvcWebClientBuilder
|
||
.webAppContextSetup(context)
|
||
.build()
|
||
}
|
||
----
|
||
|
||
NOTE: This is a simple example of using `MockMvcWebClientBuilder`. For advanced usage,
|
||
see <<spring-mvc-test-server-htmlunit-mah-advanced-builder>>.
|
||
|
||
This ensures that any URL that references `localhost` as the server is directed to our
|
||
`MockMvc` instance without the need for a real HTTP connection. Any other URL is
|
||
requested by using a network connection, as normal. This lets us easily test the use of
|
||
CDNs.
|
||
|
||
[[spring-mvc-test-server-htmlunit-mah-usage]]
|
||
====== MockMvc and HtmlUnit Usage
|
||
|
||
Now we can use HtmlUnit as we normally would but without the need to deploy our
|
||
application to a Servlet container. For example, we can request the view to create a
|
||
message with the following:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
HtmlPage createMsgFormPage = webClient.getPage("http://localhost/messages/form");
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
val createMsgFormPage = webClient.getPage("http://localhost/messages/form")
|
||
----
|
||
|
||
NOTE: The default context path is `""`. Alternatively, we can specify the context path,
|
||
as described in <<spring-mvc-test-server-htmlunit-mah-advanced-builder>>.
|
||
|
||
Once we have a reference to the `HtmlPage`, we can then fill out the form and submit it
|
||
to create a message, as the following example shows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
HtmlForm form = createMsgFormPage.getHtmlElementById("messageForm");
|
||
HtmlTextInput summaryInput = createMsgFormPage.getHtmlElementById("summary");
|
||
summaryInput.setValueAttribute("Spring Rocks");
|
||
HtmlTextArea textInput = createMsgFormPage.getHtmlElementById("text");
|
||
textInput.setText("In case you didn't know, Spring Rocks!");
|
||
HtmlSubmitInput submit = form.getOneHtmlElementByAttribute("input", "type", "submit");
|
||
HtmlPage newMessagePage = submit.click();
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
val form = createMsgFormPage.getHtmlElementById("messageForm")
|
||
val summaryInput = createMsgFormPage.getHtmlElementById("summary")
|
||
summaryInput.setValueAttribute("Spring Rocks")
|
||
val textInput = createMsgFormPage.getHtmlElementById("text")
|
||
textInput.setText("In case you didn't know, Spring Rocks!")
|
||
val submit = form.getOneHtmlElementByAttribute("input", "type", "submit")
|
||
val newMessagePage = submit.click()
|
||
----
|
||
|
||
Finally, we can verify that a new message was created successfully. The following
|
||
assertions use the https://joel-costigliola.github.io/assertj/[AssertJ] library:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
assertThat(newMessagePage.getUrl().toString()).endsWith("/messages/123");
|
||
String id = newMessagePage.getHtmlElementById("id").getTextContent();
|
||
assertThat(id).isEqualTo("123");
|
||
String summary = newMessagePage.getHtmlElementById("summary").getTextContent();
|
||
assertThat(summary).isEqualTo("Spring Rocks");
|
||
String text = newMessagePage.getHtmlElementById("text").getTextContent();
|
||
assertThat(text).isEqualTo("In case you didn't know, Spring Rocks!");
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
assertThat(newMessagePage.getUrl().toString()).endsWith("/messages/123")
|
||
val id = newMessagePage.getHtmlElementById("id").getTextContent()
|
||
assertThat(id).isEqualTo("123")
|
||
val summary = newMessagePage.getHtmlElementById("summary").getTextContent()
|
||
assertThat(summary).isEqualTo("Spring Rocks")
|
||
val text = newMessagePage.getHtmlElementById("text").getTextContent()
|
||
assertThat(text).isEqualTo("In case you didn't know, Spring Rocks!")
|
||
----
|
||
|
||
The preceding code improves on our
|
||
<<spring-mvc-test-server-htmlunit-mock-mvc-test, MockMvc test>> in a number of ways.
|
||
First, we no longer have to explicitly verify our form and then create a request that
|
||
looks like the form. Instead, we request the form, fill it out, and submit it, thereby
|
||
significantly reducing the overhead.
|
||
|
||
Another important factor is that http://htmlunit.sourceforge.net/javascript.html[HtmlUnit
|
||
uses the Mozilla Rhino engine] to evaluate JavaScript. This means that we can also test
|
||
the behavior of JavaScript within our pages.
|
||
|
||
See the http://htmlunit.sourceforge.net/gettingStarted.html[HtmlUnit documentation] for
|
||
additional information about using HtmlUnit.
|
||
|
||
[[spring-mvc-test-server-htmlunit-mah-advanced-builder]]
|
||
====== Advanced `MockMvcWebClientBuilder`
|
||
|
||
In the examples so far, we have used `MockMvcWebClientBuilder` in the simplest way
|
||
possible, by building a `WebClient` based on the `WebApplicationContext` loaded for us by
|
||
the Spring TestContext Framework. This approach is repeated in the following example:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
WebClient webClient;
|
||
|
||
@BeforeEach
|
||
void setup(WebApplicationContext context) {
|
||
webClient = MockMvcWebClientBuilder
|
||
.webAppContextSetup(context)
|
||
.build();
|
||
}
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
lateinit var webClient: WebClient
|
||
|
||
@BeforeEach
|
||
fun setup(context: WebApplicationContext) {
|
||
webClient = MockMvcWebClientBuilder
|
||
.webAppContextSetup(context)
|
||
.build()
|
||
}
|
||
----
|
||
|
||
We can also specify additional configuration options, as the following example shows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
WebClient webClient;
|
||
|
||
@BeforeEach
|
||
void setup() {
|
||
webClient = MockMvcWebClientBuilder
|
||
// demonstrates applying a MockMvcConfigurer (Spring Security)
|
||
.webAppContextSetup(context, springSecurity())
|
||
// for illustration only - defaults to ""
|
||
.contextPath("")
|
||
// By default MockMvc is used for localhost only;
|
||
// the following will use MockMvc for example.com and example.org as well
|
||
.useMockMvcForHosts("example.com","example.org")
|
||
.build();
|
||
}
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
lateinit var webClient: WebClient
|
||
|
||
@BeforeEach
|
||
fun setup() {
|
||
webClient = MockMvcWebClientBuilder
|
||
// demonstrates applying a MockMvcConfigurer (Spring Security)
|
||
.webAppContextSetup(context, springSecurity())
|
||
// for illustration only - defaults to ""
|
||
.contextPath("")
|
||
// By default MockMvc is used for localhost only;
|
||
// the following will use MockMvc for example.com and example.org as well
|
||
.useMockMvcForHosts("example.com","example.org")
|
||
.build()
|
||
}
|
||
----
|
||
|
||
As an alternative, we can perform the exact same setup by configuring the `MockMvc`
|
||
instance separately and supplying it to the `MockMvcWebClientBuilder`, as follows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
MockMvc mockMvc = MockMvcBuilders
|
||
.webAppContextSetup(context)
|
||
.apply(springSecurity())
|
||
.build();
|
||
|
||
webClient = MockMvcWebClientBuilder
|
||
.mockMvcSetup(mockMvc)
|
||
// for illustration only - defaults to ""
|
||
.contextPath("")
|
||
// By default MockMvc is used for localhost only;
|
||
// the following will use MockMvc for example.com and example.org as well
|
||
.useMockMvcForHosts("example.com","example.org")
|
||
.build();
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
// Not possible in Kotlin until https://youtrack.jetbrains.com/issue/KT-22208 is fixed
|
||
----
|
||
|
||
This is more verbose, but, by building the `WebClient` with a `MockMvc` instance, we have
|
||
the full power of MockMvc at our fingertips.
|
||
|
||
TIP: For additional information on creating a `MockMvc` instance, see
|
||
<<spring-mvc-test-server-setup-options>>.
|
||
|
||
[[spring-mvc-test-server-htmlunit-webdriver]]
|
||
===== MockMvc and WebDriver
|
||
|
||
In the previous sections, we have seen how to use MockMvc in conjunction with the raw
|
||
HtmlUnit APIs. In this section, we use additional abstractions within the Selenium
|
||
https://docs.seleniumhq.org/projects/webdriver/[WebDriver] to make things even easier.
|
||
|
||
[[spring-mvc-test-server-htmlunit-webdriver-why]]
|
||
====== Why WebDriver and MockMvc?
|
||
|
||
We can already use HtmlUnit and MockMvc, so why would we want to use WebDriver? The
|
||
Selenium WebDriver provides a very elegant API that lets us easily organize our code. To
|
||
better show how it works, we explore an example in this section.
|
||
|
||
NOTE: Despite being a part of https://docs.seleniumhq.org/[Selenium], WebDriver does not
|
||
require a Selenium Server to run your tests.
|
||
|
||
Suppose we need to ensure that a message is created properly. The tests involve finding
|
||
the HTML form input elements, filling them out, and making various assertions.
|
||
|
||
This approach results in numerous separate tests because we want to test error conditions
|
||
as well. For example, we want to ensure that we get an error if we fill out only part of
|
||
the form. If we fill out the entire form, the newly created message should be displayed
|
||
afterwards.
|
||
|
||
If one of the fields were named "`summary`", we might have something that resembles the
|
||
following repeated in multiple places within our tests:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
HtmlTextInput summaryInput = currentPage.getHtmlElementById("summary");
|
||
summaryInput.setValueAttribute(summary);
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
val summaryInput = currentPage.getHtmlElementById("summary")
|
||
summaryInput.setValueAttribute(summary)
|
||
----
|
||
|
||
So what happens if we change the `id` to `smmry`? Doing so would force us to update all
|
||
of our tests to incorporate this change. This violates the DRY principle, so we should
|
||
ideally extract this code into its own method, as follows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
public HtmlPage createMessage(HtmlPage currentPage, String summary, String text) {
|
||
setSummary(currentPage, summary);
|
||
// ...
|
||
}
|
||
|
||
public void setSummary(HtmlPage currentPage, String summary) {
|
||
HtmlTextInput summaryInput = currentPage.getHtmlElementById("summary");
|
||
summaryInput.setValueAttribute(summary);
|
||
}
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
fun createMessage(currentPage: HtmlPage, summary:String, text:String) :HtmlPage{
|
||
setSummary(currentPage, summary);
|
||
// ...
|
||
}
|
||
|
||
fun setSummary(currentPage:HtmlPage , summary: String) {
|
||
val summaryInput = currentPage.getHtmlElementById("summary")
|
||
summaryInput.setValueAttribute(summary)
|
||
}
|
||
----
|
||
|
||
Doing so ensures that we do not have to update all of our tests if we change the UI.
|
||
|
||
We might even take this a step further and place this logic within an `Object` that
|
||
represents the `HtmlPage` we are currently on, as the following example shows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
public class CreateMessagePage {
|
||
|
||
final HtmlPage currentPage;
|
||
|
||
final HtmlTextInput summaryInput;
|
||
|
||
final HtmlSubmitInput submit;
|
||
|
||
public CreateMessagePage(HtmlPage currentPage) {
|
||
this.currentPage = currentPage;
|
||
this.summaryInput = currentPage.getHtmlElementById("summary");
|
||
this.submit = currentPage.getHtmlElementById("submit");
|
||
}
|
||
|
||
public <T> T createMessage(String summary, String text) throws Exception {
|
||
setSummary(summary);
|
||
|
||
HtmlPage result = submit.click();
|
||
boolean error = CreateMessagePage.at(result);
|
||
|
||
return (T) (error ? new CreateMessagePage(result) : new ViewMessagePage(result));
|
||
}
|
||
|
||
public void setSummary(String summary) throws Exception {
|
||
summaryInput.setValueAttribute(summary);
|
||
}
|
||
|
||
public static boolean at(HtmlPage page) {
|
||
return "Create Message".equals(page.getTitleText());
|
||
}
|
||
}
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
class CreateMessagePage(private val currentPage: HtmlPage) {
|
||
|
||
val summaryInput: HtmlTextInput = currentPage.getHtmlElementById("summary")
|
||
|
||
val submit: HtmlSubmitInput = currentPage.getHtmlElementById("submit")
|
||
|
||
fun <T> createMessage(summary: String, text: String): T {
|
||
setSummary(summary)
|
||
|
||
val result = submit.click()
|
||
val error = at(result)
|
||
|
||
return (if (error) CreateMessagePage(result) else ViewMessagePage(result)) as T
|
||
}
|
||
|
||
fun setSummary(summary: String) {
|
||
summaryInput.setValueAttribute(summary)
|
||
}
|
||
|
||
fun at(page: HtmlPage): Boolean {
|
||
return "Create Message" == page.getTitleText()
|
||
}
|
||
}
|
||
}
|
||
----
|
||
|
||
Formerly, this pattern was known as the
|
||
https://github.com/SeleniumHQ/selenium/wiki/PageObjects[Page Object Pattern]. While we
|
||
can certainly do this with HtmlUnit, WebDriver provides some tools that we explore in the
|
||
following sections to make this pattern much easier to implement.
|
||
|
||
[[spring-mvc-test-server-htmlunit-webdriver-setup]]
|
||
====== MockMvc and WebDriver Setup
|
||
|
||
To use Selenium WebDriver with the Spring MVC Test framework, make sure that your project
|
||
includes a test dependency on `org.seleniumhq.selenium:selenium-htmlunit-driver`.
|
||
|
||
We can easily create a Selenium WebDriver that integrates with MockMvc by using the
|
||
`MockMvcHtmlUnitDriverBuilder` as the following example shows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
WebDriver driver;
|
||
|
||
@BeforeEach
|
||
void setup(WebApplicationContext context) {
|
||
driver = MockMvcHtmlUnitDriverBuilder
|
||
.webAppContextSetup(context)
|
||
.build();
|
||
}
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
lateinit var driver: WebDriver
|
||
|
||
@BeforeEach
|
||
fun setup(context: WebApplicationContext) {
|
||
driver = MockMvcHtmlUnitDriverBuilder
|
||
.webAppContextSetup(context)
|
||
.build()
|
||
}
|
||
----
|
||
|
||
NOTE: This is a simple example of using `MockMvcHtmlUnitDriverBuilder`. For more advanced
|
||
usage, see <<spring-mvc-test-server-htmlunit-webdriver-advanced-builder>>.
|
||
|
||
The preceding example ensures that any URL that references `localhost` as the server is
|
||
directed to our `MockMvc` instance without the need for a real HTTP connection. Any other
|
||
URL is requested by using a network connection, as normal. This lets us easily test the
|
||
use of CDNs.
|
||
|
||
[[spring-mvc-test-server-htmlunit-webdriver-usage]]
|
||
====== MockMvc and WebDriver Usage
|
||
|
||
Now we can use WebDriver as we normally would but without the need to deploy our
|
||
application to a Servlet container. For example, we can request the view to create a
|
||
message with the following:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
CreateMessagePage page = CreateMessagePage.to(driver);
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
val page = CreateMessagePage.to(driver)
|
||
----
|
||
|
||
We can then fill out the form and submit it to create a message, as follows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
ViewMessagePage viewMessagePage =
|
||
page.createMessage(ViewMessagePage.class, expectedSummary, expectedText);
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
val viewMessagePage =
|
||
page.createMessage(ViewMessagePage::class, expectedSummary, expectedText)
|
||
----
|
||
|
||
This improves on the design of our <<spring-mvc-test-server-htmlunit-mah-usage, HtmlUnit test>>
|
||
by leveraging the Page Object Pattern. As we mentioned in
|
||
<<spring-mvc-test-server-htmlunit-webdriver-why>>, we can use the Page Object Pattern
|
||
with HtmlUnit, but it is much easier with WebDriver. Consider the following
|
||
`CreateMessagePage` implementation:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
public class CreateMessagePage
|
||
extends AbstractPage { // <1>
|
||
|
||
// <2>
|
||
private WebElement summary;
|
||
private WebElement text;
|
||
|
||
// <3>
|
||
@FindBy(css = "input[type=submit]")
|
||
private WebElement submit;
|
||
|
||
public CreateMessagePage(WebDriver driver) {
|
||
super(driver);
|
||
}
|
||
|
||
public <T> T createMessage(Class<T> resultPage, String summary, String details) {
|
||
this.summary.sendKeys(summary);
|
||
this.text.sendKeys(details);
|
||
this.submit.click();
|
||
return PageFactory.initElements(driver, resultPage);
|
||
}
|
||
|
||
public static CreateMessagePage to(WebDriver driver) {
|
||
driver.get("http://localhost:9990/mail/messages/form");
|
||
return PageFactory.initElements(driver, CreateMessagePage.class);
|
||
}
|
||
}
|
||
----
|
||
<1> `CreateMessagePage` extends the `AbstractPage`. We do not go over the details of
|
||
`AbstractPage`, but, in summary, it contains common functionality for all of our pages.
|
||
For example, if our application has a navigational bar, global error messages, and other
|
||
features, we can place this logic in a shared location.
|
||
<2> We have a member variable for each of the parts of the HTML page in which we are
|
||
interested. These are of type `WebElement`. WebDriver's
|
||
https://github.com/SeleniumHQ/selenium/wiki/PageFactory[`PageFactory`] lets us remove a
|
||
lot of code from the HtmlUnit version of `CreateMessagePage` by automatically resolving
|
||
each `WebElement`. The
|
||
https://seleniumhq.github.io/selenium/docs/api/java/org/openqa/selenium/support/PageFactory.html#initElements-org.openqa.selenium.WebDriver-java.lang.Class-[`PageFactory#initElements(WebDriver,Class<T>)`]
|
||
method automatically resolves each `WebElement` by using the field name and looking it up
|
||
by the `id` or `name` of the element within the HTML page.
|
||
<3> We can use the
|
||
https://github.com/SeleniumHQ/selenium/wiki/PageFactory#making-the-example-work-using-annotations[`@FindBy` annotation]
|
||
to override the default lookup behavior. Our example shows how to use the `@FindBy`
|
||
annotation to look up our submit button with a `css` selector (*input[type=submit]*).
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
class CreateMessagePage(private val driver: WebDriver) : AbstractPage(driver) { // <1>
|
||
|
||
// <2>
|
||
private lateinit var summary: WebElement
|
||
private lateinit var text: WebElement
|
||
|
||
// <3>
|
||
@FindBy(css = "input[type=submit]")
|
||
private lateinit var submit: WebElement
|
||
|
||
fun <T> createMessage(resultPage: Class<T>, summary: String, details: String): T {
|
||
this.summary.sendKeys(summary)
|
||
text.sendKeys(details)
|
||
submit.click()
|
||
return PageFactory.initElements(driver, resultPage)
|
||
}
|
||
companion object {
|
||
fun to(driver: WebDriver): CreateMessagePage {
|
||
driver.get("http://localhost:9990/mail/messages/form")
|
||
return PageFactory.initElements(driver, CreateMessagePage::class.java)
|
||
}
|
||
}
|
||
}
|
||
----
|
||
<1> `CreateMessagePage` extends the `AbstractPage`. We do not go over the details of
|
||
`AbstractPage`, but, in summary, it contains common functionality for all of our pages.
|
||
For example, if our application has a navigational bar, global error messages, and other
|
||
features, we can place this logic in a shared location.
|
||
<2> We have a member variable for each of the parts of the HTML page in which we are
|
||
interested. These are of type `WebElement`. WebDriver's
|
||
https://github.com/SeleniumHQ/selenium/wiki/PageFactory[`PageFactory`] lets us remove a
|
||
lot of code from the HtmlUnit version of `CreateMessagePage` by automatically resolving
|
||
each `WebElement`. The
|
||
https://seleniumhq.github.io/selenium/docs/api/java/org/openqa/selenium/support/PageFactory.html#initElements-org.openqa.selenium.WebDriver-java.lang.Class-[`PageFactory#initElements(WebDriver,Class<T>)`]
|
||
method automatically resolves each `WebElement` by using the field name and looking it up
|
||
by the `id` or `name` of the element within the HTML page.
|
||
<3> We can use the
|
||
https://github.com/SeleniumHQ/selenium/wiki/PageFactory#making-the-example-work-using-annotations[`@FindBy` annotation]
|
||
to override the default lookup behavior. Our example shows how to use the `@FindBy`
|
||
annotation to look up our submit button with a `css` selector (*input[type=submit]*).
|
||
|
||
|
||
Finally, we can verify that a new message was created successfully. The following
|
||
assertions use the https://joel-costigliola.github.io/assertj/[AssertJ] assertion library:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
assertThat(viewMessagePage.getMessage()).isEqualTo(expectedMessage);
|
||
assertThat(viewMessagePage.getSuccess()).isEqualTo("Successfully created a new message");
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
assertThat(viewMessagePage.message.isEqualTo(expectedMessage)
|
||
assertThat(viewMessagePage.success.isEqualTo("Successfully created a new message")
|
||
----
|
||
|
||
We can see that our `ViewMessagePage` lets us interact with our custom domain model. For
|
||
example, it exposes a method that returns a `Message` object:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
public Message getMessage() throws ParseException {
|
||
Message message = new Message();
|
||
message.setId(getId());
|
||
message.setCreated(getCreated());
|
||
message.setSummary(getSummary());
|
||
message.setText(getText());
|
||
return message;
|
||
}
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
fun getMessage() = Message(getId(), getCreated(), getSummary(), getText())
|
||
----
|
||
|
||
We can then use the rich domain objects in our assertions.
|
||
|
||
Lastly, we must not forget to close the `WebDriver` instance when the test is complete,
|
||
as follows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
@AfterEach
|
||
void destroy() {
|
||
if (driver != null) {
|
||
driver.close();
|
||
}
|
||
}
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
@AfterEach
|
||
fun destroy() {
|
||
if (driver != null) {
|
||
driver.close()
|
||
}
|
||
}
|
||
----
|
||
|
||
For additional information on using WebDriver, see the Selenium
|
||
https://github.com/SeleniumHQ/selenium/wiki/Getting-Started[WebDriver documentation].
|
||
|
||
[[spring-mvc-test-server-htmlunit-webdriver-advanced-builder]]
|
||
====== Advanced `MockMvcHtmlUnitDriverBuilder`
|
||
|
||
In the examples so far, we have used `MockMvcHtmlUnitDriverBuilder` in the simplest way
|
||
possible, by building a `WebDriver` based on the `WebApplicationContext` loaded for us by
|
||
the Spring TestContext Framework. This approach is repeated here, as follows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
WebDriver driver;
|
||
|
||
@BeforeEach
|
||
void setup(WebApplicationContext context) {
|
||
driver = MockMvcHtmlUnitDriverBuilder
|
||
.webAppContextSetup(context)
|
||
.build();
|
||
}
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
lateinit var driver: WebDriver
|
||
|
||
@BeforeEach
|
||
fun setup(context: WebApplicationContext) {
|
||
driver = MockMvcHtmlUnitDriverBuilder
|
||
.webAppContextSetup(context)
|
||
.build()
|
||
}
|
||
----
|
||
|
||
We can also specify additional configuration options, as follows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
WebDriver driver;
|
||
|
||
@BeforeEach
|
||
void setup() {
|
||
driver = MockMvcHtmlUnitDriverBuilder
|
||
// demonstrates applying a MockMvcConfigurer (Spring Security)
|
||
.webAppContextSetup(context, springSecurity())
|
||
// for illustration only - defaults to ""
|
||
.contextPath("")
|
||
// By default MockMvc is used for localhost only;
|
||
// the following will use MockMvc for example.com and example.org as well
|
||
.useMockMvcForHosts("example.com","example.org")
|
||
.build();
|
||
}
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
lateinit var driver: WebDriver
|
||
|
||
@BeforeEach
|
||
fun setup() {
|
||
driver = MockMvcHtmlUnitDriverBuilder
|
||
// demonstrates applying a MockMvcConfigurer (Spring Security)
|
||
.webAppContextSetup(context, springSecurity())
|
||
// for illustration only - defaults to ""
|
||
.contextPath("")
|
||
// By default MockMvc is used for localhost only;
|
||
// the following will use MockMvc for example.com and example.org as well
|
||
.useMockMvcForHosts("example.com","example.org")
|
||
.build()
|
||
}
|
||
----
|
||
|
||
As an alternative, we can perform the exact same setup by configuring the `MockMvc`
|
||
instance separately and supplying it to the `MockMvcHtmlUnitDriverBuilder`, as follows:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
MockMvc mockMvc = MockMvcBuilders
|
||
.webAppContextSetup(context)
|
||
.apply(springSecurity())
|
||
.build();
|
||
|
||
driver = MockMvcHtmlUnitDriverBuilder
|
||
.mockMvcSetup(mockMvc)
|
||
// for illustration only - defaults to ""
|
||
.contextPath("")
|
||
// By default MockMvc is used for localhost only;
|
||
// the following will use MockMvc for example.com and example.org as well
|
||
.useMockMvcForHosts("example.com","example.org")
|
||
.build();
|
||
----
|
||
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
// Not possible in Kotlin until https://youtrack.jetbrains.com/issue/KT-22208 is fixed
|
||
----
|
||
|
||
This is more verbose, but, by building the `WebDriver` with a `MockMvc` instance, we have
|
||
the full power of MockMvc at our fingertips.
|
||
|
||
TIP: For additional information on creating a `MockMvc` instance, see
|
||
<<spring-mvc-test-server-setup-options>>.
|
||
|
||
[[spring-mvc-test-server-htmlunit-geb]]
|
||
===== MockMvc and Geb
|
||
|
||
In the previous section, we saw how to use MockMvc with WebDriver. In this section, we
|
||
use http://www.gebish.org/[Geb] to make our tests even Groovy-er.
|
||
|
||
[[spring-mvc-test-server-htmlunit-geb-why]]
|
||
====== Why Geb and MockMvc?
|
||
|
||
Geb is backed by WebDriver, so it offers many of the
|
||
<<spring-mvc-test-server-htmlunit-webdriver-why, same benefits>> that we get from
|
||
WebDriver. However, Geb makes things even easier by taking care of some of the
|
||
boilerplate code for us.
|
||
|
||
[[spring-mvc-test-server-htmlunit-geb-setup]]
|
||
====== MockMvc and Geb Setup
|
||
|
||
We can easily initialize a Geb `Browser` with a Selenium WebDriver that uses MockMvc, as
|
||
follows:
|
||
|
||
[source,groovy]
|
||
----
|
||
def setup() {
|
||
browser.driver = MockMvcHtmlUnitDriverBuilder
|
||
.webAppContextSetup(context)
|
||
.build()
|
||
}
|
||
----
|
||
|
||
NOTE: This is a simple example of using `MockMvcHtmlUnitDriverBuilder`. For more advanced
|
||
usage, see <<spring-mvc-test-server-htmlunit-webdriver-advanced-builder>>.
|
||
|
||
This ensures that any URL referencing `localhost` as the server is directed to our
|
||
`MockMvc` instance without the need for a real HTTP connection. Any other URL is
|
||
requested by using a network connection as normal. This lets us easily test the use of
|
||
CDNs.
|
||
|
||
[[spring-mvc-test-server-htmlunit-geb-usage]]
|
||
====== MockMvc and Geb Usage
|
||
|
||
Now we can use Geb as we normally would but without the need to deploy our application to
|
||
a Servlet container. For example, we can request the view to create a message with the
|
||
following:
|
||
|
||
[source,groovy]
|
||
----
|
||
to CreateMessagePage
|
||
----
|
||
|
||
We can then fill out the form and submit it to create a message, as follows:
|
||
|
||
[source,groovy]
|
||
----
|
||
when:
|
||
form.summary = expectedSummary
|
||
form.text = expectedMessage
|
||
submit.click(ViewMessagePage)
|
||
----
|
||
|
||
Any unrecognized method calls or property accesses or references that are not found are
|
||
forwarded to the current page object. This removes a lot of the boilerplate code we
|
||
needed when using WebDriver directly.
|
||
|
||
As with direct WebDriver usage, this improves on the design of our
|
||
<<spring-mvc-test-server-htmlunit-mah-usage, HtmlUnit test>> by using the Page Object
|
||
Pattern. As mentioned previously, we can use the Page Object Pattern with HtmlUnit and
|
||
WebDriver, but it is even easier with Geb. Consider our new Groovy-based
|
||
`CreateMessagePage` implementation:
|
||
|
||
[source,groovy]
|
||
----
|
||
class CreateMessagePage extends Page {
|
||
static url = 'messages/form'
|
||
static at = { assert title == 'Messages : Create'; true }
|
||
static content = {
|
||
submit { $('input[type=submit]') }
|
||
form { $('form') }
|
||
errors(required:false) { $('label.error, .alert-error')?.text() }
|
||
}
|
||
}
|
||
----
|
||
|
||
Our `CreateMessagePage` extends `Page`. We do not go over the details of `Page`, but, in
|
||
summary, it contains common functionality for all of our pages. We define a URL in which
|
||
this page can be found. This lets us navigate to the page, as follows:
|
||
|
||
[source,groovy]
|
||
----
|
||
to CreateMessagePage
|
||
----
|
||
|
||
We also have an `at` closure that determines if we are at the specified page. It should
|
||
return `true` if we are on the correct page. This is why we can assert that we are on the
|
||
correct page, as follows:
|
||
|
||
[source,groovy]
|
||
----
|
||
then:
|
||
at CreateMessagePage
|
||
errors.contains('This field is required.')
|
||
----
|
||
|
||
NOTE: We use an assertion in the closure so that we can determine where things went wrong
|
||
if we were at the wrong page.
|
||
|
||
Next, we create a `content` closure that specifies all the areas of interest within the
|
||
page. We can use a
|
||
http://www.gebish.org/manual/current/#the-jquery-ish-navigator-api[jQuery-ish Navigator
|
||
API] to select the content in which we are interested.
|
||
|
||
Finally, we can verify that a new message was created successfully, as follows:
|
||
|
||
[source,groovy]
|
||
----
|
||
then:
|
||
at ViewMessagePage
|
||
success == 'Successfully created a new message'
|
||
id
|
||
date
|
||
summary == expectedSummary
|
||
message == expectedMessage
|
||
----
|
||
|
||
For further details on how to get the most out of Geb, see
|
||
http://www.gebish.org/manual/current/[The Book of Geb] user's manual.
|
||
|
||
|
||
[[spring-mvc-test-client]]
|
||
=== Testing Client Applications
|
||
|
||
You can use client-side tests to test code that internally uses the `RestTemplate`. The
|
||
idea is to declare expected requests and to provide "`stub`" responses so that you can
|
||
focus on testing the code in isolation (that is, without running a server). The following
|
||
example shows how to do so:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
RestTemplate restTemplate = new RestTemplate();
|
||
|
||
MockRestServiceServer mockServer = MockRestServiceServer.bindTo(restTemplate).build();
|
||
mockServer.expect(requestTo("/greeting")).andRespond(withSuccess());
|
||
|
||
// Test code that uses the above RestTemplate ...
|
||
|
||
mockServer.verify();
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
val restTemplate = RestTemplate()
|
||
|
||
val mockServer = MockRestServiceServer.bindTo(restTemplate).build()
|
||
mockServer.expect(requestTo("/greeting")).andRespond(withSuccess())
|
||
|
||
// Test code that uses the above RestTemplate ...
|
||
|
||
mockServer.verify()
|
||
----
|
||
|
||
In the preceding example, `MockRestServiceServer` (the central class for client-side REST
|
||
tests) configures the `RestTemplate` with a custom `ClientHttpRequestFactory` that
|
||
asserts actual requests against expectations and returns "`stub`" responses. In this
|
||
case, we expect a request to `/greeting` and want to return a 200 response with
|
||
`text/plain` content. We can define additional expected requests and stub responses as
|
||
needed. When we define expected requests and stub responses, the `RestTemplate` can be
|
||
used in client-side code as usual. At the end of testing, `mockServer.verify()` can be
|
||
used to verify that all expectations have been satisfied.
|
||
|
||
By default, requests are expected in the order in which expectations were declared. You
|
||
can set the `ignoreExpectOrder` option when building the server, in which case all
|
||
expectations are checked (in order) to find a match for a given request. That means
|
||
requests are allowed to come in any order. The following example uses `ignoreExpectOrder`:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
server = MockRestServiceServer.bindTo(restTemplate).ignoreExpectOrder(true).build();
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
server = MockRestServiceServer.bindTo(restTemplate).ignoreExpectOrder(true).build()
|
||
----
|
||
|
||
Even with unordered requests by default, each request is allowed to run once only.
|
||
The `expect` method provides an overloaded variant that accepts an `ExpectedCount`
|
||
argument that specifies a count range (for example, `once`, `manyTimes`, `max`, `min`,
|
||
`between`, and so on). The following example uses `times`:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
RestTemplate restTemplate = new RestTemplate();
|
||
|
||
MockRestServiceServer mockServer = MockRestServiceServer.bindTo(restTemplate).build();
|
||
mockServer.expect(times(2), requestTo("/something")).andRespond(withSuccess());
|
||
mockServer.expect(times(3), requestTo("/somewhere")).andRespond(withSuccess());
|
||
|
||
// ...
|
||
|
||
mockServer.verify();
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
val restTemplate = RestTemplate()
|
||
|
||
val mockServer = MockRestServiceServer.bindTo(restTemplate).build()
|
||
mockServer.expect(times(2), requestTo("/something")).andRespond(withSuccess())
|
||
mockServer.expect(times(3), requestTo("/somewhere")).andRespond(withSuccess())
|
||
|
||
// ...
|
||
|
||
mockServer.verify()
|
||
----
|
||
|
||
Note that, when `ignoreExpectOrder` is not set (the default), and, therefore, requests
|
||
are expected in order of declaration, then that order applies only to the first of any
|
||
expected request. For example if "/something" is expected two times followed by
|
||
"/somewhere" three times, then there should be a request to "/something" before there is
|
||
a request to "/somewhere", but, aside from that subsequent "/something" and "/somewhere",
|
||
requests can come at any time.
|
||
|
||
As an alternative to all of the above, the client-side test support also provides a
|
||
`ClientHttpRequestFactory` implementation that you can configure into a `RestTemplate` to
|
||
bind it to a `MockMvc` instance. That allows processing requests using actual server-side
|
||
logic but without running a server. The following example shows how to do so:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||
.Java
|
||
----
|
||
MockMvc mockMvc = MockMvcBuilders.webAppContextSetup(this.wac).build();
|
||
this.restTemplate = new RestTemplate(new MockMvcClientHttpRequestFactory(mockMvc));
|
||
|
||
// Test code that uses the above RestTemplate ...
|
||
----
|
||
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
|
||
.Kotlin
|
||
----
|
||
val mockMvc = MockMvcBuilders.webAppContextSetup(this.wac).build()
|
||
restTemplate = RestTemplate(MockMvcClientHttpRequestFactory(mockMvc))
|
||
|
||
// Test code that uses the above RestTemplate ...
|
||
----
|
||
|
||
[[spring-mvc-test-client-static-imports]]
|
||
==== Static Imports
|
||
|
||
As with server-side tests, the fluent API for client-side tests requires a few static
|
||
imports. Those are easy to find by searching for `MockRest*`. Eclipse users should add
|
||
`MockRestRequestMatchers.{asterisk}` and `MockRestResponseCreators.{asterisk}` as
|
||
"`favorite static members`" in the Eclipse preferences under Java -> Editor -> Content
|
||
Assist -> Favorites. That allows using content assist after typing the first character of
|
||
the static method name. Other IDEs (such IntelliJ) may not require any additional
|
||
configuration. Check for the support for code completion on static members.
|
||
|
||
[[spring-mvc-test-client-resources]]
|
||
==== Further Examples of Client-side REST Tests
|
||
|
||
Spring MVC Test's own tests include
|
||
https://github.com/spring-projects/spring-framework/tree/master/spring-test/src/test/java/org/springframework/test/web/client/samples[example
|
||
tests] of client-side REST tests.
|
||
|
||
|
||
[[testing-resources]]
|
||
== Further Resources
|
||
See the following resources for more information about testing:
|
||
|
||
* https://www.junit.org/[JUnit]: "`A programmer-friendly testing framework for Java`".
|
||
Used by the Spring Framework in its test suite and supported in the
|
||
<<testcontext-framework, Spring TestContext Framework>>.
|
||
* https://testng.org/[TestNG]: A testing framework inspired by JUnit with added support
|
||
for test groups, data-driven testing, distributed testing, and other features. Supported
|
||
in the <<testcontext-framework, Spring TestContext Framework>>
|
||
* https://joel-costigliola.github.io/assertj/[AssertJ]: "`Fluent assertions for Java`",
|
||
including support for Java 8 lambdas, streams, and other features.
|
||
* https://en.wikipedia.org/wiki/Mock_Object[Mock Objects]: Article in Wikipedia.
|
||
* http://www.mockobjects.com/[MockObjects.com]: Web site dedicated to mock objects, a
|
||
technique for improving the design of code within test-driven development.
|
||
* https://mockito.github.io[Mockito]: Java mock library based on the
|
||
http://xunitpatterns.com/Test%20Spy.html[Test Spy] pattern. Used by the Spring Framework
|
||
in its test suite.
|
||
* https://easymock.org/[EasyMock]: Java library "`that provides Mock Objects for
|
||
interfaces (and objects through the class extension) by generating them on the fly using
|
||
Java's proxy mechanism.`"
|
||
* https://jmock.org/[JMock]: Library that supports test-driven development of Java code
|
||
with mock objects.
|
||
* https://www.dbunit.org/[DbUnit]: JUnit extension (also usable with Ant and Maven) that
|
||
is targeted at database-driven projects and, among other things, puts your database into
|
||
a known state between test runs.
|
||
* https://www.testcontainers.org/[Testcontainers]: Java library that supports JUnit
|
||
tests, providing lightweight, throwaway instances of common databases, Selenium web
|
||
browsers, or anything else that can run in a Docker container.
|
||
* https://sourceforge.net/projects/grinder/[The Grinder]: Java load testing framework.
|
||
* https://github.com/Ninja-Squad/springmockk[SpringMockK]: Support for Spring Boot
|
||
integration tests written in Kotlin using https://mockk.io/[MockK] instead of Mockito.
|