Mockito: Verifying a Method is Called Only Once with Exact Parameters While Ignoring Other Method Calls

Problem Context and Challenges

In Java unit testing, Mockito, as a popular mocking framework, provides rich verification capabilities to ensure that interactions between the tested object and its dependencies meet expectations. However, in practical testing scenarios, developers often face a specific requirement: verifying that a method is called only once with exact parameters, while ignoring calls to other methods. This need is particularly common when testing complex business logic, where the tested object may call multiple dependency methods, but the test focus is only on specific interactions.

Analysis of Common Incorrect Approaches

Many developers first attempt to use verifyNoMoreInteractions(foo), but this approach has significant drawbacks. As shown in the example code:

Mockito.verify(foo, Mockito.times(1)).add("1");
// Incorrect approach 1
Mockito.verifyNoMoreInteractions(foo);

verifyNoMoreInteractions() verifies that there are no other calls on the mock object foo, meaning it does not allow calls to other methods like clear(). This overly strict verification undermines test flexibility, especially in scenarios where the tested object needs to perform multiple operations but only some interactions require verification.

Another common mistake is using verify(foo, times(0)).add(any()):

Mockito.verify(foo, Mockito.times(1)).add("1");
// Incorrect approach 2
Mockito.verify(foo, Mockito.times(0)).add(Mockito.anyString());

This approach attempts to verify that the add() method has no calls other than the specific one, but it contains a logical contradiction. The first verification already confirms that add("1") is called once, while the second verification demands zero calls to the add() method, leading to verification failure because the two verifications target different call conditions for the same method.

Optimal Solution

Based on Mockito's verification mechanism, the most effective solution is to combine two verify() calls:

// Verify exact parameter call
Mockito.verify(foo, Mockito.times(1)).add("1");
// Verify total call count
Mockito.verify(foo, Mockito.times(1)).add(Mockito.anyString());

This combined verification works as follows:

1. First verification: Mockito.verify(foo, Mockito.times(1)).add("1") ensures the add() method is called once with the exact parameter "1".
2. Second verification: Mockito.verify(foo, Mockito.times(1)).add(Mockito.anyString()) uses the argument matcher anyString() to verify that the add() method is called exactly once in total.

The combined effect of these two verifications is: it guarantees that add("1") is called once and ensures there are no other calls to the add() method (since the total call count is 1). Simultaneously, this verification approach completely ignores calls to other methods like clear(), meeting the original requirement.

Code Example and Explanation

The following complete example demonstrates the solution in a practical test:

public class MockitoTest {
    interface Foo {
        void add(String str);
        void clear();
    }

    @Test
    public void testAddWasCalledOnceWith1IgnoringAllOtherInvocations() {
        // Create mock object
        Foo foo = Mockito.mock(Foo.class);

        // Execute test operations
        foo.add("1"); // Call to verify
        foo.add("2"); // Other add() call not allowed
        foo.clear();  // Other method call to be ignored

        // Combined verification
        Mockito.verify(foo, Mockito.times(1)).add("1");
        Mockito.verify(foo, Mockito.times(1)).add(Mockito.anyString());
    }
}

In this test:

• If foo.add("1") is not called, the first verification fails.
• If foo.add("1") is called multiple times, the first verification might pass (if parameters match), but the second verification fails because the total call count exceeds 1.
• If there are other add() calls like foo.add("2") besides foo.add("1"), the second verification fails due to the total call count exceeding 1.
• Calls to foo.clear() are completely ignored and do not affect the verification result.

Simplified Notation and Considerations

As shown in the supplementary answer, the solution can be simplified to:

Mockito.verify(foo).add("1");
Mockito.verify(foo).add(Mockito.anyString());

Here, the single-parameter form of verify() is used, which is an alias for verify(foo, times(1)). This notation is more concise, but note:

1. The simplified notation only applies to scenarios verifying one call; if other counts (e.g., 0, 2) are needed, the full times() parameter must still be used.
2. The argument matcher anyString() matches any string parameter, including null. If the test needs to exclude null, more specific matchers like Mockito.notNull() can be used.
3. This verification approach only applies to the same method of the same mock object. If multiple methods or different objects need verification, they must be handled separately.

Application Scenarios and Best Practices

This verification pattern is particularly useful in the following scenarios:

1. Selective Verification: In complex business methods, focusing only on specific dependency calls while ignoring other minor interactions.
2. High Parameter Precision Requirements: Ensuring methods are called with specific parameter values to avoid business logic errors due to incorrect parameters.
3. Strict Call Count Limitations: Certain operations (e.g., resource allocation, state changes) must be executed exactly once, as multiple calls could cause errors.

In practice, it is recommended to:

• Add clear comments to verification code to explain the intent.
• Encapsulate complex verification logic into custom verification methods to improve code readability.
• Combine with Mockito's InOrder verifier if call sequence verification is needed.
• Avoid over-verification by only verifying interactions critical to the test objective.

Conclusion

By combining two verify() calls—one for exact parameters and one for total call count—developers can effectively verify that a method is called only once with matching parameters while flexibly ignoring calls to other methods. This solution balances test strictness and flexibility, serving as the recommended approach for handling selective verification needs in the Mockito framework. Understanding how Mockito's verification mechanism works and selecting appropriate verification strategies based on specific test requirements will contribute to writing more robust and maintainable unit tests.