fix(test): 修复 Windows PowerShell 5 UI 脚本解析
为 run-ui-tests.ps1 补充 UTF-8 BOM，新增 BUG/Fix 与 TESTING 记录。 Windows PowerShell 5.1 完整 UI 回归 1 轮通过；按用户确认同时纳入 /demo/ 忽略规则。
This commit is contained in:
Codex
@@ -3,6 +3,7 @@ x64/
|
||||
.codex-temp/
|
||||
.codex-staging/
|
||||
build/
|
||||
/demo/
|
||||
TestResults/
|
||||
*.vcxproj.user
|
||||
*.obj
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# 外部 UI 驱动：启动确定性 fixture，注入真实鼠标输入，并保存像素与状态诊断。
|
||||
# 外部 UI 驱动：启动确定性 fixture，注入真实鼠标输入，并保存像素与状态诊断。
|
||||
param([int]$Repeat = 1)
|
||||
|
||||
$ErrorActionPreference = 'Stop'
|
||||
|
||||
@@ -0,0 +1,53 @@
|
||||
# BUG-20261005-0001
|
||||
|
||||
> 适用场景：记录问题本身，不展开完整修复方案。修复内容写入对应的 Fix 文档。
|
||||
|
||||
## 基本信息
|
||||
|
||||
- ID: BUG-20261005-0001
|
||||
- 标题: Windows PowerShell 5.1 无法解析 UI 测试脚本
|
||||
- 状态：已验证
|
||||
- 严重性：S3
|
||||
- 优先级：P1
|
||||
- 模块: 自动化测试 / PowerShell / UI 回归
|
||||
- 版本 / 分支: `master`，发现基线 `3d08bac`
|
||||
- 环境: Windows PowerShell 5.1 / 系统活动代码页 CP936
|
||||
- 发现人: Codex 提交前兼容性复验
|
||||
- 关联 Fix ID: Fix-BUG-20261005-0001
|
||||
|
||||
## 问题描述
|
||||
|
||||
- 现象: 使用 `powershell.exe` 启动 `scripts/run-ui-tests.ps1` 时，解析器把 `Add-Type` 的 C# here-string 内容当成 PowerShell 语句，连续报告 `Missing using directive`、`Unexpected attribute 'StructLayout'` 等错误。
|
||||
- 影响范围: Windows PowerShell 5.1 下不能直接运行 UI 测试脚本；经 `scripts/test.ps1` 进入的 `UI`、`Render` 和 `All` 套件同样受影响。
|
||||
- 期望结果: Windows PowerShell 5.1 与 PowerShell 7 都能解析并执行同一份 UI 测试脚本。
|
||||
- 实际结果: PowerShell 7 可正常执行，Windows PowerShell 5.1 在脚本解析阶段终止，尚未进入 UI fixture。
|
||||
|
||||
## 复现信息
|
||||
|
||||
- 前置条件: `scripts/run-ui-tests.ps1` 以 UTF-8 无 BOM 保存，文件中包含中文注释和 `Add-Type @' ... '@` C# here-string。
|
||||
- 复现步骤:
|
||||
|
||||
1. 在仓库根目录运行 `powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\run-ui-tests.ps1 -Repeat 0`。
|
||||
2. 观察解析器在 C# `using` 与 `StructLayout` 行报错。
|
||||
3. 检查文件首字节为 `23 20 E5 A4`，确认缺少 UTF-8 BOM `EF BB BF`。
|
||||
|
||||
- 复现概率：必现
|
||||
- 最小复现 Demo：`powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\run-ui-tests.ps1 -Repeat 0`
|
||||
- 证据：Windows PowerShell 5.1 解析错误输出；修复前文件首字节检查。
|
||||
|
||||
## 初步分析
|
||||
|
||||
- 疑似位置: `scripts/run-ui-tests.ps1` 文件编码。
|
||||
- 触发条件: Windows PowerShell 5.1 按系统 ANSI 代码页解释 UTF-8 无 BOM 脚本，中文字节流干扰后续 here-string 解析。
|
||||
- 相关线索:
|
||||
- `scripts/test.ps1` 已使用 UTF-8 BOM，并在 Windows PowerShell 5.1 下通过完整 NonUI 验证。
|
||||
- `开发记录/TESTING.md` 已明确记录测试入口脚本的 BOM 兼容性要求，但此前只覆盖 `test.ps1`。
|
||||
- 最近相关改动: `c0eca1d` 扩展了 `run-ui-tests.ps1` 的原生关闭回归，但该问题本质是脚本既有编码与 Windows PowerShell 5.1 的兼容边界。
|
||||
|
||||
## 跟踪信息
|
||||
|
||||
- 首次发现时间: 2026-10-05
|
||||
- 最后更新时间: 2026-10-05
|
||||
- 修复版本: 本次修复提交
|
||||
- 验证版本: Windows PowerShell 5.1 完整 UI 回归 1 轮通过；PowerShell 7 AST 解析零错误
|
||||
- 备注: 修复只应增加 UTF-8 BOM，不改动 UI 测试逻辑、参数或场景。
|
||||
@@ -0,0 +1,69 @@
|
||||
# Fix-BUG-20261005-0001
|
||||
|
||||
> 适用场景：记录某个 BUG 的修复方案、影响评估、验证结果与落地信息。
|
||||
|
||||
## 关联信息
|
||||
|
||||
- Fix ID: Fix-BUG-20261005-0001
|
||||
- 关联 BUG ID: BUG-20261005-0001
|
||||
- 修复目标: 让 `scripts/run-ui-tests.ps1` 可由 Windows PowerShell 5.1 和 PowerShell 7 一致解析执行
|
||||
- 状态：已验证
|
||||
- 负责人: Codex
|
||||
- 分支 / 版本: `master`，修复基线 `3d08bac`
|
||||
|
||||
## 根因分析
|
||||
|
||||
- 根因: `run-ui-tests.ps1` 使用 UTF-8 无 BOM 保存。Windows PowerShell 5.1 不会稳定按 UTF-8 解释无 BOM 脚本，在 CP936 环境中误解中文注释字节，继而破坏 `Add-Type` C# here-string 的词法边界。
|
||||
- 触发条件: 使用 Windows PowerShell 5.1 读取当前脚本；PowerShell 7 默认按 UTF-8 读取，因此不触发。
|
||||
- 为什么之前没发现: 自动回归主要由 PowerShell 7 驱动；仓库只为 `scripts/test.ps1` 明确保留了 UTF-8 BOM，没有把同一约束覆盖到包含中文注释的 UI 子脚本。
|
||||
- 关键证据: 修复前 `powershell.exe ... run-ui-tests.ps1 -Repeat 0` 在解析阶段失败，文件首字节没有 `EF BB BF`；同仓库带 BOM 的 `scripts/test.ps1` 可被 Windows PowerShell 5.1 正确解析。
|
||||
|
||||
## 修复方案
|
||||
|
||||
- 修复思路: 仅在 `scripts/run-ui-tests.ps1` 文件起始处补充 UTF-8 BOM，使 Windows PowerShell 5.1 明确按 UTF-8 解码；不改动脚本业务逻辑。
|
||||
- 关键改动:
|
||||
- `scripts/run-ui-tests.ps1`：增加 UTF-8 BOM。
|
||||
- `开发记录/TESTING.md`：把 BOM 约束扩展到 `test.ps1` 与 `run-ui-tests.ps1`。
|
||||
- 新增对应 BUG/Fix 记录，保留复现、根因、验证与回滚边界。
|
||||
- 涉及文件 / 类 / 函数: `scripts/run-ui-tests.ps1`、`开发记录/TESTING.md`。
|
||||
- 影响的 API / 行为: 无框架 API 或 UI 场景行为变化；只改变 Windows PowerShell 5.1 的脚本解码结果。
|
||||
- 关键约束 / 不变量:
|
||||
- BOM 之外脚本正文必须保持字节等价。
|
||||
- Windows PowerShell 5.1 与 PowerShell 7 均须通过解析。
|
||||
- 完整 UI 回归仍须覆盖普通场景、`native-close` 和 `modal-close`。
|
||||
- 回滚点 / 开关: 可独立移除文件开头的三字节 BOM，但会恢复 Windows PowerShell 5.1 解析失败。
|
||||
|
||||
## 影响评估
|
||||
|
||||
- 影响范围: UI 自动化测试入口的文本编码识别。
|
||||
- 兼容性影响：改善 Windows PowerShell 5.1 兼容性；PowerShell 7 原行为保持不变。
|
||||
- 行为变化：无测试逻辑变化。
|
||||
- 性能影响：无。
|
||||
- 回归风险:
|
||||
- 极少数不支持 UTF-8 BOM 的通用文本工具可能显示一个不可见签名字符；PowerShell 5.1/7 均原生支持该格式。
|
||||
- 若编辑器后续以 UTF-8 无 BOM 重写文件，问题会复发，因此同步固化文档约束。
|
||||
|
||||
## 验证结果
|
||||
|
||||
- 验证步骤:
|
||||
|
||||
1. 检查 `run-ui-tests.ps1` 首三字节为 `EF BB BF`，并确认除 BOM 外正文与修复前一致。
|
||||
2. 使用 Windows PowerShell 5.1 执行 `-Repeat 0` 解析/入口冒烟。
|
||||
3. 使用 Windows PowerShell 5.1 执行完整 UI 回归 1 轮。
|
||||
4. 使用 PowerShell 7 解析脚本并执行入口冒烟。
|
||||
5. 检查新增文档链接、末尾换行、尾随空白和 Git 暂存范围。
|
||||
|
||||
- 验证结果:
|
||||
- 文件首三字节为 `EF BB BF`；解码时去除 BOM 后，脚本正文与 `3d08bac` 中的版本完全一致。
|
||||
- Windows PowerShell 5.1 执行 `-Repeat 0` 入口冒烟通过，不再出现 C# `using`/`StructLayout` 解析错误。
|
||||
- Windows PowerShell 5.1 执行完整 UI 回归 1 轮通过。
|
||||
- PowerShell 7 AST 解析错误数为 0。
|
||||
- 回归检查: UI 普通场景、`native-close` 与 `modal-close` 均由同一轮 Windows PowerShell 5.1 回归覆盖。
|
||||
- 验证证据: `TestResults/ui/20261005-012509-923-32588`。
|
||||
|
||||
## 落地信息
|
||||
|
||||
- Commit: 与修复代码同提交（见 Git 历史）
|
||||
- PR：无
|
||||
- 发布版本：未发布
|
||||
- 备注: 本次提交按用户要求同时收口仓库内其他未提交改动；这些改动不改变本 Fix 的根因与验证边界。
|
||||
+1
-1
@@ -31,7 +31,7 @@
|
||||
|
||||
Windows MSVC AddressSanitizer 不支持 LeakSanitizer，因此脚本使用 `detect_leaks=0:halt_on_error=1`。ASan 产物独立写入 `build\x64\Debug-asan`，不会污染普通 Debug 构建。
|
||||
|
||||
`scripts/test.ps1` 使用 UTF-8 BOM 保存，确保 Windows PowerShell 5.1 能正确读取中文注释，不会把注释后的语句误判为注释内容。
|
||||
`scripts/test.ps1` 与 `scripts/run-ui-tests.ps1` 均使用 UTF-8 BOM 保存，确保 Windows PowerShell 5.1 能正确读取中文注释和内嵌 C# here-string，不会把注释后的语句或 `Add-Type` 内容误判为 PowerShell 语句。新增或重写测试脚本时不得移除 BOM。
|
||||
|
||||
## 覆盖范围
|
||||
|
||||
|
||||
Reference in New Issue
Block a user