Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 37 ยท Getting Started

Setting Up Mockito with Maven and Gradle

Add Mockito to a Maven or Gradle project, learn which artifacts you need, how the inline mock maker works, and how to check your setup.

Before you can write your first mock you need Mockito on the test classpath. The setup is short, but a few details (which artifact, which Java version, why a warning about "self-attaching" appears) trip up many beginners. This lesson walks through them for Maven and Gradle and explains what Mockito does behind the scenes when you ask for a mock.

Read-only on this site. The build files below are shown as text because the site's Java runner cannot run Maven or Gradle or download jars. The runnable examples use the labelled Mini stand-in library from What Is Mockito?.

Which artifacts do you need?

Mockito is split into a few small jars:

Artifact What it contains Needed when
org.mockito:mockito-core The library: mock, when, verify, matchers, captors, spies Always
org.mockito:mockito-junit-jupiter MockitoExtension for JUnit 5 and 6, which handles @Mock and strict stubs When you use JUnit Jupiter (almost always)
org.mockito:mockito-junit (old) / mockito-testng Runners and listeners for other frameworks Rare

mockito-junit-jupiter already depends on mockito-core, so for a Jupiter project one dependency is enough, but many teams list both to be explicit.

Maven

Add the two dependencies with test scope. Mockito 5 needs Java 11 or newer, and JUnit 6 needs Java 17, so any project that uses both runs on a modern JDK anyway:

XML
<dependencies>
  <dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter</artifactId>
    <version>6.1.3</version>
    <scope>test</scope>
  </dependency>
  <dependency>
    <groupId>org.mockito</groupId>
    <artifactId>mockito-core</artifactId>
    <version>5.17.0</version>
    <scope>test</scope>
  </dependency>
  <dependency>
    <groupId>org.mockito</groupId>
    <artifactId>mockito-junit-jupiter</artifactId>
    <version>5.17.0</version>
    <scope>test</scope>
  </dependency>
</dependencies>

The version numbers are examples: check Maven Central for the newest 5.x release when you start a project, and keep both Mockito artifacts on the same version. Run the tests with mvn test.

Gradle (Kotlin DSL)

Kotlin
dependencies {
    testImplementation("org.junit.jupiter:junit-jupiter:6.1.3")
    testImplementation("org.mockito:mockito-core:5.17.0")
    testImplementation("org.mockito:mockito-junit-jupiter:5.17.0")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

tasks.test {
    useJUnitPlatform()
}

Run gradle test. Spring Boot projects need nothing extra: spring-boot-starter-test already brings JUnit Jupiter, Mockito and AssertJ with matching versions.

What happens when you call mock(...)

Java can only create objects of a type you have a class for. For an interface the JDK can generate a class at run time (that is what java.lang.reflect.Proxy does), but it cannot do the same for a concrete or final class. Mockito solves this with a mock maker, a component that generates a subclass or modifies bytecode on the fly.

Since Mockito 5 the default is the inline mock maker, built on Byte Buddy and the JVM's instrumentation API. It can mock interfaces, regular classes, final classes and methods, and (with mockStatic) static methods. Earlier versions used a subclass-based mock maker that could not mock final classes unless you added a configuration file (mockito-extensions/org.mockito.plugins.MockMaker containing mock-maker-inline). Most tutorials you find online mention that file; with Mockito 5 you do not need it.

Here is what the limits of plain Java look like. This program tries to create a proxy for an interface (works) and for a class (fails). It is plain Java, with no Mockito or stand-in involved:

Java Why a mock maker is needed

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Mockito's mock maker closes exactly this gap, so mock(Plain.class) works in real Mockito even though the call above fails. The stand-in used on this site is built on Proxy, so it can mock interfaces only; the examples therefore use interfaces.

The self-attaching warning

On JDK 21 and newer, the inline mock maker attaches itself to the running JVM, and the JVM prints a warning like "A Java agent has been loaded dynamically ... Mockito is currently self-attaching to enable the inline-mock-maker. This will no longer work in future releases of the JDK." It is a warning, not an error, and tests still pass. The permanent fix is to start the test JVM with Mockito as an explicit agent (-javaagent: pointing at the mockito-core jar), which both Maven's Surefire plugin and Gradle's test task can do through their JVM-argument settings. The Mockito documentation shows the build snippets for the current version, so copy them from there rather than from an old blog post.

Project layout and a smoke test

Test classes go in src/test/java, in the same package as the class under test:

TEXT
src/main/java/com/shop/SignupService.java
src/test/java/com/shop/SignupServiceTest.java

A minimal real Mockito test file looks like this. It only checks that the setup works:

Java
import static org.mockito.Mockito.*;
import static org.junit.jupiter.api.Assertions.*;

import org.junit.jupiter.api.Test;

class SetupSmokeTest {
    @Test
    void mockitoIsOnTheClasspath() {
        java.util.List<String> list = mock(java.util.List.class);
        when(list.size()).thenReturn(42);
        assertEquals(42, list.size());
    }
}

If this test compiles and passes, your dependencies are right. You can run the stand-in version of the same smoke test below. It mocks an interface instead of List, because Mini mocks interfaces only:

Java A smoke test with the stand-in

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Static imports

Almost every Mockito test starts with import static org.mockito.Mockito.*;. That one line brings in mock, when, verify, times, never, any and friends so you can write when(...) instead of Mockito.when(...). Matchers such as anyString() and eq() live in ArgumentMatchers, but Mockito extends that class, so the one static import is enough. Some teams prefer explicit imports for each method; both styles work, and this course uses the wildcard.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which artifact provides MockitoExtension for JUnit Jupiter?

    mockito-junit-jupiter contains MockitoExtension. It depends on mockito-core, which holds the main API.
  2. 2. What is the default mock maker since Mockito 5?

    Mockito 5 made the inline mock maker (Byte Buddy plus instrumentation) the default, so final classes and methods can be mocked without extra configuration.
  3. 3. Why does java.lang.reflect.Proxy alone not replace Mockito's mock maker?

    Proxy generates classes that implement interfaces. Mockito needs bytecode generation to mock classes too.
  4. 4. Where should Mockito dependencies go in pom.xml?

    Mockito is only needed by tests, so it uses test scope and is not shipped with your application.

Summary

  • Add mockito-core and, for JUnit Jupiter, mockito-junit-jupiter with test scope, both on the same version.
  • Mockito 5 requires Java 11+ and uses the inline mock maker by default, so classes, final classes and methods can be mocked.
  • A "self-attaching" warning on newer JDKs is harmless; the permanent fix is to pass Mockito as a -javaagent to the test JVM.
  • Test code lives in src/test/java; one static import of org.mockito.Mockito.* covers the everyday API.
  • The stand-in library on this site mocks interfaces only because it is built on Proxy.

Next: Your First Mock