github/awesome-copilot / skills/spring-boot-4-migration
spring-boot-4-migration
VerifiedMigrate a Spring Boot 3.x application to Spring Boot 4.0 (Spring Framework 7, Jackson 3, modular starters, JSpecify). Use only for an explicit Boot 3.x to 4 migration, or to fix build or test failures caused by it, or to review one. Not for 3.x patch bumps or 4.0 to 4.1 upgrades; follow the target Boot version release notes and upgrade guide for those. Covers Maven and Gradle (Kotlin DSL, version catalogs).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.4 KB |
| references/01-prerequisites.md | markdown | 1.9 KB |
| references/02-starters-and-removed-features.md | markdown | 9.6 KB |
| references/03-jackson-3.md | markdown | 4.2 KB |
| references/04-core-framework.md | markdown | 4.2 KB |
| references/05-build-and-dependencies.md | markdown | 6.2 KB |
| references/06-configuration-properties.md | markdown | 3.0 KB |
| references/07-web-and-messaging.md | markdown | 7.3 KB |
| references/08-testing.md | markdown | 6.0 KB |
| references/09-actuator-and-observability.md | markdown | 2.7 KB |
| references/10-kotlin-and-java-build-config.md | markdown | 1.3 KB |
| references/11-checklist-pitfalls-resources.md | markdown | 5.9 KB |
references/08-testing.md
View on GitHubThis is the canonical testing migration reference. For Boot 4 test-writing patterns (Testcontainers 2.0, RestTestClient, JUnit 6), see the `spring-boot-testing` skill (`references/sb4-migration.md`).
## Testing Framework Changes
### Mockito Integration Removed
`MockitoTestExecutionListener` removed (deprecated in 3.4).
**Migration to MockitoExtension:**
```kotlin
// Old (Spring Boot 3.x)
import org.springframework.boot.test.context.SpringBootTest
import org.mockito.Mock
import org.mockito.Captor
@SpringBootTest
class MyServiceTest {
@Mock
private lateinit var repository: MyRepository
@Captor
private lateinit var captor: ArgumentCaptor<String>
}
// New (Spring Boot 4.0)
import org.springframework.boot.test.context.SpringBootTest
import org.mockito.Mock
import org.mockito.Captor
import org.mockito.junit.jupiter.MockitoExtension
import org.junit.jupiter.api.extension.ExtendWith
@SpringBootTest
@ExtendWith(MockitoExtension::class) // Explicit extension required
class MyServiceTest {
@Mock
private lateinit var repository: MyRepository
@Captor
private lateinit var captor: ArgumentCaptor<String>
}
```
### @MockBean and @SpyBean removed
Replace `org.springframework.boot.test.mock.mockito.MockBean`/`SpyBean` with `org.springframework.test.context.bean.override.mockito.MockitoBean`/`MockitoSpyBean` (Spring Framework 6.2+, so this can be done on Boot 3.5 first). Slice and `@AutoConfigure*` annotations moved to per-technology packages, for example `org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest`/`AutoConfigureMockMvc` and `org.springframework.boot.data.jpa.test.autoconfigure.DataJpaTest`; each needs its `spring-boot-starter-*-test` dependency.
### @SpringBootTest Changes
`@SpringBootTest` no longer provides **WebTestClient** or **TestRestTemplate** automatically. **MockMVC** already required `@AutoConfigureMockMvc` on Boot 3; only its package changed.
#### MockMVC Configuration
```kotlin
// Old (Spring Boot 3.x)
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@AutoConfigureMockMvc
class ControllerTest {
@Autowired
private lateinit var mockMvc: MockMvc
}
// New (Spring Boot 4.0)
import org.springframework.boot.webmvc.test.autoconfigure.AutoConfigureMockMvc
import org.springframework.boot.webmvc.test.autoconfigure.AutoConfigureMockMvc.HtmlUnit
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@AutoConfigureMockMvc // New package
class ControllerTest {
@Autowired
private lateinit var mockMvc: MockMvc
}
// HtmlUnit configuration moved to annotation attribute
@AutoConfigureMockMvc(
htmlUnit = HtmlUnit(webClient = false, webDriver = false)
)
```
#### WebTestClient Configuration
```kotlin
// Old (Spring Boot 3.x)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class WebFluxTest {
@Autowired
private lateinit var webTestClient: WebTestClient // Available automatically
}
// New (Spring Boot 4.0)
import org.springframework.boot.webtestclient.autoconfigure.AutoConfigureWebTestClient
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@AutoConfigureWebTestClient // Explicit annotation required
class WebFluxTest {
@Autowired
private lateinit var webTestClient: WebTestClient
}
```
#### TestRestTemplate → RestTestClient (Recommended)
**Spring Boot 4.0 introduces `RestTestClient`** as modern replacement for `TestRestTemplate`.
```kotlin
// Old approach (still works with annotation)
import org.springframework.boot.resttestclient.autoconfigure.AutoConfigureTestRestTemplate
import org.springframework.boot.resttestclient.TestRestTemplate
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@AutoConfigureTestRestTemplate // Required in 4.0
class RestApiTest {
@Autowired
private lateinit var testRestTemplate: TestRestTemplate
}
// New recommended approach
import org.springframework.boot.resttestclient.autoconfigure.AutoConfigureRestTestClient
import org.springframework.test.web.servlet.client.RestTestClient
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@AutoConfigureRestTestClient // New annotation
class RestApiTest {
@Autowired
private lateinit var restTestClient: RestTestClient
@Test
fun testEndpoint() {
restTestClient.get()
.uri("/api/users")
.exchange()
.expectStatus().isOk()
.expectBodyList(User::class.java)
}
}
```
**TestRestTemplate package change (if still using):**
**IMPORTANT:** If continuing to use `TestRestTemplate`, you must:
1. Add the `spring-boot-resttestclient` test dependency plus `spring-boot-starter-restclient` (verified: without it the context fails with `NoClassDefFoundError: org/springframework/boot/restclient/RestTemplateBuilder`)
2. **Update the package import** (class moved to new package)
**libs.versions.toml:**
```toml
[libraries]
spring-boot-resttestclient = { module = "org.springframework.boot:spring-boot-resttestclient", version.ref = "springBoot" }
spring-boot-starter-restclient = { module = "org.springframework.boot:spring-boot-starter-restclient", version.ref = "springBoot" }
```
**build.gradle.kts:**
```kotlin
dependencies {
testImplementation(libs.spring.boot.resttestclient)
testImplementation(libs.spring.boot.starter.restclient) // provides RestTemplateBuilder
}
```
**Update package import (required):**
```kotlin
// Old package import - will cause compilation failure
// import org.springframework.boot.test.web.client.TestRestTemplate
// New package import - required in Spring Boot 4.0
import org.springframework.boot.resttestclient.TestRestTemplate
```
### @PropertyMapping Annotation Relocation
```kotlin
// Old (Spring Boot 3.x)
import org.springframework.boot.test.autoconfigure.properties.PropertyMapping
import org.springframework.boot.test.autoconfigure.properties.Skip
// New (Spring Boot 4.0)
import org.springframework.boot.test.context.PropertyMapping
import org.springframework.boot.test.context.PropertyMapping.Skip
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |