Microsoft.Testing.Platform (MTP) CLI 选项参考指南

本文提供了 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。

    注释

    从版本 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 格式在 MTP 中可用，从版本 2.3.0 开始。

  • --maximum-failed-tests

    达到指定测试失败最大次数时，将停止测试运行。 要支持这种切换，需要框架作者实现 IGracefulStopTestExecutionCapability 功能。 达到该数量的测试失败时退出代码为 13。 有关详细信息，请参阅 MTP 退出代码。

    注释

    从版本 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

    用于放置测试结果的目录。 如果指定的目录不存在，则会创建该目录。 默认为 TestResults，位于包含测试应用程序的目录中。

  • --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 。

    注释

    从版本 4.3.0 开始，MTP 中提供了此选项。 使用 dotnet test 时，在 -- 之后传递该选项，以将其转发给每个测试模块。 如果未设置全局最低值，.NET 11 SDK 将单独确定整个运行是否为“零测试”结果。 有关详细信息，请参阅 “全运行”和“每模块最小值”。

根据场景的扩展选项

使用下表查找每个扩展的包和选项。 测试 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 运行。

另请参阅

  • 上次更新时间为