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 的完整路径。

命令

.\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 直接启动指定场景：

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

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

$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 -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 通过。