Mockito and JUnit 6 are the most powerful duo in the Java testing toolkit. Mockito handles mock creation, stubbing, and verification while JUnit 6 orchestrates the test lifecycle. Together they let you test any unit in complete isolation, regardless of how many dependencies it has. This guide covers every Mockito feature you need — from basic mocking to advanced argument captors, spies, and common pitfalls to avoid.

Setup: Mockito with JUnit 6

<!-- Mockito Core + JUnit 5/6 integration -->
<dependency>
    <groupId>org.mockito</groupId>
    <artifactId>mockito-junit-jupiter</artifactId>
    <version>5.12.0</version>
    <scope>test</scope>
</dependency>
<!-- Note: spring-boot-starter-test already includes mockito-junit-jupiter -->

Activate Mockito’s annotation processing by adding @ExtendWith(MockitoExtension.class) to your test class:

import org.junit.jupiter.api.extension.ExtendWith;
import org.mockito.junit.jupiter.MockitoExtension;

@ExtendWith(MockitoExtension.class) // enables @Mock, @InjectMocks, @Captor, @Spy
class PaymentServiceTest { }

Creating Mocks: @Mock vs Mockito.mock()

@ExtendWith(MockitoExtension.class)
class MockCreationTest {

    // Annotation style — cleanest, preferred for fields
    @Mock
    private PaymentGateway paymentGateway;

    @Mock
    private NotificationService notificationService;

    // Programmatic style — useful when you need a mock inside a method
    @Test
    void programmaticMockCreation() {
        // Create a mock inside the test method
        UserRepository mockRepo = Mockito.mock(UserRepository.class);
        when(mockRepo.findById(1L)).thenReturn(Optional.of(new User(1L, "Alice")));

        User found = mockRepo.findById(1L).orElseThrow();
        assertEquals("Alice", found.getName());
    }
}

Stubbing with when().thenReturn()

@ExtendWith(MockitoExtension.class)
class StubbingExamplesTest {

    @Mock private PaymentGateway paymentGateway;
    @InjectMocks private PaymentService paymentService;

    @Test
    @DisplayName("Successful payment returns a confirmation number")
    void successfulPaymentReturnsConfirmationNumber() {
        // Stub: when gateway.charge() is called with ANY double, return a confirmation
        when(paymentGateway.charge(anyDouble()))
            .thenReturn(new PaymentResult("CONF-12345", true));

        PaymentResult result = paymentService.processPayment(99.99);

        assertTrue(result.isSuccessful());
        assertEquals("CONF-12345", result.getConfirmationNumber());
    }

    @Test
    @DisplayName("Gateway failure propagates as PaymentException")
    void gatewayFailureThrowsPaymentException() {
        // Stub: throw an exception when the gateway is called
        when(paymentGateway.charge(anyDouble()))
            .thenThrow(new GatewayTimeoutException("Gateway timed out"));

        assertThrows(PaymentException.class,
            () -> paymentService.processPayment(99.99));
    }

    @Test
    @DisplayName("Multiple calls can return different values")
    void consecutiveCallsReturnDifferentValues() {
        // First call returns PENDING, second returns COMPLETED
        when(paymentGateway.checkStatus(anyString()))
            .thenReturn(PaymentStatus.PENDING)
            .thenReturn(PaymentStatus.COMPLETED);

        assertEquals(PaymentStatus.PENDING,   paymentGateway.checkStatus("TX-001"));
        assertEquals(PaymentStatus.COMPLETED, paymentGateway.checkStatus("TX-001"));
    }
}

The JUnit 6 extension model is not just for simple before/after hooks. At its most advanced, it lets you build entire custom testing frameworks on top of JUnit — with domain-specific annotations, automatic injection, retry logic, soft assertions, and test templates. This guide explores the most powerful extension patterns used by production-grade testing frameworks, with complete, runnable examples.

This post builds on JUnit 6 Extensions Model: Build Custom Extensions Step-by-Step. Make sure you are comfortable with basic extension interfaces before diving in here.

Pattern 1: Composed Annotation Extensions

Combine multiple annotations and extensions into a single meta-annotation so test classes need only one annotation to get a full suite of capabilities:

import org.junit.jupiter.api.*;
import org.junit.jupiter.api.extension.*;
import java.lang.annotation.*;

/**
 * @DatabaseTest: a single annotation that applies:
 *  - @ExtendWith(DatabaseSetupExtension.class) — manages DB lifecycle
 *  - @ExtendWith(TransactionRollbackExtension.class) — rolls back after each test
 *  - @Tag("integration") — marks for integration test filtering
 *  - @Tag("database") — marks for database test filtering
 *  - @TestInstance(PER_CLASS) — shares one instance across methods
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@ExtendWith(DatabaseSetupExtension.class)
@ExtendWith(TransactionRollbackExtension.class)
@Tag("integration")
@Tag("database")
@TestInstance(TestInstance.Lifecycle.PER_CLASS)
public @interface DatabaseTest {
    // Custom attribute: which database profile to use
    String profile() default "test";
}

// DatabaseSetupExtension: opens connection before all, closes after all
class DatabaseSetupExtension implements BeforeAllCallback, AfterAllCallback {
    @Override
    public void beforeAll(ExtensionContext ctx) {
        System.out.println("[DB] Opening database connection");
        // Store connection in context store for tests to access
        ctx.getStore(ExtensionContext.Namespace.GLOBAL)
           .put("db.connection", createConnection());
    }
    @Override
    public void afterAll(ExtensionContext ctx) {
        System.out.println("[DB] Closing database connection");
    }
    private Object createConnection() { return "connection-placeholder"; }
}

// TransactionRollbackExtension: wraps each test in a transaction that rolls back
class TransactionRollbackExtension implements BeforeEachCallback, AfterEachCallback {
    @Override
    public void beforeEach(ExtensionContext ctx) {
        System.out.println("[TX] Starting transaction");
    }
    @Override
    public void afterEach(ExtensionContext ctx) {
        System.out.println("[TX] Rolling back transaction"); // ensures test isolation
    }
}

// Usage — one annotation gives you DB lifecycle + transaction rollback + tags
@DatabaseTest(profile = "integration")
class UserRepositoryTest {
    @Test
    void findByEmailReturnsCorrectUser() {
        // DB is set up, wrapped in a transaction that will roll back
        assertNotNull("result");
    }
}

Building your own JUnit 6 TestEngine is the ultimate act of framework mastery. It lets you run tests written in any format — YAML, XML, a custom DSL, plain text specifications — on the same JUnit Platform that runs your regular @Test methods. This guide builds a complete, working custom engine from scratch, step by step.

Before reading this, make sure you understand how the engine works internally — see JUnit 6 Internals: How the Test Engine Works first.

What We Will Build

We will build a CSV Test Engine that discovers .csv test files on the classpath, treats each row as a test case (input values + expected output), and runs them through a target method. This demonstrates every part of the TestEngine contract in a realistic, runnable example.

Step 1: Add the Platform Engine Dependency

<!-- JUnit Platform Engine SPI — provides TestEngine, TestDescriptor, etc. -->
<dependency>
    <groupId>org.junit.platform</groupId>
    <artifactId>junit-platform-engine</artifactId>
    <version>1.11.0</version>
    <scope>test</scope>
</dependency>

<!-- Commons CSV for parsing CSV test files -->
<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-csv</artifactId>
    <version>1.10.0</version>
    <scope>test</scope>
</dependency>