# 测试文档

## 测试覆盖率

当前测试覆盖率：**99%** ✓

```
Name                          Stmts   Miss  Cover
-----------------------------------------------------------
src/agentcenter/__init__.py       3      0   100%
src/agentcenter/cli.py           38      1    97%
src/agentcenter/config.py        10      0   100%
src/agentcenter/core.py          17      0   100%
src/agentcenter/utils.py         13      0   100%
-----------------------------------------------------------
TOTAL                            81      1    99%
```

**注意：** 唯一未覆盖的代码是 `cli.py` 第93行的 `sys.exit(main())`，这是 `if __name__ == "__main__"` 块，通常不需要测试覆盖。

---

## 测试结构

### 测试文件

```
tests/
├── __init__.py
├── test_cli.py       - CLI 接口测试 (20个测试)
├── test_config.py    - 配置管理测试 (14个测试)
├── test_core.py      - 核心功能测试 (5个测试)
└── test_utils.py     - 工具函数测试 (17个测试)
```

**总计：56 个测试，全部通过 ✓**

---

## 运行测试

### 基本测试

```bash
# 运行所有测试
uv run pytest

# 运行特定测试文件
uv run pytest tests/test_config.py

# 运行特定测试函数
uv run pytest tests/test_config.py::test_settings_default_values
```

### 带覆盖率的测试

```bash
# 运行测试并显示覆盖率
uv run pytest --cov=agentcenter --cov-report=term-missing

# 生成 HTML 覆盖率报告
uv run pytest --cov=agentcenter --cov-report=html

# 查看 HTML 报告
open htmlcov/index.html
```

### 详细输出

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

# 显示打印输出
uv run pytest -s

# 详细模式 + 覆盖率
uv run pytest -v --cov=agentcenter --cov-report=term-missing
```

---

## 测试用例说明

### test_cli.py - CLI 接口测试

测试命令行接口的各种场景：

- ✓ 单消息模式
- ✓ 交互模式（quit/exit/q）
- ✓ 自定义 agent 名称
- ✓ Debug 模式
- ✓ 键盘中断处理
- ✓ 异常处理
- ✓ 帮助和版本信息

**示例：**
```python
def test_main_with_message():
    """Test main with a single message."""
    exit_code = main(["Test message"])
    assert exit_code == 0
```

---

### test_config.py - 配置管理测试

测试 Pydantic Settings 配置系统：

- ✓ 默认值
- ✓ 自定义值
- ✓ 环境变量读取
- ✓ .env 文件读取
- ✓ 布尔值转换
- ✓ 类型验证
- ✓ 配置优先级

**示例：**
```python
def test_settings_from_env_vars(monkeypatch):
    """Test Settings reads from environment variables."""
    monkeypatch.setenv("APP_NAME", "Env App")
    settings = Settings()
    assert settings.app_name == "Env App"
```

---

### test_core.py - 核心功能测试

测试 AgentCenter 类的核心功能：

- ✓ 初始化
- ✓ 添加消息
- ✓ 处理消息
- ✓ 获取消息历史
- ✓ 清除消息

**示例：**
```python
def test_process():
    """Test processing input."""
    agent = AgentCenter()
    response = agent.process("Test input")
    assert "Processed" in response
```

---

### test_utils.py - 工具函数测试

测试各种工具函数：

#### validate_input 测试
- ✓ 有效输入
- ✓ 无效输入（空字符串、过长）
- ✓ 边界情况
- ✓ 空格处理
- ✓ 非字符串类型
- ✓ 自定义长度限制

#### format_response 测试
- ✓ 空字典
- ✓ 单项
- ✓ 多项
- ✓ 不同值类型

#### setup_logging 测试
- ✓ 各种日志级别（DEBUG, INFO, WARNING, ERROR, CRITICAL）
- ✓ 大小写不敏感
- ✓ 默认级别

**示例：**
```python
def test_validate_input_edge_cases():
    """Test input validation edge cases."""
    assert validate_input("A", min_length=1) is True
    assert validate_input("A" * 1001, max_length=1000) is False
```

---

## 测试最佳实践

### 1. 使用 pytest fixtures

```python
def test_with_env_vars(monkeypatch):
    """Use monkeypatch for environment variables."""
    monkeypatch.setenv("DEBUG", "true")
    # Test code here
```

### 2. 使用 mock 隔离外部依赖

```python
from unittest.mock import Mock, patch

def test_with_mock():
    with patch("builtins.input", return_value="quit"):
        # Test code here
```

### 3. 测试边界情况

```python
def test_edge_cases():
    # Test minimum
    assert validate_input("A", min_length=1) is True

    # Test maximum
    assert validate_input("A" * 1000, max_length=1000) is True

    # Test just over limit
    assert validate_input("A" * 1001, max_length=1000) is False
```

### 4. 测试异常处理

```python
def test_exception_handling():
    with pytest.raises(ValueError):
        # Code that should raise ValueError
```

---

## 持续集成

### GitHub Actions 示例

创建 `.github/workflows/test.yml`：

```yaml
name: Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.12'
      - name: Install uv
        run: curl -LsSf https://astral.sh/uv/install.sh | sh
      - name: Install dependencies
        run: uv sync --group dev
      - name: Run tests
        run: uv run pytest --cov=agentcenter --cov-report=term-missing
      - name: Check coverage
        run: uv run pytest --cov=agentcenter --cov-fail-under=80
```

---

## 测试命令快速参考

```bash
# 基本测试
uv run pytest                                    # 运行所有测试
uv run pytest -v                                 # 详细输出
uv run pytest -k test_config                     # 运行名称匹配的测试

# 覆盖率
uv run pytest --cov=agentcenter                  # 显示覆盖率
uv run pytest --cov=agentcenter --cov-report=html # HTML 报告
uv run pytest --cov-fail-under=80                # 覆盖率低于80%则失败

# 调试
uv run pytest -s                                 # 显示打印输出
uv run pytest --pdb                              # 失败时进入调试器
uv run pytest -x                                 # 第一个失败后停止

# 特定测试
uv run pytest tests/test_cli.py                  # 运行特定文件
uv run pytest tests/test_cli.py::test_main       # 运行特定函数
```

---

## 测试覆盖率目标

- ✓ **总体覆盖率**: 99% (目标: 80%+)
- ✓ **核心模块**: 100%
- ✓ **配置模块**: 100%
- ✓ **工具模块**: 100%
- ✓ **CLI 模块**: 97% (排除 `if __name__ == "__main__"` 块)

---

## 添加新测试

### 步骤

1. 在 `tests/` 目录创建或编辑测试文件
2. 使用 `test_` 前缀命名测试函数
3. 编写清晰的文档字符串
4. 运行测试确保通过
5. 检查覆盖率

### 示例

```python
def test_new_feature():
    """Test description here."""
    # Arrange - 准备测试数据
    agent = AgentCenter()

    # Act - 执行被测试的代码
    result = agent.some_method()

    # Assert - 验证结果
    assert result == expected_value
```

---

## 常见问题

### Q: 如何测试需要用户输入的代码？

使用 `patch` mock `builtins.input`：

```python
from unittest.mock import patch

def test_user_input():
    with patch("builtins.input", return_value="test"):
        # Your test code
```

### Q: 如何测试环境变量？

使用 pytest 的 `monkeypatch` fixture：

```python
def test_with_env(monkeypatch):
    monkeypatch.setenv("MY_VAR", "value")
    # Your test code
```

### Q: 如何测试日志输出？

使用 pytest 的 `caplog` fixture：

```python
def test_logging(caplog):
    with caplog.at_level(logging.INFO):
        logger.info("Test message")
        assert "Test message" in caplog.text
```

---

## 总结

- ✅ 56 个测试全部通过
- ✅ 99% 代码覆盖率（超过80%目标）
- ✅ 全面的测试套件覆盖所有模块
- ✅ 遵循测试最佳实践
- ✅ 易于维护和扩展

运行 `uv run pytest -v --cov=agentcenter --cov-report=term-missing` 查看完整测试结果！
