dotnet-test - Man Page

.NET test driver used to execute unit tests.

Examples (TL;DR)

dotnet test

This article applies to: ✔️ .NET Core 3.1 SDK and later versions

Synopsis

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

Description

The dotnet test command is used to execute unit tests in a given solution. The dotnet test command builds the solution and runs a test host application for each test project in the solution. The test host executes tests in the given project using a test framework, for example: MSTest, NUnit, or xUnit, and reports the success or failure of each test. If all tests are successful, the test runner returns 0 as an exit code; otherwise if any test fails, it returns 1.

For multi-targeted projects, tests are run for each targeted framework. The test host and the unit test framework are packaged as NuGet packages and are restored as ordinary dependencies for the project.

Test projects specify the test runner using an ordinary <PackageReference> element, as seen in the following sample project file:

[!code-xmlXUnit Basic Template]

Where Microsoft.NET.Test.Sdk is the test host, xunit is the test framework. And xunit.runner.visualstudio is a test adapter, which allows the xUnit framework to work with the test host.

Implicit restore

You don’t have to run dotnet restore because it’s run implicitly by all commands that require a restore to occur, such as dotnet new, dotnet build, dotnet run, dotnet test, dotnet publish, and dotnet pack. To disable implicit restore, use the --no-restore option.

The dotnet restore command is still useful in certain scenarios where explicitly restoring makes sense, such as continuous integration builds in Azure DevOps Services or in build systems that need to explicitly control when the restore occurs.

For information about how to manage NuGet feeds, see the dotnet restore documentation.

Workload manifest downloads

When you run this command, it initiates an asynchronous background download of advertising manifests for workloads. If the download is still running when this command finishes, the download is stopped. For more information, see Advertising manifests.

Arguments

Options

[!WARNING] Breaking changes in options:

  • Starting in .NET 7: switch -a to alias --arch instead of --test-adapter-path
  • Starting in .NET 7: switch -r to alias --runtime instead of --results-directory

Inline RunSettings are passed as the last arguments on the command line after “–” (note the space after –). Inline RunSettings are specified as [name]=[value] pairs. A space is used to separate multiple [name]=[value] pairs.

Example: dotnet test -- MSTest.DeploymentEnabled=false MSTest.MapInconclusiveToFailed=True

For more information, see Passing RunSettings arguments through command line (https://github.com/Microsoft/vstest-docs/blob/main/docs/RunSettingsArguments.md).

Examples

Filter option details

--filter <EXPRESSION>

<Expression> has the format <property><operator><value>[|&<Expression>].

<property> is an attribute of the Test Case. The following are the properties supported by popular unit test frameworks:

Test FrameworkSupported properties
MSTest
xUnit
NUnit

The <operator> describes the relationship between the property and the value:

OperatorFunction
=Exact match
!=Not exact match
~Contains
!~Not contains

<value> is a string. All the lookups are case insensitive.

An expression without an <operator> is automatically considered as a contains on FullyQualifiedName property (for example, dotnet test --filter xyz is same as dotnet test --filter FullyQualifiedName~xyz).

Expressions can be joined with conditional operators:

OperatorFunction
|OR      
&AND

You can enclose expressions in parenthesis when using conditional operators (for example, (Name~TestMethod1) | (Name~TestMethod2)).

For more information and examples on how to use selective unit test filtering, see Running selective unit tests.

See Also

Info

2023-10-25 .NET Documentation