1(1) .NET (1)
2
6 This article applies to: ✔️ .NET Core 2.1 SDK and later versions
7
9 dotnet test - .NET test driver used to execute unit tests.
10
12 dotnet test [<PROJECT> | <SOLUTION> | <DIRECTORY> | <DLL>]
13 [-a|--test-adapter-path <ADAPTER_PATH>] [--arch <ARCHITECTURE>]
14 [--blame] [--blame-crash]
15 [--blame-crash-dump-type <DUMP_TYPE>] [--blame-crash-collect-always]
16 [--blame-hang] [--blame-hang-dump-type <DUMP_TYPE>]
17 [--blame-hang-timeout <TIMESPAN>]
18 [-c|--configuration <CONFIGURATION>]
19 [--collect <DATA_COLLECTOR_NAME>]
20 [-d|--diag <LOG_FILE>] [-f|--framework <FRAMEWORK>]
21 [--filter <EXPRESSION>] [--interactive]
22 [-l|--logger <LOGGER>] [--no-build]
23 [--nologo] [--no-restore] [-o|--output <OUTPUT_DIRECTORY>] [--os <OS>]
24 [-r|--results-directory <RESULTS_DIR>] [--runtime <RUNTIME_IDENTIFIER>]
25 [-s|--settings <SETTINGS_FILE>] [-t|--list-tests]
26 [-v|--verbosity <LEVEL>] [[--] <RunSettings arguments>]
27 dotnet test -h|--help
29
31 The dotnet test command is used to execute unit tests in a given solu‐
32 tion. The dotnet test command builds the solution and runs a test host
33 application for each test project in the solution. The test host exe‐
34 cutes tests in the given project using a test framework, for example:
35 MSTest, NUnit, or xUnit, and reports the success or failure of each
36 test. If all tests are successful, the test runner returns 0 as an ex‐
37 it code; otherwise if any test fails, it returns 1.
38 For multi-targeted projects, tests are run for each targeted framework.
40 The test host and the unit test framework are packaged as NuGet pack‐
41 ages and are restored as ordinary dependencies for the project.
42 Test projects specify the test runner using an ordinary <PackageRefer‐
44 ence> element, as seen in the following sample project file:
45 [!code-xmlXUnit Basic Template]
47 Where Microsoft.NET.Test.Sdk is the test host, xunit is the test frame‐
49 work. And xunit.runner.visualstudio is a test adapter, which allows
50 the xUnit framework to work with the test host.
51 Implicit restore
53 You don’t have to run dotnet restore because it’s run implicitly by all
54 commands that require a restore to occur, such as dotnet new, dotnet
55 build, dotnet run, dotnet test, dotnet publish, and dotnet pack. To
56 disable implicit restore, use the --no-restore option.
57 The dotnet restore command is still useful in certain scenarios where
59 explicitly restoring makes sense, such as continuous integration builds
60 in Azure DevOps Services or in build systems that need to explicitly
61 control when the restore occurs.
62 For information about how to manage NuGet feeds, see the dotnet restore
64 documentation.
65 Workload manifest downloads
67 When you run this command, it initiates an asynchronous background
68 download of advertising manifests for workloads. If the download is
69 still running when this command finishes, the download is stopped. For
70 more information, see Advertising manifests.
71 Arguments
73 • PROJECT | SOLUTION | DIRECTORY | DLL
74 • Path to the test project.
76 • Path to the solution.
78 • Path to a directory that contains a project or a solution.
80 • Path to a test project .dll file.
82 If not specified, it searches for a project or a solution in the cur‐
84 rent directory.
85
87 • -a|--test-adapter-path <ADAPTER_PATH>
88 Path to a directory to be searched for additional test adapters. On‐
90 ly .dll files with suffix .TestAdapter.dll are inspected. If not
91 specified, the directory of the test .dll is searched.
92 • --arch <ARCHITECTURE>
94 Specifies the target architecture. This is a shorthand syntax for
96 setting the Runtime Identifier (RID), where the provided value is
97 combined with the default RID. For example, on a win-x64 machine,
98 specifying --arch x86 sets the RID to win-x86. If you use this op‐
99 tion, don’t use the -r|--runtime option. Available since .NET 6 Pre‐
100 view 7.
101 • --blame
103 Runs the tests in blame mode. This option is helpful in isolating
105 problematic tests that cause the test host to crash. When a crash is
106 detected, it creates a sequence file in TestResults/<Guid>/<Guid>_Se‐
107 quence.xml that captures the order of tests that were run before the
108 crash.
109 • --blame-crash (Available since .NET 5.0 preview SDK)
111 Runs the tests in blame mode and collects a crash dump when the test
113 host exits unexpectedly. This option depends on the version of .NET
114 used, the type of error, and the operating system.
115 For exceptions in managed code, a dump will be automatically collect‐
117 ed on .NET 5.0 and later versions. It will generate a dump for
118 testhost or any child process that also ran on .NET 5.0 and crashed.
119 Crashes in native code will not generate a dump. This option works
120 on Windows, macOS, and Linux.
121 Crash dumps in native code, or when using .NET Core 3.1 or earlier
123 versions, can only be collected on Windows, by using Procdump. A di‐
124 rectory that contains procdump.exe and procdump64.exe must be in the
125 PATH or PROCDUMP_PATH environment variable. Download the tools. Im‐
126 plies --blame.
127 To collect a crash dump from a native application running on .NET 5.0
129 or later, the usage of Procdump can be forced by setting the
130 VSTEST_DUMP_FORCEPROCDUMP environment variable to 1.
131 • --blame-crash-dump-type <DUMP_TYPE> (Available since .NET 5.0 preview
133 SDK)
134 The type of crash dump to be collected. Implies --blame-crash.
136 • --blame-crash-collect-always (Available since .NET 5.0 preview SDK)
138 Collects a crash dump on expected as well as unexpected test host ex‐
140 it.
141 • --blame-hang (Available since .NET 5.0 preview SDK)
143 Run the tests in blame mode and collects a hang dump when a test ex‐
145 ceeds the given timeout.
146 • --blame-hang-dump-type <DUMP_TYPE> (Available since .NET 5.0 preview
148 SDK)
149 The type of crash dump to be collected. It should be full, mini, or
151 none. When none is specified, test host is terminated on timeout,
152 but no dump is collected. Implies --blame-hang.
153 • --blame-hang-timeout <TIMESPAN> (Available since .NET 5.0 preview
155 SDK)
156 Per-test timeout, after which a hang dump is triggered and the test
158 host process and all of its child processes are dumped and terminat‐
159 ed. The timeout value is specified in one of the following formats:
160 • 1.5h, 1.5hour, 1.5hours
162 • 90m, 90min, 90minute, 90minutes
164 • 5400s, 5400sec, 5400second, 5400seconds
166 • 5400000ms, 5400000mil, 5400000millisecond, 5400000milliseconds
168 When no unit is used (for example, 5400000), the value is assumed to
170 be in milliseconds. When used together with data driven tests, the
171 timeout behavior depends on the test adapter used. For xUnit and
172 NUnit the timeout is renewed after every test case. For MSTest, the
173 timeout is used for all test cases. This option is supported on Win‐
174 dows with netcoreapp2.1 and later, on Linux with netcoreapp3.1 and
175 later, and on macOS with net5.0 or later. Implies --blame and
176 --blame-hang.
177 • -c|--configuration <CONFIGURATION>
179 Defines the build configuration. The default for most projects is
181 Debug, but you can override the build configuration settings in your
182 project.
183 • --collect <DATA_COLLECTOR_NAME>
185 Enables data collector for the test run. For more information, see
187 Monitor and analyze test run (https://aka.ms/vstest-collect).
188 To collect code coverage on any platform that is supported by .NET
190 Core, install Coverlet (https://github.com/coverlet-coverage/cover‐
191 let/blob/master/README.md) and use the --collect:"XPlat Code Cover‐
192 age" option.
193 On Windows, you can collect code coverage by using the --collect
195 "Code Coverage" option. This option generates a .coverage file,
196 which can be opened in Visual Studio 2019 Enterprise. For more in‐
197 formation, see Use code coverage and Customize code coverage analy‐
198 sis.
199 • -d|--diag <LOG_FILE>
201 Enables diagnostic mode for the test platform and writes diagnostic
203 messages to the specified file and to files next to it. The process
204 that is logging the messages determines which files are created, such
205 as *.host_<date>.txt for test host log, and *.datacollec‐
206 tor_<date>.txt for data collector log.
207 • -f|--framework <FRAMEWORK>
209 Forces the use of dotnet or .NET Framework test host for the test bi‐
211 naries. This option only determines which type of host to use. The
212 actual framework version to be used is determined by the runtimecon‐
213 fig.json of the test project. When not specified, the TargetFrame‐
214 work assembly attribute is used to determine the type of host. When
215 that attribute is stripped from the .dll, the .NET Framework host is
216 used.
217 • --filter <EXPRESSION>
219 Filters out tests in the current project using the given expression.
221 For more information, see the Filter option details section. For
222 more information and examples on how to use selective unit test fil‐
223 tering, see Running selective unit tests.
224 • -?|-h|--help
226 Prints out a description of how to use the command.
228 • --interactive
230 Allows the command to stop and wait for user input or action. For
232 example, to complete authentication. Available since .NET Core 3.0
233 SDK.
234 • -l|--logger <LOGGER>
236 Specifies a logger for test results. Unlike MSBuild, dotnet test
238 doesn’t accept abbreviations: instead of -l "console;v=d" use -l
239 "console;verbosity=detailed". Specify the parameter multiple times
240 to enable multiple loggers.
241 • --no-build
243 Doesn’t build the test project before running it. It also implicitly
245 sets the - --no-restore flag.
246 • --nologo
248 Run tests without displaying the Microsoft TestPlatform banner.
250 Available since .NET Core 3.0 SDK.
251 • --no-restore
253 Doesn’t execute an implicit restore when running the command.
255 • -o|--output <OUTPUT_DIRECTORY>
257 Directory in which to find the binaries to run. If not specified,
259 the default path is ./bin/<configuration>/<framework>/. For projects
260 with multiple target frameworks (via the TargetFrameworks property),
261 you also need to define --framework when you specify this option.
262 dotnet test always runs tests from the output directory. You can use
263 <xref:System.AppDomain.BaseDirectory%2A?displayProperty=nameWithType>
264 to consume test assets in the output directory.
265 • --os <OS>
267 Specifies the target operating system (OS). This is a shorthand syn‐
269 tax for setting the Runtime Identifier (RID), where the provided val‐
270 ue is combined with the default RID. For example, on a win-x64 ma‐
271 chine, specifying --os os sets the RID to os-x64. If you use this
272 option, don’t use the -r|--runtime option. Available since .NET 6
273 Preview 7.
274 • -r|--results-directory <RESULTS_DIR>
276 The directory where the test results are going to be placed. If the
278 specified directory doesn’t exist, it’s created. The default is
279 TestResults in the directory that contains the project file.
280 • --runtime <RUNTIME_IDENTIFIER>
282 The target runtime to test for.
284 • -s|--settings <SETTINGS_FILE>
286 The .runsettings file to use for running the tests. The TargetPlat‐
288 form element (x86|x64) has no effect for dotnet test. To run tests
289 that target x86, install the x86 version of .NET Core. The bitness
290 of the dotnet.exe that is on the path is what will be used for run‐
291 ning tests. For more information, see the following resources:
292 • Configure unit tests by using a .runsettings file.
294 • Configure a test run (https://github.com/Microsoft/vstest-
296 docs/blob/master/docs/configure.md)
297 • -t|--list-tests
299 List the discovered tests instead of running the tests.
301 • -v|--verbosity <LEVEL>
303 Sets the verbosity level of the command. Allowed values are q[uiet],
305 m[inimal], n[ormal], d[etailed], and diag[nostic]. The default is
306 minimal. For more information, see <xref:Microsoft.Build.Frame‐
307 work.LoggerVerbosity>.
308 • RunSettings arguments
310 Inline RunSettings are passed as the last arguments on the command line
312 after “–” (note the space after –). Inline RunSettings are specified
313 as [name]=[value] pairs. A space is used to separate multiple
314 [name]=[value] pairs.
315 Example: dotnet test -- MSTest.DeploymentEnabled=false MSTest.MapIncon‐
317 clusiveToFailed=True
318 For more information, see Passing RunSettings arguments through command
320 line (https://github.com/Microsoft/vstest-docs/blob/master/docs/RunSet‐
321 tingsArguments.md).
322
324 • Run the tests in the project in the current directory:
325 dotnet test
327 • Run the tests in the test1 project:
329 dotnet test ~/projects/test1/test1.csproj
331 • Run the tests in the project in the current directory, and generate a
333 test results file in the trx format:
334 dotnet test --logger trx
336 • Run the tests in the project in the current directory, and generate a
338 code coverage file (after installing Coverlet
339 (https://github.com/coverlet-coverage/coverlet/blob/master/Documenta‐
340 tion/VSTestIntegration.md) collectors integration):
341 dotnet test --collect:"XPlat Code Coverage"
343 • Run the tests in the project in the current directory, and generate a
345 code coverage file (Windows only):
346 dotnet test --collect "Code Coverage"
348 • Run the tests in the project in the current directory, and log with
350 detailed verbosity to the console:
351 dotnet test --logger "console;verbosity=detailed"
353 • Run the tests in the project in the current directory, and report
355 tests that were in progress when the test host crashed:
356 dotnet test --blame
358 Filter option details
360 --filter <EXPRESSION>
361 <Expression> has the format <property><operator><value>[|&<Expres‐
363 sion>].
364 <property> is an attribute of the Test Case. The following are the
366 properties supported by popular unit test frameworks:
367 Test Framework Supported properties
369 ──────────────────────────────────────
370 MSTest
371 xUnit
372 NUnit
373 The <operator> describes the relationship between the property and the
375 value:
376 Operator Function
378 ───────────────────────────
379 = Exact match
380 != Not exact match
381 ~ Contains
382 !~ Not contains
383 <value> is a string. All the lookups are case insensitive.
385 An expression without an <operator> is automatically considered as a
387 contains on FullyQualifiedName property (for example, dotnet test
388 --filter xyz is same as dotnet test --filter FullyQualifiedName~xyz).
389 Expressions can be joined with conditional operators:
391 Operator Function
393 ────────────────────
394 | OR
395 & AND
396 You can enclose expressions in parenthesis when using conditional oper‐
398 ators (for example, (Name~TestMethod1) | (Name~TestMethod2)).
399 For more information and examples on how to use selective unit test
401 filtering, see Running selective unit tests.
402 See also
404 • Frameworks and Targets
405 • .NET Runtime Identifier (RID) catalog
407 • Passing runsettings arguments through commandline
409 (https://github.com/Microsoft/vstest-docs/blob/master/docs/RunSet‐
410 tingsArguments.md)
411 (1)