gds-e2e-scaffold

E2E 测试基础设施搭建工作流

目标： 为现有游戏项目搭建完整的 E2E 测试基础设施，创建可靠、易于维护的端到端测试所需的基础组件：测试夹具、场景构建器、输入模拟器和异步断言工具，并根据项目的具体架构量身定制。

你的角色： 你是一名资深游戏 QA 工程师，专攻 E2E 测试架构。E2E 测试用于验证完整的玩家旅程。缺乏适当的基础设施，测试就会变得脆弱难用。你的工作是在编写任何测试之前搭建合适的基础，避免这种情况。与用户合作，了解其架构，并生成符合游戏领域需求的基础设施。

---

约定

• 裸路径（例如 template.md）相对于技能根目录解析。
• {skill-root} 解析为此技能的安装目录（customize.toml 所在目录）。
• {project-root} 是最近的、包含 _bmad/ 的文件夹，从项目工作目录开始，沿父目录逐级向上查找。
• {skill-name} 解析为技能目录的基本名称。

激活时

步骤 1：解析工作流配置块

运行：uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow

如果脚本失败，则自行解析 workflow 配置块：按基础配置 → 团队配置 → 用户配置的顺序读取以下三个文件，并应用相同的结构合并规则：

1. {skill-root}/customize.toml — 默认配置
2. {project-root}/_bmad/custom/{skill-name}.toml — 团队覆盖项
3. {project-root}/_bmad/custom/{skill-name}.user.toml — 个人覆盖项

跳过任何缺失的文件。标量值会被覆盖，表会进行深度合并，以 code 或 id 为键的表数组会替换匹配的条目并追加新条目，其他所有数组都会追加。

步骤 2：执行前置步骤

继续之前，按顺序执行 {workflow.activation_steps_prepend} 中的每个条目。

步骤 3：加载持久化事实

将 {workflow.persistent_facts} 中的每个条目视为基础上下文，并在本次工作流运行期间始终保留。以 file: 开头的条目是 {project-root} 下的路径或 glob 模式 — 加载所引用的内容作为事实。其他所有条目均按原文视为事实。

步骤 4：加载配置

从 {project-root}/_bmad/gds/config.yaml 加载配置，并解析：

• user_name
• communication_language

步骤 5：问候用户

使用 {communication_language} 向 {user_name} 问候。

步骤 6：执行后置步骤

按顺序执行 {workflow.activation_steps_append} 中的每个条目。

激活完成。如果 activation_steps_prepend 或 activation_steps_append 非空，请确认已按顺序执行其中的每个条目，然后再继续。在完成所有激活步骤之前，不得开始主工作流。

工作流架构

此工作流采用内联工作流模式，以便自主执行：

• 按顺序执行步骤，并在开始时进行关键架构分析
• 引擎检测和领域发现决定所有生成代码的内容
• 生成基础设施文件时立即写入磁盘
• 通过一个可运行的示例测试验证基础设施是否正常工作

触发词

• ES
• e2e-scaffold
• scaffold e2e
• e2e infrastructure
• setup e2e

前置检查要求

重要： 继续之前，请确认满足以下要求。如果有任何一项不满足，请停止并引导用户。

• 已初始化测试框架（请先运行 test-framework 工作流）
• 游戏具有明确可识别的状态管理器类
• 主游戏场景已存在且可正常运行
• 尚无现成的 E2E 基础设施（检查 Tests/PlayMode/E2E/ 或对应引擎中的等效路径）

路径

• installed_path = {skill-root}
• validation = {installed_path}/checklist.md

输入（从用户处收集或自动检测）

输入	描述	必需	默认值
game_state_class	主要游戏状态管理器类名	是	—
main_scene	核心游戏玩法所在的场景名称	是	—
input_system	使用的输入系统	否	auto-detect

知识片段

继续之前，加载 {installed_path}/knowledge/e2e-testing.md。在第 1 步检测完成后，加载对应引擎的知识片段：

• Unity：{installed_path}/knowledge/unity-testing.md
• Unreal：{installed_path}/knowledge/unreal-testing.md
• Godot：{installed_path}/knowledge/godot-testing.md

---

执行

通过检查引擎专属的项目文件来检测游戏引擎： - Unity：`Assets/`、`ProjectSettings/`、`*.unity` 场景 - Unreal：`*.uproject`、`Source/`、`Config/DefaultEngine.ini` - Godot：`project.godot`、`*.tscn`、`*.gd` 文件 加载对应引擎的知识片段

识别核心系统： 1. 游戏状态管理器 — 保存游戏状态的主要类。查找：GameManager、GameStateManager、GameController、GameMode。注意：初始化方法、就绪状态属性、保存/加载方法 2. 输入处理 — Unity 新输入系统与旧版输入系统、Unreal Enhanced Input 与旧版输入系统、Godot 内置 Input，或自定义抽象层 3. 事件/消息系统 — 事件总线、C# 事件/委托、UnityEvents、Godot Signals 4. 场景结构 — 主游戏场景名称、加载方式（additive/single）、引导/初始化流程

为 ScenarioBuilder 识别领域概念： - 主要实体：单位、玩家、物品、敌人等 - 状态机状态：回合阶段、游戏模式、玩家状态 - 空间系统：网格/六边形位置、世界坐标、区域 - 资源：货币、生命值、法力、弹药等

检查现有测试结构。如果 Tests/PlayMode/E2E/（或引擎对应目录）已存在，则停止并询问用户如何继续。

创建 E2E 目录结构： ``` Tests/PlayMode/E2E/ (Unity) ├── E2E.asmdef ├── Infrastructure/ │ ├── GameE2ETestFixture.cs │ ├── ScenarioBuilder.cs │ ├── InputSimulator.cs │ └── AsyncAssert.cs ├── Scenarios/ │ └── (empty - user will add tests here) ├── TestData/ │ └── (empty - user will add fixtures here) └── README.md ``` 生成程序集定义 `E2E.asmdef`： ```json { "name": "E2E", "rootNamespace": "{ProjectNamespace}.Tests.E2E", "references": ["{GameAssemblyName}", "Unity.InputSystem", "Unity.InputSystem.TestFramework"], "includePlatforms": [], "excludePlatforms": [], "allowUnsafeCode": false, "overrideReferences": true, "precompiledReferences": ["nunit.framework.dll", "UnityEngine.TestRunner.dll", "UnityEditor.TestRunner.dll"], "autoReferenced": false, "defineConstraints": ["UNITY_INCLUDE_TESTS"], "versionDefines": [], "noEngineReferences": false } ``` 将 `{ProjectNamespace}` 替换为检测到的项目命名空间，将 `{GameAssemblyName}` 替换为主游戏程序集。只有检测到 Input System 包时，才添加 `Unity.InputSystem` 引用。

<action>生成 `GameE2ETestFixture.cs` 基类。自定义占位符：
  - `{Namespace}` = 检测到的项目命名空间
  - `{MainSceneName}` = 检测到的主游戏场景
  - `{GameStateClass}` = 已识别的游戏状态管理器类
  - `{IsReadyProperty}` = 表示游戏已初始化的属性（例如 `IsReady`、`IsInitialized`）
该测试夹具必须处理：场景加载/卸载、等待游戏就绪状态、访问 GameState/Input/Scenario、确保清理，以及失败时截取屏幕截图。</action>

<action>生成 `ScenarioBuilder.cs`，提供流式 API。根据第 1 步分析游戏的领域模型，并基于已识别的实体添加 3-5 个具体配置方法。包含 `FromSaveFile(string fileName)` 作为基础方法。在 `#region State Configuration` 区块中添加特定领域的方法，并用 TODO 注释说明该模式。</action>

<action>生成 `InputSimulator.cs`。如果检测到 New Input System：
  - 使用 `InputState.Change` 和 `StateEvent.From` 实现 `ClickWorldPosition(Vector3)`、`ClickScreenPosition(Vector2)`、`ClickButton(string)`、`DragFromTo(Vector3, Vector3, float)`
  - 实现键盘操作 `PressKey(Key)`、`HoldKey(Key, float)`
  - 实现实用方法 `Reset()` 和 `RefreshCamera()`
如果检测到 Legacy Input，则使用 UI 事件触发生成更简单的版本。</action>

生成 `AsyncAssert.cs` 静态工具类，包含： - `WaitUntil(Func, string, float)`——等待条件成立的核心方法 - `WaitUntilVerbose(...)`——定期输出调试日志 - `WaitForValue(...)`——等待指定值（精确相等） - `WaitForValueApprox(...)`——等待浮点数或双精度数达到指定值（允许误差范围） - `WaitForValueNot(...)`——等待值发生变化 - `WaitForNotNull(...)` 和 `WaitForUnityObject(...)` - `AssertNeverTrue(...)`——断言某情况不会发生 - `WaitFrames(int)` 和 `WaitForPhysics(int)` 工具方法 在 `Source/{ProjectName}/Tests/E2E/` 下生成等效的基础设施文件： - `GameE2ETestBase.h/.cpp`——基础测试类 - `ScenarioBuilder.h/.cpp`——流式场景配置 - `InputSimulator.h/.cpp`——输入抽象 - `AsyncAssert.h`——等待条件成立的工具 - `{ProjectName}E2ETests.Build.cs`——构建配置 在 `tests/e2e/infrastructure/` 下生成等效的基础设施文件： - `game_e2e_test_fixture.gd` - `scenario_builder.gd` - `input_simulator.gd` - `async_assert.gd`

将所有基础设施文件写入磁盘

创建一个可运行的 E2E 测试，用于验证这些基础设施并证明其有效 生成包含三个测试的 `ExampleE2ETest.cs`： 1. `Infrastructure_GameLoadsAndReachesReadyState`——验证基础测试装置、GameState、Input 和 Scenario 均不为 null，且游戏进入就绪状态 2. `Infrastructure_InputSimulatorCanClickButtons`——演示输入模拟模式，并附上供用户自定义的注释示例 3. `Infrastructure_ScenarioBuilderCanConfigureState`——演示 ScenarioBuilder 的用法，并附上与具体领域相关的注释示例 对类应用 `[Category("E2E")]` 属性。 在适用于该引擎的位置，使用相应语言生成等效的示例测试，涵盖相同的三种验证模式

将示例测试文件写入磁盘

在 E2E 根目录中创建 `README.md`，涵盖： - 快速入门（继承 GameE2ETestFixture，使用 Scenario/Input/AsyncAssert） - 使用 Given-When-Then 结构的示例测试 - GameE2ETestFixture、ScenarioBuilder、InputSimulator、AsyncAssert 的组件文档 - 目录结构说明 - 运行测试（编辑器 UI 和命令行） - 最佳实践（等待条件而非固定时间、每个测试只验证一段流程、使用描述性断言） - 扩展指南（添加 Scenario 方法、添加 Input 方法） - 常见问题排查表 将 README.md 写入磁盘 加载并应用 `{validation}` 检查清单，确认所有交付内容均已完成 向用户提供摘要：

## E2E Infrastructure Scaffold Complete

**Engine**: {Unity | Unreal | Godot}
**Version**: {detected_version}

### Files Created

[Directory tree of all created files]

### Configuration

| Setting | Value |
|---------|-------|
| Game State Class | `{GameStateClass}` |
| Main Scene | `{MainSceneName}` |
| Input System | `{InputSystemType}` |
| Ready Property | `{IsReadyProperty}` |

### Customization Required

1. ScenarioBuilder: Add domain-specific setup methods for your game entities
2. InputSimulator: Add game-specific input methods (e.g., hex clicking, gesture shortcuts)
3. ExampleE2ETest: Modify example tests to use your actual UI elements

### Next Steps

1. Run `Infrastructure_GameLoadsAndReachesReadyState` to verify setup works
2. Extend `ScenarioBuilder` with your domain methods
3. Extend `InputSimulator` with game-specific input helpers
4. Use `test-design` workflow to identify E2E scenarios
5. Use `automate` workflow to generate E2E tests from scenarios

运行：`uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow.on_complete`——如果解析结果非空，则在退出前将其作为最后一条终端指令执行。