dotnet test

  • 项目

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

“属性”

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

摘要

dotnet test [<PROJECT> | <SOLUTION> | <DIRECTORY> | <DLL> | <EXE>]
    [--test-adapter-path <ADAPTER_PATH>]
    [-a|--arch <ARCHITECTURE>]
    [--blame]
    [--blame-crash]
    [--blame-crash-dump-type <DUMP_TYPE>]
    [--blame-crash-collect-always]
    [--blame-hang]
    [--blame-hang-dump-type <DUMP_TYPE>]
    [--blame-hang-timeout <TIMESPAN>]
    [-c|--configuration <CONFIGURATION>]
    [--collect <DATA_COLLECTOR_NAME>]
    [-d|--diag <LOG_FILE>]
    [-f|--framework <FRAMEWORK>]
    [-e|--environment <NAME="VALUE">]
    [--filter <EXPRESSION>]
    [--interactive]
    [-l|--logger <LOGGER>]
    [--no-build]
    [--nologo]
    [--no-restore]
    [-o|--output <OUTPUT_DIRECTORY>]
    [--os <OS>]
    [--results-directory <RESULTS_DIR>]
    [-r|--runtime <RUNTIME_IDENTIFIER>]
    [-s|--settings <SETTINGS_FILE>]
    [-t|--list-tests]
    [-v|--verbosity <LEVEL>]
    [<args>...]
    [[--] <RunSettings arguments>]

dotnet test -h|--help

描述

dotnet test 命令用于在给定的解决方案中执行单元测试。 dotnet test 命令生成解决方案，并为解决方案中的每个测试项目运行测试主机应用程序。 测试主机使用测试框架（例如，MSTest、NUnit 或 xUnit）在给定项目中执行测试，并报告每个测试成功与否。 如果所有测试均成功，测试运行程序将返回 0 作为退出代码；否则将返回 1。

对于多目标项目，将为每个目标框架运行测试。 测试主机和单元测试框架打包为 NuGet 包，并还原为项目的普通依赖项。 从 .NET 9 SDK 开始，这些测试默认并行运行。 若要禁用并行执行，请将 TestTfmsInParallel MSBuild 属性设置为 false。 有关详细信息，请参阅 本文后面的并行 运行测试和 示例命令行。

测试项目使用普通 <PackageReference> 元素指定测试运行程序，如下方示例项目文件所示：

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.9.0" />
    <PackageReference Include="xunit" Version="2.7.1" />
    <PackageReference Include="xunit.runner.visualstudio" Version="2.5.8" />
  </ItemGroup>

</Project>

如果 Microsoft.NET.Test.Sdk 是测试主机，则 xunit 是测试框架。 另外，xunit.runner.visualstudio 是测试适配器，可便于 xUnit 框架与测试主机一起运行。

隐式还原

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

在执行显式还原有意义的某些情况下，例如 dotnet restore中，或在需要显式控制还原发生时间的生成系统中，dotnet restore 命令仍然有用。

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

工作负载清单下载

运行此命令时，它将为工作负载启动播发清单的异步后台下载。 如果此命令完成后，下载仍在运行，则将停止下载。 有关详细信息，请参阅播发清单。

自变量

  • PROJECT | SOLUTION | DIRECTORY | DLL | EXE

    • 指向测试项目的路径。
    • 解决方案的路径。
    • 包含项目或解决方案的目录的路径。
    • 测试项目 .dll 文件的路径。
    • 测试项目 .exe 文件的路径。

    如果未指定，则效果与使用 DIRECTORY 参数指定当前目录的效果相同。

选项

警告

选项中的中断性变更：

  • 从 .NET 7 开始：将 -a 切换到别名 --arch，而不是 --test-adapter-path
  • 从 .NET 7 开始：将 -r 切换到别名 --runtime，而不是 --results-directory

  • --test-adapter-path <ADAPTER_PATH>

    要在其中搜索其他测试适配器的目录的路径。 只检查后缀为 的 .dll 文件。 如果未指定，则会搜索测试 .dll 的目录。

    在低于 .NET SDK 7 的版本中提供缩写形式 -a。

  • --arch <ARCHITECTURE>

    指定目标体系结构。 这是用于设置运行时标识符 (RID) 的简写语法，其中提供的值与默认 RID 相结合。 例如，在 win-x64 计算机上，指定 --arch x86 会将 RID 设置为 win-x86。 如果使用此选项，请不要使用 -r|--runtime 选项。 从 .NET 6 Preview 7 开始提供。

  • --blame

    在意见模式中运行测试。 此选项有助于隔离导致测试主机出现故障的有问题的测试。 检测到故障时，它会在 TestResults/<Guid>/<Guid>_Sequence.xml 中创建一个序列文件，用于捕获在出现故障之前运行的测试的顺序。

    此选项不会创建内存转储，并且当测试挂起时没有帮助。

  • --blame-crash （自 .NET 5.0 SDK 起可用）

    在追责模式下运行测试，并在测试主机意外退出时收集故障转储。 此选项取决于所使用的 .NET 版本、错误的类型和操作系统。

    对于托管代码中的异常，将在 .NET 5.0 及更高版本上自动收集转储。 对于 testhost 或也在 .NET 5.0 上运行并且出现故障的任何子进程，它将生成转储。 本机代码中的故障将不会生成转储。 此选项适用于 Windows、macOS 和 Linux。

    本机代码中的故障转储（或者当使用 .NET Core 3.1 或更早版本时）只能使用 Procdump 在 Windows 上进行收集。 包含 procdump.exe 和 procdump64.exe 的目录必须位于 PATH 或 PROCDUMP_PATH 环境变量中。 下载工具。 意味着 --blame。

    若要从 .NET 5.0 或更高版本上运行的本机应用程序收集故障转储，可以通过将 VSTEST_DUMP_FORCEPROCDUMP 环境变量设置为 1 来强制执行 Procdump 的使用。

  • --blame-crash-dump-type <DUMP_TYPE> （自 .NET 5.0 SDK 起可用）

    要收集的故障转储的类型。 支持的转储类型为 full（默认）和 mini。 意味着 --blame-crash。

  • --blame-crash-collect-always （自 .NET 5.0 SDK 起可用）

    在预期和意外的测试主机退出时收集故障转储。

  • --blame-hang （自 .NET 5.0 SDK 起可用）

    在追责模式下运行测试，并在测试超过给定超时时长时收集挂起转储。

  • --blame-hang-dump-type <DUMP_TYPE> （自 .NET 5.0 SDK 起可用）

    要收集的故障转储的类型。 它应为 full、mini 或 none。 指定 none 时，测试主机将在超时时终止，但不会收集任何转储。 意味着 --blame-hang。

  • --blame-hang-timeout <TIMESPAN> （自 .NET 5.0 SDK 起可用）

    每个测试超时时间，在此时间后，将触发挂起转储，并转储和终止测试主机进程及其所有子进程。 超时值是采用以下格式之一指定的：

    • 1.5h、1.5hour、1.5hours
    • 90m、90min、90minute、90minutes
    • 5400s、5400sec、5400second、5400seconds
    • 5400000ms、5400000mil、5400000millisecond、5400000milliseconds

    如果未使用单位（例如，5400000），则假定该值以毫秒为单位。 与数据驱动的测试一起使用时，超时行为取决于所使用的测试适配器。 对于 xUnit、NUnit 和 MSTest 2.2.4 及更高版本，会在每个测试用例后更新超时。 对于低于 MSTest 2.2.4 的版本，超时用于所有测试用例。 此选项在具有 netcoreapp2.1 及更高版本的 Windows、具有 netcoreapp3.1 及更高版本的 Linux 以及具有 net5.0 或更高版本的 macOS 上受支持。 意味着 --blame 和 --blame-hang。

  • -c|--configuration <CONFIGURATION>

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

  • --collect <DATA_COLLECTOR_NAME>

    为测试运行启用数据收集器。 有关详细信息，请参阅监视和分析测试运行。

    例如，可以使用 --collect "Code Coverage" 选项收集代码覆盖率。 有关详细信息，请参阅使用代码覆盖率、自定义代码覆盖率分析和 GitHub 问题 dotnet/docs#34479。

    若要收集代码覆盖率，还可以通过 --collect "XPlat Code Coverage" 选项使用 Coverlet。

  • -d|--diag <LOG_FILE>

    启用测试平台的诊断模式，并将诊断消息写入到指定文件及其旁边的文件。 正在记录消息的进程可确定创建了哪些文件，如测试主机日志的 *.host_<date>.txt，以及数据收集器日志的 *.datacollector_<date>.txt。

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

    设置环境变量的值。 如果变量不存在，则创建变量；如果存在，则重写该变量。 使用此选项将强制测试在独立进程中运行。 可以多次指定该选项以提供多个变量。

  • -f|--framework <FRAMEWORK>

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

  • --filter <EXPRESSION>

    使用给定表达式筛选当前项目中的测试。 仅运行与筛选表达式匹配的测试。 有关详细信息，请参阅筛选选项详细信息部分。 若要获取使用选择性单元测试筛选的其他信息和示例，请参阅运行选择性单元测试。

  • -?|-h|--help

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

  • --interactive

    允许命令停止并等待用户输入或操作。 例如，完成身份验证。 自 .NET Core 3.0 SDK 起可用。

  • -l|--logger <LOGGER>

    指定测试结果的记录器，并可选择记录器的开关。 多次指定参数，以启用多个记录器。 有关详细信息，请参阅报告测试结果、记录器的开关以及本文后面的示例。

    若要将命令行开关传递给记录器：

    • 使用开关的全名，而不是缩写形式（例如 verbosity 代替 v）。
    • 省略任何前导短划线。
    • 将分隔每个开关的空格替换为分号 ;。
    • 如果开关具有值，请将开关与其值之间的冒号分隔符替换为等于号 =。

    例如，-v:detailed --consoleLoggerParameters:ErrorsOnly 将变为 verbosity=detailed;consoleLoggerParameters=ErrorsOnly。

  • --no-build

    不在运行测试项目之前生成它。 还将隐式设置 --no-restore 标记。

  • --nologo

    运行测试，而不显示 Microsoft TestPlatform 横幅。 自 .NET Core 3.0 SDK 起可用。

  • --no-restore

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

  • -o|--output <OUTPUT_DIRECTORY>

    查找要运行的二进制文件的目录。 如果未指定，则默认路径为 ./bin/<configuration>/<framework>/。 对于具有多个目标框架的项目（通过 TargetFrameworks 属性），在指定此选项时还需要定义 --framework。 dotnet test 始终从输出目录运行测试。 可以使用 AppDomain.BaseDirectory 以使用输出目录中的测试资产。

    • .NET 7.0.200 SDK 及更高版本

      如果在解决方案中运行此命令时指定 --output 选项，则 CLI 将因输出路径的语义不明确而发出警告（7.0.200 中的一个错误）。 不允许 --output 选项，因为所有生成项目的所有输出都将复制到指定的目录中，该目录与多目标项目以及具有不同版本的直接和可传递依赖项的项目不兼容。 有关详细信息，请参阅解决方案级 --output 选项不再对生成相关命令有效。

  • --os <OS>

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

  • --results-directory <RESULTS_DIR>

    用于放置测试结果的目录。 如果指定的目录不存在，则会创建该目录。 默认值为包含项目文件的目录中的 TestResults。

    在低于 .NET SDK 7 的版本中提供缩写形式 -r。

  • -r|--runtime <RUNTIME_IDENTIFIER>

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

    缩写形式 -r 从 .NET SDK 7 开始可用。

  • -s|--settings <SETTINGS_FILE>

    .runsettings 文件用于运行测试。 TargetPlatform 元素 (x86|x64) 对 dotnet test 不起作用。 若要运行面向 x86 的测试，请安装 .NET Core 的 x86 版本。 路径上 dotnet.exe 的位数是用于运行测试的内容。 有关更多信息，请参见以下资源：

  • -t|--list-tests

    列出已发现的测试，而不是运行测试。

  • -v|--verbosity <LEVEL>

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

  • args

    指定要传递到适配器的额外参数。 使用空格分隔多个参数。

    可能的参数的列表取决于指定的行为：

    • 指定项目、解决方案或目录时，或者如果省略此参数，调用将被转发到 msbuild。 在此情况下，可在 dotnet msbuild 文档中找到可用参数。
    • 指定 .dll 或 .exe 时，调用会被转发到 。 在此情况下，可在 dotnet vstest 文档中找到可用参数。

  • RunSettings 参数

内联的 RunSettings 作为“-- ”（请注意 -- 后面有空格）后的最后一个命令行参数传递。 内联的 RunSettings 被指定为 [name]=[value] 对。 空格用于分隔多个 [name]=[value] 对。

示例：dotnet test -- MSTest.DeploymentEnabled=false MSTest.MapInconclusiveToFailed=True

有关详细信息，请参阅通过命令行传递 RunSettings 参数。

示例

  • 运行当前目录所含项目中的测试：

    dotnet test

  • 运行 test1 项目中的测试：

    dotnet test ~/projects/test1/test1.csproj

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

    dotnet test ~/projects/test1/bin/debug/test1.dll

  • 在当前目录运行项目中的测试，并以 trx 格式生成测试结果文件：

    dotnet test --logger trx

  • 在当前目录运行项目中的测试，并生成代码覆盖率文件（安装 Coverlet 收集器集成后）：

    dotnet test --collect:"XPlat Code Coverage"

  • 在当前目录运行项目中的测试，并生成代码覆盖率文件（仅限 Windows）：

    dotnet test --collect "Code Coverage"

  • 在当前目录中运行项目中的测试，并将详细的测试结果记录到控制台：

    dotnet test --logger "console;verbosity=detailed"

  • 在当前目录中运行项目中的测试，并使用 trx 记录器将测试结果记录到 TestResults 文件夹中的 testResults.trx：

    dotnet test --logger "trx;logfilename=testResults.trx"

    由于指定了日志文件名，因此在多目标项目的情况下，每个目标框架使用相同的名称。 每个目标框架的输出将覆盖前面目标框架的输出。 文件是在测试项目文件夹的 TestResults 文件夹中创建的，因为相对路径相对于该文件夹。 下面的示例演示如何为每个目标框架生成单独的文件。

  • 在当前目录中运行项目中的测试，并使用 trx 记录器将测试结果记录到 TestResults 文件夹中的文件，文件名对于每个目标框架都是唯一的：

    dotnet test --logger:"trx;LogFilePrefix=testResults"

  • 在当前目录中运行项目中的测试，并使用 html 记录器将测试结果记录到 TestResults 文件夹中的 testResults.html：

    dotnet test --logger "html;logfilename=testResults.html"

  • 在当前目录下的项目中运行测试，并报告在测试主机发生故障时正在进行的测试：

    dotnet test --blame

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

    dotnet test ~/projects/test1/test1.csproj -bl

  • 在 test1 项目中运行测试，并将 MSBuild DefineConstants 属性设置为 DEV：

    dotnet test ~/projects/test1/test1.csproj -p:DefineConstants="DEV"

  • 在 test1 项目中运行测试，并将 MSBuild TestTfmsInParallel 属性设置为 false：

    dotnet test ~/projects/test1/test1.csproj -p:TestTfmsInParallel=false

筛选选项详细信息

--filter <EXPRESSION>

<Expression> 格式为 <property><operator><value>[|&<Expression>]。

<property> 是 Test Case 的特性。 下面介绍了常用单元测试框架支持的属性：

测试框架 支持的属性
MSTest
  • FullyQualifiedName
  • “属性”
  • ClassName
  • Priority
  • TestCategory
xUnit
  • FullyQualifiedName
  • DisplayName
  • 类别
NUnit
  • FullyQualifiedName
  • 名称
  • 类别
  • 优先级

<operator> 说明了属性和值之间的关系：

运算符 函数
= 完全匹配
!= 非完全匹配
~ 包含
!~ 不包含

<value> 是字符串。 所有查找都不区分大小写。

不含 <operator> 的表达式自动被视为 FullyQualifiedName 属性上的 contains（例如，dotnet test --filter xyz 与 dotnet test --filter FullyQualifiedName~xyz 相同）。

表达式可与条件运算符结合使用：

运算符 函数
| 或
& AND

使用条件运算符时，可以用括号将表达式括起来（例如，(Name~TestMethod1) | (Name~TestMethod2)）。

若要获取使用选择性单元测试筛选的其他信息和示例，请参阅运行选择性单元测试。

请参阅