/devkit.java.write-integration-tests

allowed-tools: Read, Write, Bash, Grep, Glob
argument-hint: "[class-path]"
description: Generates comprehensive integration tests for Spring Boot classes using Testcontainers (PostgreSQL, Redis, MongoDB) with `@ServiceConnection` pattern. Use when writing integration tests for service or repository classes.
model: inherit

Write Integration Tests for Spring Boot

Overview

Generates comprehensive integration tests for Spring Boot classes using Testcontainers (PostgreSQL, Redis, MongoDB) with `@ServiceConnection` pattern. Use when writing integration tests for service or repository classes.

You are tasked with generating a complete integration test for the Java class specified in `$1`.

Usage

When analyzing the target class, Claude will automatically reference these skills to:

• Determine the appropriate test strategy based on layer (Controller/Service/Repository)
• Select the correct Testcontainers based on dependencies
• Apply framework-specific testing patterns
• Generate comprehensive test scenarios covering all edge cases
• Use `@MockitoBean` for mocking dependencies (replaces deprecated `@MockBean`)

Arguments

| Argument | Description | |--------------|------------------------------------------| | `$ARGUMENTS` | Combined arguments passed to the command |

Execution Instructions

**Agent Selection**: To execute this task, use the following agent with fallback:

• Primary: `developer-kit-java:spring-boot-unit-testing-expert`
• If not available: Use `developer-kit-java:spring-boot-unit-testing-expert` or fallback to `general-purpose` agent with

`spring-boot-test-patterns` skill

Process

1. Analyze Target Class

• Read the class file from `$1`
• Identify the layer (Controller, Service, Repository)
• Detect dependencies (Database, Cache, Message Queue, etc.)
• Identify external integrations

2. Determine Required Testcontainers

Based on dependencies, include:

• **PostgreSQL**: For JPA repositories or database operations
• **Redis**: For caching or session management
• **MongoDB**: For NoSQL operations
• **RabbitMQ/Kafka**: For messaging operations
• **Additional containers**: Based on specific dependencies

3. Generate Integration Test

Follow these patterns from the spring-boot-test-patterns skill:

Test Structure

@SpringBootTest
@Testcontainers class

<ClassName> IntegrationTest {

    @Container
    @ServiceConnection
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>(
            DockerImageName.parse("postgres:16-alpine"))
            .withDatabaseName("testdb")
            .withUsername("test")
            .withPassword("test");

    @Container
    @ServiceConnection
    static GenericContainer<?> redis = new GenericContainer<>(
            DockerImageName.parse("redis:7-alpine"))
            .withExposedPorts(6379);

    @Autowired
    private <TargetClass > targetClass;

    @Test
    void shouldPerformIntegrationScenario () {
        // Test implementation
    }
}

Key Requirements

1. **Use `@ServiceConnection`** for Spring Boot 3.5+ automatic wiring 2. **Static containers** for reuse across test methods 3. **Minimal context loading** - only load what's needed 4. **Real dependencies** via Testcontainers 5. **Complete scenarios** - test full workflows 6. **Proper assertions** - use AssertJ for fluent assertions 7. **Use `@MockitoBean`** (not deprecated `@MockBean`) from `org.springframework.test.context.bean.override.mockito`

Container Selection Guidelines

• **`@Repository`/`@DataJpaTest`**: PostgreSQL/MySQL container
• **`@Service` with caching**: Redis container
• **`@RestController`**: MockMvc + required backend containers
• **Message consumers/producers**: RabbitMQ/Kafka container
• **MongoDB repositories**: MongoDB container

4. Dependencies Check

Verify and add required dependencies:

**Maven:**

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
<groupId>org.testcontainers</groupId>
<artifactId>junit-jupiter</artifactId>
<version>1.19.0</version>
// Use latest stable version
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.testcontainers</groupId>
<artifactId>postgresql</artifactId>
<version>1.19.0</version>
// Use latest stable version
<scope>test</scope>
</dependency>

**Gradle:**

testImplementation("org.springframework.boot:spring-boot-starter-test")
testImplementation("org.testcontainers:junit-jupiter:1.19.0")
testImplementation("org.testcontainers:postgresql:1.19.0")

5. Test Coverage

Generate tests covering:

• ✅ Happy path scenarios
• ✅ Edge cases and boundary conditions
• ✅ Error handling and validation
• ✅ Transaction rollback scenarios
• ✅ Concurrent access patterns (if applicable)

6. Performance Optimization

• Use static containers for JVM-level reuse
• Avoid `@DirtiesContext` unless absolutely necessary
• Group tests with similar configuration
• Target: < 500ms per integration test

Example Patterns

Controller Integration Test

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@Testcontainers
class UserControllerIntegrationTest {

    @Container
    @ServiceConnection
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>(
            DockerImageName.parse("postgres:16-alpine"));

    @Autowired
    private TestRestTemplate restTemplate;

    @Test
    void shouldCreateAndRetrieveUser() {
        UserRequest request = new UserRequest("john@example.com", "John Doe");

        ResponseEntity<UserResponse> createResponse = restTemplate
                .postForEntity("/api/users", request, UserResponse.class);

        assertThat(createResponse.getStatusCode()).isEqualTo(HttpStatus.CREATED);
        assertThat(createResponse.getBody()).isNotNull();

        Long userId = createResponse.getBody().id();

        Re