Python异步测试指南pytest-asyncio详解

本文深入讲解了如何正确使用 pytest-asyncio 编写 Python 异步测试，直击新手最易踩坑的核心问题：从必须通过 pyproject.toml 或 pytest.ini 启用 `asyncio_mode = "auto"` 才能让 `async def` 测试函数被自动识别和执行，到避免漏写 `await`、禁用 `asyncio.run()`、精准 mock 异步函数（推荐 `AsyncMock`）、正确声明 async fixture（必须用 `@pytest_asyncio.fixture` 而非 `@pytest.fixture`），再到路径打补丁的陷阱与事件循环隔离的关键细节——帮你绕过静默跳过、协程未执行、mock 失效、fixture 报错等典型故障，真正实现简洁、稳定、可维护的异步单元测试。

pytest-asyncio 怎么启用才能跑 async 测试函数

不显式启用，pytest-asyncio 会直接跳过 async def 测试函数，报错提示 “not a coroutine” 或干脆静默忽略——它默认只认同步函数。

必须在项目根目录加 pytest.ini、pyproject.toml 或 setup.cfg 做配置，让 pytest 知道要接管异步测试：

• pytest.ini 中写：

  [tool:pytest]
  asyncio_mode = auto

• 或 pyproject.toml（推荐）：

  [tool.pytest.ini_options]
  asyncio_mode = "auto"

• 不用改代码、不用装饰器，async def test_xxx() 就能被自动识别并 await 执行
• auto 模式会自动判断函数是否为协程；也可用 strict，但要求所有测试都显式标记（更重，不推荐新手）

async 测试里怎么调用被测异步函数又不卡住

直接 await 就行，但得确保测试函数本身是 async def，且运行环境支持事件循环——pytest-asyncio 已帮你管好了循环生命周期。

常见错误是混用同步写法，比如在 async def 测试里写 my_async_func()（漏掉 await），结果返回一个 coroutine 对象，断言失败或类型错乱。

• ✅ 正确：

  async def test_fetch_data():
      result = await fetch_from_api("https://httpbin.org/json")
      assert "json" in result

• ❌ 错误：result = fetch_from_api(...) —— 这只是创建协程对象，没执行
• 别在测试里手动 asyncio.run()：pytest 已管理循环，重复启动会报 RuntimeError: asyncio.run() cannot be called from a running event loop
• 如果被测函数依赖外部服务，务必 mock，否则测试变集成测试，慢且不稳定

mock 异步函数时为什么 patch 不生效

因为普通 unittest.mock.patch 默认不处理协程，打补丁后返回的仍是普通 Mock 对象，await 它会报 TypeError: object MagicMock can't be used in 'await' expression。

必须让 mock 对象本身可 await，有两种可靠方式：

• 用 AsyncMock（Python 3.8+）：

  from unittest.mock import AsyncMock
  ...
  mock_fetch = AsyncMock(return_value={"ok": True})
  with patch("mymodule.fetch_data", mock_fetch):
      await test_target()

• 或给普通 Mock 设置 return_value 为协程：

  m = Mock()
  m.return_value = asyncio.sleep(0, result="done")  # 注意：返回真协程，不是 awaitable 对象

• patch 路径一定要对：是“被测试代码里 import 的位置”，不是函数定义的位置。比如 test_module.py 里写了 from api import fetch，就得 @patch("test_module.fetch")，不是 "api.fetch"

测试 fixture 怎么支持 async 初始化和清理

pytest 的 @pytest.fixture 默认不支持 async def，直接写会报 Fixture function has keyword 'async' but it's not marked as async。

解决方案只有两个，且不能混用：

• 用 pytest-asyncio 提供的 @pytest_asyncio.fixture（注意不是 @pytest.fixture）：

  import pytest_asyncio
  <p>@pytest_asyncio.fixture
  async def db_pool():
  pool = await create_pool()
  yield pool
  await pool.close()</p>

• 或者退回到同步 fixture + 内部 asyncio.run()（仅限简单、无循环依赖场景）：

  @pytest.fixture
  def db_pool():
      pool = asyncio.run(create_pool())
      yield pool
      asyncio.run(pool.close())

• ⚠️ 别用 @pytest.fixture + async def：语法合法但行为未定义，pytest 可能直接忽略或报错
• fixture 之间依赖时，async fixture 只能依赖其他 async fixture，不能跨 sync/async 边界

最常被忽略的是事件循环隔离问题：多个测试共用一个 loop 时，前一个测试没 clean 掉任务，后一个可能看到残留状态。建议每个测试用独立 asyncio.new_event_loop()（pytest-asyncio 默认已做），但自定义 fixture 里若手动操作 loop，就得格外小心。

今天关于《Python异步测试指南pytest-asyncio详解》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！