Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 37 ยท Static and Final Mocking

Final Classes and the Inline Mock Maker

See why mocking libraries once could not mock final classes and methods, how Mockito 5's inline mock maker changed that, and when a wrapper is still the better design.

For years the first thing a Java developer learned about mocking was a limit: you cannot mock a final class. Records, many Kotlin classes, sealed hierarchies and well-designed immutable types are all final. Newer Mockito versions removed the limit, but understanding why it existed helps you debug odd errors and decide when mocking a final class is the wrong idea anyway.

Mockito cannot run on this site, so the real configuration is shown read-only. The runnable parts demonstrate the underlying Java rules with plain code.

Why final was a problem

Classic mock makers create a subclass of the type at run time and override its methods. That requires two things from Java:

  • the class must be non-final, otherwise you cannot extend it;
  • each method must be non-final and non-private, otherwise you cannot override it.

java.lang.reflect.Proxy is even stricter: it only builds proxies of interfaces. You can see it complain:

Java Proxy refuses classes

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.

The interface proxy works; the two classes are refused. Subclass-based tools such as the old Mockito mock maker use a different technique (bytecode generation of a subclass), but they hit the same wall for final classes: Java will not allow a subclass.

The inline mock maker

Mockito's inline mock maker works differently. Instead of subclassing, it uses an instrumentation agent to change the bytecode of the class itself so each method first asks Mockito whether it is mocked. Final classes, final methods, and even static methods and constructors can then be intercepted.

Timeline:

Mockito version Default mock maker
1.x to 4.x Subclass-based. Final needs the extra mockito-inline artifact
5.0 and later Inline is the default. mockito-core is enough

Requirements and notes for current versions:

  • Mockito 5 targets Java 11 or newer.
  • Dependencies stay simple: org.mockito:mockito-core (plus mockito-junit-jupiter for the JUnit 5 extension).
  • On recent JDKs, loading an agent dynamically into a running JVM prints a warning, and a future JDK may forbid it by default. The documented answer is to attach Mockito as a Java agent in your build, for example with -javaagent: pointing to the Mockito jar in Maven Surefire or Gradle test configuration.
  • You can go back to the old behavior with a file mockito-extensions/org.mockito.plugins.MockMaker containing mock-maker-subclass.

With the default settings, this now works:

Java
final class Money {
    private final long cents;
    Money(long cents) { this.cents = cents; }
    long cents() { return cents; }
}

Money money = mock(Money.class);
when(money.cents()).thenReturn(500L);
assertEquals(500L, money.cents());

What is still not mockable

Even the inline maker has limits. Types that the JVM itself depends on cannot be instrumented safely, for example java.lang.Class, String, the primitive wrappers and some other core classes. Mockito rejects them with an explicit message. If your code needs a different String, you have a design question, not a mocking question.

Should you mock it just because you can?

Being able to mock a final class does not mean you should. Compare:

Type Mock it?
Value types (Money, Email, records) No. Create real instances; they are cheap and deterministic
Third-party final client (SDK class you cannot subclass) Prefer your own small interface around it
Final class that talks to the outside world Mock or wrap, but wrapping gives a cleaner test and a cleaner design

The wrapper (also called an adapter or seam) is the classic technique. You define the narrow interface your code needs and implement it once with the final class. Tests use a fake or mock of the interface, and nothing about final matters.

Java A seam around a final class

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.

Final methods and Kotlin

Kotlin classes are final by default, which is why Kotlin projects were the first to demand inline mocking. In Kotlin you can either rely on Mockito 5's inline maker, open the classes with the all-open compiler plugin, or use a Kotlin-first library. For Java projects, the same advice applies: let the default inline maker handle the edge cases and keep your own design interface-based.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. Why could classic mock makers not mock a final class?

    Subclass-based mocking needs to extend the type and override methods. Final prevents both.
  2. 2. What is the default mock maker in Mockito 5?

    Since Mockito 5, inline is the default, so final classes and methods are mockable without extra artifacts.
  3. 3. Which is usually the better design for a final third-party class that talks to the network?

    A seam keeps your code independent of the vendor type and makes tests simple.

Summary

  • Subclass-based mocking cannot handle final classes or methods; Proxy only handles interfaces.
  • Mockito 5 uses the inline mock maker by default, which instruments bytecode and lifts most of those limits.
  • Some JDK core types still cannot be mocked, and recent JDKs prefer attaching the agent explicitly.
  • Value types should be real objects; third-party finals deserve your own interface seam.

Next: Mocking static methods