XCEngine/tests/UI/TEST_SPEC.md

XCUI TEST_SPEC

日期: 2026-04-06

1. 目标

本规范只约束 XCUI 模块自身的测试体系，不负责复刻完整 editor 产品。

XCUI 测试体系固定为两条并行通道：

1. unit
2. integration

两者必须同时存在，但职责严格分离：

• unit 负责规则、状态机、路由与回归稳定性，默认可自动执行。
• integration 负责生成可操作 exe，让人直接检查交互、布局、焦点、shortcut、滚动与视觉状态。

2. 顶层目录

XCUI 的测试树统一放在：

tests/UI/
  TEST_SPEC.md
  Core/
    unit/
    integration/
  Runtime/
    unit/
    integration/
  Editor/
    unit/
    integration/

三层必须明确分开：

• Core
  • 共享 UI 基础层测试。
  • 例如 tree state、layout、focus、input router、shortcut、scroll、text controller。
• Runtime
  • 面向游戏运行时 UI 的测试。
  • 例如 screen stack、layer blocking、runtime 输入路由、runtime-only widget。
• Editor
  • 面向编辑器 UI 的测试。
  • 例如 editor 输入宿主、editor shell 验证场景、editor-only widget。

禁止把 Runtime 和 Editor 混在同一个测试目标里。

3. Unit 规范

unit 测试要求：

• 直接面向底层能力。
• 不依赖人工观察。
• 默认进入自动化回归。
• 新增一块共享能力时，优先先补 unit。

unit 测试不负责：

• 人工手感检查。
• 布局观感检查。
• 完整交互场景展示。

4. Integration 规范

integration 测试要求：

• 必须产出可直接运行的 exe。
• 一个 exe 只验证一个聚焦场景。
• 每次只暴露当前批次需要检查的操作区域，不做大杂烩面板。
• 界面中的操作提示默认使用中文，必要时可混用 hover、focus、active、capture 等术语。

integration 测试不负责：

• 模拟完整 editor 产品外壳。
• 把多个无关能力塞进同一个窗口。
• 代替底层 unit 回归。

5. Scenario 目录规范

5.1 Editor

tests/UI/Editor/integration/
  shared/
    src/
  <category>/
    <scenario>/
      CMakeLists.txt
      main.cpp
      View.xcui
      captures/

约束：

• shared/ 只放宿主、渲染、截图、scenario registry 等共用基础设施。
• <category> 表示能力类别，例如 input。
• <scenario> 是最小验证单元。
• 一个 <scenario> 对应一个 exe。

5.2 Runtime

tests/UI/Runtime/integration/
  <category>/
    <scenario>/
      CMakeLists.txt
      main.cpp
      View.xcui
      captures/

Runtime 的集成测试结构与 Editor 保持同一规范，但宿主职责必须与 Editor 分离。

6. 当前已有 Editor 场景

• editor.input.keyboard_focus
• editor.input.pointer_states
• editor.input.shortcut_scope
• editor.layout.splitter_resize

这些场景只用于验证 XCUI 模块能力，不代表开始复刻完整 editor 面板。

7. 截图规范

Editor 集成宿主支持：

• F12 手动截图。
• 截图只允许截当前 exe 自己的渲染结果。
• 截图输出到当前 scenario 自己的 captures/ 目录。

输出格式：

• captures/latest.png
• captures/history/<timestamp>_<index>_<reason>.png

原则：

• 不做持续高频自动截图轰炸。
• 只在人工检查、问题复现、调试定位时触发截图。

8. 开发顺序

XCUI 必须坚持自底向上的建设顺序：

1. 先补共享底层能力。
2. 先补对应 unit。
3. 再补一个聚焦的 integration exe。
4. 人工检查通过后再继续向上推进。

禁止事项：

• 先堆 editor 具体面板，再回头补底层。
• 把 new_editor 当作 XCUI 主测试入口。
• 把一个验证 exe 做成综合试验场。
• 为了赶进度写跨层耦合的临时代码。

9. 当前入口约定

当前 XCUI 的正式验证入口是 tests/UI。

new_editor 不是后续 XCUI 测试体系的主入口，也不应继续承载新的测试场景扩展。