166 lines
3.9 KiB
Markdown
166 lines
3.9 KiB
Markdown
# XCUI TEST_SPEC
|
||
|
||
日期: `2026-04-06`
|
||
|
||
## 1. 目标
|
||
|
||
本规范只约束 XCUI 模块自身的测试体系，不负责复刻完整 editor 产品。
|
||
|
||
XCUI 测试体系固定为两条并行通道：
|
||
|
||
1. `unit`
|
||
2. `integration`
|
||
|
||
两者必须同时存在，但职责严格分离：
|
||
|
||
- `unit` 负责规则、状态机、路由与回归稳定性，默认可自动执行。
|
||
- `integration` 负责生成可操作 exe，让人直接检查交互、布局、焦点、shortcut、滚动与视觉状态。
|
||
|
||
## 2. 顶层目录
|
||
|
||
XCUI 的测试树统一放在：
|
||
|
||
```text
|
||
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
|
||
|
||
```text
|
||
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
|
||
|
||
```text
|
||
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 测试体系的主入口，也不应继续承载新的测试场景扩展。
|