TeamCity 中的 NUnit 支持
在 TeamCity 中设置 NUnit 测试报告的两种最常见方法是:
此外,您可以尝试其他方法,或者在任何其他运行器(如 PowerShell 或 Command Line)中使用 TeamCity VSTest Adapter 运行测试。
这篇文章描述了 TeamCity 对 NUnit 支持的具体情况,以及确定 NUnit 支持所采用的 替代方法。
以下 NUnit 版本受支持: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、3.0。
在代理机器上可以安装多个版本的 NUnit,并在构建中使用其中任何一个版本。
warning
NUnit 版本 3.4.0 由于在 NUnit 出现的问题,没有得到 NUnit 构建运行程序的支持。 仅版本 3.4.0 受到影响,其他 NUnit 3.x 版本与 TeamCity 协同工作完好无损。
以下表格显示了 TeamCity 运行器与 .NET 实现的兼容性:
.NET Framework 1、1.1、2、3.5 | .NET Framework 4+ | .NET Core 1+ 和 .NET 5+ | |
---|---|---|---|
NUnit 运行器
| |||
.NET 运行器
| |||
其他运行器中的 VSTest 适配器 |
如果使用 NUnit 或 .NET 构建运行程序不适用,那么 TeamCity 提供以下方法来配置在 TeamCity 中的 NUnit 测试报告:
标准的 NUnit 用于 NAnt 构建运行程序。
NUnit 测试启动器可以在 MSBuild 构建脚本中进行配置,或从 命令行启动。
TeamCity Add-in for NUnit可以开启NUnit级别的报告功能,无需修改构建过程。
附带的 XML Test Reporting plugin 允许将任何 XML 报告导入至 TeamCity。 在此情况下,总是能够实时跟踪结果并不总是可能的。
您可以向您的构建配置中添加 XML 报告处理 构建功能,或使用以下服务信息:##teamcity[importData type='sometype' path='<path to the xml file>']
。 了解更多:XML 报告处理,导入 XML 报告。通过 服务消息 手动配置测试报告。
方法 | 实时报告 | 在 CLI-based 运行器中执行 | 测试重新排序 | 隐式 TeamCity .NET 覆盖率 |
---|---|---|---|---|
<nunit2> NAnt 任务 |
| |||
<NUnit> MSBuild 任务 |
| |||
<NUnitTeamCity> MSBuild 任务 |
| |||
NUnit 的 TeamCity 插件 | ||||
TeamCity NUnit 测试启动器 | ||||
XML 报告插件 | 不适用 | 不适用 |
* TeamCity 提供的任务可能具有不同的语法/行为。 可能需要一些解决方法来在没有 TeamCity 的情况下运行脚本。
除了常见的测试报告功能外,TeamCity 允许在 x64 机器上以 x86 进程运行 NUnit 测试,通过明确指定平台和运行时环境版本来实现这一点。 您可以定义是否在 MSIL 、 x64 或 x86 平台下启动 .NET Framework 1.1 、 2.0 或 4.0 。
TeamCity 提供了自己的 NUnit 测试启动器,可以从命令行中使用。 根据传递的参数运行测试,如果该过程在 TeamCity 构建代理环境内运行,结果将报告给 TeamCity 代理。
tip
提示:
如果您需要从某个进程访问到 TeamCity NUnit 启动器的路径,您可以添加
%system.teamcity.dotnet.nunitlauncher%
环境变量。在 Command Line runner 的自定义脚本中,被
%
包围的值会被视为 TeamCity 引用。
您可以将以下命令行选项传递给 TeamCity NUnit 测试启动器:
${teamcity.dotnet.nunitlauncher} <.NET Framework> <platform> <NUnit vers.> [/category-include:<list>] [/category-exclude:<list>] [/addin:<list>] <assemblies to test>
选项 | 描述 |
---|---|
| 运行测试的 .NET Framework 版本。 可接受的值包括 v1.1、v2.0、v4.0和ANY。 |
| 运行测试的平台。 可接受的值有 x86、x64 和 MSIL。 对于 .NET Framework 1.1,只有 MSIL 选项可用。 |
| 要使用的测试框架。 数值必须按照以下格式指定: |
| 由 |
| 由 |
| 使用的第三方 NUnit 插件列表(可选)。 |
| 由 |
| 指定在新进程中运行每个程序集。 |
从 NUnit 2.4.6 开始并一直到但不包括 NUnit v3.0,可以使用 类别表达式。 这个表格展示了一些示例:
表达式 | 操作 |
---|---|
A|B|C | 选择具有类别 A 、 B 或 C 的任何测试。 |
A,B,C | 选择具有类别 A 、 B 或 C 的任何测试。 |
A + B + C | 仅选择被分配了全部三个类别的测试。 |
A + B | C | 选择既含有 A 和 B 的测试,或者分类为 C 的测试。 |
A+B-C | 选择同时具有 A 和 B 但不包含 C 的测试。 |
-A | 选择未分配A类别的测试。 |
A + (B | C) | 选择同时具有 A 类别和 B 或 C 的测试。 |
A + B,C | 选择同时具有 A 类别和 B 或 C 的测试。 |
注意: 正如最后两个示例所显示的那样,逗号运算符( ,
)等同于管道( |
)但具有更高的优先级。 评估的顺序如下:
一元排斥运算符(
-
)。高优先级联合操作符(
,
)。交集和集合减法运算符(
+
和二元-
)。低优先级联合运算符(
|
)。
由于运算符字符具有特殄意义,避免创建使用其中任何一个的类别名称。 例如,类别 db-tests
不能在命令行中使用,因为它似乎表示 "运行 db 类别,除了测试类别。 对于您正在使用的 shell 具有特殊含义的字符,也适用相同的限制。
以下示例假定在 构建配置设置 的 参数 页面上,将 teamcity.dotnet.nunitlauncher
属性设为系统属性。
从程序集中运行测试:
%teamcity.dotnet.nunitlauncher% v2.0 x64 NUnit-2.2.10 Assembly.dll
使用 NUnit 类别过滤器从一个程序集中运行测试:
%teamcity.dotnet.nunitlauncher% v2.0 x64 NUnit-2.2.10 /category-include:C1 /category-exclude:C2 Assembly.dll
从程序集运行测试:
%teamcity.dotnet.nunitlauncher% v2.0 x64 NUnit-2.5.0 /addin:Addin1.dll;Addin2.dll Assembly.dll Assebly2.dll
这部分假设,您已经有一个配备了配置的 nunit2
任务的 NAnt 构建脚本,并希望 TeamCity 跟踪测试报告,而无需对现有的构建脚本进行任何更改。 否则,考虑在您的构建配置的步骤中添加 NUnit build runner 作为其中之一。
为了通过标准的 nunt2
任务跟踪在 NAnt 构建中定义的测试,TeamCity 提供了一个自定义的 任务 实现,并自动用其自身任务替换原始的 <nunit2>
任务。 当构建被触发时,TeamCity 会使用自己的实现启动 TeamCity NUnit 测试启动器,利用 <nunit2>
。 这使您可以在不更改构建脚本的情况下,在 TeamCity 中实时接收测试报告。
如果您不希望 TeamCity 替换原始的 nunit2
任务,请考虑以下选项:
使用 NUnit 控制台与 TeamCity 的 NUnit 插件。
通过 XML 测试报告插件导入 XML 测试结果。
使用命令行 NUnit Test Launcher。
通过服务消息手动配置报告测试。
要禁用
nunit2
任务替换,请将teamcity.dotnet.nant.replaceTasks
系统属性 设置为false
。
在 TeamCity 中, nunt2
任务实现支持额外选项,可以通过 NAnt <property>
任务在构建脚本中指定,或者在 构建配置 | 构建参数 下作为 系统属性 指定。
以下选项支持 TeamCity <nunit2>
任务实施:
属性 | 描述 |
---|---|
| 运行 所有测试,不论失败的数量。 如果至少有一个测试失败,则失败。 |
| 为 x64 机器上的 .NET 2.0 设置期望的运行时执行模式。 支持的值包括 x86,x64,和 ANY(默认)。 |
| 设置所需的 .NET Framework 版本。 支持的值为 v1.1、v2.0、v4.0。 默认值等于 NAnt 目标框架。 |
| 指定使用哪个版本的 NUnit 运行器。 数值必须按照以下格式指定: 在代理机器上可以安装多个版本的 NUnit,并在构建中使用其中任何一个版本。 |
| 指定用于 NAnt 构建运行程序的第三方 NUnit 插件列表。 |
| 如果您希望在新进程中运行每个程序集,请设置 |
TeamCity NUnit 测试启动器将在 NAnt 目标框架所指定的 .NET Framework 中运行测试,也就是说,运行在 .NET Framework 1.1、2.0 或 4.0 运行时环境中。 TeamCity 也支持对 <nunit2>
任务的测试类别。
将列出的属性添加到 NAnt 构建脚本中,使其依赖于 TeamCity。 为了避免这种情况,将属性指定为构建配置下的系统属性,或者考虑添加 <if>
任务。
tip
如果您需要 TeamCity 测试运行程序支持第三方 NUnit 插件,请参阅 NUnit 插件支持 部分了解具体细节。
示例
在 .NET 2.0 下,以 x64 模式从单个汇编文件开始测试。
<property name="teamcity.dotnet.nant.nunit2.platform" value="x64" />
<nunit2>
<formatter type="Plain" />
<test assemblyname="MyProject.Tests.dll" />
</nunit2>
运行分类 C1 下的所有测试,但不包括 C2。
<nunit2 verbose="true" haltonfailure="false" failonerror="true">
<formatter type="Plain" />
<test>
<assemblies>
<include name="dll.dll" />
</assemblies>
<categories>
<include name="C1" />
<exclude name="C2"/>
</categories>
</test>
</nunit2>
明确指定 NUnit 的版本以运行测试。
请注意,在这种情况下,应在 nunit2
任务调用之前添加以下属性 。
<property name="teamcity.dotnet.nant.nunit2.version" value="NUnit-2.4.10" />
<nunit2> <!--....--> </nunit2>
此部分描述如何从 MSBuild 使用 NUnit。
这一部分假设您已经有一个带有配置的 NUnit
任务的 MSBuild 构建脚本,并且希望 TeamCity 能够跟踪测试报告,而不需要对现有的构建脚本进行任何更改。 否则,请考虑在您的构建配置步骤中添加 NUnit build runner 作为其中一步。
TeamCity 提供了一个自定义 NUnitTeamCity
任务,它与 NUnit
任务兼容,来自 MSBuild Community tasks 项目。 如果您在构建脚本中提供了 NUnitTeamCity
任务,TeamCity 将根据任务中指定的选项启动其自己的测试运行器。 因此,您不需要任何 NUnit 运行器,因为 TeamCity 将运行测试。
要正确使用 NUnitTeamCity
任务:
确保构建代理可以访问
teamcity_dotnet_nunitlauncher
系统属性。 运行 Windows 的构建代理应自动检测这些属性作为环境变量。 如果您需要手动设置它们,请参见定义 agent-specific 属性以获取更多信息。使用以下语法,通过
NUnitTeamCity
任务配置您的 MSBuild 构建脚本:<UsingTask TaskName="NUnitTeamCity" AssemblyFile="$(teamcity_dotnet_nunitlauncher_msbuild_task)" /> <NUnitTeamCity Assemblies="@(assemblies_to_test)" />
NUnitTeamCity
任务支持以下属性:
属性 | 描述 |
---|---|
| 在 x64 机器上的执行模式。 支持的值包括:x86、x64和ANY。 |
| 要使用的 .NET Framework :v1.1、v2.0、v4.0、ANY。 默认情况下,使用的是 MSBuild 运行时。 默认为 MSBuild 2.0 和 3.5 的 v2.0。 对于 MSBuild 4.0,其默认值为 v4.0。 |
| 如在 |
| 如在 |
| 要运行测试的 NUnit 版本。 要使用 NUnit 3.0 及以上版本,请参阅下方的 部分。 |
| 需使用的第三方 NUnit 插件列表。 有关使用 NUnit 插件的更多信息,请参阅 NUnit 插件支持 部分。 |
| 如果有任何测试失败,True 则会导致任务失败。 |
| 运行测试所需的程序集列表。 |
| 设定 |
定制的 TeamCity NUnit
任务也支持额外的属性。 有关可用属性的列表,请参阅 此部分。
如果您需要 TeamCity 测试运行器支持第三方 NUnit 插件,请参考 NUnit 插件支持 部分以获取详细信息。
示例(MSBuild 构建脚本的一部分):
<Project xmlns="https://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>
重要说明
在 MSBuild 脚本中 使用系统属性 时,请确保将
.
替换为_
。 例如,使用teamcity_dotnet_nunitlauncher_msbuild_task
而不是teamcity.dotnet.nunitlauncher.msbuild.task
。TeamCity 还提供适用于 Microsoft Visual Studio 2005 及以上版本的解决方案文件的 Visual Studio Solution Runner。 它允许您使用 MSBuild 风格的通配符来运行单元测试的程序集。
示例
使用特定的 NUnit 运行器版本运行 NUnit 测试:
<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>
使用 NUnit 2.4.6 和自定义插件运行 NUnit 测试:
<Target Name="build">
<NUnitTeamCity Assemblies="@(TestAssembly)" Addins="NUnitExtension.RowTest.AddIn.dll" NUnitVersion="NUnit-2.4.6"/>
</Target>
使用 NUnit 2.4.6 以及自定义插件运行 NUnit 测试在每个程序集模式下:
<Target Name="build">
<NUnitTeamCity Assemblies="@(TestAssembly)" Addins="NUnitExtension.RowTest.AddIn.dll" NUnitVersion="NUnit-2.4.6" RunProcessPerAssembly="True"/>
</Target>
为了制作一个独立的 TeamCity 构建脚本,请考虑以下选项:
<NUnitTeamCity ... Condition=" '$(TEAMCITY_VERSION)' != '' "/>
MSBuild 属性 TEAMCITY_VERSION
是在从 TeamCity 启动时添加到 MSBuild 的。
从 3.0 版开始,NUnit 原生支持 TeamCity,因此无需像 之前的 NUnit 版本那样使用专门的 MSBuild 任务。 最简单的方法是通过标准的 Exec 任务 运行 NUnit 控制台。
《NUnit 入门》文章包含了详细信息和例子。
对于 MSBuild,TeamCity 提供了以下服务任务,实现了与 Build Script Interaction 相同的选项:
TeamCitySetBuildNumber
允许更改构建编号:
<TeamCitySetBuildNumber BuildNumber="1.3_{build.number}" />
可以使用 {build.number}
作为旧版本号的占位符。
TeamCityProgressMessage
允许编写进度消息:
<TeamCityProgressMessage Text="Progress message text" />
TeamCityPublishArtifacts
允许发布来自 MSBuild 项目组的所有制品:
<ItemGroup>
<Files Include="*.dll" />
</ItemGroup>
<TeamCityPublishArtifacts SourceFiles="@(Files-> '%(FullPath)' )" Condition=" '$(TEAMCITY_VERSION)' != '' "/>
TeamCityReportStatsValue
是一个用于发布统计值的便捷任务:
<TeamCityReportStatsValue Key="StatsValueType" Value="42" />
TeamCityBuildProblem
报告了一个实际上导致构建失败的构建问题。 建筑问题会出现在 Build Results 页面,并且还会影响建筑状态文本:
<TeamCityBuildProblem description="description" identity="identity"/>
必须的
描述
属性是用人类可读的文本描述构建问题。 默认情况下,描述
会出现在构建状态文本中。身份
是一个可选属性,用于描述特定的构建问题实例。 如果出现相同问题,它在构建过程中不应有所变化:例如,相同的编译错误。 应为有效的 Java ID,最多可达60个字符长。 默认情况下,身份
基于描述
计算。
TeamCitySetStatus
是一个改变当前构建状态文本的任务。
<TeamCitySetStatus Status="<status value>" Text="{build.status.text} and some aftertext" />
{构建状态.text
被替换为了旧的状态文本。 状态可以具有 成功
值。
NUnit Add-in 是一个扩展程序,它插入到 NUnit 核心中并改变其运行方式。 请参阅 NUnit 插件页面 获取更多信息。 本节内容涵盖了 NAnt 、 MSBuild 和 NUnit Console Launcher 对 NUnit 插件支持的描述。
要在 NAnt 构建运行程序中支持 NUnit 插件,您需要在您的构建脚本中添加 teamcity.dotnet.nant.nunit2.addins
属性:
<property name="teamcity.dotnet.nant.nunit2.addins" value="<list of paths>" />
其中 <list>
是由 ;
分隔的 NUnit 插件路径列表。
例如:
<property name="teamcity.dotnet.nant.nunit2.addins" value="../tools/addins/MyFirst.AddIn.dll;MySecond.AddIn.dll" />
为了支持 NUnit 插件的 console launcher,您需要提供 /addins:<以 ; 分隔的插件列表>
命令行选项。
例如:
${teamcity.dotnet.nunitlauncher} /addin:../tools/addins/MyFirst.AddIn.dll;nunit-addins/MySecond.AddIn.dll
这一部分适用于 NUnit 3.0 之前的版本。
为了支持 MSBuild 运行器的 NUnit 插件,为 NUnitTeamCity
任务指定 插件
属性:
Addins="<list>"
在这里, <list>
是由 ;
或 ,
分隔的插件列表。
例如:
<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003" DefaultTargets="build">
<ItemGroup>
<TestAssembly Include="$(MSBuildProjectDirectory)/MyTests.dll" />
</ItemGroup>
<Target Name="build">
<NUnitTeamCity Assemblies="@(TestAssembly)" Addins="../tools/addins/MyFirst.AddIn.dll;nunit-addins/MySecond.AddIn.dll" />
</Target>
</Project>
TeamCity NUnit 插件支持 NUnit 3.0 版本之前的版本。 对于后续版本,请参考 此部分。
如果您通过 NUnit console 运行 NUnit 测试,并希望 TeamCity 能够追踪测试结果,而无需启动 TeamCity 测试运行器,那么最佳的解决方案就是使用 TeamCity 的 NUnit 插件。 您可以将此插件接入 NUnit ,然后测试结果将自动报告给 TeamCity 服务器。
或者,您可以选择使用 XML 报告处理 构建功能,或者通过 服务消息 手动配置测试报告。
要在 TeamCity 中查看测试结果:
在您的构建中,将 TeamCity 插件的路径设置为系统属性
teamcity.dotnet.nunitaddin
(对于 MSBuild,应为teamcity_dotnet_nunitaddin
),并在路径末尾添加 NUnit 的版本。 例如:对于 NUnit 2.4.X ,请使用
${teamcity.dotnet.nunitaddin}-2.4.X.dll
(对于 MSBuild :$(teamcity_dotnet_nunitaddin)-2.4.X.dll
)。
例如 NUnit 2.4.7 :NAnt:${teamcity.dotnet.nunitaddin}-2.4.7.dll
, MSBuild :$(teamcity_dotnet_nunitaddin)-2.4.7.dll
。对于 NUnit 2.5.0 alpha 4,使用
${teamcity.dotnet.nunitaddin}-2.5.0.dll
(适用于 MSBuild:$(teamcity_dotnet_nunitaddin)-2.5.0.dll
)。
将
.dll
和.pdb
TeamCity 插件文件复制到 NUnit 插件目录中。
虽然您可以一次复制这些文件,但我们强烈建议配置您的构建,以便 每次构建 时都会将 TeamCity 插件文件复制到 NUnit 插件目录,因为这些文件可能会被 TeamCity 更新。
以下示例展示了如何在 MSBuild 上使用 NUnit console runner 和 TeamCity 的 NUnit 2.4.7 插件:
<ItemGroup>
<NUnitAddinFiles Include="$(teamcity_dotnet_nunitaddin)-2.4.7.*" />
</ItemGroup>
<Target Name="RunTests">
<MakeDir Directories="$(NUnitHome)/bin/addins" />
<Copy SourceFiles="@(NUnitAddinFiles)" DestinationFolder="$(NUnitHome)/bin/addins" />
<Exec Command="$(NUnitHome)/bin/NUnit-Console.exe $(NUnitFileName)" />
</Target>
如果您需要明确地为 NUnit 配置 环境变量,请指定一个带有 %system.teamcity.dotnet.nunitaddin%
值引用的环境变量。 请参阅 此文章 以获取详细信息。
NUnit 2.4.8 问题
NUnit 2.4.8 存在以下已知问题:NUnit 2.4.8 运行器尝试根据创建的 AssemblyName
对象加载程序集。 然而,NUnit 2.4.8 的 插件
文件夹并未包含在应用程序探测路径中。 因此,NUnit 2.4.8 无法在控制台模式下加载任何插件。
为解决这个问题,我们建议您使用以下任何一种解决方法:
将 TeamCity 插件程序集复制到 NUnit
bin
和bin/addins
目录。将补丁
NUnit-Console.exe.config
包含到应用程序探针路径中以添加插件。 将以下代码添加到config/runtime
元素中:<assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1"> <probing privatePath="addins"/> </assemblyBinding>
感谢您的反馈!