How do I run tests from MSBuild?

xUnit.net includes three different ways to run builds with the MSBuild runner:
  1. The <xunit> task, to run a single assembly
  2. The <xunit> task, to run multiple assemblies
  3. The <xunitproject> task, to run 1 or more assemblies via a .xunit project file
The MSBuild runner requires two DLLs that are distributed with xUnit.net: xunit.runner.msbuild.dll and xunit.runner.utility.dll.

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="xunit.runner.msbuild.dll"
    TaskName="Xunit.Runner.MSBuild.xunit"/>

  <Target Name="Test">
    <xunit Assembly="MyTests\bin\Debug\MyTests.dll" />
  </Target>

</Project>
Here is the complete list of options for running a single test assembly:

Property Usage
Assembly [Required][String] The name of the assembly file (DLL) which contains the tests to be run.
ConfigFile [Optional][String] The name of the configuration file. Defaults to the name of the DLL, with .config appended to the end of it.
Html [Optional][String] Filename where an HTML report will be generated after run. No HTML generated by default.
ShadowCopy [Optional][Boolean] Determines whether the tests are run as a shadow copy. Defaults to "true".
Verbose [Optional][Boolean] Enables verbose output, which logs both start and finish of tests (rather than just finish). Defaults to "false".
WorkingFolder [Optional][String] The working folder where the tests are executed from. Defaults to the folder containing the assembly DLL.
Xml [Optional][String] Filename where an XML report (in xUnit.net format) will be generated after run. No XML generated by default.

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="xunit.runner.msbuild.dll"
    TaskName="Xunit.Runner.MSBuild.xunit" />

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

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

</Project>
Here is the complete list of options for running multiple assemblies:

Property Usage
Assemblies [Required][ItemGroup] The item group of the assemblies (DLLs) run tests for.
Html [Optional][String] Filename where an HTML report will be generated after run. No HTML generated by default.
ShadowCopy [Optional][Boolean] Determines whether the tests are run as a shadow copy. Defaults to "true".
Verbose [Optional][Boolean] Enables verbose output, which logs both start and finish of tests (rather than just finish). Defaults to "false".
WorkingFolder [Optional][String] The working folder where the tests are executed from. Defaults to the folder containing the assembly DLL.
Xml [Optional][String] Filename where an XML report (in xUnit.net format) will be generated after run. No XML generated by default.

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.

Running a .xunit project file with the <xunitproject> task

If you have a .xunit project file (usually created with the GUI runner), then you can run that project file with the <xunitproject> task.

Here is an example MSBuild file using the <xunitproject> task to run a .xunit project file:

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

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

  <Target Name="Test">
    <xunitproject ProjectFile="MyTests.xunit" />
  </Target>

</Project>
Here is the complete list of options for the <xunitproject> task:

Property Usage
ProjectFile [Required][String] The name of the project file to run.
Verbose [Optional][Boolean] Enables verbose output, which logs both start and finish of tests

When would I choose the MSBuild runner over the 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, or in CLR2 vs. CLR4 environments. When using the MSBuild runner, you are restricted to the CLR and bitness choice of the MSBuild executable that you used to run your build.

Last edited Nov 1, 2012 at 4:17 AM by BradWilson, version 6