测试指南

框架

模块	框架	目录
Python 核心	pytest	tests/
Web 后端	pytest	tests/
Web UI	vitest	web-ui/src/__tests__/

测试文件列表

Python 核心 (tests/)

文件	说明
test_agent_loop.py	ReAct 循环、历史压缩
test_tools.py	各工具执行、权限校验
test_sandbox.py	PathValidator、CommandValidator
test_auto_dream.py	Dream 记忆提取、阈值触发、去重
test_ingest.py	双阶段知识库摄取
test_mailbox.py	邮箱读写、FileLock
test_channel.py	频道抽象、消息路由
test_llm.py	LLM 调用、重试、多 provider 切换

Web 后端 (tests/)

文件	说明
test_auth.py	JWT 签发、验证、刷新
test_agents_api.py	Agent CRUD
test_scenes_api.py	场景 CRUD
test_knowledge_api.py	知识库 API
test_channels_api.py	频道配置 API

运行测试

全部测试

# Python
pytest tests/ -v

# Web UI
cd web-ui && npx vitest run

单个测试

# Python
pytest tests/test_tools.py -v
pytest tests/test_tools.py::test_path_validator -v

# Web UI
cd web-ui && npx vitest run -- src/__tests__/auth.test.ts

CI Pipeline

# .github/workflows/ci.yml
jobs:
  test:
    steps:
      - uses: actions/checkout@v3
      - name: Python tests
        run: pytest tests/ -v
      - name: Web UI tests
        run: cd web-ui && npx vitest run
      - name: Lint
        run: |
          ruff check cococat/

编写测试的原则

1. 隔离: 每个测试独立，使用临时目录 (tmp_path fixture)
2. Mock 外部依赖: LLM 调用用回复模拟，不依赖真实 API
3. 覆盖边界: 空输入、超大输入、权限不足等
4. 可重复: 不依赖全局状态，每次运行结果一致