NUnit for MSBuild

This page describes how to use NUnit from MSBuild.

for NUnit prior to 3.0 see Working with TeamCity-provided NUnit task
for NUnit 3.0 and above see Working with NUnit 3.0

Working with NUnit Task in MSBuild Build

The information in this section is applicable if you are using NUnit prior to version 3.0. For later versions, refer to the section below.

This section assumes that you already have an MSBuild build script with a configured NUnit task in it, and want TeamCity to track test reports without making any changes to the existing build script. Otherwise, consider adding NUnit build runner as one of the steps for your build configuration.

Using NUnitTeamCity task in MSBuild Build Script

TeamCity provides a custom NUnitTeamCity task compatible with the NUnit task from MSBuild Community tasks project. If you provide the NUnitTeamCity task in your build script, TeamCity will launch its own test runner based on the options specified within the task. Thus, you do not need to have any NUnit runner, because TeamCity will run the tests.

In order to correctly use the NUnitTeamCity task, perform the following steps:

Make sure the teamcity_dotnet_nunitlauncher system property is accessible on build agents. Build agents running Windows should automatically detect these properties as environment variables. If you need to set them manually, see defining agent-specific properties for more information.
Configure your MSBuild build script with the NUnitTeamCity task using the following syntax:
<UsingTask TaskName="NUnitTeamCity" AssemblyFile="$(teamcity_dotnet_nunitlauncher_msbuild_task)" /> <NUnitTeamCity Assemblies="@(assemblies_to_test)" />

The NUnitTeamCity task supports the following attributes:

Property	Description
`Platform`	Execution mode on a x64 machine. Supported values are: x86, x64, and ANY.
`RuntimeVersion`	.NET Framework to use: v1.1, v2.0, v4.0, ANY. By default, the MSBuild runtime is used. Default is v2.0 for MSBuild 2.0 and 3.5. For MSBuild 4.0 the default value is v4.0.
`IncludeCategory`	As used in the `NUnit` task from MSBuild Community tasks project.
`ExcludeCategory`	As used in the `NUnit` task from MSBuild Community tasks project.
`NUnitVersion`	Version of NUnit to be used to run the tests. Supported NUnit versions: 2.2.10, 2.4.1, 2.4.6, 2.4.7, 2.4.8, 2.5.0, 2.5.2, 2.5.3, 2.5.4, 2.5.5, 2.5.6, 2.5.7, 2.5.8, 2.5.9, 2.5.10, 2.6.0, 2.6.1, 2.6.2, 2.6.3. For example, `NUnit-2.2.10`. To use NUnit 3.0 and above, see the section below.
`Addins`	List of third-party NUnit addins to be used. For more information on using NUnit addins, refer to the NUnit Addins Support page.
`HaltIfTestFailed`	True to fail task, if any test fails.
`Assemblies`	List of assemblies to run tests with.
`RunProcessPerAssembly`	Set true, if you want to run each assembly in a new process.

The custom TeamCity NUnit task also supports additional attributes. For the list of available attributes refer to this section.

If you need the TeamCity test runner to support third-party NUnit addins, refer to the NUnit Addins Support section for the details.

Example (part of the MSBuild build script):

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <UsingTask TaskName="NUnitTeamCity" AssemblyFile="$(teamcity_dotnet_nunitlauncher_msbuild_task)"/>
 
  <Target Name="SayHello">
     <NUnitTeamCity Assemblies="!!!*put here item group of assemblies to run tests on*!!!"/>
  </Target>
</Project>

Important notes

Be sure to replace "." with "_" when using System Properties in MSBuild scripts. For example, use teamcity_dotnet_nunitlauncher_msbuild_task instead of teamcity.dotnet.nunitlauncher.msbuild.task.
TeamCity also provides Visual Studio Solution Runner for solution files of Microsoft Visual Studio 2005 and above. It allows you to use MSBuild-style wildcards for the assemblies to run unit tests on.

Examples

Run NUnit tests using specific NUnit runner version:

<Target Name="build_01">
     <!-- start tests for NUnit-2.2.10 -->
     <NUnitTeamCity Assemblies="@(TestAssembly)" NUnitVersion="NUnit-2.2.10"/>
 
     <!-- start tests for NUnit-2.4.6 -->
     <NUnitTeamCity Assemblies="@(TestAssembly)" NUnitVersion="NUnit-2.4.8"/>
  </Target>

Run NUnit tests with custom addins with NUnit 2.4.6:

<Target Name="build">
     <NUnitTeamCity Assemblies="@(TestAssembly)" Addins="NUnitExtension.RowTest.AddIn.dll" NUnitVersion="NUnit-2.4.6"/>
  </Target>

Run NUnit tests with custom addins with NUnit 2.4.6 in per-assembly mode:

<Target Name="build">
     <NUnitTeamCity Assemblies="@(TestAssembly)" Addins="NUnitExtension.RowTest.AddIn.dll" NUnitVersion="NUnit-2.4.6" RunProcessPerAssembly="True"/>
</Target>

To make a TeamCity independent build script, consider the following trick:

The MSBuild property TEAMCITY_VERSION is added to msbuild when started from TeamCity.

Working with NUnit 3.0

The information in this section is applicable if you are using NUnit 3.0 and above. For earlier versions of NUnit, refer to the section above.

Starting from version 3.0, NUnit supports TeamCity natively, so there is no need to use a special task for MSBuild as it was done for the earlier NUnit versions. The simplest way is to run the NUnit console via the standard Exec task. For example:

<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="14.0" DefaultTargets="RunTests" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
 <Target Name="RunTests">
  <Exec IgnoreExitCode="True" Command="nunit3-console.exe Tests.dll">
 <Output TaskParameter="ExitCode" ItemName="exitCode" />
  </Exec>
 <Error Text="Error while running tests" Condition="@(exitCode) < 0" />
  </Target>
</Project>

The NUnit console returns the number of failed tests as the positive exit code and, in case of the NUnit test infrastructure failure, as the negative exit code.

TeamCity controls the test execution progress, but the NUnit infrastructure exceptions may not allow TeamCity to collect the required information. That is why the IgnoreExitCode="True" attribute needs to be set, which will ignore the positive exit codes and will not interrupt the build due to several failed tests. The Error task will stop the build in case of the test infrastructure errors for the negative exit codes.

Besides the project file, you can define the MSBuild version and target platform, use profiles and other settings.

Getting Started with NUnit contains details and more examples.

Last modified: 30 July 2020