disknext/tests/integration

集成测试文档

概述

本目录包含 DiskNext Server 的集成测试，测试覆盖主要的 API 端点和中间件功能。

测试结构

tests/integration/
├── conftest.py                    # 测试配置和 fixtures
├── api/                           # API 端点测试
│   ├── test_site.py              # 站点配置测试
│   ├── test_user.py              # 用户相关测试
│   ├── test_admin.py             # 管理员端点测试
│   ├── test_directory.py         # 目录操作测试
│   └── test_object.py            # 对象操作测试
└── middleware/                    # 中间件测试
    └── test_auth.py              # 认证中间件测试

运行测试

运行所有集成测试

pytest tests/integration/

运行特定测试文件

# 测试站点端点
pytest tests/integration/api/test_site.py

# 测试用户端点
pytest tests/integration/api/test_user.py

# 测试认证中间件
pytest tests/integration/middleware/test_auth.py

运行特定测试函数

pytest tests/integration/api/test_user.py::test_user_login_success

显示详细输出

pytest tests/integration/ -v

生成覆盖率报告

# 生成终端报告
pytest tests/integration/ --cov

# 生成 HTML 报告
pytest tests/integration/ --cov --cov-report=html

并行运行测试

pytest tests/integration/ -n auto

测试 Fixtures

数据库相关

• test_db_engine: 测试数据库引擎（内存 SQLite）
• test_session: 测试数据库会话
• initialized_db: 已初始化的测试数据库（包含基础数据）

用户相关

• test_user_info: 测试用户信息（username, password）
• admin_user_info: 管理员用户信息
• banned_user_info: 封禁用户信息

认证相关

• test_user_token: 测试用户的 JWT token
• admin_user_token: 管理员的 JWT token
• expired_token: 过期的 JWT token
• auth_headers: 测试用户的认证头
• admin_headers: 管理员的认证头

客户端

• async_client: 异步 HTTP 测试客户端

测试数据

• test_directory_structure: 测试目录结构（包含文件夹和文件）

测试覆盖范围

API 端点测试

/api/site/* (test_site.py)

• ✅ Ping 端点
• ✅ 站点配置端点
• ✅ 配置字段验证

/api/user/* (test_user.py)

• ✅ 用户登录（成功、失败、封禁用户）
• ✅ 用户注册（成功、重复用户名）
• ✅ 获取用户信息（需要认证）
• ✅ 获取存储信息
• ✅ 两步验证初始化和启用
• ✅ 用户设置

/api/admin/* (test_admin.py)

• ✅ 认证检查（需要管理员权限）
• ✅ 获取用户列表（带分页）
• ✅ 获取用户信息
• ✅ 创建用户
• ✅ 用户组管理
• ✅ 文件管理
• ✅ 设置管理

/api/directory/* (test_directory.py)

• ✅ 获取根目录
• ✅ 获取嵌套目录
• ✅ 权限检查（不能访问他人目录）
• ✅ 创建目录（成功、重名、无效父目录）
• ✅ 目录名验证（不能包含斜杠）

/api/object/* (test_object.py)

• ✅ 删除对象（单个、批量、他人对象）
• ✅ 移动对象（成功、无效目标、移动到文件）
• ✅ 权限检查（不能操作他人对象）
• ✅ 重名检查

中间件测试

认证中间件 (test_auth.py)

• ✅ AuthRequired: 无 token、无效 token、过期 token
• ✅ AdminRequired: 非管理员用户返回 403
• ✅ Token 格式验证
• ✅ 用户不存在处理

测试数据

默认用户

1. 测试用户

   • 用户名: testuser
   • 密码: testpass123
   • 用户组: 默认用户组
   • 状态: 正常

2. 管理员

   • 用户名: admin
   • 密码: adminpass123
   • 用户组: 管理员组
   • 状态: 正常

3. 封禁用户

   • 用户名: banneduser
   • 密码: banned123
   • 用户组: 默认用户组
   • 状态: 封禁

测试目录结构

testuser/                # 根目录
├── docs/               # 文件夹
│   ├── images/        # 子文件夹
│   └── readme.md      # 文件 (1KB)

注意事项

1. 测试隔离: 每个测试使用独立的内存数据库，互不影响
2. 异步测试: 所有测试使用 @pytest.mark.asyncio 装饰器
3. 依赖覆盖: 测试客户端自动覆盖数据库依赖，使用测试数据库
4. JWT 密钥: 测试环境使用固定密钥 test_secret_key_for_jwt_token_generation

添加新测试

1. 创建测试文件

在 tests/integration/api/ 或 tests/integration/middleware/ 下创建新的测试文件。

2. 导入必要的依赖

import pytest
from httpx import AsyncClient

3. 编写测试函数

@pytest.mark.asyncio
async def test_your_feature(
    async_client: AsyncClient,
    auth_headers: dict[str, str]
):
    """测试描述"""
    response = await async_client.get(
        "/api/your/endpoint",
        headers=auth_headers
    )
    assert response.status_code == 200

4. 使用 fixtures

利用 conftest.py 提供的 fixtures：

@pytest.mark.asyncio
async def test_with_directory_structure(
    async_client: AsyncClient,
    auth_headers: dict[str, str],
    test_directory_structure: dict[str, UUID]
):
    """使用测试目录结构"""
    root_id = test_directory_structure["root_id"]
    # ... 测试逻辑

故障排除

测试失败：数据库初始化错误

检查是否所有必要的模型都已导入到 conftest.py 中。

测试失败：JWT 密钥未设置

确保 initialized_db fixture 正确设置了 JWT.SECRET_KEY。

测试失败：认证失败

检查 token 生成逻辑是否使用正确的密钥和用户名。

持续集成

建议在 CI/CD 流程中运行集成测试：

# .github/workflows/test.yml
- name: Run integration tests
  run: |
    pytest tests/integration/ -v --cov --cov-report=xml

- name: Upload coverage
  uses: codecov/codecov-action@v3
  with:
    file: ./coverage.xml