Skip to content

Commit ec7cca7

Browse files
mariam-abdullaEvangelinkgewarren
authored
Add documentation to the new dotnet test (#44866)
* Add documentation to the new dotnet test * FIx links * Fix spacing * Change headings * remove empty lines * Add missiong option in dotnet test * remove trailing space * Update doc * Update help desc in dotnet test * remove some known examples * remove duplicate example * Update doc * remove space * Remove list item * Update doc * update doc * update doc * Update headings * Remove unneeded section * Update doc * Update doc * Add dot * Add missing : * Update docs/core/tools/dotnet-test.md Co-authored-by: Amaury Levé <[email protected]> * Apply comments * Reorganize doc * Fix doc * Fix doc * Remove -t * Add --verbosity * remove space * Update verbosity description * Add a note for trace logging * Update env var * Replace "using" with "with" * Apply suggestions from code review Co-authored-by: Genevieve Warren <[email protected]> --------- Co-authored-by: Amaury Levé <[email protected]> Co-authored-by: Genevieve Warren <[email protected]>
1 parent 46c474b commit ec7cca7

File tree

1 file changed

+230
-10
lines changed

1 file changed

+230
-10
lines changed

‎docs/core/tools/dotnet-test.md

Lines changed: 230 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,33 @@ ms.date: 03/27/2024
55
---
66
# dotnet test
77

8-
**This article applies to:** ✔️ .NET Core 3.1 SDK and later versions
9-
108
## Name
119

1210
`dotnet test` - .NET test driver used to execute unit tests.
1311

14-
## Synopsis
12+
## Description
13+
14+
The `dotnet test` command builds the solution and runs the tests with either VSTest or Microsoft Testing Platform (MTP). To enable MTP, you need to add a config file named `dotnet.config` with TOML format located at the root of the solution or repository.
15+
16+
Some examples of the `dotnet.config` file:
17+
18+
```toml
19+
[dotnet.test:runner]
20+
name = "MicrosoftTestingPlatform"
21+
```
22+
23+
```toml
24+
[dotnet.test:runner]
25+
name = "VSTest"
26+
```
27+
28+
## VSTest and Microsoft Testing Platform (MTP)
29+
30+
### [dotnet test with VSTest](#tab/dotnet-test-with-vstest)
31+
32+
**This article applies to:** ✔️ .NET Core 3.1 SDK and later versions
33+
34+
#### Synopsis
1535

1636
```dotnetcli
1737
dotnet test [<PROJECT> | <SOLUTION> | <DIRECTORY> | <DLL> | <EXE>]
@@ -49,7 +69,7 @@ dotnet test [<PROJECT> | <SOLUTION> | <DIRECTORY> | <DLL> | <EXE>]
4969
dotnet test -h|--help
5070
```
5171

52-
## Description
72+
#### Description
5373

5474
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 using `VSTest`. 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.
5575

@@ -64,13 +84,13 @@ Test projects specify the test runner using an ordinary `<PackageReference>` ele
6484

6585
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.
6686

67-
### Implicit restore
87+
#### Implicit restore
6888

6989
[!INCLUDE[dotnet restore note](~/includes/dotnet-restore-note.md)]
7090

7191
[!INCLUDE [cli-advertising-manifests](../../../includes/cli-advertising-manifests.md)]
7292

73-
## Arguments
93+
#### Arguments
7494

7595
- **`PROJECT | SOLUTION | DIRECTORY | DLL | EXE`**
7696

@@ -82,7 +102,7 @@ Where `Microsoft.NET.Test.Sdk` is the test host, `xunit` is the test framework.
82102

83103
If not specified, the effect is the same as using the `DIRECTORY` argument to specify the current directory.
84104

85-
## Options
105+
#### Options
86106

87107
> [!WARNING]
88108
> Breaking changes in options:
@@ -252,7 +272,7 @@ Where `Microsoft.NET.Test.Sdk` is the test host, `xunit` is the test framework.
252272

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

255-
## Examples
275+
#### Examples
256276

257277
- Run the tests in the project in the current directory:
258278

@@ -342,7 +362,7 @@ Where `Microsoft.NET.Test.Sdk` is the test host, `xunit` is the test framework.
342362
dotnet test ~/projects/test1/test1.csproj -p:TestTfmsInParallel=false
343363
```
344364

345-
## Filter option details
365+
#### Filter option details
346366

347367
`--filter <EXPRESSION>`
348368

@@ -380,8 +400,208 @@ You can enclose expressions in parenthesis when using conditional operators (for
380400

381401
For more information and examples on how to use selective unit test filtering, see [Running selective unit tests](../testing/selective-unit-tests.md).
382402

383-
## See also
403+
#### See also
384404

385405
- [Frameworks and Targets](../../standard/frameworks.md)
386406
- [.NET Runtime Identifier (RID) catalog](../rid-catalog.md)
387407
- [Passing runsettings arguments through commandline](https://github.com/microsoft/vstest/blob/main/docs/RunSettingsArguments.md)
408+
409+
### [dotnet test with MTP](#tab/dotnet-test-with-mtp)
410+
411+
**This article applies to:** ✔️ .NET 10 SDK and later versions
412+
413+
#### Synopsis
414+
415+
```dotnetcli
416+
dotnet test
417+
[--project <PROJECT_PATH>]
418+
[--solution <SOLUTION_PATH>]
419+
[--directory <DIRECTORY_PATH>]
420+
[--test-modules <EXPRESSION>]
421+
[--root-directory <ROOT_PATH>]
422+
[--list-tests]
423+
[--max-parallel-test-modules <NUMBER>]
424+
[-a|--arch <ARCHITECTURE>]
425+
[-c|--configuration <CONFIGURATION>]
426+
[-f|--framework <FRAMEWORK>]
427+
[--os <OS>]
428+
[-r|--runtime <RUNTIME_IDENTIFIER>]
429+
[-v|--verbosity <LEVEL>]
430+
[--no-build]
431+
[--no-restore]
432+
[--no-ansi]
433+
[--no-progress]
434+
[--output <VERBOSITY_LEVEL>]
435+
[<args>...]
436+
437+
dotnet test -h|--help
438+
```
439+
440+
#### Description
441+
442+
With Microsoft Testing Platform, `dotnet test` operates faster than with VSTest. The test-related arguments are no longer fixed, as they are tied to the registered extensions in the test project(s). Moreover, MTP supports a globbing filter when running tests. For more information, see [Microsoft.Testing.Platform](../testing/unit-testing-platform-intro.md).
443+
444+
> [!WARNING]
445+
> `dotnet test` doesn't run in environments that have test projects using both VSTest and Microsoft Testing Platform in the same solution, as the two platforms are mutually incompatible.
446+
447+
#### Implicit restore
448+
449+
[!INCLUDE[dotnet restore note](~/includes/dotnet-restore-note.md)]
450+
451+
#### Options
452+
453+
- **`--project <PROJECT_PATH>`**
454+
455+
Specifies the path to the test project.
456+
457+
- **`--solution <SOLUTION_PATH>`**
458+
459+
Specifies the path to the solution.
460+
461+
- **`--directory <DIRECTORY_PATH>`**
462+
463+
Specifies the path to a directory that contains a project or a solution.
464+
465+
> [!NOTE]
466+
> You can use only one of the following options at a time: `--project`, `--solution`, or `--directory`. These options can't be combined.
467+
468+
- **`--test-modules <EXPRESSION>`**
469+
470+
Filters test modules using file globbing in .NET. Only tests belonging to those test modules will run. For more information and examples on how to use file globbing in .NET, see [File globbing](../../../docs/core/extensions/file-globbing.md).
471+
472+
- **`--root-directory <ROOT_PATH>`**
473+
474+
Specifies the root directory of the `--test-modules` option. It can only be used with the `--test-modules` option.
475+
476+
- **`--list-tests`**
477+
478+
Lists the discovered tests instead of running the tests.
479+
480+
- **`--max-parallel-test-modules <NUMBER>`**
481+
482+
Specifies the maximum number of test modules that can run in parallel.
483+
484+
[!INCLUDE [arch-no-a](../../../includes/cli-arch-no-a.md)]
485+
486+
[!INCLUDE [configuration](../../../includes/cli-configuration.md)]
487+
488+
- **`-f|--framework <FRAMEWORK>`**
489+
490+
The [target framework moniker (TFM)](../../standard/frameworks.md) of the target framework to run tests for. The target framework must also be specified in the project file.
491+
492+
[!INCLUDE [os](../../../includes/cli-os.md)]
493+
494+
- **`-r|--runtime <RUNTIME_IDENTIFIER>`**
495+
496+
The target runtime to test for.
497+
498+
Short form `-r` available starting in .NET SDK 7.
499+
500+
- **`-v|--verbosity <LEVEL>`**
501+
502+
Sets the MSBuild verbosity level. Allowed values are `q[uiet]`, `m[inimal]`, `n[ormal]`, `d[etailed]`, and `diag[nostic]`. For more information, see <xref:Microsoft.Build.Framework.LoggerVerbosity>.
503+
504+
- **`--no-build`**
505+
506+
Specifies that the test project isn't built before being run. It also implicitly sets the `--no-restore` flag.
507+
508+
- **`--no-restore`**
509+
510+
Specifies that an implicit restore isn't executed when running the command.
511+
512+
- **`--no-ansi`**
513+
514+
Disables outputting ANSI escape characters to screen.
515+
516+
- **`--no-progress`**
517+
518+
Disables reporting progress to screen.
519+
520+
- **`--output <VERBOSITY_LEVEL>`**
521+
522+
Specifies the output verbosity when reporting tests. Valid values are `Normal` and `Detailed`. The default is `Normal`.
523+
524+
- **`--property:<NAME>=<VALUE>`**
525+
526+
Sets one or more MSBuild properties. Specify multiple properties by repeating the option:
527+
528+
```dotnetcli
529+
--property:<NAME1>=<VALUE1> --property:<NAME2>=<VALUE2>
530+
```
531+
532+
The short form `-p` can be used for `--property`. The same applies for `/property:property=value` and its short form is `/p`.
533+
More informatiom about the available arguments can be found in [the dotnet msbuild documentation](dotnet-msbuild.md).
534+
535+
- **`-h|--help`**
536+
537+
Prints out a description of how to use the command. The options are dynamic and might differ from one test application to another, as they are based on the registered extensions in the test project.
538+
539+
- **`args`**
540+
541+
Specifies extra arguments to pass to the test application(s). Use a space to separate multiple arguments. For more information and examples on what to pass, see [Microsoft Testing Platform](../../../docs/core/testing/unit-testing-platform-intro.md) and [Microsoft.Testing.Platform extensions](../../../docs/core/testing/unit-testing-platform-extensions.md).
542+
543+
> [!NOTE]
544+
> To enable trace logging to a file, use the environment variable `DOTNET_CLI_TEST_TRACEFILE` to provide the path to the trace file.
545+
546+
#### Examples
547+
548+
- Run the tests in the project in the current directory:
549+
550+
```dotnetcli
551+
dotnet test
552+
```
553+
554+
- Run the tests in the `TestProject` project:
555+
556+
```dotnetcli
557+
dotnet test --project ./TestProject/TestProject.csproj
558+
```
559+
560+
- Run the tests in the `TestProjects` solution:
561+
562+
```dotnetcli
563+
dotnet test --solution ./TestProjects/TestProjects.sln
564+
```
565+
566+
- Run the tests in the `TestProjects` directory:
567+
568+
```dotnetcli
569+
dotnet test --directory ./TestProjects
570+
```
571+
572+
- Run the tests using `TestProject.dll` assembly:
573+
574+
```dotnetcli
575+
dotnet test --test-modules "**/bin/**/Debug/net10.0/TestProject.dll"
576+
```
577+
578+
- Run the tests using `TestProject.dll` assembly with the root directory:
579+
580+
```dotnetcli
581+
dotnet test --test-modules "**/bin/**/Debug/net10.0/TestProject.dll" --root-directory "c:\code"
582+
```
583+
584+
- Run the tests in the current directory with code coverage:
585+
586+
```dotnetcli
587+
dotnet test --coverage
588+
```
589+
590+
- Run the tests in the `TestProject` project, providing the `-bl` (binary log) argument to `msbuild`:
591+
592+
```dotnetcli
593+
dotnet test --project ./TestProject/TestProject.csproj -bl
594+
```
595+
596+
- Run the tests in the `TestProject` project, setting the MSBuild `DefineConstants` property to `DEV`:
597+
598+
```dotnetcli
599+
dotnet test --project ./TestProject/TestProject.csproj -p:DefineConstants="DEV"
600+
```
601+
602+
#### See also
603+
604+
- [Frameworks and Targets](../../standard/frameworks.md)
605+
- [.NET Runtime Identifier (RID) catalog](../rid-catalog.md)
606+
- [Microsoft.Testing.Platform](../../../docs/core/testing/unit-testing-platform-intro.md)
607+
- [Microsoft.Testing.Platform extensions](../../../docs/core/testing/unit-testing-platform-extensions.md)

0 commit comments

Comments
 (0)