本文提供了 MTP 命令行选项的中心入口点。
Important
平台选项可从 MTP 本身获取。 只有当每个目标测试应用程序都注册了提供这些扩展选项的扩展包时,扩展选项才可用。 直接添加该包,或使用包含该包的测试 SDK 配置或配置文件。 如果测试应用程序未注册扩展,则运行失败并出现退出代码 5,因为无法识别该选项。
平台选项
@指定响应文件的名称。 响应文件名必须紧跟在
@字符后面,并且在@字符和响应文件名之间不能有空格。响应文件中的选项被解释为在命令行中存在于该位置。 不能使用反斜杠字符
\连接行。 使用响应文件有助于执行可能超过终端限制的很长的命令。 可以将响应文件与内联命令行参数组合在一起。 例如:./TestExecutable.exe @"filter.rsp" --timeout 10s其中 filter.rsp 可以包含以下内容:
--filter "A very long filter"或者,可以使用单个 rsp 文件来指定超时和筛选,如下所示:
./TestExecutable.exe @"arguments.rsp"--filter "A very long filter" --timeout 10s注释
使用
dotnet test时,SDK 命令行分析程序使用每行令牌方法,其中响应文件中的每一行都被视为单个令牌。 在这种情况下,每个参数必须独占一行:--filter A very long filter --timeout 10s--config-file指定 testconfig.json 文件。
--debug在启动时暂停测试执行,以便可以将调试器附加到测试进程。 等效于将
TESTINGPLATFORM_WAIT_ATTACH_DEBUGGER环境变量 设置为1. 浏览器平台上不受支持。注释
从版本 1.9.0 开始,MTP 中提供了此选项。 它替换了上一
--debug-wait-attach个选项(在 MTP 1.6.0 中引入);旧名称已被删除,不能再使用。--diagnostic启用诊断日志。 默认日志级别为
Trace。 对于每个测试源,MTP 写入<asm>_<tfm>_<arch>_<timestamp>.diag。 如果时间戳冲突,MTP 会添加进程和计数器后缀,而不是覆盖现有文件。--diagnostic-synchronous-write强制内置的文件记录器以同步方式写入日志。 对于在进程崩溃时不想丢失任何日志条目的场景非常有用。 这会减慢测试执行速度。
注释
从版本 2.0.0 开始,MTP 中可用。 它取代了之前的
--diagnostic-filelogger-synchronouswrite选项,该选项已在 MTP 2.0.0 中移除。--diagnostic-output-directory诊断日志记录的输出目录,如果未指定,则会在默认的 TestResults 目录中生成该文件。
--diagnostic-file-prefix日志文件名的前缀。 默认值为
<asm>_<tfm>_<arch>。注释
从版本 2.0.0 开始,MTP 中可用。 它取代了之前的
--diagnostic-output-fileprefix选项,该选项已在 MTP 2.0.0 中移除。--diagnostic-verbosity当使用
--diagnostic开关时定义详细程度级别。 可用值包括Trace、Debug、Information、Warning、Error和Critical。--enable-dynamic-extensions启用“加载测试应用程序旁的
*.testingplatformextensions.json清单文件声明的扩展”。 默认情况下禁用动态扩展。 有关安全要求和清单架构,请参阅 动态加载扩展。注释
从版本 2.4.0 开始,MTP 中提供了此选项。
--exit-on-process-exit如果依赖进程退出,请退出测试进程。 必须提供 PID。
--filter-uid按测试节点 UID 筛选要运行的测试。 接受一个或多个 UID。
框架作者必须遵循
TestNodeUidListFilter以进行发现和执行。 有关实现指南,请参阅遵循请求筛选器。注释
从版本 1.8.0 开始,MTP 中提供了此选项。 从 MTP 2.3.0 开始,不能将
--filter-uid与--treenode-filter组合使用;如果同时指定两者,命令行验证将失败,并返回InvalidCommandLine退出代码。--help打印出有关如何使用命令的说明。
--ignore-exit-code允许忽略一些非零退出代码,并转而返回为
0。 有关详细信息,请参阅忽略特定的退出代码。--info显示有关.NET测试应用程序的高级信息,例如:
- 平台。
- 环境。
- 每个已注册的命令行提供程序,例如其
name、version、description和options。 - 每个已注册的工具,例如其
command、name、version和description,以及所有命令行提供程序。
此功能用于了解将注册相同命令行选项的扩展,或扩展(或平台)的多个版本之间可用选项的更改。
--list-tests列出可用测试而不执行它们。 可选接受一个参数,用于控制输出格式:
text(默认,便于人类阅读)或json。有关结构化元数据和示例,请参阅以 JSON 形式发现测试。
注释
输出
json格式在 MTP 中可用,从版本 2.3.0 开始。--maximum-failed-tests指定测试失败次数的最大值,该值必须为正数。 当故障计数达到最大值时,MTP 请求正常停止并返回退出代码
13。 正在进行的测试可以完成,因此最终失败计数可能会超过最大失败计数。 有关详细信息,请参阅 MTP 退出代码。框架作者必须实现并注册
IGracefulStopTestExecutionCapability,并使用AddMaximumFailedTestsService注册选项提供程序。 功能文档包括实现和注册示例。 如果测试作者的框架已经支持该选项,则测试作者无需实现该功能。注释
从版本 1.5 开始,MTP 中提供了此功能。
--minimum-expected-tests指定必须运行的最少测试数量,且该值必须为正数。 当运行执行更少的测试(包括零)时,它将退出并带有代码
9。 显式最小值取代--zero-tests-policy。使用
dotnet test时,如果在--之前指定此选项,则该选项适用于整个运行过程;如果在--之后指定,则适用于每个测试模块。 有关详细信息,请参阅 “全运行”和“每模块最小值”。注释
--minimum-expected-tests 0无效。 若要取消零测试退出代码,请使用--ignore-exit-code 8。--no-banner禁用启动横幅、版权消息和遥测横幅。 也可以通过
TESTINGPLATFORM_NOBANNER或DOTNET_NOLOGO环境变量达到同样的效果。--results-directory指定 MTP 放置测试结果的目录。 如果目录不存在,则会创建该目录。 默认位置是 MTP 工作目录下的
TestResults。 直接启动测试应用程序时,工作目录默认为包含测试应用程序的目录。使用
dotnet test时,默认值取决于 SDK 和 MTP 版本。 有关共享调用相对根路径、版本要求和构件布局覆盖设置,请参阅 结果和构件。要隔离多个测试应用程序,请在
--之前传递 SDK 的--results-directory-layout per-module选项。 此选项属于 SDK,而不是 MTP 核心,直接启动测试应用程序时不可用。--server在编辑器、IDE 或工具集成 JSON-RPC 服务器模式下启动测试应用程序。 省略值或使用
jsonrpc。 有关受支持的仅源客户端,请参阅 MTP 服务器模式。Important
dotnettestcli值及其传输参数属于 .NET SDK 集成的内部实现。 不要手动传递它们。--show-slowest-tests显示终端摘要中请求的最慢测试数。 当运行包含多个测试模块时,MTP 会报告每个模块最慢的测试。
注释
从版本 2.4.0 开始,MTP 中提供了此选项。
--timeout全局测试执行超时。 传入一个格式为
<value>[h|m|s]的字符串参数,其中<value>表示浮点数。--treenode-filter使用树筛选器表达式筛选要运行的测试。 树筛选器可提供比
--filter更丰富的匹配能力,适用于高级场景。注释
从 MTP 2.3.0 开始,不能将
--treenode-filter与--filter-uid组合使用;如果同时指定两者,命令行验证将失败,并返回InvalidCommandLine退出代码。--zero-tests-policy控制是否将因所有测试均被跳过而未执行任何测试的运行视为失败。 有效值为
allow-skipped(默认值) 和strict。 使用allow-skipped时,所有跳过的运行都会成功。 使用strict时,它失败并出现退出代码8。 显式--minimum-expected-tests值取代此策略,并在不满足最小值时使用退出代码9。注释
从版本 2.3.0 开始,MTP 中提供了此选项。 使用
dotnet test时,在--之后传递该选项,以将其转发给每个测试模块。 如果未设置全局最低值,.NET 11 SDK 将单独确定整个运行是否为“零测试”结果。 有关详细信息,请参阅 “全运行”和“每模块最小值”。
以 JSON 形式发现测试
从 MTP 2.3.0 开始,使用 --list-tests json 以计算机可读的 JSON 文档形式发现测试,而不是解析人类可读的列表:
dotnet Contoso.MyTests.dll --list-tests json --no-banner
运行已构建的测试应用程序,而不是也会写入构建输出的命令。 将标准输出与标准错误分开捕获,并在处理该文档之前检查进程退出代码。 在计算机可读模式下,不要让应用程序和扩展的启动消息进入标准输出。
不要将发现与仅执行选项(例如 --report-trx)组合在一起。 如果 testconfig.json 启用了这些选项,请使用省略这些选项的单独发现配置并配合 --config-file。
文档包含一个 schemaVersion 和一个 tests 数组。 每个测试包括 uid 和 displayName。 当测试框架提供相应的元数据时,可选字段包括type、locationtraits和properties。 例如,具有 Environment 特征的测试可以生成:
{
"schemaVersion": 1,
"tests": [
{
"uid": "<test-uid>",
"displayName": "ConnectToService",
"traits": [
{ "key": "Environment", "value": "Staging" }
]
}
]
}
traits 和 properties 都使用键值项数组,而不是 JSON 对象。 不要假设键是唯一的。 特征表示公开的 TestMetadataProperty 值,包括 MSTest 类别和自定义 TestProperty 值。
properties 数组包含由平台或兼容层提供的可序列化的字符串属性。 它不会导出所有内存中属性,其内部 SerializableKeyValuePairStringProperty 类型不是供外部框架或扩展使用的 API。
将发现的 UID 与 --filter-uid 配合使用,以运行所选测试。 对于具有发现、执行、取消和实时更新的类型化.NET客户端,请使用 MTP 服务器模式。
根据场景的扩展选项
使用下表查找每个扩展的包和选项。 测试 SDK 配置文件可以提供程序包,而不是直接引用该程序包。
| Scenario | 必需组件 | 功能文档 |
|---|---|---|
| 收集代码覆盖率 |
Microsoft.Testing.Extensions.CodeCoverage 或 coverlet.MTP |
代码覆盖率 |
| 收集故障或挂起转储 |
Microsoft.Testing.Extensions.CrashDump 或 Microsoft.Testing.Extensions.HangDump |
崩溃和挂起转储 |
| 生成测试报告 | 所选格式的扩展包,例如 Microsoft.Testing.Extensions.TrxReport |
测试报告 |
| 自定义终端输出 | MTP 核心(无其他包) | 终端输出 |
| 重试失败的测试 | Microsoft.Testing.Extensions.Retry |
重试 |
发现测试应用中的选项
使用 --helpMTP 模式运行测试可执行文件,或以 MTP 模式运行 dotnet test --help ,列出可用于当前扩展集的选项。
从 MTP 2.4 开始,如果存在唯一匹配的选项名称,遇到未知选项错误时会提示该选项名称。 如果该选项属于测试应用程序尚未注册的已知Microsoft提供的扩展,则错误还会标识提供该选项的 NuGet 包。
要对已注册的提供程序和选项进行高级诊断,请使用 --info 运行。
运行已注册的工具
某些扩展注册了处理构件而不是执行测试的命令。 将命令名称作为测试应用程序的第一个位置参数传递。 例如,TRX 扩展提供 merge-trx 和 ms-trxcompare。
使用 --info 运行应用程序以列出已注册的工具及其命令行选项。 这些命令属于测试应用程序;它们不是 dotnet tool 命令。