fix(test): 修复 Windows PowerShell 5 UI 脚本解析

为 run-ui-tests.ps1 补充 UTF-8 BOM，新增 BUG/Fix 与 TESTING 记录。 Windows PowerShell 5.1 完整 UI 回归 1 轮通过；按用户确认同时纳入 /demo/ 忽略规则。
2026-10-05 01:27:50 +08:00
parent 3d08bac1b9
commit 225bc35219
5 changed files with 125 additions and 2 deletions
@@ -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 测试逻辑、参数或场景。