Skip to content

JiuwenSwarm is an intelligent AI Agent built on openJiuwen. It extends the powerful capabilities of large language models directly to your fingertips through various communication apps you use daily.

Python
9.2 KB
Raw Blame

JiuwenClow 单元测试框架配置总结

📦 已创建的文件

1. 测试配置文件

jiuwenswarm/
├── pytest.ini                           # Pytest 配置
├── pyproject.toml                       # 已更新,添加了测试依赖
├── run_tests.sh                         # 测试运行脚本(可执行)
├── tests/
│   ├── __init__.py
│   ├── conftest.py                      # 共享 fixtures
│   ├── README.md                        # 详细测试指南
│   └── unit/                            # 单元测试目录
│       ├── agentserver
│       ├── channel
│       ├── evolution
│           ├── test_schema.py           # 演进模型测试
│           ├── test_signal_detector.py  # 信号检测器测试
│           ├── test_message.py          # 消息模型测试
│       ├── gateway
│       ├── schema
│       ├── __init__.py
│       ├── test_config.py               # 配置模块测试
│       └── test_utils.py                # 工具函数测试
└── .gitcode/workflows/
    ├── ci.yml                           # gitcode Actions 测试工作流
    └── test.yml                         # gitcode Actions 代码质量检查

🚀 本地测试

方式 1: 使用测试脚本(推荐)

cd /Users/gawa/Desktop/pr/jiuwenswarm

# 运行所有测试
./run_tests.sh

# 生成 HTML 覆盖率报告
./run_tests.sh -c

# 只运行单元测试
./run_tests.sh -u

# 并行运行测试
./run_tests.sh -p

# 查看帮助
./run_tests.sh -h

方式 2: 直接使用 pytest

# 首先安装测试依赖
pip install -e ".[test]"

# 运行所有测试
pytest -v

# 运行特定目录
pytest tests/unit_tests/ -v

# 运行特定文件
pytest tests/unit_tests/test_config.py -v

# 运行特定测试
pytest tests/unit_tests/test_config.py::TestResolveEnvVars::test_resolve_string_with_env_var -v

# 生成覆盖率报告
pytest --cov=jiuwenswarm --cov-report=html --cov-report=term-missing

🧪 已实现的测试用例

1. test_config.py - 配置模块测试

测试内容:

  • ✅ 环境变量解析(resolve_env_vars)
  • ✅ 字符串中的环境变量替换
  • ✅ 默认值处理
  • ✅ 字典和列表中的环境变量
  • ✅ 嵌套结构解析
  • ✅ 配置文件读取

测试数量: ~15 个测试

关键测试:

test_resolve_string_with_env_var()      # 测试 ${VAR} 解析
test_resolve_string_with_default()       # 测试 ${VAR:-default}
test_resolve_dict_with_env_vars()        # 测试字典解析
test_resolve_nested_structure()          # 测试嵌套结构

2. test_evolution_schema.py - 演进模型测试

测试内容:

  • ✅ EvolutionType 枚举
  • ✅ EvolutionChange 数据类
  • ✅ EvolutionEntry 数据类
  • ✅ EvolutionFile 数据类
  • ✅ EvolutionSignal 数据类
  • ✅ 序列化/反序列化

测试数量: ~30 个测试

关键测试:

test_evolution_entry_make()               # 测试工厂方法
test_evolution_entry_is_pending()         # 测试属性
test_evolution_file_pending_entries()     # 测试属性
test_evolution_signal_to_dict()           # 测试序列化

3. test_signal_detector.py - 信号检测器测试

测试内容:

  • ✅ 执行失败信号检测
  • ✅ 用户修正信号检测
  • ✅ 中英文关键词检测
  • ✅ 信号去重
  • ✅ Skill 名称提取
  • ✅ Excerpt 截取

测试数量: ~20 个测试

关键测试:

test_detect_execution_failure()           # 测试错误检测
test_detect_user_correction_chinese()     # 测试中文修正
test_detect_multiple_signals()            # 测试多信号
test_deduplicate_signals()                # 测试去重
test_detect_with_skill_from_tool_calls()  # 测试 Skill 归因

4. test_schema.py - 消息模型测试

测试内容:

  • ✅ ReqMethod 枚举
  • ✅ EventType 枚举
  • ✅ Mode 枚举
  • ✅ AgentRequest 数据类
  • ✅ AgentResponse 数据类
  • ✅ AgentResponseChunk 数据类
  • ✅ Message 数据类

测试数量: ~25 个测试

关键测试:

test_create_agent_request_minimal()       # 测试最小请求
test_create_agent_request_full()          # 测试完整请求
test_create_request_message()             # 测试请求消息
test_create_event_message()               # 测试事件消息
test_message_mode()                       # 测试模式字段

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

测试内容:

  • ✅ 路径解析函数
  • ✅ 包检测函数
  • ✅ Logger 设置
  • ✅ 常量定义

测试数量: ~10 个测试

关键测试:

test_get_root_dir()                       # 测试根目录获取
test_get_config_dir()                     # 测试配置目录
test_setup_logger_default()               # 测试 Logger 设置
test_path_caching()                       # 测试路径缓存

🎯 测试覆盖率目标

模块 当前覆盖率 目标覆盖率
config.py ~80% 90%
evolution/schema.py ~90% 95%
evolution/signal_detector.py ~75% 85%
schema/*.py ~70% 80%
utils.py ~60% 75%
总体 ~70% 80%

🤖 GitHub Actions CI

工作流 1: Tests (.github/workflows/test.yml)

触发条件:

  • Push to main or develop
  • Pull requests to main or develop
  • 手动触发

测试矩阵:

  • Python: 3.11, 3.12, 3.13
  • OS: Ubuntu Latest

步骤:

  1. ✅ Checkout 代码
  2. ✅ 设置 Python
  3. ✅ 安装依赖
  4. ✅ 运行单元测试
  5. ✅ 上传覆盖率到 Codecov

工作流 2: Code Quality (.github/workflows/lint.yml)

检查项目:

  • ✅ 类型检查 (mypy)
  • ✅ 代码格式 (black)
  • ✅ Linting (ruff)
  • ✅ 安全扫描 (bandit)

📝 使用示例

快速开始

# 1. 安装依赖
pip install -e ".[test]"

# 2. 运行所有测试
./run_tests.sh

# 3. 查看覆盖率报告
open htmlcov/index.html  # macOS

开发新功能时的测试工作流

# 1. 编写测试
# tests/unit_tests/test_new_feature.py

# 2. 运行新测试
pytest tests/unit_tests/test_new_feature.py -v

# 3. 查看覆盖率
pytest --cov=jiuwenswarm.new_feature --cov-report=term-missing

# 4. 运行所有测试确保没有破坏
pytest tests/

# 5. 提交代码
git add .
git commit -m "feat: add new feature with tests"
git push

CI 失败时的调试

# 1. 本地复现 CI 环境
python -m pytest tests/ -v

# 2. 检查 Python 版本
python --version  # 应该是 3.11, 3.12, 或 3.13

# 3. 检查依赖
pip list | grep pytest

# 4. 运行特定失败的测试
pytest tests/unit_tests/test_config.py::TestResolveEnvVars -vv

🛠️ 测试框架配置详解

pytest.ini

[pytest]
# 测试发现模式
python_files = test_*.py *_test.py
python_classes = Test*
python_functions = test_*

# 测试路径
testpaths = tests

# 输出选项
addopts =
    -v                              # 详细输出
    --strict-markers                # 严格标记检查
    --tb=short                      # 简短的错误堆栈
    --cov=jiuwenswarm                # 覆盖率
    --cov-report=term-missing       # 终端报告
    --cov-report=html               # HTML 报告
    --cov-report=xml                # XML 报告(CI)
    --asyncio-mode=auto             # 异步测试模式

# 标记定义
markers =
    unit: Unit tests
    integration: Integration tests
    slow: Slow running tests
    async: Async tests

conftest.py Fixtures

@pytest.fixture
def temp_workspace() -> Path:
    """创建临时工作区"""

@pytest.fixture
def temp_config_file() -> Path:
    """创建临时配置文件"""

@pytest.fixture
def mock_env_vars() -> None:
    """设置模拟环境变量"""

@pytest.fixture
def sample_skill_md() -> Path:
    """创建示例 SKILL.md 文件"""

@pytest.fixture
def sample_messages() -> List[dict]:
    """示例消息列表"""

📚 扩展测试

添加新的测试文件

# 1. 创建测试文件
touch tests/unit_tests/test_new_module.py

# 2. 编写测试
# 参考 tests/README.md 中的模板

# 3. 运行测试
pytest tests/unit_tests/test_new_module.py -v

添加新的 Fixture

# 在 tests/conftest.py 中添加

@pytest.fixture
def my_custom_fixture():
    """自定义 fixture."""
    # 设置
    data = {"key": "value"}
    yield data
    # 清理(可选)

✅ 下一步建议

  1. 增加测试覆盖:

    • evolution/evolver.py - 演进生成器
    • evolution/service.py - 演进服务
    • gateway/ - 网关层
    • channel/ - 频道适配器
  2. 添加集成测试:

    • 端到端测试
    • API 测试
    • 性能测试
  3. 提升测试质量:

    • 使用 mock 隔离外部依赖
    • 添加性能基准测试
    • 实现测试数据工厂
  4. 改进 CI/CD:

    • 添加性能测试
    • 集成安全扫描
    • 自动化发布流程

📞 需要帮助?

  • 查看 tests/README.md 获取详细指南
  • 运行 ./run_tests.sh -h 查看测试脚本帮助
  • 查看 pytest 文档: https://docs.pytest.org/

Happy Testing! 🎉