使用 Microsoft.Testing.Platform 进行 dotnet 测试 （MTP）

本文适用于： ✔️ .NET 10 SDK 及更高版本

Name

dotnet test - 用于使用 MTP 执行单元测试的.NET测试驱动程序。

概要

dotnet test
    [<PROJECT_OR_TRAVERSAL_PATH>]
    [--project <PROJECT_PATH>]
    [--solution <SOLUTION_PATH>]
    [--test-modules <EXPRESSION>]
    [--root-directory <ROOT_PATH>]
    [--max-parallel-test-modules <NUMBER>]
    [--config-file <CONFIG_FILE>]
    [--results-directory <RESULTS_DIRECTORY>]
    [--results-directory-layout <flat|per-module>]
    [--diagnostic-output-directory <DIAGNOSTIC_OUTPUT_DIRECTORY>]
    [--minimum-expected-tests <NUMBER>]
    [--maximum-failed-tests <NUMBER>]
    [--timeout <DURATION>]
    [-e|--environment <NAME="VALUE">]
    [-a|--arch <ARCHITECTURE>]
    [--artifacts-path <ARTIFACTS_DIR>]
    [-c|--configuration <CONFIGURATION>]
    [-f|--framework <FRAMEWORK>]
    [--os <OS>]
    [-r|--runtime <RUNTIME_IDENTIFIER>]
    [--use-current-runtime|--ucr]
    [-v|--verbosity <LEVEL>]
    [--no-build]
    [--no-dependencies]
    [--no-restore]
    [--nologo|--no-logo|--no-banner]
    [--no-ansi]
    [--no-progress]
    [--no-artifact-post-processing]
    [--output <VERBOSITY_LEVEL>]
    [--show-test-results <OUTCOME>]
    [--list-tests [text|json]]
    [--no-launch-profile]
    [--no-launch-profile-arguments]
    [--device <DEVICE_ID>]
    [--list-devices]
    [--collect-test-map]
    [--affected-tests]
    [<args>...]

dotnet test -h|--help

Description

使用 MTP 时， dotnet test 运行速度比 VSTest 更快。 与测试相关的参数不再固定，因为它们与测试project（s）中的已注册扩展相关联。 此外，MTP 在运行测试时支持通配筛选器。 有关详细信息，请参阅 MTP。

Important

特定于扩展的选项不内置于 MTP 中。 每个目标测试应用程序都必须注册提供选项的扩展。 直接添加扩展的 NuGet 包，或使用包含包的测试 SDK 配置或配置文件。 否则，测试运行失败并出现退出代码 5，因为无法识别该选项。 运行 dotnet test --help 以查看所选测试应用程序可用的选项，并 按方案查看扩展选项 以查找选项的包。

警告

选择通过 global.jsonMTP 时， dotnet test 所有测试项目都希望使用 MTP。 如果任何测试项目都使用 VSTest，则这是一个错误。

版本要求

MTP 模式dotnet test需要 .NET 10 SDK 和 MTP 1.7 或更高版本。 .NET 10 后添加的选项在以下部分中具有单独的 SDK 版本要求。 某些选项还需要更新的 MTP 包，因为 SDK 在每次测试应用程序实现相应的功能时协调完整的运行。

隐式还原

无需运行 dotnet restore，因为它由所有需要还原的命令隐式运行，如 dotnet new、dotnet build、dotnet run、dotnet test、dotnet publish 和 dotnet pack。 若要禁用隐式还原，请使用 --no-restore 选项。

在某些需要显式还原的情况下， 命令仍然很有用，例如 DevOps Services1 中或需要显式控制还原时间的生成系统中的连续 Azure集成生成。

有关如何管理 NuGet 源的信息，请参阅 dotnet restore 文档。

Important

运行项目或解决方案 --no-restore时，请将还原生成的项目状态 obj 保留在文件夹中，以及可用的匹配全局包文件夹。 测试框架和平台包导入设置用于标识 MTP 测试应用程序的 MSBuild 属性 dotnet test 。 该 --no-build 选项也意味着 --no-restore。 如果测试环境包含生成的测试应用程序，但不包含项目还原状态，请改用 --test-modules 。 有关详细信息，请参阅 No test projects were found。

选项

注释

一次只能使用以下选项之一：--project、--solution 或 --test-modules。 无法组合这些选项。 此外，使用--test-modules时，不能指定--arch、、--configuration、、--framework--device、--list-devices、--os或--runtime--use-current-runtime。 这些选项需要项目评估，或者与已生成的模块无关。

• PROJECT_OR_TRAVERSAL_PATH

  指定要运行的项目或遍历项目。 从 .NET 11 预览版 7 开始，dotnet test支持Microsoft.Build.Traversal项目（例如dirs.proj，以递归方式运行其引用的测试项目）。

  自 .NET 12 预览版 1 起，该参数还可以标识基于 C# 文件的 MTP 测试应用。 基于文件的测试应用不支持 --device。

• --project <PROJECT_PATH>

  指定要运行的project文件的路径（文件夹名称或完整路径）。 如果未指定，则默认为当前目录。

• --solution <SOLUTION_PATH>

  指定要运行的解决方案文件的路径（文件夹名称或完整路径）。 如果未指定，则默认为当前目录。

• --test-modules <EXPRESSION>

  使用文件扫描筛选测试模块。 仅属于这些测试模块的测试运行。 由于此选项不评估项目，因此当项目还原状态不可用时，使用它来运行已生成的测试应用程序。 从 .NET 11 预览版 6 开始，将模式作为排除匹配模块的!前缀。 用分号分隔多个模式;忽略每个模式周围的空格。

• --root-directory <ROOT_PATH>

  指定 --test-modules 选项的根目录。 它只能与 --test-modules 选项一起使用。

• --max-parallel-test-modules <NUMBER>

  指定可并行运行的最大测试模块数。 默认值为 Environment.ProcessorCount。

• --config-file <CONFIG_FILE>

  指定要用于测试执行的配置文件。 如果提供了相对路径，则会根据当前目录将其转换为绝对路径。 有关配置文件设置的详细信息，请参阅 testconfig.json。

• --results-directory <RESULTS_DIRECTORY>

  指定存储测试结果的目录。 如果目录不存在，则会创建该目录。 如果提供了相对路径，则会根据当前目录将其转换为绝对路径。

• --results-directory-layout <flat|per-module>

  指定多模块运行如何组织结果目录下的文件。 默认值 flat将所有结果写入同一目录。 per-module 将每个模块的结果 <project>/<target-framework>_<runtime-or-architecture>写入其中，从而阻止具有相同文件名的报告相互覆盖。

  从 .NET 11 RC 1 开始可用。

• --diagnostic-output-directory <DIAGNOSTIC_OUTPUT_DIRECTORY>

  指定存储诊断输出的目录。 如果目录不存在，则会创建该目录。 如果提供了相对路径，则会根据当前目录将其转换为绝对路径。

• --minimum-expected-tests <NUMBER>

  指定整个运行的正最小测试数。 如果聚合的测试计数小于指定的最小值，测试运行将失败，退出代码 9。 全局计数包括跳过的测试。 有关退出代码的详细信息，请参阅 MTP 退出代码。

  由于此选项出现在前面 --，因此它是一个全局（全运行）选项。 若要改为要求每个测试模块的最小值，请稍后传递该选项 -- ，以便将其转发到每个测试模块。 有关详细信息，请参阅 “全运行”和“每模块最小值”。

  注释

  全局最低要求.NET 10 SDK（10.0.100）或更高版本。

• --maximum-failed-tests <NUMBER>

  在达到指定数量的失败、出错、超时或已取消的测试后停止完整运行。 运行退出，代码为 13。

  从 .NET 11 预览版 7 开始可用，需要 MTP 2.4 或更高版本。

• --timeout <DURATION>

  在至少一个测试应用程序运行时，在指定的持续时间后停止完整运行。 指定正数后跟单位，例如500ms，、90s、10m2h或1d。 超时运行会退出，代码为 3。

  从 .NET 11 预览版 7 开始可用，需要 MTP 2.4 或更高版本。

• -e|--environment <NAME="VALUE">

  为测试过程设置环境变量。 多次指定用于设置多个变量的选项。 命令行值替代启动配置文件中的值。

  当不存在启动配置文件或指定--no-launch-profile时，请使用 .NET SDK 10.0.110 或更高版本;早期.NET 10 个 SDK 版本可以忽略这些情况下的变量。 从 .NET 11 预览版 7 开始，变量还流向功能感知生成、设备选择、部署和运行参数目标。

• -a|--arch <ARCHITECTURE>

  指定目标体系结构。 这是一种简写语法，用于设置 运行时标识符（RID），其中提供的值与默认 RID 结合使用。 例如，在 win-x64 计算机上，指定 --arch x86 将 RID 设置为 win-x86。 如果使用此选项，请不要使用 -r|--runtime 选项。 自 .NET 6 预览版 7 起可用。

• --artifacts-path <ARTIFACTS_DIR>

  执行命令中的所有生成输出文件都将位于指定路径下的子文件夹中，由项目分隔。 有关详细信息，请参阅 Artifacts 输出布局。 此选项和提供的值必须在依赖于另一dotnet个命令的输出的任何dotnet命令中显式级联，例如，使用时和 。dotnet build --no-restoredotnet publish --no-build 自 .NET 8 SDK 起可用。

  适用于从 .NET 11 开始的 MTP 模式。

• -c|--configuration <CONFIGURATION>

  定义生成配置。 大多数项目的默认值为 Debug，但你可以替代project中的生成配置设置。

• -f|--framework <FRAMEWORK>

  要对其运行测试的目标框架的目标框架名字对象 (TFM)。 还必须在project文件中指定目标框架。

• --os <OS>

  指定目标操作系统（OS）。 这是一种简写语法，用于设置 运行时标识符（RID），其中提供的值与默认 RID 结合使用。 例如，在 win-x64 计算机上，指定 --os linux 将 RID 设置为 linux-x64。 如果使用此选项，请不要使用 -r|--runtime 选项。 自 .NET 6 起可用。

• -r|--runtime <RUNTIME_IDENTIFIER>

  要针对其测试的目标运行时。

  从 .NET SDK 7 开始提供短格式 -r。

  注释

  不支持对具有全局RuntimeIdentifier属性（显式或通过或通过--arch--runtime--os或）的解决方案运行测试。 请改为在单个project级别设置 RuntimeIdentifier。

• --use-current-runtime|--ucr

  在还原和生成过程中，使用当前运行时作为目标运行时。

  从 .NET 11 预览版 6 开始可用。 不能将此选项与 --test-modules.

• -v|--verbosity <LEVEL>

  设置命令的详细级别。 允许的值为 q[uiet]、m[inimal]、n[ormal]、d[etailed]和 diag[nostic]。 有关详细信息，请参阅 LoggerVerbosity。

• --no-build

  指定在运行之前不会生成测试project。 它还隐式设置 --no-restore 标志。

• --no-dependencies

  跳过生成项目到项目的引用。

  从 .NET 11 预览版 6 开始可用。

• --no-restore

  指定运行命令时不执行隐式还原。

• --nologo|--no-logo|--no-banner

  禁止显示.NET和 MTP 启动横幅。 -nologo还支持窗体/nologo和DOTNET_NOLOGO环境变量。

  从 .NET 11 预览版 7 开始，在 MTP 模式下可用。

• --no-ansi

  禁用将 ANSI 转义字符输出到屏幕。

• --no-progress

  禁用报告进度到屏幕。

• --no-artifact-post-processing

  在多模块运行后禁用兼容项目的处理。 从 .NET 11 RC 1 和 MTP 2.4 开始，已注册的项目后处理器可以合并兼容的报表，例如 TRX 结果。 如果后期处理失败，SDK 将保留原始项目和测试退出代码。

• --output <VERBOSITY_LEVEL>

  指定测试结果的输出详细程度。 有效值为：Minimal、Normal 和 Detailed。 默认值为 Normal。 Minimal 需要 MTP 2.4 预览版。

• --show-test-results <OUTCOME>

  按结果选择结果块。 在 MTP 2.4 预览版中，使用 passed、 failed、 skipped、 all或 none。 该值 failed 还包括错误、超时和取消。

  结合passed逗号、skippedfailed空格或重复--show-test-results选项。 不要合并或none与另一个值。all 无论选项顺序如何， --output 此显式选项都会替代预设。

• --list-tests [text|json]

  列出发现的测试而不执行这些测试。 省略该值或指定 text 人工可读输出。 从 .NET 11 预览版 7 开始，指定json按程序集、目标框架和体系结构对测试进行分组的受版本控制 JSON 文档，并包括可用的标识符、源位置、方法、参数和特征。

• --no-launch-profile

  请勿尝试使用 launchSettings.json 配置应用程序。 默认情况下， launchSettings.json 使用此参数可将环境变量和命令行参数应用于测试可执行文件。

• --no-launch-profile-arguments

  不要使用在启动配置文件中指定的参数 commandLineArgs 来运行应用程序。

• --device <DEVICE_ID>

  为 Android 或 iOS 测试项目中的每个目标框架选择设备、模拟器或模拟器。 MTP 路径还支持 macOS 和 Mac Catalyst 测试项目。 如果输入是交互式的，并且有多个设备可用， dotnet test 可以提示你选择一个。

  从 .NET 11 预览版 6 开始可用。 对于多目标项目，请使用 .NET 11 RC 2 或更高版本，以便设备发现正确评估每个目标框架。 此选项不支持浏览器 WebAssembly 测试项目。

• --list-devices

  列出项目可用设备，而无需运行测试。 指定项目而不是解决方案。

  从 .NET 11 预览版 7 开始可用。

• --collect-test-map 和 --affected-tests

  收集存储库测试映射或运行受更改影响的测试。 这些实验性选项需要单独的分布式扩展和 DOTNET_CLI_ENABLE_AFFECTED_TESTS=1 环境变量。 不能合并这两个选项。 受影响的测试工作流也不支持设备测试、并行测试模块或最低测试策略。

  从 .NET 11 RC 1 开始可用。

• --property:<NAME>=<VALUE>

  设置一个或多个 MSBuild 属性。 通过重复选项指定多个属性：

  --property:<NAME1>=<VALUE1> --property:<NAME2>=<VALUE2>
  

  短格式 -p 可用于 --property。 这同样适用于 /property:property=value 及其短形式 /p。 有关可用参数的详细信息，请参阅 dotnet msbuild 文档。

• -?|-h|--help

  打印出有关如何使用命令的说明。

• args

  指定要传递给测试应用程序的额外参数。 使用空格分隔多个参数。 有关要传递的内容的详细信息和示例，请参阅 MTP 概述 和 MTP 功能。

  小窍门

  若要指定特定项目的额外参数，请使用 TestingPlatformCommandLineArguments MSBuild 属性。 当解决方案混合测试框架（例如 MSTest 和 xUnit.net）或仅当某些项目引用特定扩展时，此属性特别有用。 有关详细信息，请参阅 包含混合测试框架或扩展的解决方案。

注释

若要启用对文件的跟踪日志记录，请使用环境变量 DOTNET_CLI_TEST_TRACEFILE 提供跟踪文件的路径。

从 .NET 11 RC 1 开始，对多项目、多目标设备运行使用一个 MSBuild 会话，dotnet test -bl以便二进制日志包含完整的生成。

输出和取消行为

从 .NET 11 预览版 6 开始，交互式 ANSI 输出显示当前正在运行的测试以及每个程序集测试计数的报告。 当重定向输出、ANSI 或进度输出被禁用或环境不交互时，进度显示将保持禁用状态。

从 .NET 11 预览版 6 开始，第一个 Ctrl+C 停止计划新的测试应用程序并请求协作取消。 再次按 Ctrl+C 以立即终止子进程。 中止的运行退出，代码为 3。

实时测试主机输出需要支持协议 1.1 或更高版本的 MTP 主机。 较旧的主机将保留捕获的输出，并重播失败模块的输出。 从 .NET 11 预览版 7 开始，故障摘要将捕获的标准输出截断 40 行以上到前 30 行和最后 10 行;诊断日志将保留完整的输出。

对于多模块运行，dotnet test从 .NET 11 预览版 7 开始，在完整运行中评估零测试结果。 如果另一个模块成功执行测试，没有测试的模块不会失败，除非显式的最低测试策略需要更多测试。

结果和项目

启用 SDK 项目输出布局后，.NET 11 RC 1 及更高版本默认放置 MTP 报告、覆盖文件和诊断。<ArtifactsPath>/test/<project>/<pivot> 显式 --results-directory 或 --results-directory-layout 优先。

从 .NET 11 RC 1 和 MTP 2.4 开始，兼容的扩展可以从多模块运行后处理项目。 例如，TRX 扩展可以在保留每模块报表的同时创建合并报表。 有关扩展和报告要求，请参阅 MTP 测试报告。

将参数转发到测试应用程序

dotnet test 转发它无法识别到测试应用程序的任何令牌。 当识别的选项出现在无法识别的选项名称和其值之间时，删除已识别的选项可以更改剩余令牌绑定到测试应用程序中的选项的方式。 为了避免这种歧义，请将测试应用程序参数放在文本 --后面：

dotnet test --results-directory TestResults -- --report-trx --report-trx-filename A.trx

前面的示例要求将 Microsoft.Testing.Extensions.TrxReport 包作为直接包引用或通过包含包的测试 SDK 配置。

相同的分析程序行为适用于 dotnet run 和 dotnet build。 有关详细示例，请参阅参考中的dotnet run。

全运行和每个模块的最小值

对于 --minimum-expected-tests， -- 分隔符确定选项的范围：

• 之前的参数是全局参数--。 dotnet test业务流程协调程序为整个运行解释它们。
• 后面的--参数是本地参数。 dotnet test 将它们转发到每个测试模块，因此每个模块都独立应用它们。

由于 --minimum-expected-tests 这两个范围都可用，因此对于整个运行、每个模块或两者，可能需要至少满足以下要求：

dotnet test --minimum-expected-tests 5 -- --minimum-expected-tests 2

上述命令需要整个运行中的至少 5 个测试，每个测试模块中至少需要 2 个测试。

两个范围计数以不同的方式跳过的测试：

Scope	跳过的测试是否计入最小值？
全球	Yes. 聚合 dotnet test 总数包括跳过的测试。
每个模块	No. MTP 从运行的测试数中排除跳过的测试。

从 .NET 11 SDK 开始，从聚合结果中确定整个运行的零测试判决一次。 与任何测试匹配的模块（例如，由于或全局--filter）--test-modules退出，代码为 8（ZeroTests），但在聚合结果之前，该代码已规范化为成功。 因此，单个空模块不会使整个运行失败，尽管该模块将诊断 Exit code: 8 保留在输出中，以便查看。

MTP 4.3.0 及更高版本提供 --zero-tests-policy <allow-skipped|strict>。 默认值 allow-skipped允许所有跳过的模块成功。 该值 strict 将跳过的测试视为未运行，因此所有跳过的模块将退出代码 8。 将选项转发到每个测试模块之后 -- ：

dotnet test -- --zero-tests-policy strict

如果未设置全局最小值，.NET 11 SDK 将单独确定整个运行零测试判决。 所有跳过的整个运行都会退出，代码为 8，而不考虑每个模块 --zero-tests-policy 的值。

指定 --minimum-expected-tests 且未满足最低要求时，运行将失败并出现退出代码 9（MinimumExpectedTestsPolicyViolation）。 此代码不同于 8，因此，更严格的全局或每模块最小值不会与空模块混淆。 对于在模块运行零测试时返回代码 9 的每个模块的最小值，测试模块必须使用 MTP 4.4.0 或更高版本。

注释

--minimum-expected-tests 0 无效。 若要取消零测试退出代码，请使用 --ignore-exit-code 8。

从 .NET 11 预览版 6 --tl开始，--terminallogger并--tlp转发到 MSBuild 而不是测试应用程序。 从 .NET 12 预览版 1 开始，识别-mt的表单和-multiThreaded表单也会转发到 MSBuild。 若要传递具有其中一个名称的应用程序选项，请将它放在后面 --。

将执行模式选项（例如 --help 和 --list-tests 直接传递给 dotnet test） 从 .NET 11 预览版 6 开始，SDK 将验证与测试应用程序协商的执行模式。 如果启动配置文件或 TestingPlatformCommandLineArguments 注入其中一个选项，则请求的 SDK 操作和应用程序操作不匹配，并且运行失败并出现诊断。

例子

• 在当前目录中的project或解决方案中运行测试：

  dotnet test
  

• 在 TestProject project 中运行测试：

  dotnet test --project ./TestProject/TestProject.csproj
  

• 在 TestProjects 解决方案中运行测试：

  dotnet test --solution ./TestProjects/TestProjects.sln
  

• 使用 TestProject.dll 程序集运行测试：

  dotnet test --test-modules "**/bin/**/Debug/net10.0/TestProject.dll"
  

• 使用根目录 TestProject.dll 程序集运行测试：

  dotnet test --test-modules "**/bin/**/Debug/net10.0/TestProject.dll" --root-directory "c:\code"
  

• 运行遍历项目引用的所有测试项目，.NET 11 预览版 7 或更高版本：

  dotnet test dirs.proj
  

• 使用 .NET 11 预览版 7 或更高版本将测试列为 JSON：

  dotnet test --list-tests json
  

• 使用 .NET 12 预览版 1 或更高版本运行基于 C# 文件的 MTP 测试应用：

  dotnet test App.Tests.cs
  

• 使用 Microsoft Code Coverage 扩展在当前目录中运行测试。 测试应用程序必须直接或通过包含它的测试 SDK 配置进行引用 Microsoft.Testing.Extensions.CodeCoverage：

  dotnet test --coverage
  

• 运行测试并将结果存储在特定目录中：

  dotnet test --results-directory ./TestResults
  

• 在特定目录中使用诊断输出运行测试：

  dotnet test --diagnostic-output-directory ./Diagnostics
  

• 运行确保至少执行 10 个测试的测试：

  dotnet test --minimum-expected-tests 10
  

• 在整个运行中至少需要 5 个测试，每个测试模块中至少有 2 个测试：

  dotnet test --minimum-expected-tests 5 -- --minimum-expected-tests 2
  

• 在 TestProject project 中运行测试，为 -bl 提供 msbuild （二进制日志） 参数：

  dotnet test --project ./TestProject/TestProject.csproj -bl
  

• 在 TestProject project 中运行测试，将 MSBuild DefineConstants 属性设置为 DEV：

  dotnet test --project ./TestProject/TestProject.csproj -p:DefineConstants="DEV"
  

另请参阅

• 框架和目标
• .NET运行时标识符（RID）目录
• MTP
• MTP 功能
• MTP CLI 选项
• 运行和调试 MTP 测试
• 使用 MSTest 运行测试
• MSTest SDK 配置
• dotnet 测试
• 使用 VSTest dotnet 测试