Installing and Configuring Mockito with Maven

Integrating Mockito into Java projects for testing development is most commonly and recommended done through dependency management via Maven. Maven automatically handles library downloads, version compatibility, and conflict detection, greatly simplifying the build process. Open your project's root pom.xml file and add Mockito's core module within the <dependencies> tag.

Modern versions of Mockito (4.x and above) no longer require JUnit to be introduced as a dependency because Mockito itself includes necessary test interface implementations. Therefore, you only need to focus on Mockito's own dependencies. Here is the standard configuration code:

<dependency>
    <groupId>org.mockito</groupId>
    <artifactId>mockito-core</artifactId>
    <version>5.10.0</version>
    <scope>test</scope>
</dependency>

Pay attention to the <scope>test</scope> tag usage, which ensures that Mockito is included only during test compilation and execution phases. This avoids polluting the main code build process and reduces packaging volume. If you are using an older version of Mockito (3.x), you must additionally introduce JUnit 5 or JUnit 4 as a dependency; however, in current mainstream development environments, simply using the core dependency listed above satisfies most requirements.
Simply adding dependencies is not enough for Mockito to automatically take effect within test code; it also requires ensuring that the test runner can recognize and handle the proxy objects generated by Mockito. In the modern Java ecosystem, JUnit Platform has become de facto standard, perfectly integrating support for Mockito.

When using JUnit 5 for unit testing, you must ensure your project's pom.xml includes both the engine and platform support for JUnit Jupiter. This typically involves two key dependencies:

1. JUnit Jupiter Engine: Provides core functionality for test execution.
2. Jupiter Platform API: Provides metadata interfaces required to discover test classes and run tests.

The configuration is as follows:

<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter-engine</artifactId>
    <version>5.10.0</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter-api</artifactId>
    <version>5.10.0</version>
    <scope>test</scope>
</dependency>

Additionally, if the project has not configured a test framework yet, Maven defaults to enabling JUnit Platform. You can check the <build> section of your pom.xml to confirm whether there is plugin configuration similar to the following:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <version>3.2.2</version>
    <configuration>
        <!-- Optional: Explicitly specify test engine -->
        <includes>
            <include>**/*Test.java</include>
            <include>**/*Tests.java</include>
        </includes>
    </configuration>
</plugin>

With the above configuration, Maven will automatically invoke JUnit Platform during the build-test phase. Since JUnit Platform has built-in full support for Mockito, this means that when you use annotations like @Mock or @Spy in your test classes, there is no need to write additional Java Agent code or perform special JVM parameter configurations. The Mock objects generated by Mockito will be recognized and invoked normally by the test runner.

Verifying Installation Effectiveness

After completing dependency introduction and configuration, it is recommended to create a simple test class to verify whether Mockito works correctly. Below is an example of UserRepositoryTest.java, demonstrating how to create Mock objects in test code and assert their behavior:

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.DisplayName;
import org.mockito.Mockito;
import static org.mockito.Mockito.*;

@DisplayName("User Repository Service Test")
class UserRepositoryTest {

    // Use @Mock annotation to simulate interface
    private final UserRepository mockRepo = Mockito.mock(UserRepository.class);

    @Test
    @DisplayName("Return expected data when successfully getting user")
    void testGetUser_Success() {
        // Prepare test data
        User user = new User(1L, "Alice");
        
        // Configure Mock behavior: return 'user' when getUserById is called with id 1
        when(mockRepo.getUserById(1L)).thenReturn(user);

        // Execute test logic
        User result = mockRepo.getUserById(1L);

        // Verify result
        assertEqual(result, user);
    }

    @Test
    @DisplayName("Throw exception when getting non-existent user")
    void testGetUser_NotFound() {
        // Configure Mock behavior: throw specific exception when getUserById is called with id 999
        when(mockRepo.getUserById(999L)).thenThrow(new UserNotFoundException("User not found"));

        // Execute test logic
        assertThrows(UserNotFoundException.class, () -> {
            mockRepo.getUserById(999L);
        });
    }

    private void assertEqual(User expected, User actual) {
        if (expected != null && actual != null) {
            assertEquals(expected.getId(), actual.getId());
            assertEquals(expected.getName(), actual.getName());
        }
    }
}

Run the above test code. If everything is configured correctly, you should see output similar to the following in your terminal:

Tests run: 2, Failures: 0, Errors: 0, Skipped: 0

This indicates that Mockito has been successfully injected into the testing environment; the mockRepo object generated by the @Mock annotation can respond to calls from when() and verify() methods, and the test results meet expectations. If you encounter errors such as ClassCastException or "class not found" during execution, it usually means there is a mismatch in dependency versions or missing necessary JUnit Platform support. In this case, check Maven's dependency tree to ensure all components are consistent in versioning.