StellarX-kaifa/开发记录/模块/Module-20260915-0001-StellarX核心库与自动化测试基础设施.md

新增功能模块 / 模块重构

适用场景：新增模块、重大模块重构、核心架构能力演进。 不适用场景：小接口或轻量功能变更，请使用“功能变更”模板。

基本信息

• 模块 ID：Module-20260915-0001
• 模块名称：StellarX 核心库与自动化测试基础设施
• 状态：非 UI 与人工 UI 已验证，待提交
• 类型：模块重构 / 架构演进
• 所属系统 / 子系统：StellarX Core / Unit Test / UI Regression
• 版本 / 分支：当前工作区
• 环境：Windows + Visual Studio 2022 + MSVC v143 + EasyX
• 负责人：Codex 协作修改

背景与目标

• 背景:
  • 原应用工程同时承担框架实现、示例入口和回归验证职责，框架代码与测试代码之间缺少明确边界。
  • 本次全量缺陷修复涉及控件生命周期、重绘、事件循环、MBCS 文本和日志等多个核心模块，需要让应用、单元测试和真实 UI Fixture 复用完全相同的实现。
• 当前痛点:
  • 核心框架源文件分散在应用工程中，难以单独复用和验证。
  • 仅依赖手工启动窗口，无法稳定覆盖回调期间所有权变化、ASan 内存安全和多配置构建。
  • UI 控件基于 EasyX 绘制，不是原生子窗口，UIA/WinAppDriver 无法直接按控件语义定位。
• 目标:
  • 将框架实现集中编译为 StellarX.Core 静态库。
  • 建立纯逻辑单元测试、真实 EasyX Fixture 和外部 Win32 UI 驱动三层验证。
  • 让 Debug、Release、Win32、x64 和 x64 ASan 使用统一的核心实现。
• 非目标：[可选]
  • 不在本次工作中将静态库改为 DLL。
  • 不迁移到 Unicode，不改变 GUI 只能在主线程使用的约束。
  • 不将 UI 测试改造成依赖 DPI 或字体的全图 golden image 测试。

模块边界

• 职责:
  • StellarX.Core.vcxproj 编译 Window、Control、Canvas、各类控件、Dialog、TabControl 和日志实现。
  • 主应用、Native Unit Test 和 UI Fixture 通过 ProjectReference 使用同一份核心实现。
  • scripts/test.ps1 统一组织 Unit、Render、UI、All 和 CI 测试入口。
  • scripts/run-ui-tests.ps1 负责启动 Fixture、注入鼠标输入、等待结果并保存诊断文件。
• 不负责什么:
  • 不负责最终应用资源、业务示例和安装包制作。
  • 不把 StellarX.Core.lib 作为普通 GUI 应用用户的运行时 DLL。
  • 不替代 EasyX、Visual C++ Runtime 等外部依赖的发布判断。
• 外部依赖:
  • Visual Studio 2022、MSVC v143、Windows SDK。
  • EasyX 图形库。
  • Visual Studio Native Unit Test Framework。
  • UI 套件需要可交互的 Windows 桌面，并会短暂切换前台窗口和移动鼠标。
• 对外能力 / API:
  • 核心库对外 API 通过 StellarX.h 汇总。
  • StellarX.Core 本身是构建期静态库，不新增运行时动态加载接口。
  • 测试入口通过 PowerShell 参数和 Fixture 场景提供，不属于框架公共 API。
• 关键数据 / 状态:
  • StellarX.Core.lib：框架实现的静态链接产物。
  • StellarX.Tests.dll：Native Unit Test 产物。
  • StellarX.UiFixture.exe：真实 EasyX UI 场景进程。
  • TestResults/：TRX、JSON、PNG 和日志诊断产物。

设计说明

• 核心流程:
  1. StellarX.Core.vcxproj 编译框架头文件和源文件。
  2. imGui-easyX.vcxproj 通过 ProjectReference 链接核心静态库，应用入口保留在 z-testDome.cpp。
  3. StellarX.Tests 和 StellarX.UiFixture 同样引用核心工程，避免测试复制另一份框架代码。
  4. Release 构建将核心代码静态链接进目标可执行文件；运行时不要求单独加载 StellarX.Core.dll。
• 关键对象 / 类关系:
  • StellarX.Core.vcxproj：核心实现的构建边界。
  • Window / Canvas / Control：窗口托管、控件所有权、事件和重绘基础。
  • SxEventLoopInternal.h：批量事件处理测试辅助。
  • SxTextInternal.h：MBCS 字符边界和密码掩码测试辅助。
  • StellarX.Tests：不创建窗口的逻辑测试。
  • StellarX.UiFixture：创建确定性 EasyX 窗口并导出状态和像素证据。
• 生命周期:
  • 核心库在构建阶段生成，静态链接进应用或测试可执行文件。
  • Unit 测试进程独立运行；涉及 UAF 的回归可在 ASan 配置中隔离执行。
  • UI Fixture 按场景创建和关闭图形上下文，失败时由脚本保存证据并发送 WM_CLOSE。
• 事件 / 渲染 / 数据流:
  • 逻辑测试使用 FakeControl、假时钟、假消息源和临时目录验证状态转移。
  • UI 驱动程序通过 SendInput 注入鼠标事件，通过 SetWindowPos 驱动窗口变化。
  • Fixture 导出 JSON 状态和 EasyX 后备缓冲像素，脚本按关键像素不变量判断结果。
• 关键不变量:
  • 应用、逻辑测试和 UI Fixture 必须链接同一份核心实现。
  • ASan 产物与普通 Debug 产物使用独立目录。
  • UI 场景串行执行，避免多个 EasyX 图形上下文争用桌面。
  • UI 断言不依赖 DPI、字体抗锯齿和完整截图的像素一致性。
• 降级 / 回退策略：[可选]
  • 没有交互桌面时，CI 只运行逻辑测试；设置 STELLARX_UI_TESTS=1 且环境满足条件时才执行 UI。
  • 全局 resize、Dialog 开关等场景保留整场景重绘兜底。

实现与影响

• 关键实现点:
  • 新增 StellarX.Core 静态库工程和解决方案项目引用。
  • 新增 StellarX.Tests、StellarX.UiFixture、PowerShell 测试脚本和诊断输出约定。
  • 新增 SxEventLoopInternal.h、SxTextInternal.h 两个仅供内部实现和测试使用的头文件。
  • 核心控件采用稳定句柄、延迟变更事务和统一 geometry/coverage 处理。
• 涉及文件 / 类 / 函数:
  • 工程：StellarX.Core.vcxproj、imGui-easyX.vcxproj、imGui-easyX.sln。
  • 核心：Control、Window、Canvas、Button、Label、TextBox、Table、Dialog、TabControl、SxLogger。
  • 测试：tests/StellarXTests.cpp、tests/UiFixture.cpp、scripts/test.ps1、scripts/run-ui-tests.ps1。
• 兼容性影响:
  • 工程内部从直接编译框架源文件调整为引用 StellarX.Core。
  • 本阶段同时包含破坏性公共 API 调整，迁移方式见 MIGRATION.md。
• 性能影响:
  • 事件循环单轮最多处理 128 条消息，活动轮不固定休眠，空闲轮短暂休眠。
  • 静态库不引入运行时动态分发开销；托管重绘仍按覆盖范围选择性提交并保留全局兜底。
• 风险点:
  • EasyX UI 测试依赖前台交互桌面，不能作为无桌面 CI 的默认测试。
  • 当前 Render 入口复用 UI Fixture，尚未形成完全独立的进程内 Native Render 测试类别。
  • 编译仍存在 EasyX C4201、未使用变量和名称遮蔽等非阻断警告。

测试与验证

• 测试范围:
  • 所有权事务、空 TabControl、Tab 索引、字体拥有权、MBCS 掩码、Tooltip tick、事件批处理和日志配置。
  • Button、Label、TextBox、Canvas、Table、Dialog、TabControl 的真实 EasyX 重绘和 coverage 不变量。
  • Debug x64、Debug x64 ASan、Release x64、Debug Win32，以及 KEY1 至 KEY6 编译。
• 验证步骤:

1. 使用 scripts/test.ps1 -Suite NonUI 验证四套逻辑配置、ASan 和 KEY1 至 KEY6 编译。
2. 按 TESTING.md 的人工 UI 清单验证 KEY1、KEY2、KEY4、KEY5、KEY6。
3. 检查 TRX 和人工验收记录；只有明确允许自动 UI 时才使用 scripts/test.ps1 -Suite All。

• 验证结果:
  • 2026-09-29 的 Debug x64、Debug x64 ASan、Release x64、Debug Win32 均为 15/15 通过。
  • x64 ASan 未报告内存错误；KEY1 至 KEY6 均编译、链接通过。
  • 2026-09-30 为 scripts/test.ps1 补充 UTF-8 BOM 后，Windows PowerShell 5.1 下的 NonUI 全矩阵复验通过。
  • 本轮未启动自动 UI Fixture；用户于 2026-09-30 手工完成 KEY1 至 KEY6，暂未发现明显问题。
  • 2026-07-22 的 UI 六类场景三轮通过记录保留为历史证据；当前快照以 2026-09-30 的人工验收结果为准。
• 已知限制 / 遗留问题：[可选]
  • Render 当前复用单轮真实 UI Fixture；后续可单独建立进程内渲染测试类别。
  • UI 自动化仍需要已解锁的交互式桌面。
  • 本次未清理已有非阻断编译警告。

落地信息

• 关联功能变更 ID：[可选]
  • Feature-20260915-0001
• 关联 BUG / Fix：[可选]
  • 本次以全量缺陷修复矩阵统一记录，未为每个历史问题重新创建重复 BUG/Fix 文档。
• Commit:
  • 当前工作区未提交
• PR：[可选]
• 发布版本：[可选]
• 相关文档：[可选]
  • TESTING.md
  • MIGRATION.md