Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 37 ยท Verification

Verification Modes โ€“ times, never, atLeast, atMost, timeout

Check how often a mock was called with times, never, atLeast, atLeastOnce, atMost, only and timeout, and learn when each mode is the right choice.

verify(mock).call() insists on exactly one matching call. Often you need something else: "never", "exactly three times", "at least once", or "within half a second" for asynchronous code. A verification mode is the optional second argument to verify that states how many calls you expect. This lesson covers all of them with examples where the count really matters: retry loops, caching and failure paths.

Real Mockito code is read-only. Runnable examples use the Mini stand-in from What Is Mockito?, which implements times, never, atLeast, atLeastOnce and atMost. Modes that need threads or timing (timeout, after) are shown as real code only.

The modes at a glance

Java
import static org.mockito.Mockito.*;

verify(mock).call();                    // same as times(1)
verify(mock, times(3)).call();          // exactly 3 times
verify(mock, never()).call();           // exactly 0 times (same as times(0))
verify(mock, atLeastOnce()).call();     // 1 or more
verify(mock, atLeast(2)).call();        // 2 or more
verify(mock, atMost(5)).call();         // 0 to 5
verify(mock, only()).call();            // this is the ONLY interaction the mock had
verify(mock, timeout(500)).call();      // within 500 ms (asynchronous code)
verify(mock, after(500).never()).call();// not even after waiting 500 ms

times(n) and atLeast(n) count matching calls: the method and the arguments you passed. verify(mailer, times(2)).send("[email protected]", "Hello") ignores calls to send with other arguments and calls to other methods.

Try it: counting attempts

A retry loop is the classic reason to verify counts. The client below retries a failing call up to three times. Without a count check, a bug that retries five times (or does not retry at all) would pass any test that only looks at the final result.

Java times, atLeastOnce and atMost

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.

times(3) is the key assertion: it proves the loop made all three attempts and stopped.

never(): the negative check

Negative verification is underrated. Many important rules are of the form "if X goes wrong, do not do Y":

  • a declined payment must not mark the order paid;
  • an invalid email must not reach the repository;
  • a cache hit must not call the slow backend again.

Each is a one-line verify(..., never()). Forgetting these checks is how bugs like "we charged the customer and shipped nothing" reach production.

Java never() and a count that is too high

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.

only() and timeout()

Two more modes appear in real projects:

  • only() asserts that the call you verify is the only interaction that mock ever had. verify(mailer, only()).send(...) fails if the mock also received any other call. It is a compact combination of verify and verifyNoMoreInteractions (see No More Interactions).
  • timeout(ms) waits until the interaction has happened, polling for up to the given time. It is meant for asynchronous code, such as a listener called on another thread: verify(listener, timeout(1000)).onEvent(any()). timeout(...).times(2) and after(ms).never() modify it further. Use it sparingly, because it makes tests slower on failure; synchronize the code with a latch or executor you control when you can.

Choosing a mode

Situation Mode
"It must be called exactly once" (default) verify(mock) or times(1)
A retry or loop with a known count times(n)
"It must not happen" never()
It happens, but the count is not important atLeastOnce()
Upper bound, for example "at most one write" atMost(n)
Asynchronous code timeout(ms)

Be careful with over-precise counts. times(3) for a loop that should run once per item is precise and meaningful, but times(7) for the number of times an internal helper happens to be called today is an implementation detail that will break on the next refactoring.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is verify(mock) shorthand for?

    The default mode is times(1): exactly one matching call.
  2. 2. Which mode checks that a call did not happen?

    never() is the same as times(0). atLeast(0) would always pass.
  3. 3. verify(mailer, times(2)).send("a", "x") ignores which calls?

    Only calls matching the method and the arguments are counted.
  4. 4. When is timeout(ms) appropriate?

    timeout waits for the interaction, which only makes sense when it may happen later, on another thread.

Summary

  • A verification mode is the second argument of verify: times, never, atLeast, atLeastOnce, atMost, only, timeout, after.
  • Counts apply to calls matching method and arguments.
  • Use times(n) for retries and loops, never() for "must not happen" rules, and timeout for asynchronous code.
  • Avoid counts that merely mirror today's implementation.

Next: No More Interactions