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. When including this NuGet package into a project, the project file (for example, the .csproj file) will automatically gain access to the <xunit> task. The examples below show custom MSBuild files; when using <xunit> from within a project file, you can skip the <UsingTask> line.

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:

xUnit.net v2

<Project DefaultTargets="Test">

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

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

</Project>

xUnit.net v3

<Project DefaultTargets="Test">

  <UsingTask
    AssemblyFile="path\to\xunit.v3.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:

xUnit.net v2

<Project DefaultTargets="Test">

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

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

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

</Project>

xUnit.net v3

<Project DefaultTargets="Test">

  <UsingTask
    AssemblyFile="path\to\xunit.v3.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 [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.
Culture 3.0 [Optional][String] Controls the default culture for tests. Can be set to default (default OS culture), invariant (invariant culture), or any legal culture string (legal values are operating system dependent).
NOTE: Only supported by v3 or later test projects.
DiagnosticMessages 2.1 [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).
ExitCode 2.0 [Output][Integer] Returns the exit code from the execution.
FailSkips 2.1 [Optional][Boolean] Set to true to cause skipped tests to become failures.
Html 2.0 [Optional][String] Filename where an HTML report will be generated after run. No HTML generated by default.
IgnoreFailures 2.2 [Optional][Boolean] Set to true to allow the build to continue after tests have failed.
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.
NoAutoReporters 2.2 [Optional][Boolean] Stops reporters (like TeamCity or AppVeyor) which automatically enable themselves based on the runtime environment.
NoLogo 2.1 [Optional][Boolean] When set, disables the display of the MSBuild runner welcome banner.
NUnit 2.1 [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 [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 were deprecated in 2.1, and removed from 2.2.

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 © .NET Foundation. Contributions welcomed at https://github.com/xunit/xunit/tree/gh-pages.