Package org.springframework.test.context

Annotation Interface TestPropertySource

@Target(TYPE) @Retention(RUNTIME) @Documented @Inherited @Repeatable(TestPropertySources.class) public @interface TestPropertySource
@TestPropertySource is a class-level annotation that is used 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 (e.g., 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; however, 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.
  • 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

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    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:
      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.

      Supported File Formats

      Both traditional and XML-based properties file formats are supported — for example, "classpath:/com/example/test.properties" or "file:/path/to/file.xml".

      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 (e.g., a path prefixed with classpath:, file:, http:, etc.) will be loaded using the specified resource protocol. Resource location wildcards (e.g. **/*.properties) are not permitted: each location must evaluate to exactly one .properties or .xml resource. Property placeholders in paths (i.e., ${...}) will be resolved against the Environment.

      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:
      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:
      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.

      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"

      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:
      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:
      Default:
      true