How to Mock Void Methods with Mockito in Java

By the end of this page, you will understand how Mockito handles void methods, when to use doNothing(), doThrow(), and doAnswer(), and why fully mocking the class under test often prevents real behavior from running. You will also learn how to test state changes and interactions correctly in an observer-style design.

Mockito can mock void methods, but they work a little differently from methods that return a value.

For a normal method, you often write:

when(service.getName()).thenReturn("Alice");

That style does not work for void methods, because there is no return value to configure.

Instead, Mockito provides the do...when(...) syntax:

doNothing().when(mock).someVoidMethod();
doThrow(new RuntimeException()).when(mock).someVoidMethod();
doAnswer(invocation -> {
    // custom behavior
    return null;
}).when(mock).someVoidMethod();

Why this matters

In real code, void methods are common for:

• notifications
• logging
• sending events
• mutating object state
• updating other objects

Testing them usually means one of these:

• verifying that the method was called
• simulating side effects
• checking how other code reacts when the method throws an exception

The key issue in your example

Think of a mock as a cardboard stand-in for a real object.

It looks like the object from the outside, but it does not do any real work unless you tell it exactly what to do.

So if you create:

World w = mock(World.class);

that mock is like an empty actor reading no lines. Calling:

w.doAction(...);

does not execute your real doAction() logic.

A better mental model is:

• Real object under test = the machine you want to inspect
• Mocks = fake buttons, sensors, or connected devices around it

If you want to see whether the machine changes state correctly, use the real machine. If you want to control or observe the things connected to it, mock those.

With Mockito, void methods are configured using do...when(...).

Core syntax

doNothing().when(mock).voidMethod();
doThrow(new IllegalStateException()).when(mock).voidMethod();
doAnswer(invocation -> {
    // custom side effect
    return null;
}).when(mock).voidMethod();

Example 1: Verify that a void method was called

import static org.mockito.Mockito.*;

Listener listener = mock(Listener.class);

listener.doAction();

verify(listener).doAction();

This is the most common case. You do not always need to stub a void method at all. Often, you simply call the code and verify the interaction.

Example 2: Make a void method throw an exception

import static org.mockito.Mockito.*;

Listener listener = mock(Listener.class);
doThrow(new RuntimeException("failed")).(listener).doAction();

listener.doAction(); 

Consider this code:

public interface Action {
    void doAction(Object obj);
}

public class World {
    private String state;

    public void doAction(Action goal, Object obj) {
        setState("i received");
        goal.doAction(obj);
        setState("i finished");
    }

    public String getState() {
        return state;
    }

    public void setState(String state) {
        this.state = state;
    }
}

And this test:

World world = new World();
Action action = mock(Action.class);

world.doAction(action, "file.txt");

What happens step by step

1. world is a .

void method mocking appears in many practical situations.

Event and observer systems

A listener often reacts through a void method:

listener.onMessage(message);

Tests usually verify that the listener was notified.

Logging and auditing

Services may call:

auditService.record(userAction);

The method returns nothing, but tests may verify it was called with the right data.

Email or notification sending

emailSender.sendWelcomeEmail(user);

You usually do not want to send a real email in a test, so you mock the sender and verify the call.

External side effects

Examples include:

• writing files
• publishing events
• sending metrics
• updating caches

These methods often return void, so mocks prevent real side effects while still letting tests check behavior.

Exception-path testing

A void dependency may fail:

doThrow( ()).(emailSender).sendWelcomeEmail(user);

In real projects, developers rarely mock everything. They usually test one unit of behavior at a time.

Common pattern: real class, mocked dependencies

OrderService service = new OrderService(paymentGateway, emailSender);

In a test:

• OrderService is real
• paymentGateway may be mocked
• emailSender may be mocked

This lets the service logic run while dependencies stay controlled.

Verifying void interactions

Common in service tests:

verify(emailSender).sendWelcomeEmail(user);
verify(auditService).record("USER_CREATED");

Using doThrow() for error handling

Teams often test failure branches like this:

doThrow(new IOException()).when(fileWriter).write(data);

Then they check whether the application:

• logs the error
• retries
• returns a safe response

1. Mocking the class you want to test

Broken approach:

World world = mock(World.class);
world.doAction(action, "data");

Why it fails:

• the real doAction() method does not run
• state is not updated

Better:

World world = new World();
Action action = mock(Action.class);

2. Using when(...).thenReturn(...) on a void method

Broken code:

when(listener.doAction()).thenReturn(...);

Why it fails:

• void methods do not return a value

Correct approach:

doNothing().when(listener).doAction();

or simply verify the call without stubbing.

Quick rules

• Use do...when(...) for void methods
• Use when(...).thenReturn(...) for non-void methods
• Do not mock the class you want to test unless you have a specific reason
• Mock collaborators, not the main behavior under test

Void method syntax

doNothing().when(mock).voidMethod();
doThrow(new RuntimeException()).when(mock).voidMethod();
doAnswer(invocation -> {
    return null;
}).when(mock).voidMethod();

Verify calls

verify(mock).voidMethod();
verify(mock, never()).voidMethod();
verify(mock, times(2)).voidMethod();

Best practice for your scenario

World world = new World();
Action action = mock(Action.class);

world.doAction(action, "data");

verify(action).doAction("data");
assertEquals("i finished", world.getState());

How do you mock a void method in Mockito?

Use doNothing(), doThrow(), or doAnswer() with when(...), for example:

doThrow(new RuntimeException()).when(service).run();

Can I use when(...).thenReturn(...) with a void method?

No. That syntax only works for methods that return a value.

Why is my mocked object not changing state?

Because a Mockito mock does not run real code by default. If you want real state changes, use a real object or a spy.

Should I mock the class I am testing?

Usually no. Create a real instance of the class under test and mock its dependencies.

Do I need doNothing() for every void method?

No. Mockito does nothing by default for mocked void methods. Often you can skip stubbing and just use verify(...).

How do I test that a void method was called with the right argument?

Use verify(...) or ArgumentCaptor.

When should I use ?

• Mockito verify — used to check whether a method call happened, especially useful for void methods.
• Mocks vs spies — important for understanding when real code runs and when it does not.
• Unit testing — provides the broader testing strategy behind mocking dependencies.
• Dependency injection — makes it easier to replace real collaborators with mocks in tests.
• Observer pattern — relevant because listeners and notifications often use void methods.
• Stubbing — the general idea of defining mock behavior in tests.
• ArgumentCaptor — useful when you need to inspect arguments passed to a void method.
• Exception testing — often paired with doThrow() for failure scenarios.