TDD with Spring Boot 4 and Testcontainers: The Zero-Mocking Approach

Test-Driven Development (TDD) transformed software engineering by prioritizing automated verification before writing production code. In enterprise Java systems, however, conventional TDD often degenerates into an exercise in excessive mocking. Teams write elaborate test suites using Mockito to mock repositories, service layers, and data sources. While these unit tests execute in milliseconds, they frequently test internal implementation details rather than observable business behavior. Worse, they deliver a dangerous illusion of security: tests pass with flying colors, but the application crashes upon deployment due to incompatible SQL dialects, broken transaction boundaries, or violated foreign key constraints.

As we build modern cloud-native systems with Spring Boot 4 and Java 25, the industry standard has shifted decisively toward the zero-mocking approach. By coupling Test-Driven Development with Testcontainers and Spring Boot 4’s native @ServiceConnection SPI, developers can execute the complete Red-Green-Refactor cycle against real, production-identical infrastructure (such as PostgreSQL 16, Kafka, or Redis) running in lightweight ephemeral containers. This guide demonstrates how to eliminate brittle mocks, design change-resilient test suites, and practice true zero-mocking TDD in enterprise Spring Boot applications.

Table of Contents

• The Brittle Mock Trap: Why Excessive Mocking Fails in Modern Java
• Comparative Analysis: Java Testing Strategies Matrix
• The Zero-Mocking Philosophy: Testing Outcomes, Not Implementations
• Red-Green-Refactor with Testcontainers: A Practical Walkthrough
• Dynamic Port Isolation: Concurrency and Multi-Runner Architecture
• Full Slice Architecture: Where Mocks Belong (and Where They Do Not)
• Spring Boot 4 @ServiceConnection Deep Dive
• Enterprise Use Cases: Real-World Zero-Mocking Scenarios
• CI/CD Pipeline Automation: Fast GitHub Actions Execution
• Production Readiness and Enterprise Guardrails
• Common Pitfalls and How to Fix Them
• Frequently Asked Questions (FAQ)
• Conclusion and Next Steps
• References and Companion Code

The Brittle Mock Trap: Why Excessive Mocking Fails in Modern Java

Mocking frameworks like Mockito gained prominence when running real databases was prohibitively expensive. Spinning up an enterprise Oracle or DB2 instance required dedicated server hardware, complex network provisioning, and significant boot time. To keep the developer feedback loop short, engineers replaced external dependencies with mock interfaces.

While mock-based unit tests execute rapidly, they introduce severe structural liabilities into enterprise codebases:

• False Positive Confidence: A mock returns whatever dummy data you tell it to return. If a JPA repository method executes an invalid SQL query or references a non-existent column, Mockito stubs bypass the persistence provider completely. The test passes locally, but the application throws a DataIntegrityViolationException in production.
• Refactoring Fragility: When tests assert internal interactions (such as verify(paymentRepo, times(1)).save(any())), the test binds itself directly to the class structure. If you refactor the service to use a bulk batch update or leverage a Spring Data JPA derived query, the test breaks even though the external API contract remains completely intact. This causes developers to fear refactoring.
• Maintenance Overhead and Boilerplate: Teams spend more cognitive effort constructing intricate when(...).thenReturn(...) mock hierarchies and argument captors than authoring business assertions. Over time, tests become difficult to read, understand, and maintain.
• Invisible Concurrency and Transactional Bugs: Mocks cannot test database locking semantics, deadlock handling, or rollback behavior. Bugs relating to optimistic and pessimistic locking remain completely invisible until real traffic hits the database.

Comparative Analysis: Java Testing Strategies Matrix

Understanding how zero-mocking compares to other popular testing methodologies is essential for engineering leaders designing enterprise quality standards:

The Zero-Mocking Philosophy: Testing Outcomes, Not Implementations

The zero-mocking philosophy is grounded in black-box verification. Instead of interrogating how a service computes a result internally, the test treats the Spring context and persistence layer as an integrated engine. You trigger an action at the external boundary—typically an HTTP request or event message—and verify the outcome at the boundaries:

• Did the HTTP response return the expected HTTP status code and JSON payload?
• Were the records persisted accurately to the PostgreSQL table with correct foreign keys and timestamps?
• Did the database schema triggers and unique constraints enforce data integrity?

When tests verify observable outcomes rather than internal method calls, engineers can refactor code aggressively. You can change internal algorithms, split monolithic services into domain classes, or update ORM configurations without breaking a single integration test. This refactoring safety is the cornerstone of agile software development.

Red-Green-Refactor with Testcontainers: A Practical Walkthrough

Let us walk through the classic TDD workflow (Red, Green, Refactor) using a real enterprise PaymentService. In this scenario, we must build a payment processing endpoint that validates transactions, enforces business rules, and records successful payments into PostgreSQL.

Step 1: Red (Write the Failing Integration Test)

We begin by creating an end-to-end integration test before writing any application code. We use MockMvc to dispatch HTTP requests through the full Spring WebMvc stack, and we declare a real PostgreSQL 16 container using Testcontainers and @ServiceConnection:

package com.webcodein.testing.tdd;

import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
import org.springframework.boot.webmvc.test.autoconfigure.AutoConfigureMockMvc;
import org.springframework.http.MediaType;
import org.springframework.test.web.servlet.MockMvc;
import org.testcontainers.containers.PostgreSQLContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;

import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;

@SpringBootTest
@AutoConfigureMockMvc
@Testcontainers
class PaymentIntegrationTest {

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

    @Autowired
    private MockMvc mockMvc;

    @Test
    @DisplayName("Should successfully process valid payment and return HTTP 200")
    void shouldProcessValidPayment() throws Exception {
        String payload = """
                {
                  "reference": "TXN-1001",
                  "amount": 150.00
                }
                """;

        mockMvc.perform(post("/api/payments")
                .contentType(MediaType.APPLICATION_JSON)
                .content(payload))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.id").exists())
                .andExpect(jsonPath("$.status").value("PROCESSED"));
    }

    @Test
    @DisplayName("Should reject payment with negative amount and return HTTP 400")
    void shouldRejectNegativeAmount() throws Exception {
        String payload = """
                {
                  "reference": "TXN-1002",
                  "amount": -50.00
                }
                """;

        mockMvc.perform(post("/api/payments")
                .contentType(MediaType.APPLICATION_JSON)
                .content(payload))
                .andExpect(status().isBadRequest())
                .andExpect(jsonPath("$.error").value("Amount must be greater than zero"));
    }
}

When executed, this test fails immediately with a compilation error or HTTP 404 Not Found (Red phase) because neither the endpoint nor the underlying domain entities exist yet.

Step 2: Green (Implement Minimum Necessary Code)

To satisfy the test, we implement the minimum production code required. We create the JPA entity, the Spring Data repository, the domain service, and the REST controller:

package com.webcodein.testing.tdd.domain;

import jakarta.persistence.*;
import java.math.BigDecimal;
import java.time.Instant;

@Entity
@Table(name = "payments")
public class Payment {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, unique = true)
    private String reference;

    @Column(nullable = false)
    private BigDecimal amount;

    @Column(nullable = false)
    private String status;

    @Column(nullable = false, updatable = false)
    private Instant createdAt = Instant.now();

    public Payment() {}

    public Payment(String reference, BigDecimal amount, String status) {
        this.reference = reference;
        this.amount = amount;
        this.status = status;
    }

    public Long getId() { return id; }
    public String getReference() { return reference; }
    public BigDecimal getAmount() { return amount; }
    public String getStatus() { return status; }
}

Next, we build the business service with validation logic:

package com.webcodein.testing.tdd.domain;

import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import java.math.BigDecimal;

@Service
public class PaymentService {

    private final PaymentRepository paymentRepository;

    public PaymentService(PaymentRepository paymentRepository) {
        this.paymentRepository = paymentRepository;
    }

    @Transactional
    public Payment processPayment(String reference, BigDecimal amount) {
        if (amount == null || amount.compareTo(BigDecimal.ZERO) <= 0) {
            throw new IllegalArgumentException("Amount must be greater than zero");
        }
        Payment payment = new Payment(reference, amount, "PROCESSED");
        return paymentRepository.save(payment);
    }
}

Finally, we expose the REST endpoint via PaymentController:

package com.webcodein.testing.tdd.domain;

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import java.math.BigDecimal;
import java.util.Map;

@RestController
@RequestMapping("/api/payments")
public class PaymentController {

    private final PaymentService paymentService;

    public PaymentController(PaymentService paymentService) {
        this.paymentService = paymentService;
    }

    @PostMapping
    public ResponseEntity<?> createPayment(@RequestBody PaymentRequest request) {
        try {
            Payment payment = paymentService.processPayment(request.reference(), request.amount());
            return ResponseEntity.ok(Map.of("id", payment.getId(), "status", payment.getStatus()));
        } catch (IllegalArgumentException | IllegalStateException ex) {
            return ResponseEntity.badRequest().body(Map.of("error", ex.getMessage()));
        }
    }

    public record PaymentRequest(String reference, BigDecimal amount) {}
}

When we re-run PaymentIntegrationTest, Spring Boot boots up, Testcontainers starts PostgreSQL in Docker, Hibernate auto-generates the database schema, and both test assertions execute against real database transactions. The test turns Green.

Step 3: Refactor (Optimize and Cleanse Safely)

With verified tests backing our code, we can refactor with complete assurance. If we replace manual try-catch blocks with a central @RestControllerAdvice, optimize Hibernate query fetching, or migrate database schemas using Zero-Downtime Flyway Migrations, the test suite guarantees that our external behavior remains undamaged.

Dynamic Port Isolation: Concurrency and Multi-Runner Architecture

A classic failure mode in legacy containerized testing is the “port collision” defect. When developers run Docker Compose with fixed host port mappings (such as 5432:5432), only one test runner can execute at a time. If two developers run tests simultaneously on a shared CI server, or if Maven executes parallel test forks, the second runner crashes with a BindException: Address already in use.

Testcontainers eliminates this limitation through dynamic port virtualization. The Docker container continues to listen on internal port 5432, but the Docker daemon assigns a randomized, ephemeral high-range port on the host (e.g., 32847 or 49152). Parallel test threads communicate exclusively over their unique mapped ports, providing complete isolation between test classes and concurrent CI jobs.

Full Slice Architecture: Where Mocks Belong (and Where They Do Not)

Adopting zero-mocking does not mean mocks are completely forbidden. Rather, it establishes clear architectural boundaries separating internal domain systems from external third-party infrastructure.

The Architectural Rule of Thumb

• Inside Your System Boundary (Zero Mocks): Controllers, services, validators, repositories, ORM entities, SQL queries, cache serialization, and database transactions must execute against real implementations and real containers. Never mock a repository or a service bean.
• At the External Network Edge (Mock with Precision): Third-party SaaS APIs (such as Stripe payment gateways, Twilio SMS, or SendGrid email APIs) that cannot run in local Docker containers should be simulated using WireMock. WireMock runs a real HTTP server in-process, allowing you to verify actual HTTP client requests, JSON payloads, and response header parsing without executing brittle Mockito stubs on Java methods.

Spring Boot 4 @ServiceConnection Deep Dive

Prior to Spring Boot 3.1 and 4.0, integrating Testcontainers into Spring test suites required verbose dynamic property registration. Developers had to manually intercept container startup and register mapped JDBC URLs using @DynamicPropertySource:

// Legacy Verbose Approach
@DynamicPropertySource
static void configureProperties(DynamicPropertyRegistry registry) {
    registry.add("spring.datasource.url", postgres::getJdbcUrl);
    registry.add("spring.datasource.username", postgres::getUsername);
    registry.add("spring.datasource.password", postgres::getPassword);
}

In Spring Boot 4, the @ServiceConnection annotation leverages the Service Connection SPI. When the test context initializes, Spring detects the PostgreSQLContainer, extracts the dynamically allocated host, port, database name, and credentials, and registers a JdbcConnectionDetails bean. Spring Boot’s auto-configuration binds these parameters directly into the HikariDataSource pool without manual configuration. Learn more about local container orchestration in our companion guide on Modern Local Development with Testcontainers and Docker Compose.

Enterprise Use Cases: Real-World Zero-Mocking Scenarios

Use Case 1: Idempotent Payment Processing with Optimistic Locking

A financial application must prevent duplicate payment submissions. Using Testcontainers, the test fires concurrent HTTP requests with identical reference IDs against a real PostgreSQL container. The test asserts that the database unique constraint throws a DataIntegrityViolationException and the secondary thread receives HTTP 409 Conflict, proving transactional isolation works under concurrency.

Use Case 2: Multi-Tenant Data Isolation with PostgreSQL RLS

In multi-tenant SaaS applications, PostgreSQL Row-Level Security (RLS) ensures tenants cannot read each other’s data. Because H2 does not support native PostgreSQL RLS policies, mock-based tests cannot verify tenant isolation. With Testcontainers, tests execute genuine SQL statements under distinct database roles, verifying that unauthorized tenant access is blocked at the database engine level.

Use Case 3: Event-Driven Outbox Persistence with ACID Guarantees

An order processing microservice writes an order record and an outbox event within a single atomic database transaction. Zero-mocking tests confirm that if the order insertion fails, the outbox event table rolls back completely. Testing this transaction boundary with mocks would require complex mocking of the Spring PlatformTransactionManager, which rarely reflects real database commit and rollback semantics.

CI/CD Pipeline Automation: Fast GitHub Actions Execution

A common critique of containerized testing is pipeline execution time. However, by leveraging Docker layer caching and pre-pulling container images, Testcontainers runs remarkably fast in cloud CI runners:

name: CI Build & Test

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 15

    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Set up JDK 25
        uses: actions/setup-java@v4
        with:
          java-version: '25'
          distribution: 'temurin'
          cache: maven

      - name: Pre-pull PostgreSQL Testcontainer Image
        run: docker pull postgres:16-alpine

      - name: Run Maven Tests
        run: mvn -B -ntp clean test

Pre-pulling postgres:16-alpine ensures the image is downloaded before the Maven test suite begins, preventing network latency from causing test timeout failures.

Production Readiness and Enterprise Guardrails

To successfully standardize zero-mocking TDD across an enterprise organization, adhere to these production guardrails:

• Declare Containers as Static: Always declare container fields as static when using @Container. Instance-level containers cause JUnit to spin up a fresh Docker container for every single test method, multiplying test execution times unnecessarily.
• Keep the Ryuk Watchdog Enabled: The Ryuk container (testcontainers/ryuk) ensures orphaned containers are purged if the JVM terminates unexpectedly. Never disable Ryuk in development workstations.
• Clean State Between Tests: When sharing a single container across tests, ensure test methods clean up state using Spring’s @Transactional rollback or explicit repository truncation in @AfterEach hooks.
• Avoid Modifying Spring Test Context: Annotations like @DirtiesContext or differing @MockBean definitions invalidate Spring’s cached application context, triggering costly container reboots. Keep test configurations uniform across the test suite.

Common Pitfalls and How to Fix Them

Pitfall 1: State Leakage Between Sequential Tests

Symptom: Tests pass when executed individually in the IDE, but fail when run together during mvn test.

Root Cause: A previous test inserted rows into the database that altered the row count or violated unique constraints for subsequent tests.

Fix: Annotate test classes or methods with @Transactional so Spring automatically rolls back database changes upon test completion, or execute repository.deleteAll() in a teardown method.

Pitfall 2: Hardcoding Host Ports in Test Definitions

Symptom: Build logs throw BindException: Address already in use during CI builds.

Root Cause: The container was configured with .withFixedExposedPort(5432, 5432).

Fix: Never use fixed ports in automated tests. Let Testcontainers assign randomized ephemeral ports and use @ServiceConnection to dynamically inject connection strings.

Pitfall 3: Mock Creep Infiltrating Service Slices

Symptom: Tests pass, but production code fails with null pointer exceptions or ORM mapping bugs.

Root Cause: Developers mocked domain services or repositories out of habit, bypassing real validation logic.

Fix: Establish strict team standards: no Mockito annotations on internal Spring beans. Reserve mocks strictly for external HTTP/REST boundaries using WireMock.

Frequently Asked Questions (FAQ)

Is Testcontainers too slow for fast TDD iterations?

No. When using lightweight images such as postgres:16-alpine, initial container bootstrap takes only 1.5 to 2.5 seconds on modern SSDs. Because the static container remains warm throughout the entire test class or test suite, subsequent test executions run in 20 to 50 milliseconds, providing rapid TDD feedback.

Why not use an in-memory H2 database instead of Docker?

H2 is an entirely different database engine from PostgreSQL, MySQL, or Oracle. It lacks native support for JSONB index operators, advanced window functions, SELECT ... FOR UPDATE SKIP LOCKED, and custom stored procedures. Tests passing on H2 frequently fail in production.

How does @ServiceConnection simplify Spring Boot testing?

Spring Boot 4’s @ServiceConnection inspects the running Testcontainer, extracts its dynamic port and credentials, and registers a ConnectionDetails bean into the Spring context. This eliminates 10+ lines of verbose @DynamicPropertySource boilerplate code.

Does zero-mocking mean we should never use Mockito?

No. Mockito is still appropriate for isolated domain unit tests that verify purely algorithmic business logic with zero external dependencies. However, within Spring integration slices, internal beans should never be mocked.

How should we test third-party external APIs like payment gateways?

Use WireMock. WireMock launches a lightweight in-process HTTP mock server that simulates third-party REST endpoints. This tests your actual HTTP client code, JSON serialization, and error recovery without invoking external production services.

Conclusion and Next Steps

Excessive mocking creates fragile, implementation-dependent test suites that give false confidence while actively hindering refactoring. By adopting the zero-mocking approach with Spring Boot 4 and Testcontainers, backend engineering teams achieve true production parity from day one.

TDD with real containers ensures that SQL queries, transaction boundaries, constraint triggers, and HTTP contracts are continuously verified. You gain the freedom to refactor fearlessly, knowing that your tests validate genuine system outcomes.

For more architectural guides on modern cloud-native Java development, explore our tutorials on Modern Local Development with Testcontainers & Docker Compose, Optimistic vs. Pessimistic Locking, and Chaos Engineering with Toxiproxy.

References and Companion Code

• Companion Workshop Code on GitHub (Spring Boot 4, Testcontainers, PostgreSQL 16)
• Official Testcontainers Documentation & Ecosystem Guides
• Spring Boot 4 Reference Guide
• WireMock Documentation for External HTTP APIs
• Testcontainers PostgreSQL Module Guide