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 包,并还原为项目的普通依赖项。

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

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

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

  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.4.0" />
    <PackageReference Include="xunit" Version="2.4.2" />
    <PackageReference Include="xunit.runner.visualstudio" Version="2.4.5" />
  </ItemGroup>

</Project>

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

隐式还原

无需运行 dotnet restore,因为它由所有需要还原的命令隐式运行,如 dotnet newdotnet builddotnet rundotnet testdotnet publishdotnet pack。 若要禁用隐式还原,请使用 --no-restore 选项。

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

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

工作负载清单下载

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

自变量

  • PROJECT | SOLUTION | DIRECTORY | DLL | EXE

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

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

选项

警告

选项的重大更改:

  • 从 .NET 7 开始:切换到 -a 别名 --arch 而不是 --test-adapter-path
  • 从 .NET 7 开始:切换到 -r 别名 --runtime 而不是 --results-dir
  • --test-adapter-path <ADAPTER_PATH>

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

    在低于 7 的 .NET SDK 版本中提供短格式 -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 起可用)

    要收集的故障转储的类型。 它应为 fullmininone。 指定 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+,超时将在每个测试用例后续订。 对于版本 2.2.4 之前的 MSTest,超时适用于所有测试用例。 此选项在具有 netcoreapp2.1 及更高版本的 Windows、具有 netcoreapp3.1 及更高版本的 Linux 以及具有 net5.0 或更高版本的 macOS 上受支持。 意味着 --blame--blame-hang

  • -c|--configuration <CONFIGURATION>

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

  • --collect <DATA_COLLECTOR_NAME>

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

    在 Windows(x86、x64 和 Arm64)、Linux (x64) 和 macOS (x64) 上,可以使用 --collect "Code Coverage" 选项收集代码覆盖率数据。 有关详细信息,请参阅使用代码覆盖率自定义代码覆盖率分析

    若要在 .NET Core 支持的任何平台上收集代码覆盖率,请安装 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 属性),在指定此选项时还需要定义 --frameworkdotnet test 始终从输出目录运行测试。 可以使用 AppDomain.BaseDirectory 以使用输出目录中的测试资产。

  • --os <OS>

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

  • --results-directory <RESULTS_DIR>

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

    在低于 7 的 .NET SDK 版本中提供简短格式 -r

  • -r|--runtime <RUNTIME_IDENTIFIER>

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

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

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

筛选选项详细信息

--filter <EXPRESSION>

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

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

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

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

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

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

不含 <operator> 的表达式自动被视为 FullyQualifiedName 属性上的 contains(例如,dotnet test --filter xyzdotnet test --filter FullyQualifiedName~xyz 相同)。

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

运算符 函数
|
& AND

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

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

请参阅