e2e-design

name	e2e-design
description	测试实现分析：在黑盒测试用例基础上，分析入口函数、外部依赖(Fake)、测试数据、验证点，复用存量测试设计。当用户说"/e2e-design"、"测试实现分析"、"生成e2e-impl-design"、"测试设计细化"，或需要基于测试用例和设计文档生成测试实现分析报告时使用此技能。
user-invokable	false

用户输入

$ARGUMENTS

在继续之前, 你必须考虑用户输入(如果不为空).

概述

执行测试实现分析工作流，在黑盒测试用例基础上分析入口函数、外部依赖、测试数据、验证点，并复用存量测试设计。

调用场景：

1. 初步设计（在 /design 之后）：基于设计文档和黑盒测试用例生成测试实现分析报告
2. 独立调用：直接执行测试实现分析（需要已有 design.md 和 e2e-test.md）

输入要求：

• spec.md：功能规范文档
• design.md：设计文档
• e2e-test.md：黑盒测试用例文档

输出：

• e2e-impl-design.md：测试实现分析报告

执行流程

1. [ ] 设置环境

1. 判断操作系统：Windows 或 Linux
2. 运行前置检查脚本：
   • Windows: scripts/powershell/check-prerequisites.ps1 --json --require-design --require-e2e-test
   • Linux: scripts/bash/check-prerequisites.sh --json --require-design --require-e2e-test
3. 解析输出：
   • 提取 FEATURE_DIR（特性目录绝对路径）
   • 提取 SPEC_FILE（规范文件路径）
   • 提取 DESIGN_FILE（设计文件路径）
   • 提取 E2E_TEST_FILE（黑盒测试用例文件路径）
   • 提取 AVAILABLE_DOCS（可用文档列表）

重要：所有路径必须是绝对路径。

2. [ ] 验证前置文件

验证以下必需文件是否存在：

1. 检查规范文件：

   • {FEATURE_DIR}/spec.md 是否存在
   • 如果不存在：错误 "规范文件不存在，请先执行 /specify"

2. 检查设计文件：

   • {FEATURE_DIR}/design.md 是否存在
   • 如果不存在：错误 "设计文件不存在，请先执行 /design"

3. 检查测试用例文件：

   • {FEATURE_DIR}/e2e-test.md 是否存在
   • 如果不存在：错误 "黑盒测试用例文件不存在，请先执行 /e2e-specify"

4. 报告验证结果：

   • 所有文件存在：继续执行步骤3
   • 任何文件缺失：终止流程并报错

3. [ ] 加载上下文文档

加载用于测试实现分析的上下文文档：

必需文档：

1. spec.md：读取用户故事、功能需求、验收场景
2. design.md：读取架构设计、详细设计、接口定义、数据结构
3. e2e-test.md：读取所有黑盒测试用例（Given-When-Then 格式）

可选文档（按优先级加载）：

1. baseline 文档：

   • baseline/code-structure.md：现有代码结构
   • baseline/existing-apis.md：现有接口定义

2. 存量测试代码：

   • 搜索现有测试目录（如 tests/、test/）
   • 查找类似功能的测试实现
   • 提取测试范式、Mock 对象使用、测试数据构造方法

加载策略：

• 每个文档独立容错，失败不中断流程
• 记录成功加载的文档列表
• 标注缺失的文档

4. [ ] 启动测试实现分析 Agent

使用 Agent 工具启动 test-impl-design agent，传递以下参数：

Agent 参数：

• subagent_type: "general-purpose"（使用通用 agent）
• description: "测试实现分析 - 生成测试实现分析报告"
• prompt 包含以下内容：

# 测试实现分析任务

## 调用场景
{场景类型}: 初步设计/独立调用

## 输入文件
- spec.md: {SPEC_FILE}
- design.md: {DESIGN_FILE}
- e2e-test.md: {E2E_TEST_FILE}
- feature_dir: {FEATURE_DIR}
- baseline_docs: {成功加载的 baseline 文档列表}
- existing_tests: {找到的存量测试代码}

## 任务要求
1. 读取 spec.md、design.md、e2e-test.md
2. 分析每个黑盒测试用例的入口函数
3. 识别外部依赖并设计 Fake 对象
4. 设计测试数据（输入数据、Fake 数据）
5. 定义验证点（返回值、状态变化、可观察行为）
6. 分析存量测试复用可能性
7. 生成测试实现分析报告（e2e-impl-design.md）

## 输出位置
- e2e-impl-design.md: {FEATURE_DIR}/e2e-impl-design.md

## 重要说明
- 重点关注入口函数签名、外部依赖、测试数据
- 复用存量测试模式和测试工具
- 保持黑盒测试特性，不暴露内部实现

5. [ ] 验证生成文档

等待 agent 完成后，验证生成的文档：

1. 检查文档存在性：

   • 检查 {FEATURE_DIR}/e2e-impl-design.md 是否存在
   • 如果不存在：错误 "测试实现分析报告生成失败"

2. 验证文档内容： e2e-impl-design.md 应包含以下章节：

   a) 用例实现映射表：

   • 用例编号 → 入口函数
   • 测试类型（单元测试/集成测试/E2E测试）
   • 实现复杂度评估

   b) 入口函数详细分析：

   • 函数签名（完全限定名）
   • 参数列表和类型
   • 返回值类型
   • 所在模块/文件

   c) 外部依赖详细分析：

   • 依赖类型（数据库/消息队列/外部服务/文件系统）
   • Fake 对象设计
   • Mock 策略
   • 隔离方法

   d) 测试数据清单：

   • 输入数据（参数、配置）
   • Fake 数据（数据库记录、消息内容）
   • 数据构造方法
   • 数据清理策略

   e) 验证点详细清单：

   • 返回值验证
   • 状态变化验证
   • 可观察行为验证（日志、监控指标）
   • 异常情况验证

   f) 存量测试复用分析：

   • 可复用的测试工具类
   • 可复用的测试基类
   • 可复用的测试数据构造方法
   • 需要适配的测试模式

3. 处理验证结果：

   • [成功] 验证成功：输出完成报告，继续下一步
   • [失败] 验证失败：
     • 记录缺失的章节
     • 如果是关键章节缺失（用例映射、入口函数、外部依赖）：报告失败
     • 如果是非关键章节缺失（存量测试复用）：记录警告但继续

6. [ ] 报告完成情况

输出完成报告，包括：

• 生成文档：

  • e2e-impl-design.md 路径

• 验证结果：

  • 文档存在性检查：[成功]/[失败]
  • 内容完整性检查：[成功]/[失败]
  • 问题列表（如有）

• 分析统计：

  • 测试用例总数（来自 e2e-test.md）
  • 入口函数数量
  • 外部依赖数量
  • 测试数据项数量
  • 验证点数量
  • 可复用存量测试资源数量

• 下一步建议：

  • 推荐：执行 /e2e-varify 完善测试设计（变更点覆盖分析、异常场景设计、测试数据细化）
  • 如果测试实现分析完整：建议执行 /tasks 生成任务列表
  • 如果发现设计问题：建议返回 /design 完善设计

7. [ ] 可选：自动执行下游动作

如果用户提供了 --auto-refine 参数，自动执行下游动作：

1. 调用 e2e-varify：

   • 传递相同的 feature 目录
   • 对刚生成的 e2e-impl-design.md 进行深度细化
   • 补充变更点覆盖分析
   • 补充外部依赖异常场景
   • 补充具体测试数据设计

2. 等待下游完成：

   • 监控 e2e-varify 执行状态
   • 收集完善统计信息
   • 合并到完成报告中

错误处理

1. 前置文件缺失：

   • 明确指出缺失的文件
   • 提供解决建议（执行相应的前置命令）
   • 终止流程

2. Agent 执行失败：

   • 记录错误信息
   • 报告失败原因
   • 建议解决方案

3. 文档生成失败：

   • 检查 agent 输出日志
   • 验证输入文件是否存在且有效
   • 验证输出目录是否可写

4. 内容验证失败：

   • 如果是关键内容缺失：报告失败
   • 如果是非关键内容缺失：记录警告，继续执行

通用指南

快速指南

• 专注于测试实现层面，不涉及测试代码编写
• 基于黑盒测试用例，不暴露内部实现细节
• 复用存量测试设计，避免重复劳动
• 关注可测试性，识别难以测试的场景
• 保持测试独立性，设计合适的隔离策略

关键原则

1. 入口函数识别：

   • 从黑盒用例的 "When" 步骤推断入口函数
   • 优先选择 REST API / RPC 接口作为入口
   • 对于内部功能，选择合适的内部接口

2. 外部依赖分析：

   • 识别所有外部交互（数据库、消息队列、外部服务）
   • 为每个依赖设计 Fake 对象
   • 定义 Mock 行为和返回值

3. 测试数据设计：

   • 数据要具体可用，无需补充
   • 覆盖正常场景和异常场景
   • 考虑边界值和特殊值

4. 验证点定义：

   • 优先使用返回值验证
   • 补充使用状态变化验证
   • 必要时使用可观察行为验证（日志、监控）

5. 存量测试复用：

   • 优先复用项目已有的测试模式
   • 复用测试基类和工具类
   • 遵守项目的测试约定

建议后续步骤

测试实现分析完成后，推荐按以下顺序执行：

1. e2e-varify：完善测试设计（变更点覆盖、异常场景、测试数据细化）
2. tasks：生成任务列表（包含测试实施任务）
3. implement：开始功能实施（包含测试实施）