Annotation Interface TestBean

@Target(FIELD) @Retention(RUNTIME) @Documented @BeanOverride(org.springframework.test.context.bean.override.convention.TestBeanOverrideProcessor.class) @Reflective(org.springframework.test.context.bean.override.convention.TestBeanReflectiveProcessor.class) public @interface TestBean
@TestBean is an annotation that can be applied to a non-static field in a test class to override a bean in the test's ApplicationContext using a static factory method.

By default, the bean to override is inferred from the type of the annotated field. If multiple candidates exist, a @Qualifier annotation can be used to help disambiguate. In the absence of a @Qualifier annotation, the name of the annotated field will be used as a fallback qualifier. Alternatively, you can explicitly specify a bean name to replace by setting the value or name attribute.

A bean will be created if a corresponding bean does not exist. However, if you would like for the test to fail when a corresponding bean does not exist, you can set the enforceOverride attribute to true — for example, @TestBean(enforceOverride = true).

The instance is created from a zero-argument static factory method whose return type is compatible with the annotated field. The factory method can be declared directly in the class which declares the @TestBean field or within the type hierarchy above that class, including implemented interfaces. If the @TestBean field is declared in a nested test class, the enclosing class hierarchy is also searched. Alternatively, a factory method in an external class can be referenced via its fully-qualified method name following the syntax <fully-qualified class name>#<method name> — for example, @TestBean(methodName = "org.example.TestUtils#createCustomerRepository").

The factory method is deduced as follows.

  • If the methodName is specified, Spring looks for a static method with that name.
  • If a method name is not specified, Spring looks for exactly one static method whose name is either the name of the annotated field or the name of the bean (if specified).

Consider the following example. 

 class CustomerServiceTests {

    @TestBean
    private CustomerRepository repository;

    // @Test methods ...

    private static CustomerRepository repository() {
        return new TestCustomerRepository();
    }
}

In the example above, the repository bean is replaced by the instance generated by the repository() method. Not only is the overridden instance injected into the repository field, but it is also replaced in the BeanFactory so that other injection points for that bean use the overridden bean instance.

To make things more explicit, the bean and method names can be set, as shown in the following example. 

 class CustomerServiceTests {

    @TestBean(name = "customerRepository", methodName = "createTestCustomerRepository")
    CustomerRepository repository;

    // @Test methods ...

    static CustomerRepository createTestCustomerRepository() {
        return new TestCustomerRepository();
    }
}

WARNING: Using @TestBean in conjunction with @ContextHierarchy can lead to undesirable results since each @TestBean will be applied to all context hierarchy levels by default. To ensure that a particular @TestBean is applied to a single context hierarchy level, set the contextName to match a configured @ContextConfiguration name. See the Javadoc for @ContextHierarchy for further details and examples.

NOTE: When overriding a non-singleton bean, the non-singleton bean will be replaced with a singleton bean corresponding to the value returned from the @TestBean factory method, and the corresponding bean definition will be converted to a singleton. Consequently, if you override a prototype or scoped bean, it will be treated as a singleton. Similarly, when overriding a bean created by a FactoryBean, the FactoryBean will be replaced with a singleton bean corresponding to the value returned from the @TestBean factory method.

There are no restrictions on the visibility of @TestBean fields or factory methods. Such fields and methods can therefore be public, protected, package-private (default visibility), or private depending on the needs or coding practices of the project.

@TestBean fields will be inherited from an enclosing test class by default. See @NestedTestConfiguration for details.

Since:
6.2
Author:
Simon Baslé, Stephane Nicoll, Sam Brannen
See Also:

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String
    contextName
    The name of the context hierarchy level in which this @TestBean should be applied.
    boolean
    enforceOverride
    Whether to require the existence of the bean being overridden.
    String
    methodName
    Name of the static factory method that will be used to instantiate the bean to override.
    String
    name
    Name of the bean to override.
    String
    value
    Alias for name().

  • Element Details

    • value

      @AliasFor("name") String value
      Alias for name().

      Intended to be used when no other attributes are needed — for example, @TestBean("customBeanName").

      See Also:
      Default:
      ""

    • name

      @AliasFor("value") String name
      Name of the bean to override.

      If left unspecified, the bean to override is selected according to the annotated field's type, taking qualifiers into account if necessary. See the class-level documentation for details.

      See Also:
      Default:
      ""

    • methodName

      String methodName
      Name of the static factory method that will be used to instantiate the bean to override.

      A search will be performed to find the factory method in the class in which the @TestBean field is declared, in one of its superclasses, or in any implemented interfaces. If the @TestBean field is declared in a nested test class, the enclosing class hierarchy will also be searched.

      Alternatively, a factory method in an external class can be referenced via its fully-qualified method name following the syntax <fully-qualified class name>#<method name> — for example, @TestBean(methodName = "org.example.TestUtils#createCustomerRepository").

      If left unspecified, the name of the factory method will be detected based either on the name of the @TestBean field or the name of the bean.

      Default:
      ""

    • contextName

      String contextName
      The name of the context hierarchy level in which this @TestBean should be applied.

      Defaults to an empty string which indicates that this @TestBean should be applied to all application contexts.

      If a context name is configured, it must match a name configured via @ContextConfiguration(name=...).

      Since:
      6.2.6
      See Also:
      Default:
      ""

    • enforceOverride

      boolean enforceOverride
      Whether to require the existence of the bean being overridden.

      Defaults to false which means that a bean will be created if a corresponding bean does not exist.

      Set to true to cause an exception to be thrown if a corresponding bean does not exist.

      See Also:
      Default:
      false