aiounittest

library1.5.0pypypi✓ verified 85d ago

aiounittest is a helper library designed to simplify testing asynchronous Python code built with `asyncio`. It extends `unittest.TestCase` to support `async`/`await` syntax (Python 3.5+) and `asyncio.coroutine`/`yield from` (Python 3.4). The library is actively maintained, with its latest version being 1.5.0, released in March 2025.

testing

pip install aiounittest

github ↗package ↗

INSTALL

IMPORT

SIG · AIOUNITTEST

aiounittest

testingpythonv1.5.0

Install

1.9s avg

Import

367ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.5.0 · 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

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.395s · 18.5MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.9s · import 0.339s · 19MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

AsyncTestCase

✓ from aiounittest import AsyncTestCase

✗ from aiounittest.case import AsyncTestCase

While technically functional, the top-level import `from aiounittest import AsyncTestCase` is the recommended and cleaner approach.

async_test

✓ from aiounittest import async_test

Used as a decorator for `unittest.TestCase` methods that are coroutines, similar to `pytest.mark.asyncio`.

futurized

✓ from aiounittest import futurized

A helper to make objects awaitable, primarily used with `unittest.mock.Mock` to mock coroutines.

This quickstart demonstrates how to use `aiounittest.AsyncTestCase` to write asynchronous tests. Your async test methods should be `async def` and use `await` where necessary. Synchronous test methods can coexist within the same class.

import asyncio import aiounittest import unittest async def async_add(x, y, delay=0.01): await asyncio.sleep(delay) return x + y class MyAsyncTest(aiounittest.AsyncTestCase): async def test_async_addition(self): result = await async_add(10, 20) self.assertEqual(result, 30) def test_sync_method(self): self.assertTrue(True) # To run the tests (usually handled by test runners like `pytest` or `unittest` CLI) if __name__ == '__main__': unittest.main()

Debug

Known issues

deprecatedFor Python 3.8 and newer, consider using the built-in `unittest.IsolatedAsyncioTestCase`. The standard library's `unittest` now includes native support for asynchronous tests, reducing the need for `aiounittest` in many cases.

fix

Migrate tests to inherit from `unittest.IsolatedAsyncioTestCase` and adjust any `aiounittest`-specific helpers as needed.

affects: Python 3.8+

gotchaCreating `asyncio` loop-dependent objects (like `asyncio.Event`) in `setUp()` methods of `aiounittest.AsyncTestCase` can lead to `RuntimeError: got Future attached to a different loop`. `AsyncTestCase` creates a fresh event loop for each test, *after* `setUp()` and *before* the test method runs.

fix

Initialize `asyncio` objects within the `async def` test methods themselves, or override `get_event_loop` if you need to manage the loop lifecycle more granularly, ensuring objects are created with the test-specific loop.

affects: All

deprecatedThe `@asyncio.coroutine` decorator (for `yield from` syntax) was deprecated in Python 3.8. While `aiounittest` supports it for backward compatibility, it's recommended to use `async def` and `await` for new code.

fix

Rewrite coroutines using `async def` and `await` syntax.

affects: Python 3.8+

Errors

Common errors & fixes

RuntimeError: got Future attached to a different loop

An `asyncio` object (like a `Future` or `Event`) was created using an event loop that is different from the one `aiounittest.AsyncTestCase` uses to run the actual test. This often happens when such objects are created in `setUp()`.

fix

Ensure that any `asyncio` objects required by your test are created within the `async def` test method itself, or use `self.loop` (if overridden `get_event_loop`) to explicitly get the test's event loop.

RuntimeWarning: coroutine was never awaited

An `async def` function (coroutine) was called but its execution was not scheduled or awaited. `aiounittest.AsyncTestCase` automatically awaits `async def` test methods, but you must `await` any other coroutines called within your test.

fix

Prepend `await` to the call of any coroutine that you intend to execute, e.g., `await my_async_function()`.

TypeError: object MagicMock is not awaitable

You are trying to `await` a standard `unittest.mock.MagicMock` object that is configured to mock an `async def` function. `MagicMock` by default is not awaitable.

fix

When mocking asynchronous functions, use `unittest.mock.AsyncMock` instead of `MagicMock`. For example: `with patch('module.async_func', new_callable=AsyncMock) as mock_func:` or use `aiounittest.futurized`.

Upgrade

Version history

1.5.0latest on PyPI · released Mar 7, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

50 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/kwarunek/aiounittest ↗

packagehttps://pypi.org/project/aiounittest/ ↗