dotnet test command(1)

dotnet test

NAME

dotnet test - .NET test driver used to execute unit tests.

SYNOPSIS

  .NET Core 2.1

    dotnet test [<PROJECT>] [-a|--test-adapter-path] [--blame] [-c|--configuration] [--collect] [-d|--diag] [-f|--framework] [--filter]
        [-l|--logger] [--no-build] [--no-restore] [-o|--output] [-r|--results-directory] [-s|--settings] [-t|--list-tests]
        [-v|--verbosity] [-- <RunSettings arguments>]
    dotnet test [-h|--help]

  .NET Core 2.0

    dotnet test [<PROJECT>] [-a|--test-adapter-path] [-c|--configuration] [--collect] [-d|--diag] [-f|--framework] [--filter]
        [-l|--logger] [--no-build] [--no-restore] [-o|--output] [-r|--results-directory] [-s|--settings] [-t|--list-tests] [-v|--verbosity]
    dotnet test [-h|--help]

  .NET Core 1.x

    dotnet test [<PROJECT>] [-a|--test-adapter-path] [-c|--configuration] [-d|--diag] [-f|--framework] [--filter] [-l|--logger] [--no-build] [-o|--output] [-s|--settings] [-t|--list-tests]  [-v|--verbosity]
    dotnet test [-h|--help]

   * * * * *

DESCRIPTION

The dotnet test command is used to execute unit tests in a given project. The dotnet test command launches the test runner console application specified for a project. The test runner executes the tests defined for a unit 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. The test runner and the unit test library 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]

  Arguments

PROJECT

Path to the test project. If not specified, it defaults to current directory.

OPTIONS

  .NET Core 2.1

-a|--test-adapter-path <PATH_TO_ADAPTER>

Use the custom test adapters from the specified path in the test run.

--blame

Runs the tests in blame mode. This option is helpful in isolating the problematic tests causing test host to crash. It creates an output file in the current directory as Sequence.xml that captures the order of tests execution before the crash.

-c|--configuration {Debug|Release}

Defines the build configuration. The default value is Debug, but your project’s configuration could override this default SDK setting.

--collect <DATA_COLLECTOR_FRIENDLY_NAME>

Enables data collector for the test run. For more information, see Monitor and analyze test run.

-d|--diag <PATH_TO_DIAGNOSTICS_FILE>

Enables diagnostic mode for the test platform and write diagnostic messages to the specified file.

-f|--framework <FRAMEWORK>

Looks for test binaries for a specific framework.

--filter <EXPRESSION>

Filters out tests in the current project using the given expression. For more information, see the Filter option details section. For more information and examples on how to use selective unit test filtering, see Running selective unit tests.

-h|--help

Prints out a short help for the command.

-l|--logger <LoggerUri/FriendlyName>

Specifies a logger for test results.

--no-build

Doesn’t build the test project before running it. It also implicit sets the --no-restore flag.

--no-restore

Doesn’t execute an implicit restore when running the command.

-o|--output <OUTPUT_DIRECTORY>

Directory in which to find the binaries to run.

-r|--results-directory <PATH>

The directory where the test results are going to be placed. If the specified directory doesn’t exist, it’s created.

-s|--settings <SETTINGS_FILE>

The .runsettings file to use for running the tests. Configure unit tests by using a .runsettings file.

-t|--list-tests

List all of the discovered tests in the current project.

-v|--verbosity <LEVEL>

Sets the verbosity level of the command. Allowed values are q[uiet], m[inimal], n[ormal], d[etailed], and diag[nostic].

RunSettings arguments

Arguments passed as RunSettings configurations for the test. Arguments are specified as [name]=[value] pairs after “–” (note the space after –). A space is used to separate multiple [name]=[value] pairs.

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

For more information about RunSettings, see vstest.console.exe: Passing RunSettings args.

  .NET Core 2.0

-a|--test-adapter-path <PATH_TO_ADAPTER>

Use the custom test adapters from the specified path in the test run.

-c|--configuration {Debug|Release}

Defines the build configuration. The default value is Debug, but your project’s configuration could override this default SDK setting.

--collect <DATA_COLLECTOR_FRIENDLY_NAME>

Enables data collector for the test run. For more information, see Monitor and analyze test run.

-d|--diag <PATH_TO_DIAGNOSTICS_FILE>

Enables diagnostic mode for the test platform and write diagnostic messages to the specified file.

-f|--framework <FRAMEWORK>

Looks for test binaries for a specific framework.

--filter <EXPRESSION>

Filters out tests in the current project using the given expression. For more information, see the Filter option details section. For more information and examples on how to use selective unit test filtering, see Running selective unit tests.

-h|--help

Prints out a short help for the command.

-l|--logger <LoggerUri/FriendlyName>

Specifies a logger for test results.

--no-build

Doesn’t build the test project before running it. It also implicit sets the --no-restore flag.

--no-restore

Doesn’t execute an implicit restore when running the command.

-o|--output <OUTPUT_DIRECTORY>

Directory in which to find the binaries to run.

-r|--results-directory <PATH>

The directory where the test results are going to be placed. If the specified directory doesn’t exist, it’s created.

-s|--settings <SETTINGS_FILE>

The .runsettings file to use for running the tests. Configure unit tests by using a .runsettings file.

-t|--list-tests

List all of the discovered tests in the current project.

-v|--verbosity <LEVEL>

Sets the verbosity level of the command. Allowed values are q[uiet], m[inimal], n[ormal], d[etailed], and diag[nostic].

  .NET Core 1.x

-a|--test-adapter-path <PATH_TO_ADAPTER>

Use the custom test adapters from the specified path in the test run.

-c|--configuration {Debug|Release}

Defines the build configuration. The default value is Debug, but your project’s configuration could override this default SDK setting.

-d|--diag <PATH_TO_DIAGNOSTICS_FILE>

Enables diagnostic mode for the test platform and write diagnostic messages to the specified file.

-f|--framework <FRAMEWORK>

Looks for test binaries for a specific framework.

--filter <EXPRESSION>

Filters out tests in the current project using the given expression. For more information, see the Filter option details section. For more information and examples on how to use selective unit test filtering, see Running selective unit tests.

-h|--help

Prints out a short help for the command.

-l|--logger <LoggerUri/FriendlyName>

Specifies a logger for test results.

--no-build

Doesn’t build the test project before running it.

-o|--output <OUTPUT_DIRECTORY>

Directory in which to find the binaries to run.

-s|--settings <SETTINGS_FILE>

The .runsettings file to use for running the tests. Configure unit tests by using a .runsettings file.

-t|--list-tests

List all of the discovered tests in the current project.

-v|--verbosity <LEVEL>

Sets the verbosity level of the command. Allowed values are q[uiet], m[inimal], n[ormal], d[etailed], and diag[nostic].

   * * * * *

EXAMPLES

Run the tests in the project in the current directory:

dotnet test

Run the tests in the test1 project:

dotnet test ~/projects/test1/test1.csproj

Run the tests in the project in the current directory and generate a test results file in the trx format:

dotnet test --logger trx

  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 Framework | Supported properties
| MSTest | FullyQualifiedName Name ClassName Priority TestCategory | | xUnit | FullyQualifiedName DisplayName Traits

                                   |

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

Operator | Function
 | Exact match
!= | Not exact match
~ | 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:

Operator | Function
| | 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

•   Frameworks and Targets

•   .NET Core Runtime IDentifier (RID) catalog