Running xUnit.net tests in MSBuild

xUnit.net includes a runner which can be used from your MSBuild scripts to run unit tests. The runner is contained in the NuGet package xunit.runner.msbuild.

Table of Contents

Running a single assembly with the <xunit> task

Here is an example MSBuild file using the <xunit> task to run a single assembly:

<Project
    DefaultTargets="Test"
    xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

  <UsingTask
    AssemblyFile="path\to\xunit.runner.msbuild.dll"
    TaskName="Xunit.Runner.MSBuild.xunit"/>

  <Target Name="Test">
    <xunit Assemblies="path\to\MyTests.dll" />
  </Target>

</Project>

Running multiple assemblies with the <xunit> task

Often, you will want to run multiple assemblies. You can use an <ItemGroup> in MSBuild to specify which test DLLs to run (including using the wildcard syntax to automatically find test DLLs).

Here is an example MSBuild file using the <xunit> task to run several assemblies:

<Project
    DefaultTargets="Test"
    xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

  <UsingTask
    AssemblyFile="path\to\xunit.runner.msbuild.dll"
    TaskName="Xunit.Runner.MSBuild.xunit" />

  <ItemGroup>
    <TestAssemblies Include="**\bin\Release\*.tests.dll" />
  </ItemGroup>

  <Target Name="Test">
    <xunit Assemblies="@(TestAssemblies)" />
  </Target>

</Project>

Options for the MSBuild runner

The <xunit> MSBuild task has several options to help you configure your test execution. The version column indicates the minimum version of the MSBuild runner you must be using to take advantage of the feature.

Property Min Version Usage
AppDomains 2.1 beta 4 [Optional][Boolean] Controls whether app domains are used for test discovery and execution. Defaults to true.
Assemblies 2.0 [Required][ItemGroup] The item group of the assemblies (DLLs) run tests for.
DiagnosticMessages 2.1 beta 2 [Optional][Boolean] Set to true to include diagnostic messages when running tests.
ExcludeTraits 2.0 [Optional][String] When set, excludes tests that match the given traits (in Name=Value;Name=Value format).
Html 2.0 [Optional][String] Filename where an HTML report will be generated after run. No HTML generated by default.
IncludeTraits 2.0 [Optional][String] When set, only runs tests that match the given traits (in Name=Value;Name=Value format).
MaxParallelThreads 2.0 [Optional][String] Controls the number of threads to use when running tests in parallel. Can be set to default (one thread per CPU), unlimited, or any positive number.
NoLogo 2.1 beta 3 [Optional][Boolean] When set, disables the display of the MSBuild runner welcome banner.
NUnit 2.1 beta 3 [Optional][String] Filename where an XML report (in NUnit format) will be generated after run.
ParallelizeAssemblies 2.0 [Optional][Boolean] When set to true, runs multiple assemblies in parallel. Defaults to false.
ParallelizeTestCollections 2.0 [Optional][Boolean] When set to true, runs multiple test collections in parallel. Defaults to true.
Reporter 2.1 beta 3 [Optional][String] Selects a reporter to use for printing test results. Default reporters include teamcity, appveyor, verbose, and quiet. Third parties can add additional reporter options.
ShadowCopy 2.0 [Optional][Boolean] Determines whether the tests are run as a shadow copy. Defaults to true. Ignored when AppDomains is set to false.
WorkingFolder 2.0 [Optional][String] The working folder where the tests are executed from. Defaults to the folder containing the assembly DLL.
Xml 2.0 [Optional][String] Filename where an XML report (in xUnit.net v2 format) will be generated after run.
XmlV1 2.0 [Optional][String] Filename where an XML report (in xUnit.net v1 format) will be generated after run.

Note: When running multiple assemblies, you can specify the configuration file for each assembly using ItemGroup metadata. The <xunit> task looks for metadata named ConfigFile on each item in your item group. Configuration files are ignored when AppDomains is set to false.

The following configuration elements have been deprecated in 2.1, and will be removed from subsequent releases.

Property Replacement
TeamCity Set Reporter to teamcity
Verbose Set Reporter to verbose

Choosing MSBuild runner vs. Console runner

You can use an <exec> task in MSBuild to run the console runner. You may choose to use the console runner if you need more control over running tests in 32- vs. 64-bit environments. When using the MSBuild runner, you are restricted to the bitness choice of the MSBuild executable that you used to run your build.

Copyright © 2017 .NET Foundation. Contributions welcomed at https://github.com/xunit/xunit.github.io.