qa-game

QA 游戏

为现有游戏项目添加 Playwright 自动化 QA 测试。测试会验证游戏能否启动、场景是否正常、计分功能是否有效，以及视觉效果是否出现问题——为游戏增设一道安全网。

说明

分析 $ARGUMENTS 指定的游戏（如果未提供路径，则分析当前目录）。

首先，加载 game-qa 技能，以获取完整的测试模式和测试夹具。

第 1 步：审查可测试性

• 阅读 package.json，确定游戏引擎和开发服务器端口
• 阅读 vite.config.js，查看服务器端口
• 阅读 src/main.js，检查是否已暴露 window.__GAME__、window.__GAME_STATE__、window.__EVENT_BUS__
• 阅读 src/core/GameState.js，了解有哪些状态可用
• 阅读 src/core/EventBus.js，了解有哪些事件
• 阅读 src/core/Constants.js，了解游戏参数（速率、速度、持续时间、最大值）
• 阅读所有场景文件，了解游戏流程
• 如果存在 design-brief.md，请阅读——其中记录了预期机制、数值范围以及胜负状态是否可达

第 2 步：配置 Playwright

1. 安装依赖：npm install -D @playwright/test @axe-core/playwright && npx playwright install chromium
2. 创建 playwright.config.js，配置正确的开发服务器端口和 webServer 配置
3. 如果 src/main.js 中尚未暴露 window.__GAME__、window.__GAME_STATE__、window.__EVENT_BUS__、window.__EVENTS__，则将其暴露
4. 创建测试目录结构：

   tests/
   ├── e2e/
   │   ├── game.spec.js
   │   ├── visual.spec.js
   │   └── perf.spec.js
   ├── fixtures/
   │   └── game-test.js
   └── helpers/
       └── seed-random.js
   

5. 添加 npm 脚本：test、test:ui、test:headed、test:update-snapshots

第 3 步：生成测试

根据游戏的实际行为编写测试：

• game.spec.js：启动测试、场景切换、输入处理、计分、游戏结束、重新开始
• visual.spec.js：对稳定场景进行截图回归测试（游戏开始时的初始状态、游戏结束画面）。跳过游戏进行中的截图——移动对象会导致截图不稳定。
• perf.spec.js：加载时间预算、游戏进行中的 FPS、画布尺寸

遵循 game-qa 技能中的模式。使用 gamePage 测试夹具。使用 page.evaluate() 读取游戏状态。使用 page.keyboard.press() 输入操作。

第 4 步：设计意图测试

在 game.spec.js 中添加一个 test.describe('Design Intent') 块。这些测试用于发现那些虽然存在，但作用太弱、无关紧要的机制。

1. 失败条件：确定性地检测游戏是否存在失败状态。 阅读 GameState.js——如果其中有 won、result 或类似的布尔值／枚举字段，说明游戏能区分胜利和失败。还要检查 main.js 中的 render_game_to_text()——如果它返回不同的结果模式（例如 'win' 与 'game_over'），则说明游戏存在失败状态。

   如果存在失败状态：开始游戏，不输入任何操作，让游戏运行至结束（使用 page.waitForFunction，并根据 Constants.js 中的回合持续时间设定等待时间）。断言结果为失败（例如 won === false、mode === 'game_over'）。

   此断言不可妥协。 不要编写在玩家什么都不做就获胜时也能通过的测试。如果当前游戏的行为是“玩家不输入操作也会获胜”，那就是一个 bug——编写测试来捕获它。

2. 对手／AI 压力：如果存在 AI 驱动的机制（自动攀升的条形、敌人生成、难度递增），则测试其是否能造成显著的状态变化。让游戏在玩家不输入操作的情况下运行半个回合。断言对手状态至少达到其最大值的 25%。如果存在 design-brief.md，则使用其中预期的数值范围设置阈值。否则，根据 Constants.js 推算：计算 rate * duration，并断言其达到有意义的程度。

3. 胜利条件：测试玩家主动输入是否能带来胜利。在整个回合中持续快速输入，并断言最终结果为胜利。

第 5 步：实体交互审计

审查碰撞和交互逻辑，找出可能让初次游玩的玩家感到困惑的不对称之处。

如果 design-brief.md 中有“实体交互”一节，就以此为检查清单。否则，直接审查 GameScene.js：

1. 找出所有碰撞处理程序、重叠检查或基于距离的交互
2. 梳理各实体之间的交互关系
3. 标记任何可见的移动实体：它会与一方（玩家或对手）交互，却不会与另一方交互。在测试文件中添加 // QA FLAG: asymmetric interaction 注释，并注明实体名称和不对称之处

这只是标记，不会导致测试直接失败。有些不对称是有意为之的（例如，只影响玩家的危险物）。该标记可确保这种不对称是经过有意识的设计选择，而非疏忽。

第 6 步：运行并验证

1. 运行 npx playwright test 执行所有测试
2. 如果视觉测试首次运行时失败，这是预期情况——使用 npx playwright test --update-snapshots 生成基准
3. 再次运行以验证所有测试均通过
4. 总结结果

第 7 步：报告

用通俗易懂的英语告诉用户：

• 创建了多少项测试，以及这些测试会检查什么
• 如何运行测试：npm test（无头模式）、npm run test:headed（查看浏览器）、npm run test:ui（交互式仪表板）
• “这些测试是你的安全网。修改后运行它们，确保没有任何内容出错。”

使用示例

/qa-game examples/flappy-bird

结果：安装 Playwright → 创建 15 项测试（启动、场景转换、输入、计分、重新开始、游戏结束、视觉回归、FPS、加载时间）→ 生成包含 fixtures 和辅助程序的 tests/ 目录 → 所有测试均通过。修改后可随时运行 npm test。

下一步

告诉用户：

你的游戏现在有自动化测试了！最后，运行 /game-creator:review-game，进行全面的架构审查——它会检查你的代码结构和性能模式，并给出评分及具体的改进建议。

流程进度： /viral-game → /design-game → /add-audio → /qa-game → /review-game

（这是 /viral-game 一次性流程，而非 /make-game 的多阶段、里程碑驱动工作流。）