Skip to content

TESTING.md

Latest commit

 

History

History
309 lines (223 loc) · 6.38 KB

TESTING.md

File metadata and controls

309 lines (223 loc) · 6.38 KB
Raw

测试指南

本文档说明如何运行 NL2SQL Agent 的各种测试。

测试概览

项目包含以下测试套件：

  1. 端到端集成测试 (test_e2e.py) - 测试完整的查询流程
  2. 错误自愈测试 (test_error_recovery.py) - 测试 SQL 错误的自动修正
  3. 多轮对话测试 (test_multi_turn.py) - 测试会话上下文和多轮对话
  4. 本地环境验证 (test_local_validation.py) - 验证本地运行环境
  5. AgentCore 部署验证 (test_agentcore_deployment.py) - 验证 AgentCore 部署

前置条件

1. 安装依赖

pip install -r requirements.txt

2. 配置数据库

创建或编辑 rds_demo/db_config.txt 文件：

endpoint=your-database-endpoint
port=3306
database=demodb
username=your-username
password=your-password
region=us-west-2

或者设置环境变量：

export DB_ENDPOINT=your-database-endpoint
export DB_PORT=3306
export DB_NAME=demodb
export DB_USER=your-username
export DB_PASSWORD=your-password
export AWS_REGION=us-west-2

3. 初始化数据库（如果需要）

cd rds_demo
./setup.sh

运行测试

方式 1: 运行所有测试（推荐）

python run_all_tests.py

这会运行除部署验证外的所有测试。

方式 2: 运行特定测试套件

# 端到端集成测试
python test_e2e.py

# 错误自愈测试
python test_error_recovery.py

# 多轮对话测试
python test_multi_turn.py

# 本地环境验证
python test_local_validation.py

# AgentCore 部署验证
python test_agentcore_deployment.py

方式 3: 使用 run_all_tests.py 运行特定套件

# 只运行端到端测试
python run_all_tests.py --suite e2e

# 只运行错误自愈测试
python run_all_tests.py --suite error

# 只运行多轮对话测试
python run_all_tests.py --suite multi

# 只运行本地验证
python run_all_tests.py --suite local

# 只运行部署验证
python run_all_tests.py --suite deploy

# 运行所有测试（包括部署验证）
python run_all_tests.py --all

测试详情

1. 端到端集成测试 (test_e2e.py)

测试内容：

  • 简单查询流程
  • 复杂查询（聚合、JOIN、GROUP BY）
  • 带过滤条件的查询
  • 空结果集处理
  • 组件集成验证

运行：

python test_e2e.py

预期结果：

  • 所有查询应该成功执行
  • 返回正确的分析报告
  • 各组件协同工作正常

2. 错误自愈测试 (test_error_recovery.py)

测试内容：

  • SQL 语法错误自动修正
  • 表名错误自动修正
  • 字段名错误自动修正
  • 最大重试次数限制（3次）
  • SQL 安全验证
  • 错误日志记录

运行：

python test_error_recovery.py

预期结果：

  • 系统能够识别并修正常见的 SQL 错误
  • 危险的 SQL 操作被正确拒绝
  • 错误信息清晰有用

3. 多轮对话测试 (test_multi_turn.py)

测试内容：

  • 基本多轮对话
  • 上下文引用（代词、省略）
  • 追问场景
  • 会话隔离
  • Memory Service 集成
  • 长对话处理

运行：

python test_multi_turn.py

预期结果：

  • 系统能够维护会话上下文
  • 正确理解代词和省略
  • 不同会话之间互不干扰

注意： Memory Service 集成测试需要配置 MEMORY_ID 环境变量。

4. 本地环境验证 (test_local_validation.py)

测试内容：

  • 配置文件加载
  • 各种查询场景（简单、复杂、聚合、JOIN）
  • 错误场景处理
  • 日志输出验证

运行：

python test_local_validation.py

预期结果：

  • local_test.py 脚本工作正常
  • 各种查询场景都能正确处理
  • 日志输出完整清晰

5. AgentCore 部署验证 (test_agentcore_deployment.py)

测试内容：

  • AgentCore CLI 工具检查
  • AWS 凭证验证
  • 部署文件检查
  • 环境变量验证
  • 部署配置测试
  • 调用测试
  • Memory Service 集成
  • CloudWatch Logs 验证

前置条件：

  • 安装 AgentCore CLI: pip install bedrock-agentcore
  • 配置 AWS 凭证: aws configure
  • 设置必要的环境变量

运行：

python test_agentcore_deployment.py

预期结果：

  • 所有前置检查通过
  • Agent 已正确配置和部署
  • 调用测试成功
  • 日志正常输出到 CloudWatch

使用 Mock LLM 测试

为了避免调用 AWS Bedrock（产生费用），大部分测试默认使用 Mock LLM。

如果要使用真实的 Bedrock 模型测试，需要：

  1. 配置 AWS 凭证
  2. 修改测试代码，将 use_mock_llm=True 改为 use_mock_llm=False

常见问题

1. 数据库连接失败

错误： Can't connect to MySQL server

解决方案：

  • 检查数据库配置是否正确
  • 确保数据库可访问（网络、安全组）
  • 验证用户名和密码

2. 测试超时

错误： TimeoutExpired

解决方案：

  • 检查数据库响应速度
  • 增加超时时间
  • 检查网络连接

3. Memory Service 初始化失败

错误： Memory Service 初始化失败

解决方案：

  • 确保 AWS 凭证已配置
  • 确保 MEMORY_ID 正确
  • 确保 Memory 资源已创建（运行 python setup_memory.py）

4. AgentCore CLI 不可用

错误： agentcore: command not found

解决方案：

pip install bedrock-agentcore

5. 测试失败但不知道原因

解决方案：

  • 使用 --verbose 参数查看详细日志
  • 检查测试输出中的错误信息
  • 查看 CloudWatch Logs（如果已部署）

持续集成

如果要在 CI/CD 流程中运行测试：

# 设置环境变量
export DB_ENDPOINT=...
export DB_NAME=...
export DB_USER=...
export DB_PASSWORD=...

# 运行测试（跳过部署验证）
python run_all_tests.py --skip-deploy

测试覆盖率

当前测试覆盖以下需求：

  • ✓ 需求 1.1, 2.1, 4.1 - 端到端集成测试
  • ✓ 需求 2.2, 2.3, 2.4, 2.5 - 错误自愈测试
  • ✓ 需求 8.1, 8.2, 8.3, 8.4, 8.5 - 多轮对话测试
  • ✓ 需求 6.2 - 本地环境验证
  • ✓ 需求 7.4, 7.5, 7.6, 9.5 - AgentCore 部署验证

贡献测试

如果要添加新的测试：

  1. 创建新的测试文件（如 test_new_feature.py）
  2. 遵循现有测试的结构和风格
  3. 使用中文注释和日志
  4. 添加到 run_all_tests.py 中
  5. 更新本文档

联系支持

如果遇到测试问题，请：

  1. 查看本文档的常见问题部分
  2. 检查项目的 README.md
  3. 查看相关的设计文档（.kiro/specs/sql-analysis-agent/）