Install & Compatibility
Where this runs
tested against v0.4.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.352s · 18MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.303s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AsyncMock
✓ from asyncmock import AsyncMock
✗ from unittest.mock import AsyncMock
While unittest.mock.AsyncMock exists in Python 3.8+, asyncmock.AsyncMock offers additional helpers like assert_awaited_*.
patch
✓ from unittest.mock import patch
✗ from asyncmock import patch
The patch function is part of the standard unittest.mock module, which asyncmock extends.
This quickstart demonstrates how to create an `AsyncMock`, set its `return_value` and `side_effect`, and then await it. It also shows how to use `assert_awaited_once()` to verify that the mock was called asynchronously. In real tests, you would typically use `unittest.mock.patch` to replace the actual dependency.
import asyncio
from asyncmock import AsyncMock
async def my_async_function_to_test():
return await some_external_async_call()
async def some_external_async_call():
# This would be an actual external async call in a real app
await asyncio.sleep(0.01)
return "original result"
async def test_my_async_function():
# Create an AsyncMock instance
mocked_external_call = AsyncMock(return_value="mocked result")
# Temporarily replace the actual async call with the mock
# For this example, let's just use the mock directly for simplicity.
# In a real test, you'd typically use unittest.mock.patch.
# For quickstart, let's redefine the async function to use the mock directly
async def my_async_function_with_mock():
return await mocked_external_call()
print(f"Calling function with mock...")
result = await my_async_function_with_mock()
print(f"Received result: {result}")
assert result == "mocked result"
# Assert that the mock was awaited exactly once
mocked_external_call.assert_awaited_once()
print("Mocked function was awaited once successfully.")
# Demonstrate side_effect
mocked_external_call.reset_mock()
mocked_external_call.side_effect = ["first", "second", RuntimeError("Async error!")]
try:
print(f"Side effect 1: {await my_async_function_with_mock()}")
print(f"Side effect 2: {await my_async_function_with_mock()}")
await my_async_function_with_mock() # This will raise an exception
except RuntimeError as e:
print(f"Caught expected error: {e}")
asyncio.run(test_my_async_function())
Debug
Known issues
gotchaCalling an `AsyncMock` instance without `await` (e.g., `mocked_func()`) will return a coroutine object, not its configured `return_value` or `side_effect` result. This is a common mistake that leads to unexpected behavior in your tests.fixAlways `await` calls to `AsyncMock` instances when you expect their resolved value: `result = await mocked_func()`.
affects: All versions
gotcha`asyncmock` is primarily useful for Python versions < 3.8. For Python 3.8 and newer, `unittest.mock.AsyncMock` is built-in. While `asyncmock` provides specific `assert_awaited_*` helpers, consider using the built-in option first to reduce external dependencies if these specific helpers are not critical for your needs.fixFor Python 3.8+, evaluate whether `unittest.mock.AsyncMock` meets your needs. If you require explicit `assert_awaited_*` methods, then `asyncmock.AsyncMock` is still a valid choice.
affects: < 3.8 primarily
gotchaThe library is in a 0.x.x version state (pre-1.0). While stable and widely used for its purpose, users should be aware that minor version increments *could* theoretically introduce breaking changes or subtle behavior shifts, as the API is not yet guaranteed to be stable under strict Semantic Versioning principles.fixPin your `asyncmock` dependency to an exact version (e.g., `asyncmock==0.4.2`) in your `requirements.txt` or `pyproject.toml` to prevent unexpected updates. Review release notes before upgrading.
affects: All 0.x.x versions
Errors
Common errors & fixes
TypeError: object NoneType is not awaitable
You are attempting to await a mock object that was created with `unittest.mock.Mock` (or `MagicMock`) instead of `asyncmock.AsyncMock`. Standard mocks do not return awaitable objects by default.
fixReplace `Mock()` or `MagicMock()` with `asyncmock.AsyncMock()` when mocking an `async def` function.
AttributeError: 'AsyncMock' object has no attribute 'assert_awaited_once'
You are likely using `unittest.mock.AsyncMock` (the built-in version from Python 3.8+) but attempting to call methods like `assert_awaited_once` or `assert_awaited` which are specific to the `asyncmock` library's `AsyncMock` implementation.
fixIf you need the `assert_awaited_*` functionality, ensure you are importing and using `asyncmock.AsyncMock` from the `asyncmock` library. Otherwise, use standard `unittest.mock.AsyncMock` assertions like `assert_called_once()` and verify its return value.
RuntimeWarning: coroutine '...' was never awaited
This warning (or similar unexpected behavior where a variable holds a coroutine object instead of the mock's return value) often occurs when you call an `AsyncMock` instance but forget to `await` it.
fixAlways `await` calls to `AsyncMock` instances when you expect their `return_value` or `side_effect` to be resolved. For example: `result = await my_mock()`.
Upgrade
Version history
0.4.2latest on PyPI · released Mar 15, 2020
Audit
Dependencies
No dependency data recorded yet.