Why Spring Boot 4 Breaks Your Tests and How to Fix It

What Happens After Upgrading to Spring Boot 4

Running mvn test after moving to Spring Boot 4 often yields compilation errors such as missing @WebMvcTest and MockMvc. The root cause is not a project‑specific bug but a fundamental change in Spring Boot’s architecture.

A 2 MiB JAR Gets Split Into Modules

When Spring Boot 1.0 was released, the spring-boot-autoconfigure JAR was only 182 KB and contained all auto‑configuration classes (Web, JDBC, Kafka, etc.). By Spring Boot 3.5 the same JAR grew to about 2 MiB, slowing startup, cluttering IDE auto‑completion, and introducing unexpected auto‑configuration side effects.

Spring Boot 4 addresses this by modularizing the monolithic JAR into dozens of smaller modules, each named spring-boot-<technology> with a corresponding starter spring-boot-starter-<technology>.

Impact on Testing and Starters

In the 3.x line, @WebMvcTest and other test annotations were bundled in the large autoconfigure JAR and became available automatically when spring-boot-starter-test was on the classpath. In 4.0 those test classes have been moved to dedicated test starters. If you do not declare the new starter, the classes are absent from the classpath, causing the compilation errors.

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webmvc-test</artifactId>
    <scope>test</scope>
</dependency>

Adding this dependency restores the missing test classes.

Other Breaking Changes

Web Starter Renamed

The former spring-boot-starter-web is now spring-boot-starter-webmvc, making the MVC nature explicit.

<!-- Spring Boot 3.x -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

<!-- Spring Boot 4.0 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webmvc</artifactId>
</dependency>

Test Starters Must Match Their Main Starters

spring-boot-starter-webmvc

→

spring-boot-starter-webmvc-test

spring-boot-starter-jdbc

→

spring-boot-starter-jdbc-test

spring-boot-starter-data-jpa

→ spring-boot-starter-data-jpa-test This tighter coupling prevents unnecessary test dependencies from being pulled in.

Auto‑Configuration Package Names Changed

If you directly reference auto‑configuration classes (e.g., WebMvcAutoConfiguration), their package moved from org.springframework.boot.autoconfigure.web.servlet to org.springframework.boot.webmvc.autoconfigure. Such references must be updated manually.

Migration Strategies

Option 1 – Classic Starter (Transitional)

For large projects that cannot be refactored immediately, add the “classic” starter which re‑bundles all modular auto‑configurations into a single JAR, mimicking the 3.x behavior.

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-classic</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test-classic</artifactId>
    <scope>test</scope>
</dependency>

This gets the project running quickly, but it is a technical debt that should be eliminated later.

Option 2 – Direct Modular Migration (Recommended)

Upgrade first to the latest Spring Boot 3.5.x and resolve all deprecation warnings.

Identify all Spring Boot features used in the project. Tools like OpenRewrite can automate the dependency changes:

mod config recipes jar install io.moderne.recipe:rewrite-spring:0.17.0

Then, replace each old starter with its new modular counterpart and add the matching test starter. Adjust any custom configuration class names to the new package structure.

Although this approach requires more effort, it results in a clean, future‑proof dependency graph.

Core Takeaways

Spring Boot 4 modularizes the former 2 MiB autoconfigure JAR, improving startup time and IDE experience.

Test‑related classes are now in dedicated test starters; update your pom.xml accordingly.

Starter names have changed (e.g., web → webmvc), and auto‑configuration package names have been updated.

Choose the Classic Starter for a quick fix or migrate directly to the modular setup for long‑term health.