asyncmock

Common errors

• TypeError: object NoneType is not awaitable

  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.
  fix Replace `Mock()` or `MagicMock()` with `asyncmock.AsyncMock()` when mocking an `async def` function.

• AttributeError: 'AsyncMock' object has no attribute 'assert_awaited_once'

  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.
  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.

• RuntimeWarning: coroutine '...' was never awaited

  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.
  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()`.

Warnings

• gotcha 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.
  Fix: Always `await` calls to `AsyncMock` instances when you expect their resolved value: `result = await mocked_func()`.
• 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.
  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.
• gotcha 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.
  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.

Install

• pip install asyncmock Install stable version

Imports

• AsyncMock
  wrong:

  from unittest.mock import AsyncMock

  correct:

  from asyncmock import AsyncMock

  While unittest.mock.AsyncMock exists in Python 3.8+, asyncmock.AsyncMock offers additional helpers like assert_awaited_*.
• patch
  wrong:

  from asyncmock import patch

  correct:

  from unittest.mock import patch

  The patch function is part of the standard unittest.mock module, which asyncmock extends.

Quickstart

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())