This topic applies to .NET Core Tools Preview 2. For the .NET Core Tools RC4 version, see the dotnet-test (.NET Core Tools RC4) topic.


dotnet-test - Runs unit tests using the configured test runner.


dotnet test [project] [--help] [--parentProcessId] [--port] [--configuration] [--output] [--build-base-path] [--framework] [--runtime] [--no-build]


The dotnet test command is used to execute unit tests in a given project. Unit tests are class library projects that have dependencies on the unit test framework (for example, NUnit or xUnit) and the dotnet test runner for that unit testing framework. These are packaged as NuGet packages and are restored as ordinary dependencies for the project.

Test projects also need to specify a test runner property in project.json using the "testRunner" node. This value should contain the name of the unit test framework.

The following sample project.json shows the properties needed:

  "version": "1.0.0-*",
  "buildOptions": {
    "debugType": "portable"
  "dependencies": {
    "System.Runtime.Serialization.Primitives": "4.1.1",
    "xunit": "2.1.0",
    "dotnet-test-xunit": "1.0.0-rc2-192208-24"
  "testRunner": "xunit",
  "frameworks": {
    "netcoreapp1.0": {
      "dependencies": {
        "Microsoft.NETCore.App": {
          "type": "platform",
          "version": "1.0.0"
      "imports": [

dotnet test supports two running modes:

  1. Console: In console mode, dotnet test simply executes fully any command gets passed to it and outputs the results. Anytime you invoke dotnet test without passing --port, it runs in console mode, which in turn will cause the runner to run in console mode.
  2. Design time: used in the context of other tools, such as editors or Integrated Development Environments (IDEs). You can find out more about this mode in the dotnet-test protocol document.



Specifies a path to the test project. If omitted, it defaults to current directory.


Prints out a short help for the command.


Used by IDEs to specify their process ID. Test will exit if the parent process does.


Used by IDEs to specify a port number to listen for a connection.

-c|--configuration <Debug|Release>

Configuration under which to build. The default value is Release.

-o|--output [OUTPUT_DIRECTORY]

Directory in which to find the binaries to run.

-b|--build-base-path <OUTPUT_DIRECTORY>

Directory in which to place temporary outputs.

-f|--framework [FRAMEWORK]

Looks for test binaries for a specific framework.


Look for test binaries for a for the specified runtime.


Does not build the test project prior to running it.


Run the tests in the project in the current directory:

dotnet test

Run the tests in the test1 project:

dotnet test /projects/test1/project.json

See also

dotnet-test communication protocol


Runtime IDentifier (RID) catalog