Asserting successive calls to a mock method

python

unittest

mocking

testing

byAnton Shumikhin·Jan 13, 2025

To verify that a mock method has been called with specific arguments in a particular sequence, use the mock.assert_has_calls method. Here's a quick example:

from unittest.mock import Mock, call

mock_obj = Mock()

# Playing a song with your mock instrument
mock_obj.method('call1')
mock_obj.method('call2')

# Checking if the song played right, 'call1' before 'call2'
mock_obj.assert_has_calls([call.method('call1'), call.method('call2')])

This code reassures the method of the mock object was called first with 'call1' and then 'call2'. If it played a different tune, it hits a sharp note—assertion error.

Understanding assert_has_calls

When dealing with 'unittest.mock' library, assert_has_calls is your trusted instrument for validating a series of mock calls. It's expecting a list of call, each representing an awaited method call and its arguments.

Key features to remember while composing with assert_has_calls:

Order of calls matters by default.
To make testing less strict about the sequence, set any_order=True.
It can handle expected repetitive calls in the same order.
For a more flexible validation, use assert_any_call. It checks if any of the calls has occurred and doesn't mind the order.

Handling out-of-order calls

If your orchestra plays in jazz style and the order of solos doesn't matter, simply define any_order=True:

# Listen to the jazz, it's not about the order!
mock_obj.assert_has_calls([
    call.method('call2'),
    call.method('call1')
], any_order=True)

Diving deeper with call_args_list

To explore the fine details of your calls sequence, use 'call_args_list'. It's a list storing arguments for each call. It allows comparing actual arguments with the expected ones:

expected_args = [('call1',), ('call2',)]
actual_args = [c.args for c in mock_obj.method.call_args_list]
assert expected_args == actual_args  # making sure we played the right notes

Counting the beats with call_count

What if you want to check how many times the beat was hit? Here 'call_count' saves the day. This attribute gives you the total number of calls to the mock method:

assert mock_obj.method.call_count == 2  # expecting duet, not a solo or a trio

Combined use of call_args_list and call_count gives full control over your mock calls—how many and what notes were played.

Cautious coding and testing practices

Testing everything with strict assertions might indicate code that is complex or tests that are too tied with implementation details. Remember the rule of thumb: Test behavior, not the implementation. Strike a balance to make your tests easily understandable, maintainable, and reflective of real-world usage of the system.

Defining your testing strategy

When playing with assert_has_calls, always keep in mind your testing strategy:

Do you need to check every note? Maybe just ensure the music was in the right key.
Are you stuffing your test with too many assertions? This might be a sign of complicated music—time to revise sheet music.
If the test becomes hard to maintain, you might need to rethink your mockchestra.

Tricky parts of mock testing

Nailing mock tests can be tricky. Here are some common traps to watch out for:

Refrain from asserting too many specific calls—focus on major chords.
Changes in implementation shouldn't result in a failed test, unless it affects the symphony itself.
Having too many mocks might lead to false positives, and results that sound fine but aren't.

Tips to hit the right notes

Strike the right chords with these tips:

Compose your code well from the start; this helps set up natural points for mocks.
Use return_value and side_effect attributes of Mock object to tune different mock scenarios.
Alongside unit tests, integration tests help ensure the symphony plays as expected when all pieces come together.