Package org.springframework.test.context

# Annotation Interface TestPropertySource

@Target(TYPE) @Retention(RUNTIME) @Documented @Inherited @Repeatable(TestPropertySources.class) public @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 the `locations` and `inheritLocations` 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`.
- This annotation will be inherited from an enclosing test class by default. See `@NestedTestConfiguration` for details.

Since:
  4.1
Author:
  Sam Brannen
See Also:
  - `ContextConfiguration`
  - `DynamicPropertySource`
  - `Environment`
  - `PropertySource`
  - `PropertySource`

## Optional Element Summary

Optional Elements
Modifier and Type
Optional Element
Description
`String`
`encoding`
Specify the character encoding for the given resources — for example, "UTF-8".
`Class<? extends org.springframework.core.io.support.PropertySourceFactory>`
`factory`
Specify a custom `PropertySourceFactory`, if any.
`boolean`
`inheritLocations`
Whether test property source `locations()` from superclasses and enclosing classes should be inherited.
`boolean`
`inheritProperties`
Whether inlined test `properties()` from superclasses and enclosing classes should be inherited.
`String[]`
`locations`
The resource locations of properties files to be loaded into the `Environment`'s set of `PropertySources`.
`String[]`
`properties`
Inlined properties in the form of key-value pairs that should be added to the Spring `Environment` before the `ApplicationContext` is loaded for the test.
`String[]`
`value`
Alias for `locations()`.

## Element Details

### value

@AliasFor("locations") String[] value
Alias for `locations()`.

This attribute may not be used in conjunction with `locations()`, but it may be used instead of `locations()`.

See Also:
  - `locations()`

Default:
  {}

### locations

@AliasFor("value") String[] locations
The resource locations of properties files to be loaded into the `Environment`'s set of `PropertySources`.

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 appropriate `PropertySourceFactory`.

#### 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 with `classpath:`, `file:`, `http:`, etc.) will be loaded using the specified resource protocol.

Property placeholders in paths (i.e., `${...}`) will be resolved against the `Environment`.

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 of `value()`.

See Also:
  - `inheritLocations()`
  - `value()`
  - `properties()`
  - `encoding()`
  - `factory()`
  - `PropertySource`

Default:
  {}

### inheritLocations

boolean inheritLocations
Whether test property source `locations()` 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 to `false`, 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` for `BaseTest` will be loaded using only the `"base.properties"` file as a test property source. In contrast, the `ApplicationContext` for `ExtendedTest` 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.

1. 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.
2. All local `@TestPropertySource` annotations must declare the same value for the `inheritLocations` flag.
3. 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:
  - `locations()`

Default:
  true

### properties

String[] properties
Inlined properties in the form of key-value pairs that should be added to the Spring `Environment` before the `ApplicationContext` is loaded for the test. All key-value pairs will be added to the enclosing `Environment` as a single test `PropertySource` 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()` or `locations()`.

See Also:
  - `inheritProperties()`
  - `locations()`
  - `PropertySource`

Default:
  {}

### inheritProperties

boolean inheritProperties
Whether inlined test `properties()` 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 to `false`, 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` for `BaseTest` will be loaded using only the inlined `key1` property. In contrast, the `ApplicationContext` for `ExtendedTest` will be loaded using the inlined `key1` and `key2` 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.

1. 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.
2. All local `@TestPropertySource` annotations must declare the same value for the `inheritProperties` flag.
3. 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:
  - `properties()`

Default:
  true

### encoding

String encoding
Specify 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 org.springframework.core.io.support.PropertySourceFactory> factory
Specify a custom `PropertySourceFactory`, if any.

By default, a factory for standard resource files will be used which supports `*.properties` and `*.xml` file formats for `Properties`.

Since:
  6.1
See Also:
  - `DefaultPropertySourceFactory`
  - `ResourcePropertySource`

Default:
  org.springframework.core.io.support.PropertySourceFactory.class