Unit Testing Service Layer with Mockito Skill

Unit Testing Service Layer with Mockito

Overview

Provides patterns for unit testing @Service classes using Mockito. Mocks repository calls, verifies method invocations, tests exception scenarios, and stubs external API responses. Enables fast, isolated tests without Spring container or database.

When to Use

Testing business logic in @Service classes
Mocking repository and external client dependencies
Verifying service interactions with mocked collaborators
Testing error handling and edge cases in services
Writing fast, isolated unit tests (no database, no API calls)

Instructions

Follow this workflow to test service layer with Mockito, including validation checkpoints:

1. Setup Test Class

Use @ExtendWith(MockitoExtension.class) to enable Mockito annotations.

2. Declare Mocks with `@Mock` and `@InjectMocks`

Use @Mock for dependencies (repositories, clients) and @InjectMocks for the service under test.

3. Arrange-Act-Assert with Validation

Arrange: Create test data and configure mock return values using when().thenReturn().

Act: Execute the service method being tested.

Assert:

Verify returned values with AssertJ assertions
Verify mock interactions with verify()
Validation checkpoint: Run test and confirm green bar

4. Test Exception Scenarios

Configure mocks to throw exceptions with when().thenThrow().

Validation checkpoint: Verify exception type and message

5. Verify Complete Coverage

Run full test suite: mvn test or gradle test
Check coverage report: mvn test jacoco:report
Validation checkpoint: Confirm all service methods have corresponding tests

Examples

Basic Service Test Pattern

@ExtendWith(MockitoExtension.class)
class UserServiceTest {

  @Mock
  private UserRepository userRepository;

  @InjectMocks
  private UserService userService;

  @Test
  void shouldReturnUserWhenFound() {
    // Arrange
    User expected = new User(1L, "Alice");
    when(userRepository.findById(1L)).thenReturn(Optional.of(expected));

    // Act
    User result = userService.getUser(1L);

    // Assert
    assertThat(result.getName()).isEqualTo("Alice");
    verify(userRepository).findById(1L);
  }

  @Test
  void shouldThrowWhenUserNotFound() {
    // Arrange
    when(userRepository.findById(999L)).thenReturn(Optional.empty());

    // Act & Assert
    assertThatThrownBy(() -> userService.getUser(999L))
      .isInstanceOf(UserNotFoundException.class);
  }
}

Verify Method Invocations

@Test
void shouldSendEmailOnUserCreation() {
  User newUser = new User(1L, "Alice", "alice@example.com");
  when(userRepository.save(any(User.class))).thenReturn(newUser);

  enrichmentService.registerNewUser("Alice", "alice@example.com");

  verify(userRepository).save(any(User.class));
  verify(emailService).sendWelcomeEmail("alice@example.com");
}

For additional patterns (multiple dependencies, argument captors, async services, InOrder verification), see references/examples.md.

Best Practices

Use @ExtendWith(MockitoExtension.class) for JUnit 5 integration
Mock only direct dependencies of the service under test
Verify interactions to ensure correct collaboration
Test one behavior per test method - keep tests focused
Use descriptive variable names: expectedUser, actualUser, captor
Create real instances for value objects and DTOs (don't mock them)

Constraints and Warnings

Do not mock value objects or DTOs; create real instances with test data.
Avoid mocking too many dependencies; consider refactoring if a service has too many collaborators.
Tests must be independent; do not rely on execution order.
Be cautious with @Spy; partial mocking is harder to understand and maintain.
Do not test private methods directly; test them through public method behavior.
Argument matchers (any(), eq()) cannot be mixed with actual values in the same stub.
Avoid over-verifying; verify only interactions important to the test scenario.

Agent Skills: Unit Testing Service Layer with Mockito

Install this agent skill to your local

Skill Files