xunit

xUnit.net

诊断输出预算

保持原生测试进度和 ANSI 可见；使用检测到的运行器所支持的标志（MTP/TUnit 使用 --progress on --ansi on），不要在 VSTest 中使用 MTP 开关。将控制台日志级别设为 Warning 或更高，并仅输出一条简洁的最终摘要。不要将进度重绘、成功测试输出或 Information/Debug/Trace 日志重新写入模型上下文。发生失败或崩溃时，仅显示失败的测试/资源、根本错误和相关堆栈帧；去重，并将每条诊断响应限制在 80 行 / 8 KiB 以内。切勿转储完整的控制台/主机/浏览器日志、HTML、TRX 或崩溃产物。将必要产物保存在上下文之外并限制其大小，提供链接，并检查精确且有界的摘录。通过捕获/筛选保留运行器退出代码；说明是否发生截断。仅凭静默不能判定发生卡顿。

适用情况

• 仓库使用 xUnit v2 或 xUnit v3
• 需要添加、运行、调试或修复 xUnit 测试
• 团队不确定项目使用的是 VSTest 还是 Microsoft.Testing.Platform

价值

• 产出具体的项目变更：代码、文档、配置、测试、CI 或审查产物
• 通过明确的规划、验证和最终检查技能减少歧义
• 留下可复用的项目上下文，让后续任务更快、更安全

不适用情况

• TUnit 项目
• MSTest 项目
• 不涉及 xUnit 特定机制的通用测试策略

输入

• 最近的 AGENTS.md
• 测试项目文件和包引用
• 测试项目使用的运行器模型

快速开始

1. 阅读最近的 AGENTS.md，并确认范围和约束。
2. 持续通过 Ralph Loop 执行此技能的 Workflow，直至结果符合要求。
3. 返回包含具体产物和验证证据的 Required Result Format。

工作流

1. 更改命令前，检测正在使用的 xUnit 模型：
   • xunit 通常表示 v2
   • xunit.v3 表示 v3
   • xunit.runner.visualstudio 加上 Microsoft.NET.Test.Sdk 通常表示已启用 VSTest 兼容性
   • TestingPlatformDotnetTestSupport 或 UseMicrosoftTestingPlatformRunner 表示正在使用 Microsoft.Testing.Platform
2. 从 AGENTS.md 中读取仓库实际使用的 test 命令。如果仓库尚未指定命令，请从 dotnet test PROJECT_OR_SOLUTION 开始。
3. 保持运行器模型一致：
   • xUnit v2 通常通过 VSTest 运行
   • xUnit v3 可以作为独立可执行文件，通过 dotnet run 运行
   • xUnit v3 也可以与 Microsoft.Testing.Platform 集成
   • 不要在 Microsoft.Testing.Platform 运行中混用仅适用于 VSTest 的开关
4. 先运行范围最小且有用的测试：
   • 一个项目
   • 一个类
   • 一个 trait
   • 一个方法
5. 对稳定的基于数据的覆盖，优先使用 [Theory]；对单路径不变量检查，使用 [Fact]。
6. 若启用了 xunit.analyzers，请保持启用。修复分析器发现的问题，不要轻易屏蔽。

缺少配置时的初始化

如果用户要求使用 xUnit，但尚未配置：

1. 先检测当前框架：
   • rg -n "xunit(\\.v3)?|xunit\\.runner\\.visualstudio|TestingPlatformDotnetTestSupport|UseMicrosoftTestingPlatformRunner|TUnit|MSTest" -g '*.csproj' .
2. 如果仓库当前使用 TUnit 或 MSTest，不要自动迁移。除非明确要求迁移，否则返回 status: not_applicable。
3. 如果明确要求采用 xUnit，请将包添加到目标测试项目：
   • dotnet add TEST_PROJECT.csproj package xunit.v3
   • 可选的 VSTest 桥接包：dotnet add TEST_PROJECT.csproj package xunit.runner.visualstudio
4. 将仓库测试命令和运行器说明添加到 AGENTS.md。
5. 运行 dotnet test TEST_PROJECT.csproj 或仓库定义的 xUnit 命令，并返回 status: configured 或 status: improved。

交付内容

• 符合仓库当前 xUnit 版本和运行器的 xUnit 测试
• 可在本地和 CI 运行的命令
• 在执行更大范围的测试套件前进行有针对性的验证

验证

• 所选 CLI 与当前运行器模型匹配
• 测试筛选条件或定向运行适用于该运行器
• 测试使用确定性输入和断言
• 除非仓库文档说明存在例外，否则应保持启用 xUnit 专用分析器

Ralph Loop

每项任务都使用 Ralph Loop，包括文档、架构、测试和工具相关工作。

1. 先制定计划（必须）：
   • 分析当前状态
   • 定义目标结果、约束和风险
   • 编写详细的执行计划
   • 列出最终要运行的验证技能，并注明运行顺序和原因
2. 执行一个计划步骤，并产生具体变更。
3. 检查结果，并记录发现的问题及可执行的后续修复措施。
4. 分批应用修复，并重新运行相关检查或审查步骤。
5. 每次迭代后更新计划。
6. 重复上述步骤，直到结果可接受，或只剩下明确的例外。
7. 如果缺少依赖项，则引导安装该依赖项；否则，返回 status: not_applicable，并说明具体原因和备用方案。

必需的结果格式

• status：complete | clean | improved | configured | not_applicable | blocked
• plan：简要计划和当前迭代步骤
• actions_taken：已执行的具体更改
• validation_skills：最终运行的技能，或说明跳过的原因
• verification：命令、检查或审查证据摘要
• remaining：尚未解决的主要事项，或 none

对于仅设置且未执行的请求，返回 status: configured 和准确的后续命令。

加载参考资料

• references/xunit.md
• references/patterns.md
• references/anti-patterns.md

示例请求

• “正确运行此 xUnit 测试套件。”
• “修复我们的 xUnit v3 测试命令。”
• “添加 xUnit 回归测试，并确保与 CI 兼容。”