{"id":7016,"library":"asyncmock","title":"asyncmock","description":"asyncmock is a Python library that extends the standard `unittest.mock` framework to provide robust support for mocking asynchronous functions and coroutines. It's particularly useful for testing async codebases in Python versions prior to 3.8 (where `unittest.mock.AsyncMock` was introduced). The current version is 0.4.2, and while stable, the project has a slow release cadence, with the latest significant updates being several years ago.","status":"active","version":"0.4.2","language":"en","source_language":"en","source_url":"https://github.com/timsavage/asyncmock","tags":["async","testing","mocking","unittest"],"install":[{"cmd":"pip install asyncmock","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"While unittest.mock.AsyncMock exists in Python 3.8+, asyncmock.AsyncMock offers additional helpers like assert_awaited_*.","wrong":"from unittest.mock import AsyncMock","symbol":"AsyncMock","correct":"from asyncmock import AsyncMock"},{"note":"The patch function is part of the standard unittest.mock module, which asyncmock extends.","wrong":"from asyncmock import patch","symbol":"patch","correct":"from unittest.mock import patch"}],"quickstart":{"code":"import asyncio\nfrom asyncmock import AsyncMock\n\nasync def my_async_function_to_test():\n    return await some_external_async_call()\n\nasync def some_external_async_call():\n    # This would be an actual external async call in a real app\n    await asyncio.sleep(0.01)\n    return \"original result\"\n\nasync def test_my_async_function():\n    # Create an AsyncMock instance\n    mocked_external_call = AsyncMock(return_value=\"mocked result\")\n\n    # Temporarily replace the actual async call with the mock\n    # For this example, let's just use the mock directly for simplicity.\n    # In a real test, you'd typically use unittest.mock.patch.\n    # For quickstart, let's redefine the async function to use the mock directly\n\n    async def my_async_function_with_mock():\n        return await mocked_external_call()\n\n    print(f\"Calling function with mock...\")\n    result = await my_async_function_with_mock()\n\n    print(f\"Received result: {result}\")\n    assert result == \"mocked result\"\n\n    # Assert that the mock was awaited exactly once\n    mocked_external_call.assert_awaited_once()\n    print(\"Mocked function was awaited once successfully.\")\n\n    # Demonstrate side_effect\n    mocked_external_call.reset_mock()\n    mocked_external_call.side_effect = [\"first\", \"second\", RuntimeError(\"Async error!\")]\n\n    try:\n        print(f\"Side effect 1: {await my_async_function_with_mock()}\")\n        print(f\"Side effect 2: {await my_async_function_with_mock()}\")\n        await my_async_function_with_mock() # This will raise an exception\n    except RuntimeError as e:\n        print(f\"Caught expected error: {e}\")\n\nasyncio.run(test_my_async_function())","lang":"python","description":"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."},"warnings":[{"fix":"Always `await` calls to `AsyncMock` instances when you expect their resolved value: `result = await mocked_func()`.","message":"Calling 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For 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.","message":"`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.","severity":"gotcha","affected_versions":"< 3.8 primarily"},{"fix":"Pin 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.","message":"The 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.","severity":"gotcha","affected_versions":"All 0.x.x versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Replace `Mock()` or `MagicMock()` with `asyncmock.AsyncMock()` when mocking an `async def` function.","cause":"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.","error":"TypeError: object NoneType is not awaitable"},{"fix":"If 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.","cause":"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.","error":"AttributeError: 'AsyncMock' object has no attribute 'assert_awaited_once'"},{"fix":"Always `await` calls to `AsyncMock` instances when you expect their `return_value` or `side_effect` to be resolved. For example: `result = await my_mock()`.","cause":"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.","error":"RuntimeWarning: coroutine '...' was never awaited"}]}