disknext/tests/integration/QUICK_REFERENCE.md

集成测试快速参考

快速命令

# 运行所有测试
pytest tests/integration/ -v

# 运行特定类别
pytest tests/integration/api/ -v              # 所有 API 测试
pytest tests/integration/middleware/ -v       # 所有中间件测试

# 运行单个文件
pytest tests/integration/api/test_user.py -v

# 运行单个测试
pytest tests/integration/api/test_user.py::test_user_login_success -v

# 生成覆盖率
pytest tests/integration/ --cov --cov-report=html

# 并行运行
pytest tests/integration/ -n auto

# 显示详细输出
pytest tests/integration/ -vv -s

测试文件速查

文件	测试内容	端点前缀
test_site.py	站点配置	/api/site/*
test_user.py	用户操作	/api/user/*
test_admin.py	管理员功能	/api/admin/*
test_directory.py	目录操作	/api/directory/*
test_object.py	对象操作	/api/object/*
test_auth.py	认证中间件	-

常用 Fixtures

# HTTP 客户端
async_client: AsyncClient

# 认证
auth_headers: dict[str, str]          # 普通用户
admin_headers: dict[str, str]         # 管理员

# 数据库
initialized_db: AsyncSession          # 预填充的测试数据库
test_session: AsyncSession            # 空的测试会话

# 用户信息
test_user_info: dict                  # {"username": "testuser", "password": "testpass123"}
admin_user_info: dict                 # {"username": "admin", "password": "adminpass123"}

# 测试数据
test_directory_structure: dict        # {"root_id": UUID, "docs_id": UUID, ...}

# Tokens
test_user_token: str                  # 有效的用户 token
admin_user_token: str                 # 有效的管理员 token
expired_token: str                    # 过期的 token

测试模板

基础 API 测试

import pytest
from httpx import AsyncClient

@pytest.mark.asyncio
async def test_endpoint_name(
    async_client: AsyncClient,
    auth_headers: dict[str, str]
):
    """测试描述"""
    response = await async_client.get(
        "/api/path",
        headers=auth_headers
    )
    assert response.status_code == 200
    data = response.json()
    assert "expected_field" in data

需要测试数据的测试

@pytest.mark.asyncio
async def test_with_data(
    async_client: AsyncClient,
    auth_headers: dict[str, str],
    test_directory_structure: dict[str, UUID]
):
    """使用预创建的测试数据"""
    folder_id = test_directory_structure["docs_id"]
    # 测试逻辑...

认证测试

@pytest.mark.asyncio
async def test_requires_auth(async_client: AsyncClient):
    """测试需要认证"""
    response = await async_client.get("/api/protected")
    assert response.status_code == 401

权限测试

@pytest.mark.asyncio
async def test_requires_admin(
    async_client: AsyncClient,
    auth_headers: dict[str, str]
):
    """测试需要管理员权限"""
    response = await async_client.get(
        "/api/admin/endpoint",
        headers=auth_headers
    )
    assert response.status_code == 403

测试数据

默认用户

• testuser / testpass123 (普通用户)
• admin / adminpass123 (管理员)
• banneduser / banned123 (封禁用户)

目录结构

testuser/
├── docs/
│   ├── images/
│   └── readme.md (1KB)

常见断言

# 状态码
assert response.status_code == 200
assert response.status_code == 401  # 未认证
assert response.status_code == 403  # 权限不足
assert response.status_code == 404  # 不存在
assert response.status_code == 409  # 冲突

# 响应数据
data = response.json()
assert "field" in data
assert data["field"] == expected_value
assert isinstance(data["list"], list)

# 列表长度
assert len(data["items"]) > 0
assert len(data["items"]) <= page_size

# 嵌套数据
assert "nested" in data
assert "field" in data["nested"]

调试技巧

# 显示完整输出
pytest tests/integration/api/test_user.py -vv -s

# 只运行失败的测试
pytest tests/integration/ --lf

# 遇到第一个失败就停止
pytest tests/integration/ -x

# 显示最慢的 10 个测试
pytest tests/integration/ --durations=10

# 使用 pdb 调试
pytest tests/integration/ --pdb

故障排查

问题: 测试全部失败

# 检查依赖
pip install -e .

# 检查 Python 路径
python -c "import sys; print(sys.path)"

问题: JWT 相关错误

# 检查 JWT 密钥是否设置
from utils.JWT import JWT
print(JWT.SECRET_KEY)

问题: 数据库错误

# 确保所有模型都已导入
from models import *

性能基准

预期测试时间（参考）:

• 单个测试: < 1s
• 整个文件: < 10s
• 所有集成测试: < 1min

如果超过这些时间，检查:

1. 数据库连接
2. 异步配置
3. Fixtures 作用域

相关文档

• README.md - 详细的测试文档
• conftest.py - Fixtures 定义
• ../../INTEGRATION_TESTS_SUMMARY.md - 实现总结