Test assertion

Ensures a mocked dependency was invoked exactly once with the expected arguments, catching both incorrect call counts and incorrect parameter values in a single assertion.

Unit testing: verifying a service call received correct parameters after a single execution; API mocking: confirming a client sent the right payload exactly once; Event handling: asserting a callback fired once with expected data

unittest.mock, pytest-mock, Python unit testing, test-driven development

mock_func.assert_called_once_with(*args, **kwargs)

mock_func.assert_called_once_with(...)

mock_func: Mock object instance, args: expected positional arguments, kwargs: expected keyword arguments

• unittest.mock.Mock
• unittest.mock.patch
• @patch decorator
• mock.call
• assert_called
• assert_called_once
• assert_called_with
• assert_not_called

• assert_called_with(*args
• **kwargs) — checks only the most recent call's arguments
• not call count
• assert_called_once — checks single invocation but ignores arguments entirely
• assert_has_calls([call(...)]) — verifies an ordered sequence of multiple calls

1) Using assert_called_once_with on a mock called zero times — raises AssertionError with a diff showing expected vs actual calls; 2) Calling assert_called_once_with when the mock was called twice — fails because it checks exact count, not 'at least once'; 3) Confusing assert_called_once (no args check) with assert_called_once_with (checks args) — the former only verifies call count, not argument values; 4) Passing mutable defaults in the assertion that differ from what the actual call received — deep comparison requires exact match

assert_called_with — same argument check but only verifies the most recent call, not call count; assert_called_once — checks single invocation without argument verification; assert_any_call — checks the mock was called with these args at least once regardless of total call count

Coming from JavaScript/Jest: expect(mock).toHaveBeenCalledWith() only checks if the call happened, not that it happened exactly once — Python's assert_called_once_with combines both count and argument verification in one assertion.

• assert_called
• assert_called_once
• assert_called_with
• assert_called_once_with
• assert_any_call
• assert_not_called
• assert_has_calls

Do not use when you need to verify multiple calls or call order — use assert_has_calls instead. The assertion compares arguments deeply, so nested structures must match exactly. If the mock was called more than once, this assertion always fails even if one of the calls matches — it is not 'at least once with'.

Catches both incorrect call counts and incorrect argument passing in a single assertion, preventing subtle bugs where a function is called too many times causing duplicate side effects or with wrong data causing downstream errors.

Like a bouncer checking both the guest list (was your name on it?) and the ticket (did you bring the right one?) — you need exactly one visit with the right credentials.

The 'once' in the name refers to the call count constraint, not the assertion itself. The method raises AssertionError with a helpful diff if the expectation is not met, showing expected vs actual call arguments.

assert_has_calls([call(...), call(...)]) for verifying ordered sequences of multiple calls