JUnit 5 & Mockito Best Practices: Effective Unit Testing for Spring Boot Microservices

Table of Contents

1. The Test Pyramid for Spring Boot Microservices
2. JUnit 5 Essentials: Lifecycle, Extensions, and Nested Tests
3. Mockito Setup: @ExtendWith vs @SpringBootTest
4. Stubbing Strategies: when/thenReturn vs doReturn/when
5. ArgumentCaptor: Verifying What You Pass to Dependencies
6. Parameterized Tests: @MethodSource, @CsvSource, and @EnumSource
7. Spy vs Mock: When to Partially Mock Real Objects
8. Common Anti-Patterns and How to Fix Them
9. Key Takeaways

@ExtendWith(MockitoExtension.class)
class OrderServiceTest {

    @Mock
    private OrderRepository orderRepository;

    @Mock
    private InventoryClient inventoryClient;

    @Mock
    private EventPublisher eventPublisher;

    @InjectMocks
    private OrderService orderService;

    @Nested
    @DisplayName("Place Order")
    class PlaceOrderTests {

        @BeforeEach
        void setUp() {
            when(inventoryClient.isAvailable("sku-A", 2)).thenReturn(true);
        }

        @Test
        @DisplayName("should create order and publish event when inventory available")
        void shouldCreateOrderAndPublishEvent() {
            OrderRequest request = new OrderRequest("user-1", "sku-A", 2);
            Order savedOrder = new Order(UUID.randomUUID(), "user-1", "PENDING");
            when(orderRepository.save(any(Order.class))).thenReturn(savedOrder);

            Order result = orderService.placeOrder(request);

            assertThat(result.getStatus()).isEqualTo("PENDING");
            verify(eventPublisher).publish(any(OrderCreatedEvent.class));
        }

        @Test
        @DisplayName("should throw InsufficientInventoryException when out of stock")
        void shouldThrowWhenInventoryUnavailable() {
            when(inventoryClient.isAvailable("sku-A", 2)).thenReturn(false);

            assertThatThrownBy(() -> orderService.placeOrder(new OrderRequest("user-1", "sku-A", 2)))
                .isInstanceOf(InsufficientInventoryException.class)
                .hasMessageContaining("sku-A");

            verify(orderRepository, never()).save(any());
        }
    }
}

// ✅ Preferred for service/domain logic — no Spring context
@ExtendWith(MockitoExtension.class)
class PaymentServiceTest {
    @Mock PaymentGatewayClient gatewayClient;
    @InjectMocks PaymentService paymentService;
    // Test runs in <100ms
}

// ✅ Use @WebMvcTest for controller tests — Spring MVC context only
@WebMvcTest(PaymentController.class)
class PaymentControllerTest {
    @Autowired MockMvc mockMvc;
    @MockBean PaymentService paymentService; // spring-managed mock
}

// ❌ Avoid for service tests — 10+ second startup for no benefit
@SpringBootTest
class PaymentServiceHeavyTest {
    @MockBean PaymentGatewayClient gatewayClient;
    @Autowired PaymentService paymentService;
    // Same coverage, 50x slower
}

// Standard stubbing for mocks
when(userRepository.findById(42L)).thenReturn(Optional.of(testUser));
when(userRepository.findById(99L)).thenReturn(Optional.empty());

// Chained responses — first call returns user, second throws
when(userRepository.findById(1L))
    .thenReturn(Optional.of(testUser))
    .thenThrow(new DataAccessException("DB unavailable") {});

// Throw checked exception on void method
doThrow(new MailException("SMTP down") {})
    .when(emailService).sendWelcomeEmail(anyString());

// Stub a spy without calling the real method
OrderService spyService = spy(new OrderService(repository));
doReturn(BigDecimal.ZERO).when(spyService).calculateDiscount(any());

// Answer — dynamic response based on argument
when(inventoryClient.reserveStock(anyString(), anyInt()))
    .thenAnswer(invocation -> {
        int quantity = invocation.getArgument(1);
        return quantity <= 100; // return true only for reasonable quantities
    });

@Test
void shouldPublishOrderCreatedEventWithCorrectDetails() {
    // Given
    OrderRequest request = new OrderRequest("user-123", "sku-A", 3, "EUR");
    when(orderRepository.save(any())).thenAnswer(inv -> {
        Order o = inv.getArgument(0);
        o.setId(UUID.fromString("a1b2c3d4-..."));
        return o;
    });

    // When
    orderService.placeOrder(request);

    // Then — capture the event published to the event bus
    ArgumentCaptor<OrderCreatedEvent> eventCaptor =
        ArgumentCaptor.forClass(OrderCreatedEvent.class);
    verify(eventPublisher).publish(eventCaptor.capture());

    OrderCreatedEvent capturedEvent = eventCaptor.getValue();
    assertThat(capturedEvent.getUserId()).isEqualTo("user-123");
    assertThat(capturedEvent.getSkuCode()).isEqualTo("sku-A");
    assertThat(capturedEvent.getQuantity()).isEqualTo(3);
    assertThat(capturedEvent.getCurrency()).isEqualTo("EUR");
    assertThat(capturedEvent.getTimestamp()).isNotNull();
}

// Capturing multiple invocations
@Test
void shouldSendEmailsToAllOrderParticipants() {
    orderService.placeOrder(multiPartyRequest);

    ArgumentCaptor<EmailRequest> emailCaptor =
        ArgumentCaptor.forClass(EmailRequest.class);
    verify(emailService, times(2)).sendEmail(emailCaptor.capture());

    List<EmailRequest> emails = emailCaptor.getAllValues();
    assertThat(emails).extracting(EmailRequest::getRecipient)
        .containsExactlyInAnyOrder("buyer@example.com", "seller@example.com");
}

// @CsvSource — tabular test cases inline
@ParameterizedTest(name = "order {0} units at price {1} should total {2}")
@CsvSource({
    "1,   100.00, 100.00",
    "3,    50.00, 150.00",
    "10,   29.99, 299.90",
    "0,   100.00,   0.00"
})
void shouldCalculateOrderTotal(int qty, BigDecimal price, BigDecimal expected) {
    BigDecimal total = pricingService.calculateTotal(qty, price);
    assertThat(total).isEqualByComparingTo(expected);
}

// @MethodSource — complex objects from factory
@ParameterizedTest
@MethodSource("invalidOrderRequests")
void shouldRejectInvalidOrders(OrderRequest request, String expectedMessage) {
    assertThatThrownBy(() -> orderService.placeOrder(request))
        .isInstanceOf(ValidationException.class)
        .hasMessageContaining(expectedMessage);
}

static Stream<Arguments> invalidOrderRequests() {
    return Stream.of(
        arguments(new OrderRequest(null, "sku-A", 1), "userId is required"),
        arguments(new OrderRequest("u1", null, 1), "skuCode is required"),
        arguments(new OrderRequest("u1", "sku-A", 0), "quantity must be positive"),
        arguments(new OrderRequest("u1", "sku-A", -5), "quantity must be positive")
    );
}

// @EnumSource — test all payment methods
@ParameterizedTest
@EnumSource(PaymentMethod.class)
void shouldAcceptAllPaymentMethods(PaymentMethod method) {
    OrderRequest req = new OrderRequest("u1", "sku-A", 1, method);
    when(inventoryClient.isAvailable(any(), anyInt())).thenReturn(true);
    when(orderRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));

    assertThatCode(() -> orderService.placeOrder(req)).doesNotThrowAnyException();
}

@ExtendWith(MockitoExtension.class)
class DiscountServiceTest {

    // Spy — real implementation, but we can stub specific methods
    @Spy
    private DiscountService discountService = new DiscountService();

    @Test
    void shouldApplyVIPDiscountOnTopOfStandardDiscount() {
        // Stub the external loyalty tier lookup only
        doReturn(LoyaltyTier.VIP).when(discountService).getLoyaltyTier("user-gold");

        // Real implementation calculates standard discount (10%)
        // then applies VIP modifier (additional 5%)
        BigDecimal discounted = discountService.calculate("user-gold", BigDecimal.valueOf(200));

        assertThat(discounted).isEqualByComparingTo("170.00"); // 200 * 0.85
    }
}

// Using @Spy annotation — Mockito calls new DiscountService() automatically
@ExtendWith(MockitoExtension.class)
class AnnotationSpyTest {
    @Spy
    DiscountService discountService; // default constructor required

    @Test
    void shouldUseRealImplementationForUnstubbedMethods() {
        // Only stub the external call
        doReturn(LoyaltyTier.STANDARD).when(discountService).getLoyaltyTier(anyString());

        BigDecimal result = discountService.calculate("any-user", BigDecimal.valueOf(100));

        assertThat(result).isEqualByComparingTo("90.00"); // real 10% standard discount
    }
}

Leave a Comment

Related Posts