Encountering a NullPointerException (NPE) during unit tests can be a frustrating experience, especially when you’re diligently using a powerful mocking framework like Mockito. This common issue often arises precisely when you’re trying to set up test conditions – specifically, when attempting to stub a method. The dreaded “Mockito - NullPointerException when stubbing Method” error message isn’t just a cryptic failure; it’s a signal that something fundamental about your mock setup, or perhaps even your tested code’s design, needs a closer look. Understanding why this happens is the first step towards writing robust, reliable tests and preventing future debugging headaches. This article will delve into the common causes, provide clear diagnostic steps, and outline best practices to help you overcome this prevalent testing challenge.

Understanding the Root Cause of Stubbing NPEs

A NullPointerException in a Mockito stubbing scenario typically means that the object you’re trying to interact with is null at the point of stubbing. While Mockito excels at creating test doubles, it cannot conjure an object out of thin air if your test setup hasn’t provided one. Many developers assume that merely declaring a mock instance is enough, but proper initialization and understanding of how mocks and real objects interact are crucial. This section explores the primary reasons behind this common testing pitfall, highlighting the differences between various Mockito features.

Stubbing a Null Object: The Most Common Scenario

The most frequent cause of a “Mockito - NullPointerException when stubbing Method” is attempting to stub a method on an object that hasn’t been initialized or is genuinely null. This often happens if you declare a mock field but forget to call Mockito.mock() or use the @Mock annotation with a Mockito runner or rule. For instance, if you have private MyDependency mockDependency; but never assign an actual mock instance to it, any call like Mockito.when(mockDependency.someMethod()).thenReturn(value); will result in an NPE because mockDependency itself is null.

Even when using annotations like @Mock, forgetting to initialize them with MockitoAnnotations.openMocks(this); or a JUnit runner (like @RunWith(MockitoJUnitRunner.class) or @ExtendWith(MockitoExtension.class) for JUnit 5) will leave your mock objects uninitialized. Always ensure your mock objects are properly instantiated before any stubbing attempts. This fundamental step ensures that Mockito has a valid test double to work with, preventing the system from trying to invoke a method on a non-existent object.

Misuse of spy() vs. mock() and Real Objects

Another common source of NPEs when stubbing arises from a misunderstanding of Mockito’s spy() function, particularly when dealing with real objects that have complex dependencies. While Mockito.mock() creates a complete dummy object, Mockito.spy() wraps an existing, real object, allowing you to selectively stub some of its methods while still calling real methods for others. The issue emerges if the real object passed to spy() has uninitialized dependencies within itself, and a method you don’t stub tries to access one of those null internal dependencies.

For example, if you spy on an instance of MyService and one of its real methods (which you haven’t stubbed) internally calls this.anotherDependency.doSomething(), and anotherDependency is null in the real MyService instance, then a NullPointerException will occur. This isn’t a Mockito stubbing issue directly, but rather a problem with the state of your real object that the spy is wrapping. The key here is to ensure that any real object you spy on is in a valid, initialized state, or that all methods accessing potentially null internal states are explicitly stubbed out to prevent their real execution.

Stubbing Final, Static, or Private Methods: Limitations and Workarounds

Mockito, by default, works best with non-final, non-static, and public/protected methods. Attempting to stub a final method on a real object (even a spy) or a static method will generally not work as expected with standard Mockito and can lead to various runtime exceptions, including NPEs, or simply no stubbing taking effect. Historically, Mockito relied on Java’s proxy mechanisms which couldn’t override final methods. While newer versions of Mockito (since 2.x) offer an experimental “inline” mock maker that can mock final classes and methods by default, it’s essential to understand its implications.

For more complex scenarios involving static or private methods, Mockito alone is insufficient. Tools like PowerMock are often used in conjunction with Mockito to overcome these limitations. However, using PowerMock adds significant complexity to your test suite and often indicates a design smell in the code under test. As advised by the official Mockito documentation, it’s often better to refactor your code to improve testability by avoiding final classes/methods or separating static logic into testable components. This approach leads to cleaner, more maintainable code and tests.

Diagnosing and Debugging the NPE: Practical Steps

When faced with a “Mockito - NullPointerException when stubbing Method,” a systematic approach to diagnosis is crucial. The stack trace, though sometimes daunting, holds the key to pinpointing the exact location of the null reference. Understanding where to look and what common pitfalls to check for can significantly reduce debugging time. As software engineer Martin Fowler notes, “Tests that are hard to write usually point to design problems.” A stubborn NPE during stubbing often reveals such underlying issues.

1. Examine the Stack Trace Carefully: Look for the line number where the NPE occurs. Specifically, identify if the NPE happens inside your Mockito.when(...) call or within the method being stubbed (if it’s a real object being spied). If it’s within Mockito.when(), the object being stubbed is likely null. If it’s inside the method being stubbed, a real method is executing prematurely or accessing a null dependency.
2. Verify Mock Initialization: Double-check that all your @Mock or @Spy annotated fields are properly initialized. This means having @RunWith(MockitoJUnitRunner.class), @ExtendWith(MockitoExtension.class), or calling MockitoAnnotations.openMocks(this); in a @BeforeEach or @Before method. For manually created mocks, ensure MyDependency mockDependency = Mockito<b>Question & Answer : </b><br></br><p>So I started writing tests for our Java-Spring-project. </p> <p>What I use is JUnit and Mockito. It's said, that when I use the when()...thenReturn() option I can mock services, without simulating them or so. So what I want to do is, to set:</p> <pre>when(classIwantToTest.object.get().methodWhichReturnsAList(input))thenReturn(ListcreatedInsideTheTestClass) </pre> <p>But no matter which when-clause I do, I always get a NullpointerException, which of course makes sense, because input is null. </p> <p>Also when I try to mock another method from an object: </p> <pre>when(object.method()).thenReturn(true) </pre> <p>There I also get a Nullpointer, because the method needs a variable, which isn't set. </p> <p>But I want to use when()..thenReturn() to get around creating this variable and so on. I just want to make sure, that if any class calls this method, then no matter what, just return true or the list above.</p> <p>Is it a basically misunderstanding from my side, or is there something else wrong?</p> <p><strong>Code:</strong></p> <pre>public class classIWantToTest implements classIWantToTestFacade{ @Autowired private SomeService myService; @Override public Optional<OutputData> getInformations(final InputData inputData) { final Optional<OutputData> data = myService.getListWithData(inputData); if (data.isPresent()) { final List<ItemData> allData = data.get().getItemDatas(); //do something with the data and allData return data; } return Optional.absent(); } } </pre> <p>And here is my test class:</p> <pre>public class Test { private InputData inputdata; private ClassUnderTest classUnderTest; final List<ItemData> allData = new ArrayList<ItemData>(); @Mock private DeliveryItemData item1; @Mock private DeliveryItemData item2; @Mock private SomeService myService; @Before public void setUp() throws Exception { classUnderTest = new ClassUnderTest(); myService = mock(myService.class); classUnderTest.setService(myService); item1 = mock(DeliveryItemData.class); item2 = mock(DeliveryItemData.class); } @Test public void test_sort() { createData(); when(myService.getListWithData(inputdata).get().getItemDatas()); when(item1.hasSomething()).thenReturn(true); when(item2.hasSomething()).thenReturn(false); } public void createData() { item1.setSomeValue("val"); item2.setSomeOtherValue("test"); item2.setSomeValue("val"); item2.setSomeOtherValue("value"); allData.add(item1); allData.add(item2); } </pre><br></br><p>I had this issue and my problem was that I was calling my method with any() instead of anyInt(). So I had:</p> <pre>doAnswer(...).with(myMockObject).thisFuncTakesAnInt(any()) </pre> <p>and I had to change it to:</p> <pre>doAnswer(...).with(myMockObject).thisFuncTakesAnInt(anyInt()) </pre> <p>I have no idea why that produced a NullPointerException. Maybe this will help the next poor soul.</p>