iTi-Flask/tests/README.md

测试文档

📊 测试概览

测试文件	测试数量	覆盖模块	状态
test_config.py	7	配置管理	✅ 通过
test_limiter.py	6	限流器	✅ 通过
test_http_utils.py	33	HTTP 响应工具	✅ 通过
总计	46	-	✅ 全部通过

---

🚀 运行测试

运行所有测试

hatch run test

运行特定测试文件

# 运行 HTTP 工具测试
hatch run test tests/test_http_utils.py

# 运行配置测试
hatch run test tests/test_config.py

# 运行限流器测试
hatch run test tests/test_limiter.py

运行特定测试类

# 运行 success() 函数测试
hatch run test tests/test_http_utils.py::TestSuccessFunction

# 运行分页构建器测试
hatch run test tests/test_http_utils.py::TestPaginationBuilder

运行特定测试用例

# 运行单个测试
hatch run test tests/test_http_utils.py::TestSuccessFunction::test_success_with_data

带详细输出

# 详细模式
hatch run test -v

# 超详细模式
hatch run test -vv

---

📈 测试覆盖率

生成覆盖率报告

# 运行测试并生成覆盖率报告
hatch run cov

查看覆盖率报告

覆盖率报告会生成在 htmlcov/ 目录：

# Windows
start htmlcov/index.html

# macOS
open htmlcov/index.html

# Linux
xdg-open htmlcov/index.html

---

📝 测试文件说明

test_config.py - 配置测试

测试内容：

• ✅ 开发环境配置
• ✅ 测试环境配置
• ✅ 生产环境配置
• ✅ 配置类定义
• ✅ 配置获取函数
• ✅ 应用创建
• ✅ 应用上下文

测试类：

• TestConfig2: 配置类测试

---

test_limiter.py - 限流器测试

测试内容：

• ✅ 测试环境禁用限流
• ✅ 开发环境限流配置
• ✅ 生产环境限流配置
• ✅ 限流器初始化
• ✅ 自定义限流配置
• ✅ 禁用限流配置

---

test_http_utils.py - HTTP 工具测试

测试内容：

• ✅ success() 函数（6 个测试）
• ✅ fail() 函数（5 个测试）
• ✅ pagination_builder() 函数（6 个测试）
• ✅ page() 函数（7 个测试）
• ✅ Schema 定义（2 个测试）
• ✅ Flask 集成（4 个测试）
• ✅ 边界情况（5 个测试）

测试类：

• TestSuccessFunction: success() 函数测试
• TestFailFunction: fail() 函数测试
• TestPaginationBuilder: pagination_builder() 测试
• TestPageFunction: page() 函数测试
• TestSchemaDefinitions: Schema 定义测试
• TestIntegrationWithFlaskApp: Flask 集成测试
• TestEdgeCases: 边界情况测试

详细测试列表：

success() 函数测试

1. ✅ test_success_default - 默认参数
2. ✅ test_success_with_data - 带数据
3. ✅ test_success_with_custom_msg - 自定义消息
4. ✅ test_success_with_custom_code - 自定义状态码
5. ✅ test_success_with_list - 列表数据
6. ✅ test_success_with_none_data - None 数据

fail() 函数测试

1. ✅ test_fail_default - 默认参数
2. ✅ test_fail_with_custom_msg - 自定义消息
3. ✅ test_fail_with_custom_code - 自定义状态码
4. ✅ test_fail_with_data - 带额外数据
5. ✅ test_fail_returns_dict - 返回字典

pagination_builder() 测试

1. ✅ test_manual_mode_basic - 手动模式基础
2. ✅ test_manual_mode_auto_calculate_pages - 自动计算页数
3. ✅ test_manual_mode_with_explicit_pages - 显式指定页数
4. ✅ test_manual_mode_zero_total - 总数为 0
5. ✅ test_manual_mode_urls_are_none_outside_request - 请求上下文外 URL
6. ✅ test_auto_mode_with_mock_pagination - 自动模式

page() 函数测试

1. ✅ test_page_with_list_and_dict - 列表 + 字典
2. ✅ test_page_with_custom_msg - 自定义消息
3. ✅ test_page_with_custom_code - 自定义状态码
4. ✅ test_page_with_mock_pagination_object - Pagination 对象
5. ✅ test_page_with_items_and_pagination_object - 数据 + Pagination
6. ✅ test_page_empty_items - 空数据列表
7. ✅ test_page_with_large_total - 大数据量

Flask 集成测试

1. ✅ test_success_in_route - success() 在路由中
2. ✅ test_fail_in_route - fail() 在路由中
3. ✅ test_page_in_route - page() 在路由中
4. ✅ test_index_with_schema - Schema 验证

---

✍️ 编写测试

测试规范

1. 文件命名: test_*.py
2. 类命名: Test*（可选）
3. 函数命名: test_*
4. 使用 pytest: 使用 pytest 而非 unittest
5. 使用 fixtures: 复用测试设置

示例：添加新测试

在 tests/test_http_utils.py 中添加：

import pytest
from iti.applications.common.utils import success

class TestMyNewFeature:
    """测试新功能"""
    
    def test_my_feature(self):
        """测试我的功能"""
        result = success({'key': 'value'})
        assert result['code'] == 200
        assert result['data']['key'] == 'value'

使用 Fixtures

@pytest.fixture
def app():
    """创建测试应用"""
    from iti.applications import create_app
    return create_app('test')

@pytest.fixture
def client(app):
    """创建测试客户端"""
    return app.test_client()

def test_with_fixture(client):
    """使用 fixture 测试"""
    response = client.get('/')
    assert response.status_code == 200

---

🐛 调试测试

查看详细输出

# 显示 print() 输出
hatch run test -s

# 显示局部变量
hatch run test -l

# 进入调试器
hatch run test --pdb

仅运行失败的测试

# 首次运行记录结果
hatch run test

# 仅运行上次失败的测试
hatch run test --lf

# 先运行失败的，再运行其他的
hatch run test --ff

---

📊 持续集成

GitHub Actions 示例

name: Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install Hatch
        run: pip install hatch
      - name: Run tests
        run: hatch run test
      - name: Generate coverage
        run: hatch run cov

---

📚 参考资料

• Pytest 官方文档
• Flask Testing 文档
• Coverage.py 文档

---

最后更新： 2025-10-14
维护者： iTi-Flask Team