Annotation Interface MockitoBean

@Target({FIELD,TYPE}) @Retention(RUNTIME) @Documented @Repeatable(MockitoBeans.class) @BeanOverride(org.springframework.test.context.bean.override.mockito.MockitoBeanOverrideProcessor.class) public @interface MockitoBean
@MockitoBean is an annotation that can be used in test classes to override a bean in the test's ApplicationContext with a Mockito mock.

@MockitoBean can be applied in the following ways.

  • On a non-static field in a test class or any of its superclasses.
  • On a non-static field in an enclosing class for a @Nested test class or in any class in the type hierarchy or enclosing class hierarchy above the @Nested test class.
  • At the type level on a test class or any superclass or implemented interface in the type hierarchy above the test class.
  • At the type level on an enclosing class for a @Nested test class or on any class or interface in the type hierarchy or enclosing class hierarchy above the @Nested test class.

When @MockitoBean is declared on a field, the bean to mock is inferred from the type of the annotated field. If multiple candidates exist in the ApplicationContext, a @Qualifier annotation can be declared on the field 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 mock by setting the value or name attribute.

When @MockitoBean is declared at the type level, the type of bean (or beans) to mock must be supplied via the types attribute. If multiple candidates exist in the ApplicationContext, you can explicitly specify a bean name to mock by setting the name attribute. Note, however, that the types attribute must contain a single type if an explicit bean name is configured.

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, @MockitoBean(enforceOverride = true).

Dependencies that are known to the application context but are not beans (such as those registered directly) will not be found, and a mocked bean will be added to the context alongside the existing dependency.

WARNING: Using @MockitoBean in conjunction with @ContextHierarchy can lead to undesirable results since each @MockitoBean will be applied to all context hierarchy levels by default. To ensure that a particular @MockitoBean 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 mocking a non-singleton bean, the non-singleton bean will be replaced with a singleton mock, and the corresponding bean definition will be converted to a singleton. Consequently, if you mock a prototype or scoped bean, the mock will be treated as a singleton. Similarly, when mocking a bean created by a FactoryBean, the FactoryBean will be replaced with a singleton mock of the type of object created by the FactoryBean.

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

@MockitoBean fields and type-level @MockitoBean declarations will be inherited from an enclosing test class by default. See @NestedTestConfiguration for details.

@MockitoBean may be used as a meta-annotation to create custom composed annotations — for example, to define common mock configuration in a single annotation that can be reused across a test suite. @MockitoBean can also be used as a repeatable annotation at the type level — for example, to mock several beans by name.

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

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    org.mockito.Answers
    answers
    The Answers type to use in the mock.
    String
    contextName
    The name of the context hierarchy level in which this @MockitoBean should be applied.
    boolean
    enforceOverride
    Whether to require the existence of the bean being mocked.
    Class<?>[]
    extraInterfaces
    Extra interfaces that should also be declared by the mock.
    String
    name
    Name of the bean to mock.
    MockReset
    reset
    The reset mode to apply to the mock.
    boolean
    serializable
    Whether the generated mock is serializable.
    Class<?>[]
    types
    One or more types to mock.
    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, @MockitoBean("customBeanName").

      See Also:
      Default:
      ""

    • name

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

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

      See Also:
      Default:
      ""

    • types

      Class<?>[] types
      One or more types to mock.

      Defaults to none.

      Each type specified will result in a mock being created and registered with the ApplicationContext.

      Types must be omitted when the annotation is used on a field.

      When @MockitoBean also defines a name, this attribute can only contain a single value.

      Returns:
      the types to mock
      Since:
      6.2.2
      Default:
      {}

    • contextName

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

      Defaults to an empty string which indicates that this @MockitoBean 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:
      ""

    • extraInterfaces

      Class<?>[] extraInterfaces
      Extra interfaces that should also be declared by the mock.

      Defaults to none.

      Returns:
      any extra interfaces
      See Also:
      • MockSettings.extraInterfaces(Class...)
      Default:
      {}

    • answers

      org.mockito.Answers answers
      The Answers type to use in the mock.

      Defaults to Answers.RETURNS_DEFAULTS.

      Returns:
      the answer type
      Default:
      RETURNS_DEFAULTS

    • serializable

      boolean serializable
      Whether the generated mock is serializable.

      Defaults to false.

      Returns:
      true if the mock is serializable
      See Also:
      • MockSettings.serializable()
      Default:
      false

    • reset

      MockReset reset
      The reset mode to apply to the mock.

      The default is MockReset.AFTER meaning that mocks are automatically reset after each test method is invoked.

      Returns:
      the reset mode
      Default:
      AFTER

    • enforceOverride

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

      Defaults to false which means that a mock 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