run-helix-tests

用途

该技能用于从本地机器向 Helix 基础设施提交并监控 .NET MAUI 单元测试。它面向需要验证测试改动、在多个平台（Windows + macOS）上运行测试，或在本地调试 Helix 特定测试失败的用户。注意：它运行的是单元测试（eng/helix.proj），而非设备测试（设备测试使用 helix_xharness.proj）。

主要能力

提交单元测试到 Helix，覆盖 XAML、Core、Essentials、Resizetizer 等测试项目。
支持指定配置（如 Debug）和指定队列提交。
监控已提交作业的状态，支持轮询等待完成。
获取指定工作项的控制台日志，或仅获取失败工作项的日志。
在多个 Helix 队列上并行运行测试。

使用方式

工具要求：使用 pwsh（PowerShell 7+）运行脚本，脚本调用本地 .dotnet/dotnet SDK。

前置条件：

本地 SDK 已就绪，.dotnet/ 文件夹必须存在。若缺失，运行： dotnet cake --target=dotnet
首次运行时需编译构建任务：
- Windows：.\build.cmd -restore -build -configuration Release -projects .\Microsoft.Maui.BuildTasks.slnf
- macOS/Linux：./build.sh -restore -build -configuration Release -projects ./Microsoft.Maui.BuildTasks.slnf

脚本位于 .github/skills/run-helix-tests/scripts/。

提交单元测试到 Helix：
- 提交全部单元测试：pwsh .github/skills/run-helix-tests/scripts/Submit-HelixTests.ps1
- 指定配置：pwsh .github/skills/run-helix-tests/scripts/Submit-HelixTests.ps1 -Configuration Debug
- 仅提交到指定队列：pwsh .github/skills/run-helix-tests/scripts/Submit-HelixTests.ps1 -Queue "Windows.10.Amd64.Open"
监控 Helix 作业状态：
- pwsh .github/skills/run-helix-tests/scripts/Get-HelixJobStatus.ps1 -JobId <JOB_ID>
- 轮询等待完成：pwsh .github/skills/run-helix-tests/scripts/Get-HelixJobStatus.ps1 -JobId <JOB_ID> -Wait
获取 Helix 工作项控制台日志：
- pwsh .github/skills/run-helix-tests/scripts/Get-HelixWorkItemLog.ps1 -JobId <JOB_ID> -WorkItem <WORK_ITEM_NAME>
- 仅获取失败工作项：pwsh .github/skills/run-helix-tests/scripts/Get-HelixWorkItemLog.ps1 -JobId <JOB_ID> -FailedOnly

手动快速开始（不使用脚本）：

Windows：.\helix.cmd
macOS/Linux：./helix.sh 这些包装脚本会设置所需环境变量并提交到 Helix。

提交的测试项目（定义于 eng/helix.proj）：

Controls.Xaml.UnitTests：XAML 解析与编译测试
Controls.Core.UnitTests：核心控件单元测试
Controls.BindingSourceGen.UnitTests：绑定源生成器测试
SourceGen.UnitTests：通用源生成器测试
Core.UnitTests：核心框架测试
Essentials.UnitTests：Essentials API 测试
Resizetizer.UnitTests：图像缩放测试

Helix 队列（并行运行）：

Windows.10.Amd64.Open：Windows 10 x64
osx.15.arm64.maui.open：macOS 15 ARM64

工作流：

提交测试并记录输出中的作业 ID。
监控进度：pwsh .github/skills/run-helix-tests/scripts/Get-HelixJobStatus.ps1 -JobId $jobId -Wait
检查失败：pwsh .github/skills/run-helix-tests/scripts/Get-HelixWorkItemLog.ps1 -JobId $jobId -FailedOnly

调试特定测试失败：

从 Helix 提交输出获取作业 ID。
找到失败的工作项名称。
获取控制台日志：pwsh .github/skills/run-helix-tests/scripts/Get-HelixWorkItemLog.ps1 -JobId <JOB_ID> -WorkItem "Microsoft.Maui.Controls.Xaml.UnitTests.dll"

结果查看：

Helix Portal：https://helix.dot.net/api/2019-06-17/jobs/{jobId}
工作项控制台：https://helix.dot.net/api/2019-06-17/jobs/{jobId}/workitems/{workItemName}/console

适用场景

用户要求“在 Helix 上运行测试”。
用户希望在 Helix 基础设施上验证测试改动。
用户要求“在多个平台上测试”（Windows + macOS）。
用户希望在本地调试 Helix 特定的测试失败。
用户询问“Helix 单元测试”（非设备测试）。

限制

仅运行单元测试，不运行设备测试（iOS、Android、MacCatalyst 模拟器/仿真器）。设备测试需使用 helix_xharness.proj，例如：./eng/common/msbuild.sh ./eng/helix_xharness.proj /t:Test /p:TargetOS=ios，并参考 .github/instructions/helix-device-tests.instructions.md。
需要 PowerShell 7+ 和本地 .dotnet SDK。
首次运行需先编译构建任务。

常见问题：

“dotnet not found”：运行 dotnet cake --target=dotnet 以准备 SDK。
“Build failed”：先运行 build.cmd/build.sh 构建所需项目。
“Queue not available”：在 https://helix.dot.net 检查队列状态。
“Test timeout”：部分测试执行时间较长，属正常现象。

技能介绍

用途

主要能力

使用方式

适用场景

限制