350 lines
13 KiB
Plaintext
350 lines
13 KiB
Plaintext
|
[[integration-testing-annotations-junit-jupiter]]
|
|||
|
|
= Spring JUnit Jupiter Testing Annotations
|
|||
|
|
|
|||
|
|
The following annotations are supported 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-nestedtestconfiguration>>
|
|||
|
|
* <<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
|
|||
|
|
<<appendix.adoc#appendix-spring-properties,`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-nestedtestconfiguration]]
|
|||
|
|
== `@NestedTestConfiguration`
|
|||
|
|
|
|||
|
|
`@NestedTestConfiguration` is a type-level annotation that is used to configure how
|
|||
|
|
Spring test configuration annotations are processed within enclosing class hierarchies
|
|||
|
|
for inner test classes.
|
|||
|
|
|
|||
|
|
If `@NestedTestConfiguration` is not present or meta-present on a test class, in its
|
|||
|
|
supertype hierarchy, or in its enclosing class hierarchy, the default _enclosing
|
|||
|
|
configuration inheritance mode_ will be used. See the tip below for details on how to
|
|||
|
|
change the default mode.
|
|||
|
|
|
|||
|
|
.Changing the default enclosing configuration inheritance mode
|
|||
|
|
[TIP]
|
|||
|
|
=====
|
|||
|
|
The default _enclosing configuration inheritance mode_ is `INHERIT`, but it can be
|
|||
|
|
changed by setting the `spring.test.enclosing.configuration` JVM system property to
|
|||
|
|
`OVERRIDE`. Alternatively, the default mode may be set via the
|
|||
|
|
<<appendix.adoc#appendix-spring-properties,`SpringProperties`>> mechanism.
|
|||
|
|
=====
|
|||
|
|
|
|||
|
|
The <<testcontext-framework>> honors `@NestedTestConfiguration` semantics for the
|
|||
|
|
following annotations.
|
|||
|
|
|
|||
|
|
* <<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-recordapplicationevents>>
|
|||
|
|
* <<testcontext-tx,`@Transactional`>>
|
|||
|
|
* <<spring-testing-annotation-commit>>
|
|||
|
|
* <<spring-testing-annotation-rollback>>
|
|||
|
|
* <<spring-testing-annotation-sql>>
|
|||
|
|
* <<spring-testing-annotation-sqlconfig>>
|
|||
|
|
* <<spring-testing-annotation-sqlmergemode>>
|
|||
|
|
* <<integration-testing-annotations-testconstructor>>
|
|||
|
|
|
|||
|
|
NOTE: The use of `@NestedTestConfiguration` typically only makes sense in conjunction
|
|||
|
|
with `@Nested` test classes in JUnit Jupiter; however, there may be other testing
|
|||
|
|
frameworks with support for Spring and nested test classes that make use of this
|
|||
|
|
annotation.
|
|||
|
|
|
|||
|
|
See <<testcontext-junit-jupiter-nested-test-configuration>> for an example and further
|
|||
|
|
details.
|
|||
|
|
|
|||
|
|
[[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 {}
|
|||
|
|
----
|
|||
|
|
|
|||
|
|
[NOTE]
|
|||
|
|
====
|
|||
|
|
`@EnabledOnMac` is meant only as an example of what is possible. If you have that exact
|
|||
|
|
use case, please use the built-in `@EnabledOnOs(MAC)` support in JUnit Jupiter.
|
|||
|
|
====
|
|||
|
|
|
|||
|
|
[WARNING]
|
|||
|
|
====
|
|||
|
|
Since JUnit 5.7, JUnit Jupiter also has a condition annotation named `@EnabledIf`. Thus,
|
|||
|
|
if you wish to use Spring's `@EnabledIf` support make sure you import the annotation type
|
|||
|
|
from the correct package.
|
|||
|
|
====
|
|||
|
|
|
|||
|
|
[[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 {}
|
|||
|
|
----
|
|||
|
|
|
|||
|
|
[NOTE]
|
|||
|
|
====
|
|||
|
|
`@DisabledOnMac` is meant only as an example of what is possible. If you have that exact
|
|||
|
|
use case, please use the built-in `@DisabledOnOs(MAC)` support in JUnit Jupiter.
|
|||
|
|
====
|
|||
|
|
|
|||
|
|
[WARNING]
|
|||
|
|
====
|
|||
|
|
Since JUnit 5.7, JUnit Jupiter also has a condition annotation named `@DisabledIf`. Thus,
|
|||
|
|
if you wish to use Spring's `@DisabledIf` support make sure you import the annotation type
|
|||
|
|
from the correct package.
|
|||
|
|
====
|
|||
|
|
|
|||
|
|
|
|||
|
|
|