?JUnit 5 and Mockito Guide – From Scratch to Advanced (with Real-Time Spring Boot Examples)

Introduction

Imagine building a skyscraper without checking the strength of each floor. Risky, right?
That’s exactly what happens in software when we skip testing — we risk everything collapsing later.

In this guide, we’ll master JUnit 5 and Mockito from the ground up, moving from basic unit tests to advanced real-world scenarios like mocking APIs, testing exceptions, and measuring coverage with JaCoCo — all in a Spring Boot application.

By the end, you’ll have:

A complete testing toolkit for controllers, services, and repositories.
Confidence to write tests for real production scenarios.
Knowledge of best practices and common pitfalls to avoid.

1. Unit Testing vs Integration Testing – How JUnit Fits In

Unit Testing:

Tests individual components (e.g., a method in a service class).
Fast, isolated, no database or network calls.
Example: Testing a calculateFare() method without hitting the DB.

Integration Testing:

Tests multiple layers together (controller → service → repository).
May involve DB, APIs, message queues.
Example: Testing a booking API end-to-end with a real DB.

Where JUnit Fits In:

JUnit is a testing framework that lets you write and run repeatable tests in Java.
Works for both unit and integration tests.
Plays well with Mockito for mocking.

Mini Exercise:

Write down 3 examples from your project that should be tested as unit tests and 3 as integration tests.

2. JUnit 5 Features & Annotations with Examples

JUnit 5 = JUnit Platform + JUnit Jupiter + JUnit Vintage.

Common Annotations:

Annotation	Purpose
`@Test`	Marks a test method
`@BeforeEach`	Runs before each test
`@AfterEach`	Runs after each test
`@BeforeAll`	Runs once before all tests
`@AfterAll`	Runs once after all tests
`@DisplayName`	Custom name for test
`@Disabled`	Skips a test
`@ParameterizedTest`	Runs the same test with different inputs

class CalculatorTest {

    Calculator calc;

    @BeforeEach
    void init() {
        calc = new Calculator();
    }

    @Test
    @DisplayName("Addition Test")
    void testAdd() {
        assertEquals(5, calc.add(2, 3));
    }
}

3. Setting Up JUnit 5 in Spring Boot

Maven Dependency:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
</dependency>

This brings:

JUnit 5
Mockito
Spring Test
AssertJ, Hamcrest

Test Folder Structure:

src
 ├── main
 │    ├── java/com/example/demo
 │    └── resources
 └── test
      ├── java/com/example/demo
      └── resources

4. Real-World Example Project – Train Booking App

We’ll test a Train Booking service with:

Controller
Service
Repository
External API for train availability

Entitry

@Entity
public class Booking {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String trainName;
    private String passengerName;
    private double fare;

    // Constructors, getters, setters
}

Repository

public interface BookingRepository extends JpaRepository<Booking, Long> {
}

Service

@Service
public class BookingService {

    @Autowired
    private BookingRepository bookingRepository;

    public Booking createBooking(Booking booking) {
        booking.setFare(calculateFare(booking.getTrainName()));
        return bookingRepository.save(booking);
    }

    public Booking getBooking(Long id) {
        return bookingRepository.findById(id)
                .orElseThrow(() -> new RuntimeException("Booking not found"));
    }

    public double calculateFare(String trainName) {
        return trainName.contains("AC") ? 1500.0 : 800.0;
    }
}

Controller

@RestController
@RequestMapping("/bookings")
public class BookingController {

    @Autowired
    private BookingService bookingService;

    @PostMapping
    public ResponseEntity<Booking> createBooking(@RequestBody Booking booking) {
        return ResponseEntity.ok(bookingService.createBooking(booking));
    }

    @GetMapping("/{id}")
    public ResponseEntity<Booking> getBooking(@PathVariable Long id) {
        return ResponseEntity.ok(bookingService.getBooking(id));
    }
}

5. Writing Tests with Mockito

Service Layer Test

@ExtendWith(MockitoExtension.class)
class BookingServiceTest {

    @Mock
    BookingRepository bookingRepository;

    @InjectMocks
    BookingService bookingService;

    @Test
    void testCreateBooking() {
        Booking booking = new Booking();
        booking.setTrainName("AC Express");

        when(bookingRepository.save(any(Booking.class)))
            .thenReturn(new Booking(1L, "AC Express", "John", 1500.0));

        Booking savedBooking = bookingService.createBooking(booking);

        assertEquals(1500.0, savedBooking.getFare());
        verify(bookingRepository, times(1)).save(any(Booking.class));
    }
}

6. Testing Repository with H2

@DataJpaTest
class BookingRepositoryTest {

    @Autowired
    BookingRepository bookingRepository;

    @Test
    void testSaveAndFind() {
        Booking booking = new Booking();
        booking.setTrainName("Sleeper Express");
        booking.setPassengerName("Alice");
        booking.setFare(800.0);

        bookingRepository.save(booking);

        List<Booking> bookings = bookingRepository.findAll();
        assertEquals(1, bookings.size());
    }
}

7. Testing Controller with MockMvc

@WebMvcTest(BookingController.class)
class BookingControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @MockBean
    private BookingService bookingService;

    @Test
    void testGetBooking() throws Exception {
        Booking booking = new Booking(1L, "AC Express", "John", 1500.0);
        when(bookingService.getBooking(1L)).thenReturn(booking);

        mockMvc.perform(get("/bookings/1"))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.trainName").value("AC Express"));
    }
}

8. Advanced Scenarios

Mocking External APIs → WireMock setup
Testing Exceptions → assertThrows(RuntimeException.class, ...)
Parameterized Tests → @CsvSource({"AC Express,1500.0", "Sleeper Express,800.0"})
Verifying Calls → verify(bookingRepository, times(1)).save(any())

9. Best Practices

Test method naming: methodName_expectedBehavior_condition
Keep tests independent
Avoid over-mocking
Target 80%+ coverage but don’t write useless tests

10. JaCoCo Setup

Maven Plugin:

<plugin>
    <groupId>org.jacoco</groupId>
    <artifactId>jacoco-maven-plugin</artifactId>
    <version>0.8.8</version>
    <executions>
        <execution>
            <goals>
                <goal>prepare-agent</goal>
            </goals>
        </execution>
        <execution>
            <id>report</id>
            <phase>prepare-package</phase>
            <goals>
                <goal>report</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Run:

mvn clean test

Report will be in:

target/site/jacoco/index.html

Conclusion

Testing isn’t just about finding bugs — it’s about building confidence in your code.
With JUnit 5 and Mockito, you can write clean, fast, reliable tests for any Spring Boot app.