Spring Boot Testing with JUnit and Mockito: The Definitive Guide

// ── Production code the tests exercise ───────────────────────────────────────
// Product.java
package io.thecodeforge.model;

import java.math.BigDecimal;

public record Product(Long id, String name, BigDecimal price) {}

// ProductRepository.java
package io.thecodeforge.repository;

import io.thecodeforge.model.Product;
import org.springframework.data.jpa.repository.JpaRepository;

public interface ProductRepository extends JpaRepository<Product, Long> {}

// ProductService.java
package io.thecodeforge.service;

import io.thecodeforge.model.Product;
import io.thecodeforge.repository.ProductRepository;
import org.springframework.stereotype.Service;
import java.util.NoSuchElementException;

@Service
public class ProductService {

    private final ProductRepository repository;

    public ProductService(ProductRepository repository) {
        this.repository = repository;
    }

    public Product getProductById(Long id) {
        return repository.findById(id)
                .orElseThrow(() -> new NoSuchElementException("Product not found: " + id));
    }

    public Product save(Product product) {
        return repository.save(product);
    }
}

// ── Unit Test — no Spring context, runs in under 50ms ─────────────────────────
package io.thecodeforge.service;

import io.thecodeforge.model.Product;
import io.thecodeforge.repository.ProductRepository;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.mockito.InjectMocks;
import org.mockito.Mock;
import org.mockito.junit.jupiter.MockitoExtension;
import org.mockito.junit.jupiter.MockitoSettings;
import org.mockito.quality.Strictness;

import java.math.BigDecimal;
import java.util.NoSuchElementException;
import java.util.Optional;

import static org.assertj.core.api.Assertions.*;
import static org.mockito.Mockito.*;

// STRICT_STUBS catches unnecessary stubbing — if you stub something the code
// never calls, it fails fast. Dead stubbing is dead test code.
@ExtendWith(MockitoExtension.class)
@MockitoSettings(strictness = Strictness.STRICT_STUBS)
class ProductServiceTest {

    @Mock
    private ProductRepository repository;

    @InjectMocks
    private ProductService productService;

    @Test
    @DisplayName("getProductById: returns product when ID exists")
    void shouldReturnProductWhenIdExists() {
        // Arrange
        Product mockProduct = new Product(1L, "Forge Blade", new BigDecimal("99.99"));
        when(repository.findById(1L)).thenReturn(Optional.of(mockProduct));

        // Act
        Product result = productService.getProductById(1L);

        // Assert
        assertThat(result).isNotNull();
        assertThat(result.name()).isEqualTo("Forge Blade");
        assertThat(result.price()).isEqualByComparingTo("99.99");
        verify(repository, times(1)).findById(1L);
    }

    @Test
    @DisplayName("getProductById: throws NoSuchElementException when ID is missing")
    void shouldThrowWhenProductNotFound() {
        // Arrange
        when(repository.findById(99L)).thenReturn(Optional.empty());

        // Act + Assert — test the failure path, not just the happy path
        assertThatThrownBy(() -> productService.getProductById(99L))
                .isInstanceOf(NoSuchElementException.class)
                .hasMessageContaining("Product not found: 99");

        verify(repository).findById(99L);
    }
}

package io.thecodeforge.controller;

import io.thecodeforge.model.Product;
import io.thecodeforge.service.ProductService;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.boot.test.mock.mockito.MockBean;
import org.springframework.http.MediaType;
import org.springframework.test.web.servlet.MockMvc;

import java.math.BigDecimal;
import java.util.NoSuchElementException;

import static org.mockito.BDDMockito.given;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;

/**
 * @WebMvcTest loads only the web layer:
 *   - The specified controller
 *   - Spring MVC infrastructure and MockMvc
 *   - Jackson for JSON serialisation
 *
 * It does NOT load:
 *   - Service beans (provide via @MockBean)
 *   - Repository beans
 *   - Security configuration by default
 *
 * This makes it 10-50x faster than @SpringBootTest for controller testing.
 */
@WebMvcTest(ProductController.class)
class ProductControllerTest {

    @Autowired
    private MockMvc mockMvc;

    // @MockBean replaces the real ProductService bean in the Spring context
    // @Mock would not work here — there is no @InjectMocks in a Spring slice test
    @MockBean
    private ProductService productService;

    @Test
    void shouldReturnOkStatusAndProductJson() throws Exception {
        // Arrange — BDD style: given a product exists
        Product forgeItem = new Product(1L, "Cloud Core", new BigDecimal("45.00"));
        given(productService.getProductById(1L)).willReturn(forgeItem);

        // Act + Assert
        mockMvc.perform(get("/api/v1/products/1")
                       .accept(MediaType.APPLICATION_JSON))
               .andExpect(status().isOk())
               .andExpect(content().contentType(MediaType.APPLICATION_JSON))
               .andExpect(jsonPath("$.name").value("Cloud Core"))
               .andExpect(jsonPath("$.price").value(45.00));
    }

    @Test
    void shouldReturn404WhenProductDoesNotExist() throws Exception {
        // Arrange — stub the failure path
        given(productService.getProductById(99L))
                .willThrow(new NoSuchElementException("Product not found: 99"));

        // Act + Assert — verifies that the controller maps the exception to 404
        // This test only passes if GlobalExceptionHandler is loaded in the slice
        mockMvc.perform(get("/api/v1/products/99")
                       .accept(MediaType.APPLICATION_JSON))
               .andExpect(status().isNotFound());
    }
}

package io.thecodeforge.service;

import io.thecodeforge.model.Product;
import io.thecodeforge.repository.ProductRepository;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.mockito.ArgumentCaptor;
import org.mockito.Captor;
import org.mockito.InjectMocks;
import org.mockito.Mock;
import org.mockito.junit.jupiter.MockitoExtension;
import org.mockito.junit.jupiter.MockitoSettings;
import org.mockito.quality.Strictness;

import java.math.BigDecimal;

import static org.assertj.core.api.Assertions.assertThat;
import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.when;

@ExtendWith(MockitoExtension.class)
@MockitoSettings(strictness = Strictness.STRICT_STUBS)
class ProductServiceCaptorTest {

    @Mock
    private ProductRepository repository;

    @InjectMocks
    private ProductService productService;

    // Declare the captor as a field — @Captor initializes it via MockitoExtension
    @Captor
    private ArgumentCaptor<Product> productCaptor;

    @Test
    @org.junit.jupiter.api.DisplayName("save: persists product with correct name and price")
    void shouldPersistProductWithCorrectFields() {
        // Arrange
        Product input = new Product(null, "  Forge Blade  ", new BigDecimal("99.99"));
        Product savedProduct = new Product(1L, "Forge Blade", new BigDecimal("99.99"));
        when(repository.save(org.mockito.ArgumentMatchers.any(Product.class)))
                .thenReturn(savedProduct);

        // Act
        productService.save(input);

        // Assert — capture what actually reached the repository
        // verify() MUST come before getValue() — the captor populates during verify
        verify(repository).save(productCaptor.capture());
        Product captured = productCaptor.getValue();

        // Now inspect the object that the service passed to the repository
        // This tests the transformation logic, not just that save() was called
        assertThat(captured.name()).isEqualTo("Forge Blade");
        assertThat(captured.price()).isEqualByComparingTo("99.99");
    }

    @Test
    @org.junit.jupiter.api.DisplayName("save: ID is null on the entity passed to repository")
    void shouldPassNullIdToRepository() {
        // Arrange — ID generation is the database's job, not the service's
        Product input = new Product(null, "Forge Blade", new BigDecimal("99.99"));
        when(repository.save(org.mockito.ArgumentMatchers.any(Product.class)))
                .thenReturn(new Product(1L, "Forge Blade", new BigDecimal("99.99")));

        // Act
        productService.save(input);

        // Assert
        verify(repository).save(productCaptor.capture());
        assertThat(productCaptor.getValue().id()).isNull();
    }
}

package io.thecodeforge.service;

import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.mockito.InjectMocks;
import org.mockito.Mock;
import org.mockito.junit.jupiter.MockitoExtension;
import org.mockito.junit.jupiter.MockitoSettings;
import org.mockito.quality.Strictness;

import static org.assertj.core.api.Assertions.assertThatThrownBy;
import static org.mockito.Mockito.*;

/**
 * NotificationService.java (referenced by tests below)
 *
 * @Service
 * public class NotificationService {
 *     private final EmailClient emailClient;
 *
 *     public NotificationService(EmailClient emailClient) {
 *         this.emailClient = emailClient;
 *     }
 *
 *     public void notifyUser(String email, String message) {
 *         try {
 *             emailClient.send(email, message);
 *         } catch (EmailDeliveryException e) {
 *             throw new RuntimeException("Notification failed for: " + email, e);
 *         }
 *     }
 * }
 */
@ExtendWith(MockitoExtension.class)
@MockitoSettings(strictness = Strictness.STRICT_STUBS)
class NotificationServiceTest {

    @Mock
    private EmailClient emailClient; // EmailClient.send() is a void method

    @InjectMocks
    private NotificationService notificationService;

    @Test
    @DisplayName("notifyUser: delegates to emailClient with correct arguments")
    void shouldDelegateToEmailClientWithCorrectArgs() {
        // Arrange — void methods do nothing by default; doNothing() makes intent explicit
        doNothing().when(emailClient).send("user@forge.io", "Welcome!");

        // Act
        notificationService.notifyUser("user@forge.io", "Welcome!");

        // Assert — verify the side effect occurred with the right arguments
        verify(emailClient, times(1)).send("user@forge.io", "Welcome!");
    }

    @Test
    @DisplayName("notifyUser: wraps EmailDeliveryException in RuntimeException")
    void shouldWrapEmailClientExceptionInRuntimeException() {
        // Arrange — use doThrow().when() syntax for void methods
        // NOT when(emailClient.send(...)).thenThrow() — that syntax does not work on void methods
        doThrow(new EmailDeliveryException("SMTP connection refused"))
                .when(emailClient).send(anyString(), anyString());

        // Act + Assert — verify that the service wraps and rethrows correctly
        assertThatThrownBy(() -> notificationService.notifyUser("user@forge.io", "Welcome!"))
                .isInstanceOf(RuntimeException.class)
                .hasMessageContaining("Notification failed for: user@forge.io")
                .hasCauseInstanceOf(EmailDeliveryException.class);
    }

    @Test
    @DisplayName("notifyUser: does not call emailClient when email is blank")
    void shouldNotCallEmailClientWhenEmailIsBlank() {
        // Act — call with empty email (assumes service has a guard clause)
        // notificationService.notifyUser("", "Welcome!");

        // If the guard clause exists, emailClient.send() should never be called
        // verifyNoInteractions() confirms the mock was untouched
        // This test would be enabled once the guard clause is implemented
        verifyNoInteractions(emailClient);
    }
}

package io.thecodeforge.repository;

import io.thecodeforge.model.Product;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.orm.jpa.DataJpaTest;
import org.springframework.test.context.ActiveProfiles;

import java.math.BigDecimal;
import java.util.List;
import java.util.Optional;

import static org.assertj.core.api.Assertions.assertThat;

/**
 * @DataJpaTest loads:
 *   - JPA infrastructure (Hibernate, EntityManager)
 *   - Embedded H2 database configured to replace your real datasource
 *   - Your @Repository beans
 *   - Flyway/Liquibase migrations if present
 *
 * @DataJpaTest does NOT load:
 *   - @Service, @Controller, @Component beans
 *   - Security configuration
 *   - The full application context
 *
 * Each test runs in a transaction rolled back on completion — no cleanup needed.
 * To test with a real PostgreSQL database instead of H2, add:
 *   @AutoConfigureTestDatabase(replace = Replace.NONE)
 *   @Testcontainers with a static @Container PostgreSQLContainer
 */
@DataJpaTest
class ProductRepositoryTest {

    @Autowired
    private ProductRepository repository;

    @BeforeEach
    void setUp() {
        // Each test gets a clean, rolled-back transaction.
        // setUp() here demonstrates @BeforeEach placement — use it for
        // test data that every test in this class needs.
        repository.deleteAll();
    }

    @Test
    @DisplayName("findById: returns product when it exists")
    void shouldFindProductById() {
        // Arrange — save a product to the embedded H2
        Product saved = repository.save(
                new Product(null, "Forge Blade", new BigDecimal("99.99")));

        // Act
        Optional<Product> found = repository.findById(saved.id());

        // Assert
        assertThat(found).isPresent();
        assertThat(found.get().name()).isEqualTo("Forge Blade");
    }

    @Test
    @DisplayName("findAll: returns all persisted products")
    void shouldReturnAllProducts() {
        // Arrange
        repository.save(new Product(null, "Forge Blade", new BigDecimal("99.99")));
        repository.save(new Product(null, "Cloud Core", new BigDecimal("45.00")));

        // Act
        List<Product> products = repository.findAll();

        // Assert
        assertThat(products).hasSize(2);
        assertThat(products).extracting(Product::name)
                            .containsExactlyInAnyOrder("Forge Blade", "Cloud Core");
    }

    @Test
    @DisplayName("save: persists product and generates ID")
    void shouldGenerateIdOnSave() {
        // Arrange
        Product newProduct = new Product(null, "Anvil Pro", new BigDecimal("199.00"));

        // Act
        Product saved = repository.save(newProduct);

        // Assert — ID is assigned by the database, not the application
        assertThat(saved.id()).isNotNull();
        assertThat(saved.id()).isGreaterThan(0L);
    }

    @Test
    @DisplayName("delete: removes product from database")
    void shouldDeleteProduct() {
        // Arrange
        Product saved = repository.save(
                new Product(null, "Deprecated Blade", new BigDecimal("1.00")));

        // Act
        repository.deleteById(saved.id());

        // Assert
        assertThat(repository.findById(saved.id())).isEmpty();
    }
}

package io.thecodeforge.service;

import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.extension.ExtendWith;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.*;
import org.mockito.InjectMocks;
import org.mockito.Mock;
import org.mockito.junit.jupiter.MockitoExtension;

import java.math.BigDecimal;
import java.util.stream.Stream;

import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;

/**
 * ProductValidator.java (inline for reference)
 *
 * public class ProductValidator {
 *     public boolean isValidName(String name) {
 *         return name != null && !name.isBlank() && name.length() <= 100;
 *     }
 *
 *     public void validatePrice(BigDecimal price) {
 *         if (price == null || price.compareTo(BigDecimal.ZERO) <= 0) {
 *             throw new IllegalArgumentException("Price must be positive");
 *         }
 *     }
 * }
 */
@ExtendWith(MockitoExtension.class)
class ProductValidatorTest {

    private final ProductValidator validator = new ProductValidator();

    // @ValueSource: single argument, multiple values
    // Each value runs the test independently
    @ParameterizedTest(name = "isValidName returns false for: [{0}]")
    @NullAndEmptySource                          // covers null and ""
    @ValueSource(strings = {" ", "   ", "\t"})  // covers blank strings
    @DisplayName("isValidName: returns false for null, empty, and blank names")
    void shouldReturnFalseForInvalidNames(String invalidName) {
        assertThat(validator.isValidName(invalidName)).isFalse();
    }

    // @ValueSource for valid inputs — the happy path also deserves parameterization
    @ParameterizedTest(name = "isValidName returns true for: [{0}]")
    @ValueSource(strings = {"Forge Blade", "A", "Cloud Core Pro Max"})
    @DisplayName("isValidName: returns true for valid names")
    void shouldReturnTrueForValidNames(String validName) {
        assertThat(validator.isValidName(validName)).isTrue();
    }

    // @MethodSource: multiple arguments per test case
    // The static method returns Stream<Arguments> — each Arguments is one test run
    @ParameterizedTest(name = "validatePrice throws for price: {0}")
    @MethodSource("invalidPrices")
    @DisplayName("validatePrice: throws IllegalArgumentException for non-positive prices")
    void shouldThrowForInvalidPrice(BigDecimal price, String expectedMessage) {
        assertThatThrownBy(() -> validator.validatePrice(price))
                .isInstanceOf(IllegalArgumentException.class)
                .hasMessageContaining(expectedMessage);
    }

    // Static factory method for @MethodSource — must be static
    static Stream<Arguments> invalidPrices() {
        return Stream.of(
            Arguments.of(null,                     "Price must be positive"),
            Arguments.of(BigDecimal.ZERO,           "Price must be positive"),
            Arguments.of(new BigDecimal("-1.00"),   "Price must be positive")
        );
    }

    // @CsvSource: inline table for compact input/output pairs
    // Useful when the data is simple enough to live in the annotation
    @ParameterizedTest(name = "name=[{0}] expected={1}")
    @CsvSource({
        "Forge Blade,   true",
        "'',           false",
        "A,             true",
        "'   ',        false"
    })
    @DisplayName("isValidName: CsvSource variant for inline documentation")
    void shouldValidateNamesWithCsvSource(String name, boolean expected) {
        assertThat(validator.isValidName(name)).isEqualTo(expected);
    }
}

package io.thecodeforge.service;

import io.thecodeforge.model.Product;
import io.thecodeforge.repository.ProductRepository;
import org.junit.jupiter.api.*;
import org.junit.jupiter.api.extension.ExtendWith;
import org.mockito.InjectMocks;
import org.mockito.Mock;
import org.mockito.junit.jupiter.MockitoExtension;
import org.mockito.junit.jupiter.MockitoSettings;
import org.mockito.quality.Strictness;

import java.math.BigDecimal;
import java.util.NoSuchElementException;
import java.util.Optional;

import static org.assertj.core.api.Assertions.*;
import static org.mockito.Mockito.*;

@ExtendWith(MockitoExtension.class)
@MockitoSettings(strictness = Strictness.STRICT_STUBS)
@DisplayName("ProductService")
class ProductServiceNestedTest {

    // Shared across all nested classes — MockitoExtension manages injection
    @Mock  private ProductRepository repository;
    @InjectMocks private ProductService productService;

    @Nested
    @DisplayName("getProductById")
    class GetProductById {

        @Test
        @DisplayName("should return product when ID exists")
        void shouldReturnProductWhenIdExists() {
            // Arrange
            Product mockProduct = new Product(1L, "Forge Blade", new BigDecimal("99.99"));
            when(repository.findById(1L)).thenReturn(Optional.of(mockProduct));

            // Act
            Product result = productService.getProductById(1L);

            // Assert
            assertThat(result.name()).isEqualTo("Forge Blade");
            verify(repository).findById(1L);
        }

        @Test
        @DisplayName("should throw NoSuchElementException when ID does not exist")
        void shouldThrowWhenProductNotFound() {
            // Arrange
            when(repository.findById(99L)).thenReturn(Optional.empty());

            // Act + Assert
            assertThatThrownBy(() -> productService.getProductById(99L))
                    .isInstanceOf(NoSuchElementException.class)
                    .hasMessageContaining("99");
        }
    }

    @Nested
    @DisplayName("save")
    class Save {

        @Test
        @DisplayName("should delegate to repository and return saved entity")
        void shouldDelegateToRepositoryAndReturnSaved() {
            // Arrange
            Product input  = new Product(null,  "Anvil Pro", new BigDecimal("199.00"));
            Product output = new Product(42L,   "Anvil Pro", new BigDecimal("199.00"));
            when(repository.save(input)).thenReturn(output);

            // Act
            Product result = productService.save(input);

            // Assert
            assertThat(result.id()).isEqualTo(42L);
            verify(repository).save(input);
        }
    }
}