How to Test Async Functions with pytest: Simple Guide

To test async functions in pytest, use the pytest-asyncio plugin and mark your test with @pytest.mark.asyncio. Then write your test as an async def function and use await to call the async function inside it.

Syntax

Use the @pytest.mark.asyncio decorator to tell pytest that the test function is asynchronous. Define the test function with async def. Inside the test, use await to call the async function you want to test.

• @pytest.mark.asyncio: Marks the test as async.
• async def: Defines an asynchronous test function.
• await: Waits for the async function to complete.

python

import pytest

@pytest.mark.asyncio
async def test_async_function():
    result = await async_function_to_test()
    assert result == expected_value

Example

This example shows how to test a simple async function that returns a greeting string. The test uses pytest-asyncio to run the async test and asserts the returned value.

python

import pytest
import asyncio

async def greet(name: str) -> str:
    await asyncio.sleep(0.1)  # simulate async work
    return f"Hello, {name}!"

@pytest.mark.asyncio
async def test_greet():
    result = await greet("Alice")
    assert result == "Hello, Alice!"

Output

============================= test session starts =============================
collected 1 item

test_async.py .                                                           [100%]

============================== 1 passed in 0.12s ==============================

Common Pitfalls

Common mistakes when testing async functions include:

• Not using @pytest.mark.asyncio on async test functions, causing pytest to treat them as normal functions and fail.
• Forgetting to await the async function call, which returns a coroutine instead of the result.
• Using synchronous test functions to test async code, which leads to errors or warnings.

python

import pytest
import asyncio

async def greet(name: str) -> str:
    await asyncio.sleep(0.1)  # simulate async work
    return f"Hello, {name}!"

# Wrong: missing @pytest.mark.asyncio and no await
async def test_wrong():
    result = greet("Bob")  # Missing await
    assert result == "Hello, Bob!"

# Right:
@pytest.mark.asyncio
async def test_right():
    result = await greet("Bob")
    assert result == "Hello, Bob!"

Quick Reference

Step	Description
Install pytest-asyncio	Run pip install pytest-asyncio to add async support.
Mark test async	Use @pytest.mark.asyncio on async test functions.
Define async test	Write test functions with async def.
Await async calls	Use await to call async functions inside tests.
Run tests	Run pytest as usual to execute async tests.

Key Takeaways

Use the pytest-asyncio plugin to enable async test support in pytest.

Mark async test functions with @pytest.mark.asyncio and define them with async def.

Always await async function calls inside your async test functions.

Forgetting to mark tests or await calls causes test failures or errors.

Run pytest normally after setup; async tests run seamlessly with pytest-asyncio.