ai-proj-helper/plugins/req-plugin/test-guide.md

测试环境流程指南

测试必须按照以下环境顺序依次进行，每个环境通过后才能进入下一个环境。

测试环境流程

[1] 本机环境 ─── 通过 ──→ [2] 预发布环境 ─── 通过 ──→ [3] 生产环境
      │                        │                        │
      ↓ 失败                   ↓ 失败                   ↓ 失败
  修复并重测              回到步骤[1]              回到步骤[1]

项目环境配置表

项目	本机环境	预发布环境	生产环境
ai-proj	localhost:3000/8080	staging.ai.pipexerp.com	ai.pipexerp.com
coolbuy-paas	localhost	fnos 测试环境	39.106.88.83:8888
coolbuy-platform	localhost	fnos 测试环境	生产服务器

第一阶段：本机测试环境

⚠️ 关键约束：本机测试必须全部通过，才能部署到 staging 环境。

测试内容：

• 单元测试 - 测试单个函数/方法，Mock 外部依赖
• 集成测试 - 测试模块间交互，使用测试数据库
• 功能验证 - 验证功能逻辑正确性
• 前端截图验证 - 使用 chrome-dev MCP 截图确认 UI 显示正确

后端测试

# Go 后端单元测试
go test ./... -v

# 指定模块测试
go test ./backend/handlers/... -v
go test ./backend/services/... -v

前端截图验证（⚠️ 必须步骤）

重要：前端改动必须通过截图验证，不能只测后端 API。这一步经常被忽略，导致功能未正确显示。

验证流程：

1. 确保本机服务运行

   # 终端1：后端
   cd backend && go run main.go
   
   # 终端2：前端
   cd frontend && npm start
   

2. 使用 chrome-dev MCP 截图验证

   # 步骤1：导航到目标页面
   mcp__chrome-dev__navigate_page(url="http://localhost:3000/requirements/686")
   
   # 步骤2：等待页面加载完成（可选）
   mcp__chrome-dev__wait_for(selector=".requirement-detail")
   
   # 步骤3：截图
   mcp__chrome-dev__take_screenshot()
   
   # 步骤4：检查截图中功能是否正确显示
   # - 新增的列/字段是否显示
   # - 样式是否正确
   # - 数据是否正确渲染
   

3. 常见验证场景

   改动类型	验证页面	检查项
   列表新增列	列表页面	新列是否显示、数据是否正确
   表单新增字段	表单页面	字段是否显示、能否正常输入
   样式调整	相关页面	样式是否生效、布局是否正确
   权限控制	相关页面	按钮/菜单是否正确显示/隐藏

4. 截图保存

   • 截图应保存到测试任务文档中作为验证记录
   • 命名规范：REQ-XXXXX-本机测试-功能名称.png

前端截图验证示例

/req test REQ-20260125-0002

→ 检查代码评审... ✓ 已完成
→ 验证开发任务... ✓ 已完成

=== 本机测试阶段 ===

1. 后端单元测试
   → go test ./backend/handlers/requirement_handler_test.go -v
   → ✓ 3/3 测试通过

2. 前端截图验证
   → 启动 chrome-dev MCP...
   → 导航到: http://localhost:3000/requirements/687
   → 截图验证...
   → ✓ 任务ID列正确显示 (#5284 格式)
   → ✓ 列宽度和样式正确
   → 截图已保存

=== 本机测试通过 ===
→ 可以执行: /req deploy REQ-20260125-0002 --env staging

通过标准

• 所有后端单元测试通过
• 前端截图验证通过（有前端改动时必须）
• 功能在本地环境正常运行
• 无控制台错误
• 截图已保存到测试文档

跳过前端验证

仅当改动不涉及前端时，可使用 --backend-only 参数：

/req test REQ-XXXXX --backend-only

第二阶段：预发布环境

测试内容：

• E2E 测试 - 测试完整用户流程
• 跨浏览器测试 - Chrome、Firefox、Safari
• 性能测试 - 页面加载时间、API 响应时间

通过标准：

• 功能在预发布环境正常运行
• 与生产环境配置一致
• 无跨环境兼容性问题

第三阶段：生产环境

测试内容：

• UAT 验收 - 用户验收测试
• 冒烟测试 - 核心功能快速验证
• 回归测试 - 确保未破坏现有功能

通过标准：

• 功能在生产环境正常运行
• 用户验收通过
• 无生产环境特有问题

API 验证清单

# 1. 本机环境
curl -s "http://localhost:8080/api/v1/requirements?search=REQ-2026" \
  -H "Authorization: Bearer $TOKEN" | jq '.data | length'

# 2. 预发布环境
curl -s "https://staging.ai.pipexerp.com/api/v1/requirements?search=REQ-2026" \
  -H "X-API-Key: $SYNC_REMOTE_API_KEY" | jq '.data | length'

# 3. 生产环境
curl -s "https://ai.pipexerp.com/api/v1/requirements?search=REQ-2026" \
  -H "X-API-Key: $SYNC_REMOTE_API_KEY" | jq '.data | length'

测试失败处理

失败阶段	处理方式
本机测试	修复代码，重新运行本机测试
预发布测试	修复代码，重新从本机测试开始
生产环境测试	修复代码，重新从本机测试开始

任何阶段测试失败，修复后必须从本机测试环境重新开始。