dotnet-test

Execute tests for a .NET project/solution in the current directory

$ dotnet test

$ dotnet test [path/to/project_or_solution]

$ dotnet test --filter [Name~TestMethod1]

dotnet test [ | | ] [options] [--- ]

Where:
| | : Specifies the path to a .NET project file, a solution file, or a directory containing a project or solution. If omitted, the command searches the current directory for a project or solution file.
[options]: Represents various command-line options that modify the behavior of the test run.
[--- ]: A special syntax to pass arbitrary arguments directly to the underlying vstest.console.exe test runner.

-h | --help
    Displays help information and a list of available options for the dotnet test command.

-c | --configuration
    Defines the build configuration for the tests, such as Debug (default) or Release.

--no-build
    Does not build the test project before running tests. This option is useful when tests have already been built manually.

--no-restore
    Does not perform an implicit NuGet package restore during command execution. Requires packages to be restored manually beforehand (e.g., with dotnet restore).

-f | --framework
    The target framework moniker (TFM) for which to run tests (e.g., net6.0, net8.0). Tests will only be run for this specific framework.

--filter
    Filters tests based on a given expression. Expressions can use properties like FullyQualifiedName, DisplayName, Category. Example: Category=SmokeTests or FullyQualifiedName~MyNamespace.MyClass.

--logger
    Specifies a logger for test results. Common loggers include trx (for VSTest TRX format) and console. Example: trx;LogFileName=test_results.trx to generate a TRX report.

-o | --output
    The directory in which to find the binaries to run. If not specified, the command will look for the binaries in the default build output location.

--results-directory
    The directory where test results files (e.g., TRX reports) will be placed. Defaults to a TestResults subdirectory within the project's directory.

--verbosity
    Sets the verbosity level of logging during the test run. Allowed values are quiet, minimal, normal, detailed, and diagnostic.

--collect
    Enables a data collector for the test run. A common use case is Coverage to collect code coverage information.

--nologo
    Does not display the Microsoft Test Platform banner and copyright message.

--settings
    The path to the .runsettings file to use for configuring the test run. This file can specify data collectors, test run parameters, and more.

---
    Passes additional, unparsed arguments directly to the underlying vstest.console.exe executable. This allows for fine-grained control over the test execution engine.

The dotnet test command is an essential part of the .NET Command-Line Interface (CLI), designed to execute unit tests within a .NET project or solution. It is used extensively by developers to ensure the quality and correctness of their codebases.

When invoked, dotnet test first attempts to build the specified project or solution if necessary. It then discovers tests using registered test adapters for popular frameworks like xUnit.NET, NUnit, and MSTest. Once tests are discovered, it executes them and reports the outcomes, including passed, failed, and skipped tests.

The command offers a rich set of options for customizing test runs, such as filtering tests by name or category, specifying build configurations, selecting target frameworks, and configuring loggers for detailed test results. It plays a crucial role in automated testing and continuous integration/continuous delivery (CI/CD) pipelines, enabling rapid feedback on code changes.

While powerful, dotnet test has a few considerations:
.NET SDK Dependency: It requires a compatible .NET SDK to be installed on the system to function.
Test Adapter Requirement: To run tests from specific frameworks (e.g., xUnit, NUnit, MSTest), the corresponding test adapter NuGet package must be referenced in the test project.
Cross-Platform Nuances: Although cross-platform, some underlying tools and path conventions might behave slightly differently between Linux, Windows, and macOS.
Performance: For very large test suites or complex projects, test execution can be time-consuming. Utilizing options like --no-build, --filter, or parallel test execution (if supported by the test runner) can help mitigate this.

To run all tests in the current directory's project and generate a TRX report:
dotnet test --logger trx

To run tests from a specific project file with a filter:
dotnet test MyProject.Tests.csproj --filter 'Category=SmokeTests'

To run tests in Release configuration without rebuilding:
dotnet test --configuration Release --no-build

By default, dotnet test outputs results to the console. However, for structured reporting and integration with CI/CD systems, using the --logger option is common. The TRX format (specified with --logger trx) is widely supported by tools like Azure DevOps, Jenkins, and TeamCity for displaying detailed test results, including stack traces for failed tests.

The --results-directory option allows specifying where these report files are saved, making it easier to collect them for analysis or archiving.

dotnet test is a fundamental command in automated CI/CD pipelines. Its command-line nature makes it easy to script and integrate into various build servers and orchestrators, promoting a robust DevOps culture by providing immediate feedback on code quality and regressions.

The dotnet test command is a cornerstone of the .NET Core CLI, which was introduced to provide a unified, cross-platform command-line experience for .NET development. It emerged as part of the broader effort to modernize .NET and move away from Windows-specific tooling (like MSBuild directly from Visual Studio) towards a more flexible and platform-agnostic approach.

Since its inception with .NET Core 1.0, dotnet test has continuously evolved with each subsequent .NET release (e.g., .NET Core 2.x, 3.x, and now .NET 5, 6, 7, 8). It standardized the process of running unit, integration, and functional tests across different test frameworks, becoming the de facto command for automated testing in the .NET ecosystem. Its development has focused on improving performance, adding more filtering capabilities, enhancing logging, and integrating with advanced testing features like data collection and run settings.

dotnet build: Compiles source code into executable binaries or libraries., dotnet restore: Downloads and restores NuGet packages that a project depends on., dotnet run: Executes a .NET application from source code., dotnet publish: Publishes a .NET application and its dependencies to a folder for deployment., dotnet new: Creates new .NET projects, solutions, or configuration files from templates.