Spring Boot Integration Test Patterns: @SpringBootTest (2026)

@SpringBootTest can be a black box if you don’t know what’s happening under the hood.

Let’s see what @SpringBootTest actually does when you run a test. Imagine we have a simple Spring Boot application:

// src/main/java/com/example/demo/MyService.java
@Service
public class MyService {
    public String greet(String name) {
        return "Hello, " + name + "!";
    }
}

// src/main/java/com/example/demo/MyController.java
@RestController
public class MyController {
    private final MyService myService;

    public MyController(MyService myService) {
        this.myService = myService;
    }

    @GetMapping("/greet")
    public String greet(@RequestParam String name) {
        return myService.greet(name);
    }
}

And a test using @SpringBootTest:

// src/test/java/com/example/demo/MyControllerTest.java
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@AutoConfigureMockMvc
class MyControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    void testGreetEndpoint() throws Exception {
        mockMvc.perform(get("/greet?name=World"))
               .andExpect(status().isOk())
               .andExpect(content().string("Hello, World!"));
    }
}

When you run MyControllerTest, Spring Boot doesn’t just instantiate your beans. It launches a miniature application context specifically for this test. Think of it as a stripped-down version of your main application, but running within the JVM of your test runner.

The webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT setting is crucial. It tells Spring Boot to start a real web server (like Tomcat or Netty, depending on your dependencies) on a randomly assigned port. This is why you can use tools like MockMvc to actually send HTTP requests to your application endpoints during the test, just like you would with a deployed application. MockMvc is a powerful testing utility that allows you to simulate HTTP requests and inspect their responses without needing a fully running, external server.

The @AutoConfigureMockMvc annotation is what injects the MockMvc instance into your test class. This MockMvc is pre-configured to work with the embedded web server started by @SpringBootTest.

So, in essence, @SpringBootTest is your gateway to integration testing Spring Boot applications. It creates a fully-fledged, albeit temporary, application context, allowing you to test the interactions between your components in a realistic environment.

The mental model to build here is that @SpringBootTest is not just a shortcut for dependency injection; it’s a lightweight application lifecycle manager for your tests. It brings up the necessary infrastructure (like web servers, data sources, etc., depending on your application’s needs and test configuration) so your beans can interact as they would in production.

Here’s the surprising part: even when you’re not explicitly testing web endpoints, @SpringBootTest is still starting up a significant portion of your application’s context. If you have database configurations, message queue connections, or scheduled tasks defined, @SpringBootTest will attempt to initialize those as well, unless you specifically exclude them. This can make your tests slower than you might expect if you’re not mindful of what’s being loaded.

The webEnvironment attribute is your primary lever for controlling how the web layer is tested. WebEnvironment.MOCK starts a mock web server, which is faster but less realistic. WebEnvironment.RANDOM_PORT starts a real server on a random port, ideal for testing with MockMvc or even TestRestTemplate. WebEnvironment.DEFINED_PORT uses the port defined in your application properties, and WebEnvironment.NONE skips the web server entirely.

If you’re looking to speed up your integration tests, consider using @WebMvcTest for controller-specific tests or @DataJpaTest for repository tests. These are more specialized annotations that load only the necessary parts of your application context, leading to significantly faster test execution.

The next problem you’ll likely encounter is managing the application context lifecycle more granularly, especially when dealing with complex configurations or when you need to reset state between tests.