StellarX-kaifa/开发记录/TESTING.md

# StellarX 自动化测试

## 依赖

- Visual Studio 2022 MSVC v143、Windows SDK、Native Unit Test Framework。
- EasyX 已安装到当前 MSVC 环境。
- UI 套件需要已解锁的交互式 Windows 桌面，会短暂切换前台窗口并移动鼠标，结束后恢复鼠标位置。

默认工具路径为 `D:\vs2022`。其他安装位置可设置：

- `STELLARX_MSBUILD`：`MSBuild.exe` 的完整路径。
- `STELLARX_VSTEST`：`vstest.console.exe` 的完整路径。

## 命令

```powershell
.\scripts\test.ps1 -Suite Unit -Configuration Debug -Platform x64
.\scripts\test.ps1 -Suite NonUI
.\scripts\test.ps1 -Suite Render
.\scripts\test.ps1 -Suite UI
.\scripts\test.ps1 -Suite All
.\scripts\test.ps1 -Suite CI
```

- `Unit`：构建核心静态库并运行 VS Native Unit Test。
- `NonUI`：运行 Debug x64、Debug x64 ASan、Release x64、Debug Win32 和 KEY1 至 KEY6 编译，不启动或操作任何窗口。
- `Render`：运行确定性 EasyX fixture 和关键像素断言；当前与单轮 UI fixture 共用实现。
- `UI`：使用 `SendInput` 驱动 ownership、geometry、tooltip、tab、table、dialog 六类真实窗口场景。
- `All`：Debug x64、Debug x64 ASan、Release x64、Debug Win32、KEY1 至 KEY6 编译、UI 连续三轮。
- `CI`：默认运行 Debug x64、Release x64 和 Debug Win32；设置 `STELLARX_UI_TESTS=1` 后增加单轮 UI。

Windows MSVC AddressSanitizer 不支持 LeakSanitizer，因此脚本使用 `detect_leaks=0:halt_on_error=1`。ASan 产物独立写入 `build\x64\Debug-asan`，不会污染普通 Debug 构建。

`scripts/test.ps1` 与 `scripts/run-ui-tests.ps1` 均使用 UTF-8 BOM 保存，确保 Windows PowerShell 5.1 能正确读取中文注释和内嵌 C# here-string，不会把注释后的语句或 `Add-Type` 内容误判为 PowerShell 语句。新增或重写测试脚本时不得移除 BOM。

## 覆盖范围

逻辑测试覆盖：

- 稳定句柄与回调期间 self/sibling/add/remove/clear 所有权变更。
- Tab 延迟新增、失败返还所有权、重复标题和页面激活状态。
- 字体名拥有权与内容比较。
- MBCS 密码掩码、非法尾字节容错。
- Tooltip 单调时钟 tick、禁用和移出清理。
- 1000 条消息的 128 条批处理上限、空闲休眠和关闭顺序。
- 日志配置原子切换与滚动行完整性。

UI/像素测试覆盖：

- 回调删除自身后旧区域恢复。
- Button、Label、TextBox、Canvas 的移动、缩放和隐藏残影。
- 静止 Tooltip 到期显示及移出清除。
- 同名页签唯一选中、唯一页面可见。
- 极窄 Table 的最小宽度和 coverage 外像素不变量。
- 两层异步 Dialog 先后关闭、下层可见且可继续交互。

## 诊断产物

所有产物位于未跟踪的 `TestResults\`：

- 单元测试：TRX。
- UI 成功：场景 JSON、`screen.png`、fixture 标准输出和错误日志。
- UI 失败：`driver-error.json`、`failure.png`，以及已生成的场景中间截图。

UI fixture 按 PID 和精确标题枚举 `EasyXWnd`，使用 `PrintWindow(PW_CLIENTONLY)` 获取不受遮挡影响的客户区像素，不使用 DPI 和字体敏感的全图 golden image。

## 人工 UI 验收

本轮收口不自动启动 UI。发布或推送前，由人工依次验证 KEY1、KEY2、KEY4、KEY5、KEY6；KEY3 只做启动兼容性冒烟。

### 构建与启动

推荐双击仓库根目录的 `Run-Key-Test.cmd`，输入 `1` 至 `6` 后，脚本会重新构建并启动对应场景。关闭测试窗口后会返回选择菜单，输入 `0` 退出；脚本只负责构建和启动，不会自动操作 UI。

也可以从 PowerShell 直接启动指定场景：

```powershell
.\scripts\run-key.ps1 -Key 5
```

若启动器不可用，将下面命令中的 `KeyScenario` 改为待测编号。每次构建完成后手动启动生成的程序：

```powershell
$msbuild = 'D:\vs2022\MSBuild\Current\Bin\MSBuild.exe'
& $msbuild .\imGui-easyX.vcxproj /m /t:Rebuild /p:Configuration=Debug /p:Platform=x64 /p:KeyScenario=1 /p:EnableAsan=false /v:minimal
.\build\x64\Debug\imGui-easyX.exe
```

### 通用通过标准

- 窗口可正常启动、缩放、最大化、还原和关闭，无崩溃、卡死或断言。
- Hover、按下、释放和 Tooltip 状态及时变化，鼠标移出后不残留高亮、文字或浮层。
- 切页、分页、移动或缩放后无旧像素、黑块、重影、错层和控件穿透。
- 一次点击只触发一次结果；禁用控件不触发回调；模态对话框阻止底层交互。

### 必测场景

| 场景 | 操作 | 通过标准 |
|---|---|---|
| KEY1 | 进入页签 1，点击页内“按钮”重置表格，不移动鼠标立即观察分页区；连续重置三次并执行上一页、下一页；点击外部 `test` 多次激活同一页，再依次切换三个页签 | 重置后的首帧立即完整显示“第1页/共2页”，不依赖 hover 或后续重绘恢复；重复激活不闪烁；Table 超出页面区域的内容在切页后完全清除；无残影或层级错乱 |
| KEY2 | 拉宽、缩窄、最大化并还原窗口；点击多个位按钮，执行位取反、左移、右移、一键置 0/1 和有符号切换 | 32 位“位号 + 按钮”始终对齐；五个区块铺满且不重叠；十六进制、十进制、上次值、本次值立即同步 |
| KEY4 | 打开非模态对话框，在顶部按钮、页签和分页区快速移动鼠标；再打开模态对话框并拖动窗口，随后关闭 | 遮挡区不发生 Hover/Tooltip 穿透；标题、关闭按钮和底层背景无残影；关闭后底层 Hover 立即恢复 |
| KEY5 | 在三层 Canvas、两个页签及其页内按钮间移动和点击；触发各处 Tooltip；操作 Table 分页按钮并观察粉色浮层 | 深层按钮状态正常；Tooltip 出现和清除完整；页签与页面层级正确；Table 重绘不会擦除或覆盖上层浮层 |
| KEY6 | 点击圆形和椭圆按钮的内部及外接矩形角落；点击禁用按钮；切换右侧页签并操作页内控件；分别验证 YesNo、RetryCancel、AbortRetryIgnore | 形状外区域不误触发；禁用按钮不改变状态；右侧页签布局稳定；消息框结果正确，非模态关闭后无残留且底层 Hover 恢复 |
| KEY3 | 启动后完成登录页和旧业务页的基本切换 | 能正常进入和切换，无明显布局或交互倒退 |

### 本轮验收记录

- 验收日期：2026-09-30
- 验收方式：用户按上述清单手工执行 KEY1 至 KEY6。
- 验收结论：全部场景已完成，当前快照暂未发现明显问题。
- 自动复验：2026-09-30 使用 Windows PowerShell 5.1 执行 `NonUI`，四种配置均为 15/15 通过，KEY1 至 KEY6 编译链接成功。
- 说明：该结论代表本轮人工回归通过，不等同于对所有运行环境和未覆盖路径作无缺陷保证。

### 阶段 1 输入地基人工回归（2026-10-07，已完成）

本轮阶段 1 保留旧 `EX_KEY` 业务旁路，人工目标是确认“采集与观察队列接入后，现有交互和真实 IME 行为没有改变”。自动测试不能替代以下操作：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\run-input-probe-manual.ps1 -ImeName MicrosoftPinyin
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\run-input-probe-manual.ps1 -ImeName Sogou
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\run-key.ps1
```

- 微软拼音与搜狗分别完成固定非敏感测试串的候选、提交、重复字符、Escape 取消、数字选词和输入布局切换；候选 UI、输入响应和关闭流程不得卡顿或重复提交。
- 输入探测摘要必须 `sequenceStrict=True`、`textRawWParamLeaks=0`、结果/回声关系符合对应 IME 实际行为，并正常观察到关闭；探测器显式记账的诊断丢失不应被隐藏。
- KEY1–6 按上表执行；重点确认一次按键/点击只触发一次，阶段 1 兼容旁路没有造成双触发。
- 完成后，`Module-20261007-0005` 才可记为“自动与人工兼容性回归通过”。

#### 2026-10-07 执行结果

- 用户按固定清单分别完成微软拼音与搜狗真实输入，并完成 KEY1–6 人工交互；当前快照未发现卡顿、重复提交、双触发或既有控件行为退化。
- 微软拼音有效证据位于 `TestResults/InputProbe/manual-20261007-192828-293-MicrosoftPinyin`：`sequenceStrict=True`、`recordsLost=0`、`textRawWParamLeaks=0`，3 次正式结果均形成 `WM_IME_CHAR:matched`，关闭与 `session_end` 完整。
- 搜狗有效证据位于 `TestResults/InputProbe/manual-20261007-193100-289-Sogou`：`sequenceStrict=True`、`recordsLost=0`、`textRawWParamLeaks=0`，3 次正式结果均形成 `WM_IME_CHAR:matched`，关闭与 `session_end` 完整。搜狗本轮只出现 3 组标准生命周期，再次证明生命周期不能替代原始 `VK_PROCESSKEY` 的单键归属快照。
- 两轮均未观察到 `WM_INPUTLANGCHANGE`；这与当前系统同一 HKL 下切换 TSF 输入配置文件的既有证据一致，不把“用户执行过切换”和“窗口收到 HKL 变化消息”混写成同一结论。
- 微软拼音候选框在无文本焦点叶子、无 caret 锚点的输入探测夹具中落到系统回退位置。阶段 1 不实现 FocusManager、TextBox 或 `ImmSetCandidateWindow`，因此该现象作为后续集成边界保留，不把本轮采集通过误写成候选框定位通过；定位能力仍以阶段 0C 证据为准。
- 人工回归发现 KEY5/KEY6 曾把 Tooltip 延时覆盖为 `120 ms`，不是框架默认计时错误；现已移除覆盖，使人工用例使用 Button 默认 `1000 ms`。自动化 Tooltip fixture 继续使用独立的 `200 ms` 测试延时。
- KEY2 是 KEY1–6 中唯一启用文件日志的场景；轮转阈值由 `1024` 字节调整为 `10 * 1024 * 1024` 字节（10 MiB）。轮转在完整日志行写完后检查，单文件允许最多超出最后一行的长度。
- 调整后执行正式 `NonUI`：Debug x64、x64 ASan、Release x64、Debug Win32 均为 27/27，KEY1–6 全部重新编译链接成功。

### 失败留证

- 记录 KEY 编号、窗口尺寸、操作顺序和实际现象。
- 截取包含整个客户区的截图；闪烁或延迟问题录制短视频。
- 若崩溃，保留 Visual Studio 调用栈和当次日志，不继续把该快照标记为 UI 通过。