Unit Test Agent - 使用指南

🎯 产品概述

Unit Test Agent 是一款基于大语言模型 (LLM) 的智能测试生成工具，能够自动分析代码结构并生成高质量的单元测试用例。

🧠 智能代码分析

自动解析 Python、Java、JavaScript/TypeScript 代码，识别函数、类和方法。

🤖 LLM 驱动生成

利用 Claude/GPT 等先进大模型生成高质量、可读性强的测试代码。

🔧 多框架支持

支持 pytest、JUnit、Jest 等主流测试框架，无缝集成现有工作流。

📊 覆盖率分析

集成代码覆盖率统计，确保测试充分性。

👥 人机协同

支持人工审查和修改 AI 生成的测试，持续改进生成质量。

⚡ 批量处理

支持整个项目目录的测试生成，大幅提升效率。

📊 核心功能

功能	描述	状态
代码解析	支持 Python、Java、JS/TS 代码结构分析	✅ 已实现
测试生成	基于 LLM 自动生成单元测试用例	✅ 已实现
测试执行	自动执行生成的测试并收集结果	✅ 已实现
边缘用例	生成边界条件和异常场景测试	✅ 已实现
人机协同	人工审查和修改生成的测试	✅ 已实现
自动修复	尝试自动修复失败的测试	🚧 实验中

📦 安装指南

从源码安装

cd unit_test_agent
pip install -e .

依赖要求

Python: 3.9+
Anthropic SDK: 使用 Claude (可选)
OpenAI SDK: 使用 GPT (可选)
pytest: Python 测试执行
JUnit: Java 测试执行
Jest: JavaScript 测试执行

💡 提示

如果使用 Docker 或虚拟环境，请确保已安装所有系统依赖。

🔑 API Key 配置

设置环境变量

# Anthropic API Key (使用 Claude)
export ANTHROPIC_API_KEY=your_key_here

# OpenAI API Key (使用 GPT)
export OPENAI_API_KEY=your_key_here

或在配置文件中设置

{
  "llm": {
    "provider": "claude",
    "api_key": "your_key_here"
  }
}

🚀 快速开始

1. 基础使用

from unit_test_agent import UnitTestAgent

# 创建 Agent 实例
agent = UnitTestAgent()

# 分析源代码文件
module_info = agent.analyze_file("src/calculator.py")

# 生成测试
response = agent.generate_tests("src/calculator.py")

# 保存测试
agent.save_tests("./generated_tests", response.test_cases)

# 执行测试
report = agent.execute_tests(response.test_cases, 
                             source_file="src/calculator.py")

# 查看结果
print(f"Passed: {report.passed}")
print(f"Failed: {report.failed}")
print(f"Pass Rate: {report.pass_rate:.2%}")

2. 一键生成并执行

from unit_test_agent import UnitTestAgent

agent = UnitTestAgent()

# 生成并执行测试
result = agent.generate_and_execute(
    "src/calculator.py",
    options={
        'max_tests_per_function': 5,
        'generate_edge_cases': True,
    },
    auto_fix=True  # 自动修复失败的测试
)

print(result['summary'])

💡 提示

首次使用时，建议先用小文件测试，熟悉工作流程后再处理大型项目。

📖 API 文档

UnitTestAgent 类

主要方法

方法	参数	返回值	描述
`analyze_file`	file_path: str	ModuleInfo	分析源代码文件
`generate_tests`	target, options	GenerationResponse	为指定目标生成测试
`execute_tests`	test_cases, source_file	TestReport	执行测试用例
`generate_and_execute`	target, options, auto_fix	Dict	生成并执行测试
`save_tests`	output_dir, test_cases	List[str]	保存测试到文件
`get_session_report`	-	Dict	获取会话报告

数据模型

TestCase

@dataclass
class TestCase:
    id: str                    # 唯一标识符
    name: str                  # 测试名称
    target_function: str       # 目标函数
    target_class: Optional[str] # 目标类
    description: str           # 描述
    test_code: str             # 测试代码
    test_type: str             # 类型：unit/edge_case/integration
    confidence_score: float    # 置信度 (0-1)

TestReport

@dataclass
class TestReport:
    total_tests: int           # 总测试数
    passed: int                # 通过数
    failed: int                # 失败数
    skipped: int               # 跳过数
    pass_rate: float           # 通过率
    execution_time: float      # 执行时间
    coverage_summary: Dict     # 覆盖率摘要

💻 CLI 使用指南

基本命令

生成测试

unit-test-agent generate src/calculator.py --output ./tests

生成并执行

unit-test-agent generate-and-execute src/api.py --auto-fix

分析代码

unit-test-agent analyze src/ --format json

常用选项

选项	简写	描述	默认值
--output	-o	输出目录	./generated_tests
--max-tests	-m	每个函数的最大测试数	5
--edge-cases	-e	包含边缘用例	false
--coverage-target	-	覆盖率目标 (0.0-1.0)	0.8
--config	-c	配置文件路径	-

⚙️ 配置选项

配置文件示例

{
  "llm": {
    "provider": "claude",
    "model": "claude-sonnet-4-20250514",
    "temperature": 0.3,
    "max_tokens": 4096
  },
  "generator": {
    "coverage_target": 0.8,
    "generate_edge_cases": true,
    "max_tests_per_function": 5
  },
  "executor": {
    "timeout_seconds": 300,
    "parallel_execution": true,
    "coverage_enabled": true
  },
  "collaboration": {
    "enabled": true,
    "auto_approve_threshold": 0.9
  }
}

配置说明

配置项	类型	描述	推荐值
llm.provider	string	LLM 提供商 (claude/openai)	claude
llm.temperature	float	生成创造性 (0.0-1.0)	0.3
generator.coverage_target	float	目标覆盖率	0.8
executor.parallel_execution	bool	并行执行测试	true
collaboration.enabled	bool	启用人机协同	true

📝 使用示例

示例 1: 简单函数测试

# 源代码：calculator.py
def add(a, b):
    return a + b

def divide(a, b):
    if b == 0:
        raise ValueError("Cannot divide by zero")
    return a / b

# 生成的测试
from unit_test_agent import UnitTestAgent

agent = UnitTestAgent()
response = agent.generate_tests("calculator.py")

# 生成的测试用例包括:
# - test_add_positive_numbers
# - test_add_negative_numbers
# - test_divide_normal_case
# - test_divide_by_zero_raises_error

示例 2: 类方法测试

# 源代码
class Calculator:
    def __init__(self):
        self.history = []
    
    def add(self, a, b):
        result = a + b
        self.history.append(f"{a} + {b} = {result}")
        return result

# 生成的测试会覆盖:
# - 基本功能测试
# - 边界条件测试
# - 状态变化测试 (history)

示例 3: 批量处理

from unit_test_agent import UnitTestAgent

agent = UnitTestAgent()

# 分析整个目录
modules = agent.analyze_directory("src/", recursive=True)

# 为所有模块生成测试
for module in modules:
    response = agent.generate_tests(module)
    agent.save_tests("./tests", response.test_cases)

# 生成汇总报告
report = agent.get_session_report()
agent.export_report("./session_report.json")