asynctest

0.13.0 · maintenance · verified Mon Apr 06

asynctest is a Python library that enhances the standard `unittest` package with features tailored for testing `asyncio` applications. It reduces boilerplate by providing `TestCase` subclasses and mock objects designed to work seamlessly with coroutines and event loops. While built on `unittest`, it overrides and adds features for asynchronous testing, currently targeting the 'selector' model. The current version is 0.13.0, and its release cadence has been infrequent, indicating a maintenance status.

Warnings

breaking Python 3.4 is no longer supported since asynctest 0.13.0. Importing the library on Python 3.4 will raise a SyntaxError.
Fix: Upgrade to Python 3.5 or newer.
breaking The behavior of `@patch` decorators for coroutines changed in asynctest 0.13.0. Previously, the mock object was re-used for each call of the coroutine, which was inconsistent with `unittest.patch`.
Fix: Review existing tests using `@patch` on coroutines and adapt them to the new behavior where mocks are no longer implicitly re-used in the same way, aligning with standard `unittest.mock` behavior. Consult issue #121 on GitHub for details.
gotcha asynctest currently targets the 'selector' model for event loops. Some features may not work as expected or at all with Windows' 'proactor' event loop policy.
Fix: Consider testing on a 'selector' compatible environment or be aware of potential limitations on Windows using the 'proactor' model.
deprecated Internal usage of the `@asyncio.coroutine` decorator within asynctest's mock module may trigger `DeprecationWarning` in Python 3.8+ (where `async def` is preferred). While tests may still run, it indicates reliance on deprecated asyncio features.
Fix: This is primarily an internal warning. Users should ensure their own asynchronous code uses `async def` and `await` keywords for modern asyncio patterns.
gotcha Forgetting to `await` asynchronous calls within `async def` test methods, `setUp`, or `tearDown` can lead to coroutines not running or tests passing unexpectedly without verifying the asynchronous operation's completion.
Fix: Always use `await` for any coroutine calls (including mocked ones) within your `asynctest.TestCase` methods to ensure they execute and their results are processed correctly.
gotcha Setting `TestCase.use_default_loop = True` to share a single event loop across multiple tests can lead to unpredictable test states and side effects, as tasks or callbacks from previous tests might interfere with subsequent ones.
Fix: Avoid sharing event loops between tests if possible. asynctest's default behavior of creating a new isolated loop for each test is generally recommended for reliable unit testing. If a shared loop is necessary, carefully manage its state with `setUp` and `tearDown` to ensure isolation.

Install

pip install asynctest Install stable version

Imports

TestCase
```
from asynctest import TestCase
```
asynctest.TestCase is the core class, inheriting from and extending unittest.TestCase for asyncio.
CoroutineMock
```
from asynctest.mock import CoroutineMock
```
CoroutineMock specifically handles mocking of async def functions, returning awaitable objects.
patch
```
from asynctest.mock import patch
```
asynctest's patch is enhanced to correctly mock coroutines and asynchronous context managers/iterators.

Quickstart

This quickstart demonstrates how to create an asynchronous test case using `asynctest.TestCase`, defining an `async def` test method, and how to use `asynctest.CoroutineMock` to mock asynchronous functions. Tests are automatically run within their own event loop, which is managed by `asynctest`.

import asynctest
import asyncio

class MyAsyncTest(asynctest.TestCase):
    async def my_async_function(self):
        # Simulate an asynchronous operation
        await asyncio.sleep(0.001)
        return "async_result"

    async def test_my_async_method(self):
        result = await self.my_async_function()
        self.assertEqual(result, "async_result")

    async def test_with_coroutine_mock(self):
        mock_return = "mocked_async_data"
        my_mock = asynctest.CoroutineMock(return_value=mock_return)
        
        # Call the mocked coroutine
        data = await my_mock()
        
        self.assertEqual(data, mock_return)
        my_mock.assert_awaited_once()

# To run these tests, save the file (e.g., test_my_module.py) and run:
# python -m unittest test_my_module.py
# asynctest.main() can also be used if explicitly desired, but unittest discovery works.

view raw JSON →