# XCUI TEST_SPEC 日期: `2026-04-09` ## 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、shared widget primitive。 - `Runtime` - 面向游戏运行时 UI 的测试。 - 例如 screen stack、layer blocking、runtime 输入路由、runtime-only widget。 - `Editor` - 面向编辑器 UI 的测试。 - 例如 editor host、editor shell、editor-only widget、editor domain 集成。 - 当前阶段采用固定代码样式：Editor 默认样式、palette、metrics 与视觉语义由代码层固定维护，不再为 Editor 主题解析单独扩测试主线。 当前阶段的资源化方向约束： - `Core` / `Runtime` 可以继续推进资源化、热重载与资源驱动验证。 - `Editor` 当前不以主题资源解析作为主线，验证重点放在 editor-only 结构、状态机、交互和固定代码样式。 禁止把 `Runtime` 和 `Editor` 混在同一个测试目录里。 当前正式验证入口固定为 `tests/UI`，不得把 `new_editor` 当作当前验证树的替代入口。 ## 3. Unit 规范 `unit` 测试要求： - 直接面向底层能力。 - 不依赖人工观察。 - 默认进入自动化回归。 - 新增一块共享能力时，优先先补 `unit`。 `unit` 测试不负责： - 人工手感检查。 - 布局观感检查。 - 完整交互场景展示。 ## 4. Integration 规范 `integration` 测试要求： - 必须产出可直接运行的 exe。 - 一个 exe 只验证一个聚焦场景。 - 如果某个交互契约已经超出 basic 场景的检查范围，例如 multi-select、drag/drop、inline rename，就必须拆成独立 scenario，不得继续往 basic exe 里堆。 - 每次只暴露当前批次需要检查的操作区域，不做大杂烩面板。 - 界面中的操作提示默认使用中文，必要时可混用 `hover`、`focus`、`active`、`capture` 等术语。 - 测哪一层，就把场景放到哪一层的 `integration/` 目录下。 - `Editor` 集成验证当前只覆盖 editor-only 基础层；在 `Core / Editor` 基础层未收口前，不在 `new_editor` 中提前做业务面板验证。 `integration` 测试不负责： - 模拟完整 editor 产品外壳。 - 把多个无关能力堆进同一个窗口。 - 代替底层 `unit` 回归。 ## 5. Scenario 目录规范 ### 5.1 Core ```text tests/UI/Core/integration/ shared/ src/ themes/ / / CMakeLists.txt main.cpp View.xcui captures/ ``` 约束： - `shared/` 只放共享宿主、渲染、截图、scenario registry 等基础设施。 - `` 表示共享能力类别，例如 `input`、`layout`、`style`。 - `` 是最小验证单元。 - 一个 `` 对应一个 exe。 ### 5.2 Runtime ```text tests/UI/Runtime/integration/ / / CMakeLists.txt main.cpp View.xcui captures/ ``` Runtime 的集成测试结构与 Core 保持同一规范，但宿主职责必须与 Core / Editor 分离。 ### 5.3 Editor ```text tests/UI/Editor/integration/ / / CMakeLists.txt main.cpp [View.xcui] captures/ ``` Editor 集成测试只承载 editor-only 场景，不再承载共享 Core primitive。 补充规则： - 当验证目标是 `editor-only` 状态机、workspace 装配或 panel 生命周期，而不是 XCUI markup 渲染本身时，允许使用 custom host 场景，不强制要求 `View.xcui`。 - 即使使用 custom host，也必须保持“一场景一个 exe、一个目录、一套独立 captures”。 ## 6. 当前已有场景 ### 6.1 Core - `core.input.keyboard_focus` - `core.input.pointer_states` - `core.input.scroll_view` - `core.input.shortcut_scope` - `core.layout.splitter_resize` - `core.layout.tab_strip_selection` - `core.layout.workspace_compose` 这些场景只用于验证 XCUI 共享基础能力，不代表开始复刻完整 editor 面板。 ### 6.2 Editor - `editor.shell.workspace_compose` - `editor.state.panel_session_flow` - `editor.shell.tree_view_multiselect` - `editor.shell.tree_view_inline_rename` - `editor.shell.list_view_multiselect` - `editor.shell.list_view_inline_rename` ## 7. 截图规范 集成宿主支持： - `F12` 手动截图。 - 截图只允许截当前 exe 自己的渲染结果。 - 截图只允许输出到当前构建目录下、当前 exe 自己的 `Debug/captures//` 目录。 输出格式： - `build/.../Debug/captures//latest.png` - `build/.../Debug/captures//history/__.png` 原则： - 不做持续高频自动截图轰炸。 - 只在人工检查、问题复现、调试定位时触发截图。 ## 8. 开发顺序 XCUI 必须坚持自底向上的建设顺序： 1. 先补共享底层能力。 2. 先补对应 `unit`。 3. 再补一个聚焦的 `integration` exe。 4. 人工检查通过后再继续向上推进。 5. 基础层稳定后，才允许把能力接入 `new_editor` 宿主做装配冒烟；不反向把 `new_editor` 当作验证入口。 禁止事项： - 先堆 editor 具体面板，再回头补底层。 - 把 `new_editor` 当作 XCUI 主测试入口。 - 在基础层未完成前，把业务面板直接塞进 `new_editor` 作为主推进路径。 - 把一个验证 exe 做成综合试验场。 - 为了赶进度写跨层耦合的临时代码。 ## 9. 当前入口约定 当前 XCUI 的正式验证入口是 `tests/UI`，其下的 `Core / Runtime / Editor` 三层测试树是唯一有效的当前验证体系。 `new_editor` 只作为未来重建 editor 的产品宿主，不是当前测试入口，也不继续承载新的测试场景扩展。 `tests/UI/TEST_SPEC.md` 负责顶层测试分层、职责边界和执行规则。 `tests/UI/Editor/integration/README.md` 负责 Editor 集成验证的当前入口说明、场景清单、构建运行和截图约定。