Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/spring-projects/spring-boot/llms.txt

Use this file to discover all available pages before exploring further.

Spring Boot’s testing support is built on top of the Spring Test framework and extends it with auto-configuration, dedicated test slice annotations, and first-class Testcontainers integration. Adding a single dependency to your build gives you a curated set of libraries and a consistent testing model that works whether you are writing a focused unit test or a full integration test with a running server.

​
Test scope dependencies

The spring-boot-starter-test starter pulls in everything you need for most tests:
The standard for unit testing Java applications. Spring Boot’s @SpringBootTest and all @...Test slice annotations are already meta-annotated with @ExtendWith(SpringExtension.class), so you do not need to add it yourself.
A fluent assertion library used throughout Spring Boot’s own test helpers, including MockMvcTester and ApplicationContextAssert.
The Java mocking framework. Spring Framework’s @MockitoBean and @MockitoSpyBean annotations integrate Mockito directly with the Spring ApplicationContext.
Libraries for asserting on JSON content. Spring Boot wraps them in JacksonTester, GsonTester, JsonbTester, and BasicJsonTester helpers.
Hamcrest provides matcher objects for use with MockMvc. Awaitility helps test asynchronous systems by polling until a condition is met.
If these libraries do not suit your needs, you can add additional test dependencies of your own.

​
How test support is structured

Spring Boot’s testing model offers two main strategies: loading the full application context with @SpringBootTest, or loading only a focused slice of the application with a @...Test annotation.
@SpringBootTest starts an ApplicationContext through SpringApplication, which means external properties, logging, and all auto-configuration are active by default.
@SpringBootTest
class MyIntegrationTests {

    @Test
    void contextLoads() {
    }

}
Use @SpringBootTest when you want an end-to-end integration test or when multiple layers of the application need to interact.

​
Detecting test configuration

Spring Boot’s @*Test annotations automatically search for your primary configuration by walking up the package hierarchy until they find a class annotated with @SpringBootApplication or @SpringBootConfiguration. You rarely need to specify configuration explicitly. When you need to add test-specific beans on top of the primary configuration, use a @TestConfiguration class. Unlike a nested @Configuration class, it is used in addition to rather than instead of the primary configuration: 
@TestConfiguration(proxyBeanMethods = false)
static class MyTestConfig {

    @Bean
    RemoteService remoteService() {
        return new StubRemoteService();
    }

}
Spring’s test framework caches application contexts between tests. As long as your tests share the same configuration, the context is loaded only once, reducing overall test run time.

​
Mocking beans with @MockitoBean and @MockitoSpyBean

When running tests, it is sometimes necessary to mock components inside the application context—for example, when a service depends on a remote system that is unavailable during testing. Spring Framework’s @MockitoBean replaces a bean with a Mockito mock, and @MockitoSpyBean wraps an existing bean in a Mockito spy: 
@SpringBootTest
class MyServiceTests {

    @MockitoBean
    private RemoteService remoteService;

    @Autowired
    private MyService myService;

    @Test
    void testWithMock() {
        given(this.remoteService.getData()).willReturn("mocked");
        assertThat(this.myService.process()).isEqualTo("mocked");
    }

}

​
Testcontainers integration

The Testcontainers library manages services running inside Docker containers and integrates with JUnit to start containers before tests run. It is especially useful for integration tests that need a real backing service such as MySQL, MongoDB, or Kafka. Spring Boot supports two ways to use Testcontainers:
1

Use the JUnit extension

Apply @Testcontainers to your test class and declare containers as static fields annotated with @Container:
@Testcontainers
@SpringBootTest
class MyIntegrationTests {

    @Container
    static Neo4jContainer neo4j = new Neo4jContainer("neo4j:5");

    @Test
    void myTest() {
        // neo4j is running
    }

}
2

Declare containers as Spring beans (preferred)

Managing containers as Spring beans gives Spring full control over their lifecycle—containers start before all other beans and stop after the context shuts down. Add @ServiceConnection to automatically configure connection details:
@Testcontainers
@SpringBootTest
class MyIntegrationTests {

    @Container
    @ServiceConnection
    static Neo4jContainer neo4j = new Neo4jContainer("neo4j:5");

    @Test
    void myTest() {
        // neo4j connection details auto-configured
    }

}
With @ServiceConnection, Spring Boot automatically creates the appropriate ConnectionDetails bean (such as Neo4jConnectionDetails), overriding any connection-related configuration properties.
When using the JUnit extension, container instances are stopped after the test class finishes. If Spring’s TestContext framework caches the application context beyond that point, later tests that rely on container-backed beans may fail. Prefer managing containers as Spring beans or using @ImportTestcontainers when the context needs to remain usable across test classes.

​
Explore further

Spring Boot Tests

@SpringBootTest web environment modes, MockMvc, slice tests for MVC, JPA, MongoDB, WebFlux, and JSON.

Test Utilities

OutputCaptureExtension, TestPropertyValues, ApplicationContextRunner, ConfigDataApplicationContextInitializer, and TestRestTemplate.

Build docs developers (and LLMs) love

Get started for freeTalk to us