Spring Boot Testing: Fix Flaky CI/CD from Mockito Static Mock Leaks

We've all been there. You push a perfectly fine Spring Boot service, the CI pipeline runs 200 tests, and three fail randomly. You rerun — they pass. You merge, and now production monitoring shows a different issue. The flaky test problem is the bane of every Java team, and in 2024, one of the most common culprits is Mockito's static mocking leaks.

I've spent the last decade debugging these exact scenarios in payment-processing systems and real-time analytics pipelines. The root cause is almost always the same: developers use Mockito.mockStatic() without properly scoping its lifecycle. The static mock persists across test methods, corrupting the Mockito state machine. When you have 100+ tests in a suite, the probability of a collision skyrockets.

Spring Boot 3.x with JUnit 5 and Mockito 4.x is the current standard, but even this combination has pitfalls if you don't understand the internals. This article will walk you through a real production incident, show you the exact code that caused it, and provide a battle-tested fix. We'll also cover how to use @MockitoBean (introduced in Spring Boot 3.2) and MockitoSession to prevent leaks.

If you're maintaining a SaaS billing system or a high-throughput API, flaky tests are not just annoying — they erode trust. Let's fix that.

Understanding the Problem: Static Mock Lifecycle

Mockito's mockStatic() creates a mock for all static methods of a class within the current thread. The mock is active until you explicitly close the MockedStatic object. If you forget to close it, the mock persists beyond the test method's execution. In a typical Spring Boot test suite, multiple tests run in the same JVM process. When test A creates a static mock and test B runs next (without its own static mock), test B might invoke the mocked static method, triggering an UnnecessaryStubbingException because Mockito detects that the stubbing from test A was never used by test B.

This is especially problematic in CI/CD environments where tests are executed in parallel or in a fixed order that changes between runs. The symptom is always the same: a test fails locally but passes on the next run, or vice versa.

Consider a real-world example: a PaymentGateway class that uses Instant.now() to timestamp transactions. If you mock Instant.now() in one test and don't close it, another test that calls PaymentGateway.process() will see the mocked timestamp, potentially causing assertion failures.

import org.junit.jupiter.api.Test;
import org.mockito.MockedStatic;
import java.time.Instant;

class PaymentGatewayTest {

    @Test
    void testWithStaticMock() {
        MockedStatic<Instant> mockedInstant = Mockito.mockStatic(Instant.class);
        mockedInstant.when(Instant::now).thenReturn(Instant.parse("2024-01-01T00:00:00Z"));
        // BUG: forgot to close mockedInstant
        // Test logic that uses Instant.now()
    }

    @Test
    void testWithoutMock() {
        // This test may fail because Mockito still has the static mock active
        Instant now = Instant.now(); // Might return mocked value
    }
}

What the Official Docs Won't Tell You

The official Mockito documentation shows you how to use mockStatic() but glosses over the cleanup requirements. It says: 'Static mocks are automatically cleaned up after the test method if you use JUnit 5's MockitoExtension.' This is misleading. The MockitoExtension only handles @Mock and @InjectMocks annotations, not static mocks created programmatically.

Another undocumented behavior: when you use mockStatic() inside a Spring Boot test with @SpringBootTest, the application context might cache the mocked static method. This is because Spring's context caching reuses beans, and the static mock affects the entire JVM. I've seen teams waste days adding @DirtiesContext to every test, which kills performance.

The real fix is to use MockitoSession or @MockitoSettings to enforce strict stubbings and automatic cleanup. In Spring Boot 3.2+, you can use @MockitoBean which integrates with the Spring context and avoids static mocks entirely for beans that are injected via @Autowired.

import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.Test;
import org.mockito.MockedStatic;
import org.mockito.Mockito;

class SafePaymentGatewayTest {

    private MockedStatic<Instant> mockedInstant;

    @AfterEach
    void tearDown() {
        if (mockedInstant != null) {
            mockedInstant.close();
        }
    }

    @Test
    void testWithStaticMock() {
        mockedInstant = Mockito.mockStatic(Instant.class);
        mockedInstant.when(Instant::now).thenReturn(Instant.parse("2024-01-01T00:00:00Z"));
        // Test logic
    }

    @Test
    void testWithoutMock() {
        // This test is now safe
        Instant now = Instant.now();
    }
}

Root Cause Analysis: The Mockito State Machine

Mockito maintains a global state machine to track stubbings and invocations. When you call mockStatic(), it registers a MockedStatic instance in a thread-local map. The map is keyed by the class being mocked. If you create a second mockStatic() for the same class without closing the first, Mockito throws an exception. But if you close the first one in a different thread or after the test ends, the state becomes inconsistent.

The UnnecessaryStubbingException occurs when Mockito detects that a stubbing was never used by any invocation. This happens when the static mock from test A is still active when test B runs, and test B invokes the static method without using the stubbing (because test B doesn't know about it). Mockito sees the stubbing as 'unnecessary' and fails the test.

In Spring Boot, the problem is amplified because @SpringBootTest loads the full application context. If any bean uses a static method that you mocked elsewhere, the leak affects the entire context. I've debugged cases where a @Service class used UUID.randomUUID() and a static mock on UUID leaked from an unrelated test, causing all UUIDs to be the same value.

import org.junit.jupiter.api.Test;
import org.mockito.MockedStatic;
import java.util.UUID;

class UuidServiceTest {

    @Test
    void testUuidGeneration() {
        MockedStatic<UUID> mockedUuid = Mockito.mockStatic(UUID.class);
        mockedUuid.when(UUID::randomUUID).thenReturn(UUID.fromString("0000-00-00-00-000000"));
        // No close() called
    }

    @Test
    void testAnotherUuid() {
        // This test will see the mocked UUID
        UUID result = UUID.randomUUID(); // Returns 0000-00-00-00-000000
    }
}

The Fix: Using try-with-resources and MockitoSession

The most reliable fix is to use try-with-resources for every mockStatic() call. This ensures the MockedStatic is closed even if an exception occurs. For complex test suites, consider using MockitoSession which provides a session-level scope for mocks and automatically validates stubbings at the end.

Here's the pattern: create the MockedStatic inside a try block, perform your test logic, and let the try-with-resources close it automatically. If you need the mock across multiple test methods, use MockitoSession with @MockitoSettings to enforce strict stubbings.

In Spring Boot 3.2+, you can also use @MockitoBean which replaces a bean in the application context with a Mockito mock. This is cleaner because it avoids static mocks entirely for beans that are injected via @Autowired. However, for truly static methods (like Instant.now()), you still need mockStatic().

import org.junit.jupiter.api.Test;
import org.mockito.MockedStatic;
import org.mockito.Mockito;
import java.time.Instant;

class SafePaymentGatewayTest {

    @Test
    void testWithStaticMock() {
        try (MockedStatic<Instant> mockedInstant = Mockito.mockStatic(Instant.class)) {
            mockedInstant.when(Instant::now).thenReturn(Instant.parse("2024-01-01T00:00:00Z"));
            // Test logic here
            Instant result = Instant.now();
            assertEquals("2024-01-01T00:00:00Z", result.toString());
        } // Auto-closed here
    }

    @Test
    void testWithoutMock() {
        Instant now = Instant.now(); // Real value
    }
}

Spring Boot 3.2+: @MockitoBean and @MockitoSpyBean

Spring Boot 3.2 introduced @MockitoBean and @MockitoSpyBean as first-class citizens for testing. These annotations replace a bean in the application context with a Mockito mock or spy for the duration of the test method. The key advantage is that the mock is automatically cleaned up after the test method, and it doesn't require static mocking.

This is a game-changer for Spring Boot testing. Instead of mocking static methods to control bean behavior, you can now mock the bean directly. For example, if you have a PaymentService bean that calls Instant.now(), you can mock PaymentService itself rather than mocking Instant.

However, @MockitoBean doesn't work for static methods on utility classes. For those, you still need mockStatic() with proper cleanup. But for most Spring Boot applications, @MockitoBean eliminates the need for static mocks entirely.

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.bean.override.mockito.MockitoBean;

@SpringBootTest
class PaymentServiceTest {

    @Autowired
    private PaymentService paymentService;

    @MockitoBean
    private ExternalRateService rateService;

    @Test
    void testPayment() {
        Mockito.when(rateService.getRate("USD")).thenReturn(1.2);
        double result = paymentService.convert(100, "USD");
        assertEquals(120.0, result);
    }
}

Advanced: Using MockitoSession for Suite-Level Control

When you have a suite of tests that share a static mock, use MockitoSession. A MockitoSession allows you to define a set of mocks that are valid for the duration of the session. At the end of the session, Mockito validates that all stubbings were used and cleans up.

This is useful for integration tests where multiple test methods need the same static mock. For example, if you're testing a batch processing system that runs multiple steps, you might want to mock System.currentTimeMillis() for the entire suite.

To use MockitoSession, create it in a @BeforeAll method and close it in @AfterAll. You can also set strict stubbings via @MockitoSettings to fail on unused stubbings.

import org.junit.jupiter.api.AfterAll;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.Test;
import org.mockito.Mockito;
import org.mockito.MockitoSession;

class BatchProcessingTest {

    private static MockitoSession session;
    private static MockedStatic<System> mockedSystem;

    @BeforeAll
    static void setup() {
        session = Mockito.mockitoSession()
                .strictness(Strictness.STRICT_STUBS)
                .startMocking();
        mockedSystem = Mockito.mockStatic(System.class);
        mockedSystem.when(() -> System.currentTimeMillis()).thenReturn(1000L);
    }

    @Test
    void testStepOne() {
        assertEquals(1000L, System.currentTimeMillis());
    }

    @Test
    void testStepTwo() {
        assertEquals(1000L, System.currentTimeMillis());
    }

    @AfterAll
    static void teardown() {
        mockedSystem.close();
        session.finishMocking();
    }
}

CI/CD Configuration: JVM Args and Parallel Execution

Flaky tests often surface in CI/CD because of parallel execution. JUnit 5's parallel test execution can cause thread-local static mocks to collide. To mitigate this, configure JUnit 5 to run tests in isolation and add JVM args to force Mockito cleanup.

Add the following JVM arg to your CI/CD pipeline: -Dmockito.mockito-static-cleanup=true. This tells Mockito to aggressively clean up static mocks after each test method. Note that this is a Mockito internal flag and may change in future versions.

For JUnit 5 parallel execution, set junit.jupiter.execution.parallel.enabled=false in your junit-platform.properties file for the test profile. If you must run tests in parallel, use @Execution(CONCURRENT) carefully and ensure each test class has its own Mockito state.

junit.jupiter.execution.parallel.enabled=false
junit.jupiter.execution.parallel.config.strategy=dynamic
junit.jupiter.execution.parallel.config.dynamic.factor=0.5

Monitoring and Debugging: Detecting Leaks in Production

Static mock leaks can also affect production if you have test code that runs in production (bad practice, but it happens). To detect leaks, add a JUnit extension that logs Mockito state after each test. You can also use a custom TestExecutionListener to verify that no static mocks remain.

For production monitoring, add a metric that tracks the number of active MockedStatic instances. You can do this by wrapping Mockito.mockStatic() in a custom utility class that increments a counter on creation and decrements on close. If the counter doesn't return to zero after a test suite, you have a leak.

In extreme cases, use a thread dump to see if any threads hold references to MockedStatic objects. This is a last resort but can identify hard-to-find leaks.

import org.junit.jupiter.api.extension.AfterEachCallback;
import org.junit.jupiter.api.extension.ExtensionContext;
import org.mockito.Mockito;

public class LeakDetectorExtension implements AfterEachCallback {

    @Override
    public void afterEach(ExtensionContext context) throws Exception {
        // Check if any inline mocks remain
        Mockito.framework().clearInlineMocks();
        // Log a warning if any static mocks were active
        System.out.println("Mockito state cleaned for: " + context.getDisplayName());
    }
}