Skip to content
Tutorials Center
My learning

Topics

Lesson 35 of 40 ยท Testing and Debugging

Testing Async Code - unittest, pytest-asyncio and Fakes

Test asyncio code reliably: IsolatedAsyncioTestCase, pytest-asyncio, fake clients and clocks, testing timeouts, cancellation, streams and race conditions without sleeping.

Async code is easy to write and surprisingly easy to test badly. Tests that call asyncio.sleep(1) to "wait for things to happen" are slow and flaky. Tests that never await the code under test pass for the wrong reason. This lesson shows how to run async tests properly, and how to design code so that time, networks and concurrency are controllable in a test.

Three ideas carry the lesson: use a real test runner that understands coroutines; replace slow, external things with fakes; and control time and ordering explicitly instead of sleeping.

What runs where. The read-only snippets (IsolatedAsyncioTestCase, pytest) show the tools you will use on your computer. The runnable examples use the standard unittest module with a small run() helper (asyncio.run), which is plain Python that works the same on your machine. Everything under test is async code that really runs here.

Test runners for coroutines

unittest: IsolatedAsyncioTestCase

The standard library has an async-aware base class. Methods named test_* may be async def, and asyncSetUp / asyncTearDown can await. Each test gets a fresh event loop, so tests cannot leak tasks into each other.

Python
import unittest

class TotalTests(unittest.IsolatedAsyncioTestCase):
    async def asyncSetUp(self):
        self.api = FakeApi()

    async def test_total(self):
        self.assertEqual(await fetch_total(self.api, [1, 2, 3]), 60)

    async def test_timeout(self):
        with self.assertRaises(TimeoutError):
            await with_deadline(hang(), 0.01)

if __name__ == "__main__":
    unittest.main()

pytest with pytest-asyncio (or anyio)

Most projects use pytest. After pip install pytest pytest-asyncio you mark coroutine tests, or set asyncio_mode = auto in the configuration so every async def test_... is run automatically:

Python
import pytest

@pytest.mark.asyncio
async def test_total():
    assert await fetch_total(FakeApi(), [1, 2, 3]) == 60

@pytest.fixture
async def api():
    client = FakeApi()
    yield client                 # async fixtures can set up and tear down with await
    await client.close()

The anyio pytest plugin is an alternative that also runs tests under Trio. Whichever you choose, the habit is the same: the test itself is a coroutine, and it awaits the code under test.

A runnable harness

Here is the shape of a real test module that you can run in the lesson editor. The run() helper executes one coroutine to completion, which is all a sync-style test needs:

Python unittest for async functions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The last test shows a good safety net: a test that checks no task was left running. Leaked tasks are a typical source of "works alone, fails in the suite" flakiness.

Replace the network with a fake

The simplest, most valuable technique is to pass dependencies in (a client, a session, a clock) so the test can substitute a fake. A fake client is a small class, written by you, with the same async methods, that records calls and returns canned data or raises canned errors. It beats mock patching because the test reads like documentation.

unittest.mock.AsyncMock is the ready-made option: await mock() returns mock.return_value, side_effect can be a list of values and exceptions, and assert_awaited_once_with(...) checks the calls.

Python
from unittest.mock import AsyncMock

client = AsyncMock()
client.get.side_effect = [ConnectionError("reset"), {"status": 200}]
result = await retry(lambda: client.get("/items"))
assert result == {"status": 200}
assert client.get.await_count == 2

Control time instead of waiting for it

Never write await asyncio.sleep(2) in a test to wait for a retry or a refresh timer. Design the code under test so the sleep function is injectable, then pass a fake that records the requested delays and returns immediately:

Python Testing backoff without waiting

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

A test that checks seven seconds of backoff completes in milliseconds. The same idea works for clocks: inject time.monotonic or loop.time. If you cannot change the code, the time-machine and async-solipsism packages offer virtual time for pytest.

Test streams and protocols with feed_data

You can test network code without a network. A StreamReader is filled with feed_data() and feed_eof(), and protocol callbacks can be driven with a fake transport, as shown in protocols and transports. Example, testing a line parser with awkward chunking:

Python A parser test with chunked input

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Force interleavings with events

Race conditions depend on which task runs when. Rather than hoping a sleep produces the order you want, use asyncio.Event objects inside the test to script it exactly: task A waits for an event that the test sets after task B has done its part. The test then asserts the outcome of that specific interleaving. Pair it with a timeout around the whole test, so a deadlock shows up as a failure rather than a frozen build:

Python
async def test_waiter_sees_update():
    ready, proceed = asyncio.Event(), asyncio.Event()

    async def worker():
        ready.set()
        await proceed.wait()
        return "done"

    task = asyncio.create_task(worker())
    async with asyncio.timeout(1):         # never let a test hang forever
        await ready.wait()
        proceed.set()
        assert await task == "done"

A checklist for good async tests

  • Await everything under test, and add a timeout to any test that could wait forever.
  • Test cancellation: start the task, cancel() it, await it and assert that cleanup ran, as in cancelling tasks.
  • Test failure paths: timeouts, connection errors, partial reads, and what happens when one of several concurrent calls fails.
  • Prefer fakes and injected clocks over real sleeps and real servers; keep a few slow integration tests separate.
  • Check for leaked tasks at the end of tests, and turn on debug mode in the test suite so un-awaited coroutines become visible warnings (-W error::RuntimeWarning makes them failures).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does unittest.IsolatedAsyncioTestCase give each test?

    Each test runs in its own new loop, which isolates tests from each other's leftover tasks.
  2. 2. Why inject the sleep function into code that uses backoff?

    A fake sleep returns at once, so a test of several seconds of backoff takes milliseconds.
  3. 3. Which approach is best for testing a line-parsing coroutine that reads from a StreamReader?

    feed_data() lets you script exactly how bytes arrive, including awkward chunk boundaries, with no network.
  4. 4. How can you avoid a deadlocked test freezing your build?

    A timeout turns a hang into a failing test with a traceback.

Summary

  • Run coroutine tests with IsolatedAsyncioTestCase, pytest-asyncio or anyio; every test awaits the code under test.
  • Replace external services with fakes or AsyncMock, and inject clocks and sleep functions so tests never wait.
  • Test streams with feed_data(), protocols with fake transports, and races with events.
  • Use timeouts and a leaked-task check to keep the suite fast and flake-free.

Next: Common asyncio mistakes and how to avoid them