This version is still in development and is not considered stable yet. For the latest stable version, please use Spring Framework 6.1.11! |
Spring JUnit Jupiter Testing Annotations
The following annotations are supported when used in conjunction with the
SpringExtension
and JUnit Jupiter
(that is, the programming model in JUnit 5):
@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:
-
Java
-
Kotlin
@SpringJUnitConfig(TestConfig.class) (1)
class ConfigurationClassJUnitJupiterSpringTests {
// class body...
}
1 | Specify the configuration class. |
@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:
-
Java
-
Kotlin
@SpringJUnitConfig(locations = "/test-config.xml") (1)
class XmlJUnitJupiterSpringTests {
// class body...
}
1 | Specify the location of a configuration file. |
@SpringJUnitConfig(locations = ["/test-config.xml"]) (1)
class XmlJUnitJupiterSpringTests {
// class body...
}
1 | Specify the location of a configuration file. |
See Context Management as well as the javadoc for
@SpringJUnitConfig
and @ContextConfiguration
for further details.
@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:
-
Java
-
Kotlin
@SpringJUnitWebConfig(TestConfig.class) (1)
class ConfigurationClassJUnitJupiterSpringWebTests {
// class body...
}
1 | Specify the configuration class. |
@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:
-
Java
-
Kotlin
@SpringJUnitWebConfig(locations = "/test-config.xml") (1)
class XmlJUnitJupiterSpringWebTests {
// class body...
}
1 | Specify the location of a configuration file. |
@SpringJUnitWebConfig(locations = ["/test-config.xml"]) (1)
class XmlJUnitJupiterSpringWebTests {
// class body...
}
1 | Specify the location of a configuration file. |
See Context Management as well as the javadoc for
@SpringJUnitWebConfig
,
@ContextConfiguration
, and
@WebAppConfiguration
for further details.
@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
The default test constructor autowire mode can be changed by setting the
As of Spring Framework 5.3, the default mode may also be configured as a JUnit Platform configuration parameter. If the |
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.
|
@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
The default enclosing configuration inheritance mode is |
The Spring TestContext Framework honors @NestedTestConfiguration
semantics for the
following annotations.
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 @Nested
test class configuration for an example and further
details.
@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:
-
Spring Expression Language (SpEL) expression. For example:
@EnabledIf("#{systemProperties['os.name'].toLowerCase().contains('mac')}")
-
Placeholder for a property available in the Spring
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:
-
Java
-
Kotlin
@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@EnabledIf(
expression = "#{systemProperties['os.name'].toLowerCase().contains('mac')}",
reason = "Enabled on Mac OS"
)
public @interface EnabledOnMac {}
@Target(AnnotationTarget.TYPE, AnnotationTarget.FUNCTION)
@Retention(AnnotationRetention.RUNTIME)
@EnabledIf(
expression = "#{systemProperties['os.name'].toLowerCase().contains('mac')}",
reason = "Enabled on Mac OS"
)
annotation class EnabledOnMac {}
|
Since JUnit 5.7, JUnit Jupiter also has a condition annotation named |
@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:
-
Spring Expression Language (SpEL) expression. For example:
@DisabledIf("#{systemProperties['os.name'].toLowerCase().contains('mac')}")
-
Placeholder for a property available in the Spring
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:
-
Java
-
Kotlin
@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@DisabledIf(
expression = "#{systemProperties['os.name'].toLowerCase().contains('mac')}",
reason = "Disabled on Mac OS"
)
public @interface DisabledOnMac {}
@Target(AnnotationTarget.TYPE, AnnotationTarget.FUNCTION)
@Retention(AnnotationRetention.RUNTIME)
@DisabledIf(
expression = "#{systemProperties['os.name'].toLowerCase().contains('mac')}",
reason = "Disabled on Mac OS"
)
annotation class DisabledOnMac {}
|
Since JUnit 5.7, JUnit Jupiter also has a condition annotation named |