coverlet.collector 6.0.2

Coverlet与VSTest（即Visual Studio测试平台）的集成

支持的运行时版本:

自版本6.0.0起

• .NET Core >= 6.0
• .NET Framework >= 4.6.2

如快速入门部分所述，要使用收集器，您需要运行SDK v6.0.100（LTS）或更高版本，并且您的项目文件必须引用coverlet.collector和一个最低版本的Microsoft.NET.Test.Sdk。

一个示例项目文件如下所示

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFrameworks>net6.0;net48</TargetFrameworks>
  </PropertyGroup>
  <ItemGroup>
    
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.8.0" />
    
    <PackageReference Include="coverlet.collector" Version="6.0.0">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
    </PackageReference>
  ...
  </ItemGroup>
...
</Project>

在xunit模板测试（dotnet new xunit）中默认包含对coverlet.collector包的引用，您只需像更新其他任何包引用一样更新包。

在设置正确的引用后，您可以通过默认的dotnet test CLI动词运行覆盖率

dotnet test --collect:"XPlat Code Coverage"

或者

dotnet publish
...
  ... -> C:\project\bin\Debug\netcoreapp3.0\testdll.dll
  ... -> C:\project\bin\Debug\netcoreapp3.0\publish\
...
dotnet vstest C:\project\bin\Debug\netcoreapp3.0\publish\testdll.dll --collect:"XPlat Code Coverage"

正如您在vstest动词的情况下所见，您必须先发布项目。

测试结束，您可以在默认的 VSTest 平台目录 TestResults 下找到覆盖率文件数据。

Attachments:
  C:\git\coverlet\Documentation\Examples\VSTest\HelloWorld\XUnitTestProject1\TestResults\bc5e983b-d7a8-4f17-8c0a-8a8831a4a891\coverage.cobertura.xml
Test Run Successful.
Total tests: 1
     Passed: 1
 Total time: 2,5451 Seconds

您可以使用标准的 dotnet test 开关 --results-directory 更改输出目录。

注意：设计上，VSTest 平台将在一个随机命名的文件夹（GUID 字符串）下创建您的文件，因此如果您需要将其加载到某些不支持 glob 模式或层次性搜索的图形用户界面报告系统（例如 coveralls、codecov、reportgenerator 等）中，则需要手动将结果文件移动到一个可预测的文件夹。

Coverlet 支持的 VSTest 集成选项

⚠️当前 VSTest 集成不支持 msbuild 和 .NET 工具的所有功能，例如在控制台显示结果、报告合并和阈值验证。我们正在努力填平这些差距。

PS：如果您没有其他合并报告的方法（例如，您的报告生成器不支持多覆盖率文件），您目前可以利用我们的一位贡献者 Daniel Paz(@p4p3) 报告的一个技巧 https://github.com/tonerdo/coverlet/pull/225#issuecomment-573896446

默认选项（如果没有指定 runsettings 文件）

如果没有指定 runsettings 文件而只通过收集器名称调用 coverlet，生成覆盖率输出的结果默认为 cobertura 格式。

dotnet test --collect:"XPlat Code Coverage"

Coverage 报告的输出格式也可以不通过 runsettings 文件指定，通过在参数中指定来更改。支持的格式包括 lcov、opencover、cobertura、teamcity、json（默认为 coverlet 自有格式）。

dotnet test --collect:"XPlat Code Coverage;Format=json"

甚至还可以指定多个输出格式。

dotnet test --collect:"XPlat Code Coverage;Format=json,lcov,cobertura"

高级选项（通过 runsettings 支持）

以下是一些 coverlet 支持的选项，您可以在 runsettings 中将其指定为数据收集器配置。

如何通过 runsettings 指定这些选项？

<?xml version="1.0" encoding="utf-8" ?>
<RunSettings>
  <DataCollectionRunSettings>
    <DataCollectors>
      <DataCollector friendlyName="XPlat code coverage">
        <Configuration>
          <Format>json,cobertura,lcov,teamcity,opencover</Format>
          <Exclude>[coverlet.*.tests?]*,[*]Coverlet.Core*</Exclude> 
          <Include>[coverlet.*]*,[*]Coverlet.Core*</Include> 
          <ExcludeByAttribute>Obsolete,GeneratedCodeAttribute,CompilerGeneratedAttribute</ExcludeByAttribute>
          <ExcludeByFile>**/dir1/class1.cs,**/dir2/*.cs,**/dir3/**/*.cs,</ExcludeByFile> 
          <IncludeDirectory>../dir1/,../dir2/,</IncludeDirectory>
          <SingleHit>false</SingleHit>
          <UseSourceLink>true</UseSourceLink>
          <IncludeTestAssembly>true</IncludeTestAssembly>
          <SkipAutoProps>true</SkipAutoProps>
          <DeterministicReport>false</DeterministicReport>
          <ExcludeAssembliesWithoutSources>MissingAll,MissingAny,None</ExcludeAssembliesWithoutSources>
        </Configuration>
      </DataCollector>
    </DataCollectors>
  </DataCollectionRunSettings>
</RunSettings>

过滤细节见 msbuild 指南。

可以通过以下命令行选项轻松提供该 runsettings 文件：

• dotnet test --collect:"XPlat Code Coverage" --settings coverlet.runsettings
• dotnet vstest C:\project\bin\Debug\netcoreapp3.0\publish\testdll.dll --collect:"XPlat Code Coverage" --settings coverlet.runsettings

请参阅我们的 HelloWorld 示例。

通过命令行传递 runsettings 参数

您可以通过使用命令行中的 xml 平面语法来避免向 dotnet test 驱动程序传递 runsettings 文件。

例如，如果您想将 Format 元素设置为 runsettings 选项，可以使用此语法：

dotnet test --collect:"XPlat Code Coverage" -- DataCollectionRunSettings.DataCollectors.DataCollector.Configuration.Format=json,cobertura,lcov,teamcity,opencover

有关更多信息，请参阅此处：https://github.com/microsoft/vstest/blob/main/docs/RunSettingsArguments.md

工作原理

借助数据收集器实现 Coverlet 集成。当我们指定 --collect:"XPlat Code Coverage" 时，VSTest 平台会尝试从 coverlet.collector.dll 中加载 coverlet 收集器

1. 进程外数据收集器：进程外收集器在运行测试的进程之外的进程（datacollector.exe/datacollector.dll）中运行。此数据收集器负责调用 Coverlet API 对 .dll 进行插桩，收集覆盖率结果并将覆盖率输出文件发送回测试平台。

2. 进程内数据收集器：进程内收集器在执行测试的 testhost 进程中加载。此收集器需要删除对进程退出处理器的依赖，以刷新命中文件，避免出现这个严重已知问题

常见问题

有关已知问题的完整列表，请查看详细文档KnownIssues.md