giuseppe-trisciuoglio/developer-kit

spring-boot-test-patterns

Provides comprehensive testing patterns for Spring Boot applications covering unit, integration, slice, and container-based testing with JUnit 5, Mockito, Testcontainers, and performance optimization.

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill spring-boot-test-patterns

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

Spring Boot Testing Patterns

Overview

Comprehensive guidance for writing robust test suites for Spring Boot applications using JUnit 5, Mockito, Testcontainers, and performance-optimized slice testing patterns.

When to Use

  • Writing unit tests for services or repositories with mocked dependencies
  • Implementing integration tests with real databases via Testcontainers
  • Testing REST APIs with @WebMvcTest or MockMvc
  • Configuring @ServiceConnection for container management in Spring Boot 3.5+

Quick Reference

Test TypeAnnotationTarget TimeUse Case
Unit Tests@ExtendWith(MockitoExtension.class)< 50msBusiness logic without Spring context
Repository Tests@DataJpaTest< 100msDatabase operations with minimal context
Controller Tests@WebMvcTest / @WebFluxTest< 100msREST API layer testing
Integration Tests@SpringBootTest< 500msFull application context with containers
Testcontainers@ServiceConnection / @TestcontainersVariesReal database/message broker containers

Core Concepts

Test Architecture Philosophy

  1. Unit Tests — Fast, isolated tests without Spring context (< 50ms)
  2. Slice Tests — Minimal Spring context for specific layers (< 100ms)
  3. Integration Tests — Full Spring context with real dependencies (< 500ms)

Key Annotations

Spring Boot Test:

  • @SpringBootTest — Full application context (use sparingly)
  • @DataJpaTest — JPA components only (repositories, entities)
  • @WebMvcTest — MVC layer only (controllers, @ControllerAdvice)
  • @WebFluxTest — WebFlux layer only (reactive controllers)
  • @JsonTest — JSON serialization components only

Testcontainers:

  • @ServiceConnection — Wire Testcontainer to Spring Boot (3.5+)
  • @DynamicPropertySource — Register dynamic properties at runtime
  • @Testcontainers — Enable Testcontainers lifecycle management

Instructions

1. Unit Testing Pattern

Test business logic with mocked dependencies:

java
@ExtendWith(MockitoExtension.class)
class UserServiceTest {
    @Mock
    private UserRepository userRepository;

    @InjectMocks
    private UserService userService;

    @Test
    void shouldFindUserByIdWhenExists() {
        when(userRepository.findById(1L)).thenReturn(Optional.of(user));
        Optional<User> result = userService.findById(1L);
        assertThat(result).isPresent();
        verify(userRepository).findById(1L);
    }
}

See unit-testing.md for advanced patterns.

2. Slice Testing Pattern

Use focused test slices for specific layers:

java
@DataJpaTest
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
@TestContainerConfig
class UserRepositoryIntegrationTest {
    @Autowired
    private UserRepository userRepository;

    @Test
    void shouldSaveAndRetrieveUser() {
        User saved = userRepository.save(user);
        assertThat(userRepository.findByEmail("test@example.com")).isPresent();
    }
}

See slice-testing.md for all slice patterns.

3. REST API Testing Pattern

Test controllers with MockMvc:

java
@WebMvcTest(UserController.class)
class UserControllerTest {
    @Autowired
    private MockMvc mockMvc;

    @MockBean
    private UserService userService;

    @Test
    void shouldGetUserById() throws Exception {
        mockMvc.perform(get("/api/users/1"))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.email").value("test@example.com"));
    }
}

4. Testcontainers with @ServiceConnection

Configure containers with Spring Boot 3.5+:

java
@TestConfiguration
public class TestContainerConfig {
    @Bean
    @ServiceConnection
    public PostgreSQLContainer<?> postgresContainer() {
        return new PostgreSQLContainer<>("postgres:16-alpine");
    }
}

Apply with @Import(TestContainerConfig.class) on test classes. See testcontainers-setup.md for detailed configuration.

5. Add Dependencies

Include required testing dependencies:

xml
<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>
    <scope>test</scope>
</dependency>

See test-dependencies.md for complete dependency list.

6. Configure CI/CD

Set up GitHub Actions for automated testing:

yaml
name: Tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    services:
      docker:
        image: docker:20-dind
    steps:
    - uses: actions/checkout@v4
    - name: Set up JDK 17
      uses: actions/setup-java@v4
      with:
        distribution: 'temurin'
    - name: Run tests
      run: ./mvnw test

See ci-cd-configuration.md for full CI/CD patterns.

Validation Checkpoints

After implementing tests, verify:

  • Container running: docker ps (look for testcontainer images)
  • Context loaded: check startup logs for "Started Application in X.XX seconds"
  • Test isolation: run tests individually and confirm no cross-contamination

Examples

Full Integration Test with @ServiceConnection

java
@SpringBootTest
@Import(TestContainerConfig.class)
class OrderServiceIntegrationTest {

    @Autowired
    private OrderService orderService;

    @Autowired
    private UserRepository userRepository;

    @Test
    void shouldCreateOrderForExistingUser() {
        User user = userRepository.save(User.builder()
            .email("order-test@example.com")
            .build());

        Order order = orderService.createOrder(user.getId(), List.of(
            new OrderItem("SKU-001", 2)
        ));

        assertThat(order.getId()).isNotNull();
        assertThat(order.getStatus()).isEqualTo(OrderStatus.PENDING);
    }
}

@DataJpaTest with Real Database

java
@DataJpaTest
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
@TestContainerConfig
class UserRepositoryTest {

    @Autowired
    private UserRepository userRepository;

    @Test
    void shouldFindByEmail() {
        userRepository.save(User.builder()
            .email("jpa-test@example.com")
            .build());
        assertThat(userRepository.findByEmail("jpa-test@example.com"))
            .isPresent();
    }
}

See workflow-patterns.md for complete end-to-end examples.

Best Practices

  • Use the right test type: @DataJpaTest for repositories, @WebMvcTest for controllers, @SpringBootTest only for full integration
  • Prefer `@ServiceConnection` on Spring Boot 3.5+ for cleaner container management over @DynamicPropertySource
  • Keep tests deterministic: Initialize all test data explicitly in @BeforeEach
  • Organize by layer: Group tests by layer to maximize context caching
  • Reuse Testcontainers at JVM level (withReuse(true) + TESTCONTAINERS_REUSE_ENABLE=true)
  • Avoid `@DirtiesContext`: Forces context rebuild, significantly hurts performance
  • Mock external services, use real databases only when necessary
  • Performance targets: Unit < 50ms, Slice < 100ms, Integration < 500ms

Constraints and Warnings

  • Never use @DirtiesContext unless absolutely necessary (forces context rebuild)
  • Avoid mixing @MockBean with different configurations (creates separate contexts)
  • Testcontainers require Docker; ensure CI/CD pipelines have Docker support
  • Do not rely on test execution order; each test must be independent
  • Be cautious with @TestPropertySource (creates separate contexts)
  • Do not use @SpringBootTest for unit tests; use plain Mockito instead
  • Context caching can be invalidated by different @MockBean configurations
  • Avoid static mutable state in tests (causes flaky tests)

References

  • [test-dependencies.md](references/test-dependencies.md) — Maven/Gradle test dependencies
  • [unit-testing.md](references/unit-testing.md) — Unit testing with Mockito patterns
  • [slice-testing.md](references/slice-testing.md) — Repository, controller, and JSON slice tests
  • [testcontainers-setup.md](references/testcontainers-setup.md) — Testcontainers configuration patterns
  • [ci-cd-configuration.md](references/ci-cd-configuration.md) — GitHub Actions, GitLab CI, Docker Compose
  • [api-reference.md](references/api-reference.md) — Complete test annotations and utilities
  • [best-practices.md](references/best-practices.md) — Testing patterns and optimization
  • [workflow-patterns.md](references/workflow-patterns.md) — Complete integration test examples

Related by task

from this repository

More skills

All skills
giuseppe-trisciuoglio
Community

drizzle-orm-patterns

Provides comprehensive Drizzle ORM patterns for schema definition, CRUD operations, relations, queries, transactions, and migrations. Proactively use for any Drizzle ORM development including defining database schemas, writing type-safe queries, implementing relations, managing transactions, and setting up migrations with Drizzle Kit. Supports PostgreSQL, MySQL, SQLite, MSSQL, and CockroachDB.

1h installs
3
GitHub stars
372
Updated
Sep 10
giuseppe-trisciuoglio
Community

tailwind-css-patterns

Provides comprehensive Tailwind CSS utility-first styling patterns including responsive design, layout utilities, flexbox, grid, spacing, typography, colors, and modern CSS best practices. Use when styling React/Vue/Svelte components, building responsive layouts, implementing design systems, or optimizing CSS workflow.

1h installs
1
GitHub stars
372
Updated
Sep 10
giuseppe-trisciuoglio
Community

dynamodb-toolbox-patterns

Provides TypeScript patterns for DynamoDB-Toolbox v2 including schema/table/entity modeling, .build() command workflow, query/scan access patterns, batch and transaction operations, and single-table design with computed keys. Use when implementing type-safe DynamoDB access layers with DynamoDB-Toolbox v2 in TypeScript services or serverless applications.

1h installs
1
GitHub stars
371
Updated
Sep 10
giuseppe-trisciuoglio
Community

spring-boot-dependency-injection

Provides dependency injection patterns for Spring Boot projects, including constructor-first design, optional collaborator handling, bean selection, and wiring validation. Use when creating services and configurations, replacing field injection, or troubleshooting ambiguous or fragile Spring wiring.

1h installs
1
GitHub stars
371
Updated
Sep 10