Annotation Interface TestPropertySource
@TestPropertySource
is an annotation that can be applied to a test
class to configure the locations()
of properties files and inlined
properties()
to be added to the Environment
's set of
PropertySources
for an
ApplicationContext
for integration tests.
Precedence
Test property sources have higher precedence than those loaded from the
operating system's environment or Java system properties as well as property
sources added by the application declaratively via
@PropertySource
or programmatically (for example, via an
ApplicationContextInitializer
or some other means). Thus, test property sources can be used to selectively
override properties defined in system and application property sources.
Furthermore, inlined properties()
have higher precedence than
properties loaded from resource locations()
. Note, however, that
properties registered via @DynamicPropertySource
have higher precedence than those loaded via @TestPropertySource
.
Default Properties File Detection
If @TestPropertySource
is declared as an empty annotation
(i.e., without explicit values for locations()
or properties()
),
an attempt will be 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
will be thrown.
Enabling @TestPropertySource
@TestPropertySource
is enabled if the configured
context loader honors it. Every
SmartContextLoader
that is a subclass of either
AbstractGenericContextLoader
or
AbstractGenericWebContextLoader
provides automatic support for @TestPropertySource
, and this includes
every SmartContextLoader
provided by the Spring TestContext Framework.
Miscellaneous
- Typically,
@TestPropertySource
will be used in conjunction with@ContextConfiguration
. @TestPropertySource
can be used as a repeatable annotation.- This annotation may be used as a meta-annotation to create
custom composed annotations, but caution should be taken if
this annotation and
@ContextConfiguration
are combined on a composed annotation since thelocations
andinheritLocations
attributes of both annotations can lead to ambiguity during the attribute resolution process. Note, however, that ambiguity can be avoided via explicit annotation attribute overrides using@AliasFor
. - As of Spring Framework 5.3, this annotation will be inherited from an
enclosing test class by default. See
@NestedTestConfiguration
for details.
- Since:
- 4.1
- Author:
- Sam Brannen
- See Also:
-
Optional Element Summary
Modifier and TypeOptional ElementDescriptionSpecify the character encoding for the given resources — for example, "UTF-8".Class<? extends PropertySourceFactory>
Specify a customPropertySourceFactory
, if any.boolean
Whether test property sourcelocations()
from superclasses and enclosing classes should be inherited.boolean
Whether inlined testproperties()
from superclasses and enclosing classes should be inherited.String[]
The resource locations of properties files to be loaded into theEnvironment
's set ofPropertySources
.String[]
Inlined properties in the form of key-value pairs that should be added to the SpringEnvironment
before theApplicationContext
is loaded for the test.String[]
Alias forlocations()
.
-
Element Details
-
value
Alias forlocations()
.This attribute may not be used in conjunction with
locations()
, but it may be used instead oflocations()
.- See Also:
- Default:
- {}
-
locations
The resource locations of properties files to be loaded into theEnvironment
's set ofPropertySources
.Each location will be added to the enclosing
Environment
as its own property source, in the order declared (or in the order in which resource locations are resolved when location wildcards are used).Supported File Formats
By default, both traditional and XML-based properties file formats are supported — for example,
"classpath:/com/example/test.properties"
or"file:/path/to/file.xml"
. To support a different file format, configure an appropriatePropertySourceFactory
.Path Resource Semantics
Each path will be interpreted as a Spring
Resource
. A plain path — for example,"test.properties"
— will be treated as a classpath resource that is relative to the package in which the test class is defined. A path starting with a slash will be treated as an absolute classpath resource, for example:"/org/example/test.xml"
. A path which references a URL (for example, a path prefixed withclasspath:
,file:
,http:
, etc.) will be loaded using the specified resource protocol.Property placeholders in paths (i.e.,
${...}
) will be resolved against theEnvironment
.As of Spring Framework 6.1, resource location patterns are also supported — for example,
"classpath*:/config/*.properties"
.WARNING: a pattern such as
"classpath*:/config/*.properties"
may be effectively equivalent to an explicit enumeration of resource locations such as{"classpath:/config/mail.properties", classpath:/config/order.properties"}
; however, the two declarations will result in different keys for the context cache since the pattern cannot be eagerly resolved to concrete locations. Consequently, to benefit from the context cache you must ensure that you consistently use either patterns or explicit enumerations of resource locations within your test suite.Default Properties File Detection
See the class-level Javadoc for a discussion on detection of defaults.
Precedence
Properties loaded from resource locations have lower precedence than inlined
properties()
.This attribute may not be used in conjunction with
value()
, but it may be used instead ofvalue()
.- Default:
- {}
-
inheritLocations
boolean inheritLocationsWhether test property sourcelocations()
from superclasses and enclosing classes should be inherited.The default value is
true
, which means that a test class will inherit property source locations defined by a superclass or enclosing class. Specifically, the property source locations for a test class will be appended to the list of property source locations defined by a superclass or enclosing class. Thus, subclasses and nested classes have the option of extending the list of test property source locations.If
inheritLocations
is set tofalse
, the property source locations for the test class will shadow and effectively replace any property source locations defined by a superclass or enclosing class.In the following example, the
ApplicationContext
forBaseTest
will be loaded using only the"base.properties"
file as a test property source. In contrast, theApplicationContext
forExtendedTest
will be loaded using the"base.properties"
and"extended.properties"
files as test property source locations.@TestPropertySource("base.properties") @ContextConfiguration public class BaseTest { // ... } @TestPropertySource("extended.properties") @ContextConfiguration public class ExtendedTest extends BaseTest { // ... }
If
@TestPropertySource
is used as a repeatable annotation, the following special rules apply.- All
@TestPropertySource
annotations at a given level in the test class hierarchy (i.e., directly present or meta-present on a test class) are considered to be local annotations, in contrast to@TestPropertySource
annotations that are inherited from a superclass. - All local
@TestPropertySource
annotations must declare the same value for theinheritLocations
flag. - The
inheritLocations
flag is not taken into account between local@TestPropertySource
annotations. Specifically, the property source locations for one local annotation will be appended to the list of property source locations defined by previous local annotations. This allows a local annotation to extend the list of test property source locations, potentially overriding individual properties.
- See Also:
- Default:
- true
- All
-
properties
String[] propertiesInlined properties in the form of key-value pairs that should be added to the SpringEnvironment
before theApplicationContext
is loaded for the test. All key-value pairs will be added to the enclosingEnvironment
as a single testPropertySource
with the highest precedence. As of Spring Framework 6.1, multiple key-value pairs may be specified via a single text block.Supported Syntax
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"
WARNING: although properties can be defined using any of the above syntax variants and any number of spaces between the key and the value, it is recommended that you use one syntax variant and consistent spacing within your test suite — for example, consider always using
"key = value"
instead of"key= value"
,"key=value"
, etc. Similarly, if you define inlined properties using text blocks you should consistently use text blocks for inlined properties throughout your test suite. The reason is that the exact strings you provide will be used to determine the key for the context cache. Consequently, to benefit from the context cache you must ensure that you define inlined properties consistently.Examples
// Using an array of strings @TestPropertySource(properties = { "key1 = value1", "key2 = value2" }) @ContextConfiguration class MyTests { // ... }
// Using a single text block @TestPropertySource(properties = """ key1 = value1 key2 = value2 """ ) @ContextConfiguration class MyTests { // ... }
Precedence
Properties declared via this attribute have higher precedence than properties loaded from resource
locations()
.This attribute may be used in conjunction with
value()
orlocations()
.- See Also:
- Default:
- {}
-
inheritProperties
boolean inheritPropertiesWhether inlined testproperties()
from superclasses and enclosing classes should be inherited.The default value is
true
, which means that a test class will inherit inlined properties defined by a superclass or enclosing class. Specifically, the inlined properties for a test class will be appended to the list of inlined properties defined by a superclass or enclosing class. Thus, subclasses and nested classes have the option of extending the list of inlined test properties.If
inheritProperties
is set tofalse
, the inlined properties for the test class will shadow and effectively replace any inlined properties defined by a superclass or enclosing class.In the following example, the
ApplicationContext
forBaseTest
will be loaded using only the inlinedkey1
property. In contrast, theApplicationContext
forExtendedTest
will be loaded using the inlinedkey1
andkey2
properties.@TestPropertySource(properties = "key1 = value1") @ContextConfiguration public class BaseTest { // ... } @TestPropertySource(properties = "key2 = value2") @ContextConfiguration public class ExtendedTest extends BaseTest { // ... }
If
@TestPropertySource
is used as a repeatable annotation, the following special rules apply.- All
@TestPropertySource
annotations at a given level in the test class hierarchy (i.e., directly present or meta-present on a test class) are considered to be local annotations, in contrast to@TestPropertySource
annotations that are inherited from a superclass or enclosing class. - All local
@TestPropertySource
annotations must declare the same value for theinheritProperties
flag. - The
inheritProperties
flag is not taken into account between local@TestPropertySource
annotations. Specifically, inlined properties for one local annotation will be appended to the list of inlined properties defined by previous local annotations. This allows a local annotation to extend the list of inlined properties, potentially overriding individual properties.
- See Also:
- Default:
- true
- All
-
encoding
String encodingSpecify the character encoding for the given resources — for example, "UTF-8".If not specified, the default character encoding of the JVM will be used.
- Since:
- 6.1
- Default:
- ""
-
factory
Class<? extends PropertySourceFactory> factorySpecify a customPropertySourceFactory
, if any.By default, a factory for standard resource files will be used which supports
*.properties
and*.xml
file formats forProperties
.- Since:
- 6.1
- See Also:
- Default:
- org.springframework.core.io.support.PropertySourceFactory.class
-