Meaning
Verifies that a mock object was called exactly once with the specified arguments. This assertion helps ensure that a unit under test interacts with its dependencies as expected, catching cases where the mock is called zero times, multiple times, or with incorrect parameters. It is typically used after exercising the code under test to validate the interaction contract.
Primary Function
Mock verification
Communicative Purpose
Verifies that a mock was called exactly once with expected arguments.
Pattern
mock.assert_called_once_with(*expected_args, **expected_kwargs)
Core Structure
mock.assert_called_once_with(*..., **...)
Função primária
Mock verification
Propósito comunicativo
Verifies that a mock was called exactly once with expected arguments.
Situações de gatilho
Python unit testing: verifying that a service method calls its logger exactly once with a specific error message; Python unit testing: ensuring a mock dependency is invoked once with correct parameters during an API call simulation; Python unit testing: confirming that a callback is triggered a single time with the expected payload.
Contextos
Python unit testing frameworks such as unittest.mock, pytest-mock, and the standalone mock library.
Padrão
mock.assert_called_once_with(*expected_args, **expected_kwargs)
Estrutura central
mock.assert_called_once_with(*..., **...)
Slots de substituição
expected_args: iterable of positional arguments, expected_kwargs: mapping of keyword arguments
Colocados típicos
- unittest.mock.patch
- MagicMock
- assert_called_with
- assert_any_call
- call_count
Substituições comuns
- assert_called_with(*args
- **kwargs) – checks at least one call with the given arguments
- assert_not_called() – ensures the mock was never invoked
- accessing mock.call_count – manual count of invocations.
Erros comuns
1. Forgetting to pass expected arguments – cause: assuming the mock was called with specific values; consequence: AssertionError if the mock was called with different arguments or no arguments. 2. Using assert_called_once_with after the mock has been called multiple times – cause: not resetting the mock between tests; consequence: false failure due to extra calls. 3. Confusing assert_called_once_with with assert_called_with – cause: believing they are interchangeable; consequence: false positive when the mock was called more than once with the same arguments. 4. Neglecting to match keyword arguments exactly – cause: omitting or misnaming a kwarg; consequence: AssertionError despite correct positional arguments.
Similar / contraste
assert_called_with – verifies at least one call with args; assert_called_once – verifies exactly one call without args; assert_any_call – verifies any call with args.
Interferências
Coming from Java's Mockito: may use verify(mock, times(1)).method(args) – Python's mock uses assert_called_once_with() instead.
Família do chunk
- mock.assert_called_with
- mock.assert_any_call
- mock.call_count
- mock.reset_mock
Nuance
Do not use when you only need to verify that the mock was called at least once; negligible performance impact; boundary: if the mock was called zero times, the assertion fails with an AssertionError.
Efeito pragmático
Guarantees that the unit test accurately verifies the interaction contract, preventing false confidence in code that misbehaves.
Dica de memória
Like a security guard who checks that exactly one person entered the building with the correct ID badge.
Nota
The method is available on unittest.mock.Mock and MagicMock objects; also works with patch decorators.
Upgrade path
Consider using assert_called_with for call count flexibility or mock.call_args_list for detailed inspection.
Log in to save chunks.