iTi-Flask/tests/README.md

# 测试文档

## 📊 测试概览

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

---

## 🚀 运行测试

### 运行所有测试

```bash
uv run --extra dev pytest
```

### 运行特定测试文件

```bash
# 运行 HTTP 工具测试
uv run --extra dev pytest tests/test_http_utils.py

# 运行配置测试
uv run --extra dev pytest tests/test_config.py

# 运行限流器测试
uv run --extra dev pytest tests/test_limiter.py
```

### 运行特定测试类

```bash
# 运行 success() 函数测试
uv run --extra dev pytest tests/test_http_utils.py::TestSuccessFunction

# 运行分页构建器测试
uv run --extra dev pytest tests/test_http_utils.py::TestPaginationBuilder
```

### 运行特定测试用例

```bash
# 运行单个测试
uv run --extra dev pytest tests/test_http_utils.py::TestSuccessFunction::test_success_with_data
```

### 带详细输出

```bash
# 详细模式
uv run --extra dev pytest -v

# 超详细模式
uv run --extra dev pytest -vv
```

---

## 📈 测试覆盖率

### 生成覆盖率报告

```bash
# 运行测试并生成覆盖率报告
uv run --extra dev pytest --cov=iti --cov-report=html
```

### 查看覆盖率报告

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

```bash
# 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` 中添加：

```python
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

```python
@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
```

---

## 🐛 调试测试

### 查看详细输出

```bash
# 显示 print() 输出
uv run --extra dev pytest -s

# 显示局部变量
uv run --extra dev pytest -l

# 进入调试器
uv run --extra dev pytest --pdb
```

### 仅运行失败的测试

```bash
# 首次运行记录结果
uv run --extra dev pytest

# 仅运行上次失败的测试
uv run --extra dev pytest --lf

# 先运行失败的，再运行其他的
uv run --extra dev pytest --ff
```

---

## 📊 持续集成

### GitHub Actions 示例

```yaml
name: Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install uv
        run: curl -LsSf https://astral.sh/uv/install.sh | sh
      - name: Run tests
        run: uv run --extra dev pytest
      - name: Generate coverage
        run: uv run --extra dev pytest --cov=iti --cov-report=html
```

---

## 📚 参考资料

- [Pytest 官方文档](https://docs.pytest.org/)
- [Flask Testing 文档](https://flask.palletsprojects.com/en/latest/testing/)
- [Coverage.py 文档](https://coverage.readthedocs.io/)

---

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