gds-test-framework

游戏测试框架设置

工作流 ID：gds-test-framework 版本：1.0（BMad v6）

约定

• 裸路径（例如 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 不为空，请确认已按顺序执行其中的每一项，然后再继续。在所有激活步骤完成之前，不得开始主工作流。

目标

为 Unity、Unreal Engine 或 Godot 项目初始化可用于生产环境的游戏测试框架。此工作流会搭建完整的测试基础设施，包括适用于检测到的游戏引擎的单元测试、集成测试和游戏模式测试。

角色

你是一名专攻测试基础设施的游戏 QA 架构师。你负责检测所用的游戏引擎、搭建相应的测试框架、生成可运行的示例测试并编写文档，让团队从第一天起就拥有一套可全面运行的测试环境。

---

工作流架构

此工作流会检测游戏引擎，并直接在游戏项目中创建所有必要的测试基础设施文件。

主要输出：{test_dir}/README.md

支持组件：

• 验证：{installed_path}/checklist.md

知识库参考：

• knowledge/unity-testing.md
• knowledge/unreal-testing.md
• knowledge/godot-testing.md

从 {module_config} 加载并解析配置：

output_folder: {from config}
user_name: {from config}
communication_language: {from config}
document_output_language: {from config}
game_dev_experience: {from config}
date: {system-generated}

解析工作流变量：

test_dir: "{project-root}/tests"    # Root test directory
game_engine: "auto"                  # auto | unity | unreal | godot
test_framework: "auto"               # auto | gut (godot) | unity-test-framework | unreal-automation

---

执行

前置检查要求

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

• 游戏项目存在且能识别其引擎
• 尚未配置测试框架（检查是否存在现有测试目录）
• 可以访问项目结构

---

第 1 步：检测游戏引擎

操作

1. 识别引擎类型

   查找引擎专用文件：

   • Unity：Assets/、ProjectSettings/ProjectSettings.asset、*.unity 场景文件
   • Unreal：*.uproject、Source/、Config/DefaultEngine.ini
   • Godot：project.godot、*.tscn、*.gd 文件

2. 验证引擎版本

   • Unity：检查 ProjectSettings/ProjectVersion.txt
   • Unreal：检查 *.uproject 文件中的 EngineAssociation
   • Godot：检查 project.godot 中的 config_version

3. 检查是否已有测试框架

   • Unity：检查 Tests/ 文件夹、*.Tests.asmdef
   • Unreal：检查 Source 中的 Tests/、*Tests.Build.cs
   • Godot：检查 tests/ 文件夹、addons/gut/ 中的 GUT 插件

**停止条件：**如果检测到已有框架，请提供升级方案或停止。

---

第 2 步：搭建框架

Unity 测试框架

知识库参考：knowledge/unity-testing.md

1. 创建目录结构

   Assets/
   ├── Tests/
   │   ├── EditMode/
   │   │   ├── EditModeTests.asmdef
   │   │   └── ExampleEditModeTest.cs
   │   └── PlayMode/
   │       ├── PlayModeTests.asmdef
   │       └── ExamplePlayModeTest.cs
   

2. 生成程序集定义

   EditModeTests.asmdef：

   {
     "name": "EditModeTests",
     "references": ["<GameAssembly>"],
     "includePlatforms": ["Editor"],
     "defineConstraints": ["UNITY_INCLUDE_TESTS"],
     "optionalUnityReferences": ["TestAssemblies"]
   }
   

   PlayModeTests.asmdef：

   {
     "name": "PlayModeTests",
     "references": ["<GameAssembly>"],
     "includePlatforms": [],
     "defineConstraints": ["UNITY_INCLUDE_TESTS"],
     "optionalUnityReferences": ["TestAssemblies"]
   }
   

3. 生成示例测试

   编辑模式测试示例：

   using NUnit.Framework;
   
   [TestFixture]
   public class DamageCalculatorTests
   {
       [Test]
       public void Calculate_BaseDamage_ReturnsCorrectValue()
       {
           // Arrange
           var calculator = new DamageCalculator();
   
           // Act
           float result = calculator.Calculate(100f, 1f);
   
           // Assert
           Assert.AreEqual(100f, result);
       }
   }
   

   播放模式测试示例：

   using System.Collections;
   using NUnit.Framework;
   using UnityEngine;
   using UnityEngine.TestTools;
   
   public class PlayerMovementTests
   {
       [UnityTest]
       public IEnumerator Player_WhenInputApplied_Moves()
       {
           // Arrange
           var playerGO = new GameObject("Player");
           var controller = playerGO.AddComponent<PlayerController>();
   
           // Act
           controller.SetMoveInput(Vector2.right);
           yield return new WaitForSeconds(0.5f);
   
           // Assert
           Assert.Greater(playerGO.transform.position.x, 0f);
   
           // Cleanup
           Object.Destroy(playerGO);
       }
   }
   

---

Unreal Engine 自动化

知识库参考：knowledge/unreal-testing.md

1. 创建目录结构

   Source/
   ├── <ProjectName>/
   │   └── ...
   └── <ProjectName>Tests/
       ├── <ProjectName>Tests.Build.cs
       └── Private/
           ├── DamageCalculationTests.cpp
           └── PlayerCombatTests.cpp
   

2. 生成模块构建文件

   <ProjectName>Tests.Build.cs：

   using UnrealBuildTool;
   
   public class <ProjectName>Tests : ModuleRules
   {
       public <ProjectName>Tests(ReadOnlyTargetRules Target) : base(Target)
       {
           PCHUsage = ModuleRules.PCHUsageMode.UseExplicitOrSharedPCHs;
   
           PublicDependencyModuleNames.AddRange(new string[] {
               "Core",
               "CoreUObject",
               "Engine",
               "<ProjectName>"
           });
   
           PrivateDependencyModuleNames.AddRange(new string[] {
               "AutomationController"
           });
       }
   }
   

3. 生成示例测试

   #include "Misc/AutomationTest.h"
   
   IMPLEMENT_SIMPLE_AUTOMATION_TEST(
       FDamageCalculationTest,
       "<ProjectName>.Combat.DamageCalculation",
       EAutomationTestFlags::ApplicationContextMask |
       EAutomationTestFlags::ProductFilter
   )
   
   bool FDamageCalculationTest::RunTest(const FString& Parameters)
   {
       // Arrange
       float BaseDamage = 100.f;
       float CritMultiplier = 2.f;
   
       // Act
       float Result = UDamageCalculator::Calculate(BaseDamage, CritMultiplier);
   
       // Assert
       TestEqual("Critical hit doubles damage", Result, 200.f);
   
       return true;
   }
   

---

Godot GUT 框架

知识库参考：knowledge/godot-testing.md

1. 创建目录结构

   project/
   ├── addons/
   │   └── gut/ (plugin files)
   ├── tests/
   │   ├── unit/
   │   │   └── test_damage_calculator.gd
   │   └── integration/
   │       └── test_player_combat.gd
   └── gut_config.json
   

2. 生成 GUT 配置

   gut_config.json：

   {
     "dirs": ["res://tests/"],
     "include_subdirs": true,
     "prefix": "test_",
     "suffix": ".gd",
     "should_exit": true,
     "should_exit_on_success": true,
     "log_level": 1,
     "junit_xml_file": "results.xml"
   }
   

3. 生成示例测试

   tests/unit/test_damage_calculator.gd：

   extends GutTest
   
   var calculator: DamageCalculator
   
   func before_each():
       calculator = DamageCalculator.new()
   
   func after_each():
       calculator.free()
   
   func test_calculate_base_damage():
       var result = calculator.calculate(100.0, 1.0)
       assert_eq(result, 100.0, "Base damage should equal input")
   
   func test_calculate_critical_hit():
       var result = calculator.calculate(100.0, 2.0)
       assert_eq(result, 200.0, "Critical hit should double damage")
   

---

第 3 步：生成文档

创建 tests/README.md，包含：

• 针对检测到的引擎的测试框架概述
• 目录结构说明
• 在本地运行测试
• CI 集成命令
• 游戏测试最佳实践
• 知识库内容片段的链接

---

第 4 步：交付内容

创建的主要产物

1. 目录结构 — 符合引擎要求的测试文件夹
2. 配置文件 — 框架专用配置（asmdef、Build.cs、gut_config.json）
3. 示例测试 — 可运行的单元测试和集成测试示例
4. 文档 — tests/README.md

---

输出摘要

完成此工作流后，请提供摘要：

## Game Test Framework Scaffold Complete

**Engine Detected**: {Unity | Unreal | Godot}
**Framework**: {Unity Test Framework | Unreal Automation | GUT}

**Artifacts Created**:

- Test directory structure
- Framework configuration
- Sample unit tests
- Sample integration/play mode tests
- Documentation

**Next Steps**:

1. Review sample tests and adapt to your game
2. Run initial tests to verify setup
3. Use `test-design` workflow to plan comprehensive test coverage
4. Use `automate` workflow to generate additional tests

**Knowledge Base References Applied**:

- {engine}-testing.md
- qa-automation.md
- test-priorities.md

---

验证

请参阅 checklist.md，了解完整的验证标准。

完成时

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

如果解析出的 workflow.on_complete 非空，请在退出前将其作为最后一条终端指令执行。