编写高效的 Python 测试

核心原则

每个测试都应是原子的、自包含的，且仅测试单一功能。测试多个行为的用例更难调试与维护。

测试结构

原子化单元测试

每个测试应验证一种行为。测试名称应在失败时清晰表明哪个行为出错。当多个断言均用于验证同一行为时，允许多个断言共存。

# 优秀：名称明确指示失败原因
def test_user_creation_sets_defaults():
    user = User(name="Alice")
    assert user.role == "member"
    assert user.id is not None
    assert user.created_at is not None

# 不佳：若此测试失败，无法判断具体是哪项行为异常？
def test_user():
    user = User(name="Alice")
    assert user.role == "member"
    user.promote()
    assert user.role == "admin"
    assert user.can_delete_others()

对同一概念的不同变体使用参数化

import pytest

@pytest.mark.parametrize("input,expected", [
    ("hello", "HELLO"),
    ("World", "WORLD"),
    ("", ""),
    ("123", "123"),
])
def test_uppercase_conversion(input, expected):
    assert input.upper() == expected

不同功能应使用独立测试

切勿对不相关的功能进行参数化。若测试逻辑存在差异，请分别编写独立测试。

项目特定规则

无需 async 标记

本项目全局启用 asyncio_mode = "auto"。请直接编写异步测试函数，无需额外装饰器：

# 正确写法
async def test_async_operation():
    result = await some_async_function()
    assert result == expected

# 错误写法 —— 请勿添加该装饰器
@pytest.mark.asyncio
async def test_async_operation():
    ...

导入语句置于模块顶层

所有导入语句必须位于文件顶部：

# 正确写法
import pytest
from fastmcp import FastMCP
from fastmcp.client import Client

async def test_something():
    mcp = FastMCP("test")
    ...

# 错误写法 —— 禁止局部导入
async def test_something():
    from fastmcp import FastMCP  # 请勿如此操作
    ...

测试中使用内存传输（in-memory transport）

将 FastMCP 服务实例直接传入客户端：

from fastmcp import FastMCP
from fastmcp.client import Client

mcp = FastMCP("TestServer")

@mcp.tool
def greet(name: str) -> str:
    return f"Hello, {name}!"

async def test_greet_tool():
    async with Client(mcp) as client:
        result = await client.call_tool("greet", {"name": "World"})
        assert result[0].text == "Hello, World!"

仅在显式测试网络相关功能时才使用 HTTP 传输。

复杂数据结构使用内联快照（inline snapshots）

对 JSON Schema 及其他复杂结构的测试，请使用 inline-snapshot：

from inline_snapshot import snapshot

def test_schema_generation():
    schema = generate_schema(MyModel)
    assert schema == snapshot()  # 首次运行时自动填充

常用命令：

• pytest --inline-snapshot=create — 填充空快照
• pytest --inline-snapshot=fix — 在有意变更后更新快照

Fixture

优先使用函数作用域的 fixture

@pytest.fixture
def client():
    return Client()

async def test_with_client(client):
    result = await client.ping()
    assert result is not None

文件操作请使用 tmp_path

def test_file_writing(tmp_path):
    file = tmp_path / "test.txt"
    file.write_text("content")
    assert file.read_text() == "content"

Mocking

在边界处 Mock

from unittest.mock import patch, AsyncMock

async def test_external_api_call():
    with patch("mymodule.external_client.fetch", new_callable=AsyncMock) as mock:
        mock.return_value = {"data": "test"}
        result = await my_function()
        assert result == {"data": "test"}

不要 Mock 自己的代码

尽可能使用真实实现来测试自身代码。仅 Mock 外部服务，而非内部类。

测试命名规范

使用具备描述性的名称，准确表达所测试的场景：

# 优秀
def test_login_fails_with_invalid_password():
def test_user_can_update_own_profile():
def test_admin_can_delete_any_user():

# 不佳
def test_login():
def test_update():
def test_delete():

错误处理测试

import pytest

def test_raises_on_invalid_input():
    with pytest.raises(ValueError, match="must be positive"):
        calculate(-1)

async def test_async_raises():
    with pytest.raises(ConnectionError):
        await connect_to_invalid_host()

运行测试

uv run pytest -n auto              # 并行运行全部测试
uv run pytest -n auto -x           # 首次失败即停止
uv run pytest path/to/test.py      # 运行指定文件
uv run pytest -k "test_name"       # 运行匹配模式的测试
uv run pytest -m "not integration" # 排除集成测试

检查清单

提交测试前请确认：

• 每个测试仅验证一项功能
• 未使用 @pytest.mark.asyncio 装饰器
• 所有导入语句均位于模块顶层
• 测试名称具有充分描述性
• 除非测试网络功能，否则使用内存传输（非 HTTP）
• 对同一行为的不同变体使用参数化
• 不同行为使用独立测试