coverlet.console 6.0.2

作为全局工具的Coverlet

要查看选项列表，请运行

coverlet --help

当前选项为 (输出自 coverlet --help)

Cross platform .NET Core code coverage tool 6.0.0.0

Usage: coverlet [arguments] [options]

Arguments:
  <ASSEMBLY|DIRECTORY>                  Path to the test assembly or application directory.

Options:
  -t|--target (REQUIRED)                Path to the test runner application.
  -a|--targetargs                       Arguments to be passed to the test runner.
  -o|--output                           Output of the generated coverage report
  -v|--verbosity                        Sets the verbosity level of the command. Allowed values are quiet, minimal, normal, detailed.
  -f|--format                           Format of the generated coverage report. [default: json]
  --threshold                           Exits with error if the coverage % is below value.
  --threshold-type                      Coverage type to apply the threshold to.
  --threshold-stat                      Coverage statistic used to enforce the threshold value. [default: Minimum]
  --exclude                             Filter expressions to exclude specific modules and types.
  --include                             Filter expressions to include only specific modules and types.
  --exclude-by-file                     Glob patterns specifying source files to exclude.
  --include-directory                   Include directories containing additional assemblies to be instrumented.
  --exclude-by-attribute                Attributes to exclude from code coverage.
  --include-test-assembly               Specifies whether to report code coverage of the test assembly.
  --single-hit                          Specifies whether to limit code coverage hit reporting to a single hit for each location
  --skipautoprops                       Neither track nor record auto-implemented properties.
  --merge-with                          Path to existing coverage result to merge.
  --use-source-link                     Specifies whether to use SourceLink URIs in place of file system paths.
  --does-not-return-attribute           Attributes that mark methods that do not return.
  --exclude-assemblies-without-sources  Specifies behaviour of heuristic to ignore assemblies with missing source documents.
  --source-mapping-file                 Specifies the path to a SourceRootsMappings file.
  --version                             Show version information
  -?, -h, --help                        Show help and usage information

注意：对于 [多个值] 选项，您可以通过多次指定值来进行，即

--exclude-by-attribute 'Obsolete' --exclude-by-attribute 'GeneratedCode' --exclude-by-attribute 'CompilerGenerated'

或者通过空格分隔的序列传递多个值，即

--exclude-by-attribute "Obsolete" "GeneratedCode" "CompilerGenerated"

对于 --merge-with 查看示例。

代码覆盖率

使用 coverlet 工具通过指定包含单元测试的程序的路径来调用该工具。您还需要使用 --target 和 --targetargs 选项分别指定测试运行器和传递给测试运行器的参数。使用所提供的参数调用测试运行器时，必须不涉及单元测试程序集的重新编译，否则将不会生成覆盖率数据。

以下示例显示如何使用熟悉的 dotnet test 工具链

coverlet /path/to/test-assembly.dll --target "dotnet" --targetargs "test /path/to/test-project --no-build"

运行以上命令后，将在运行 coverlet 命令的目录中生成包含结果的 coverage.json 文件。终端将还显示结果的摘要。

注意：指定了 --no-build 标志，因此不会重新构建 /path/to/test-assembly.dll

集成测试和端到端测试的代码覆盖率

有时，存在不使用像 xunit 这样的常规单元测试框架的测试。您可能会遇到测试由自定义可执行文件/脚本驱动的情景，当运行时，可能会执行从调用 API 到驱动 Selenium 的任何操作。

以示例来说明，假设您有一个文件夹 /integrationtest，该文件夹包含所需的可执行文件（我们称其为 runner.exe）以及执行过程中所需的一切。您可以使用我们的工具来启动可执行文件并收集实时覆盖率。

coverlet "/integrationtest" --target "/application/runner.exe"

Coverlet 最初将对 integrationtests 文件夹中的所有 .NET 程序集进行代码插装，然后执行 runner.exe。最后，在您的 runner.exe 关闭时，它将生成覆盖率报告。您可以使用所有可用的参数来自定义报告生成。一旦 runner.exe 退出，就会生成覆盖率结果。您可以使用所有可用的参数来自定义报告生成。

注意：今天，Coverlet 依赖于 AppDomain.CurrentDomain.ProcessExit 和 AppDomain.CurrentDomain.DomainUnload 记录对文件系统的访问次数，因此需要确保进程关闭得体。强制关闭进程将导致覆盖率报告不完整。

覆盖率输出

Coverlet 可以使用 --format 或 -f 选项生成多种格式的覆盖率结果。例如，下面的命令将覆盖率结果以 opencover 格式输出，而不是 json 格式。

coverlet <ASSEMBLY> --target <TARGET> --targetargs <TARGETARGS> --format opencover

支持的格式

• json（默认）
• lcov
• opencover
• cobertura
• teamcity

您可以通过多次指定 --format 选项来在一个运行中输出多个格式。

coverlet <ASSEMBLY> --target <TARGET> --targetargs <TARGETARGS> --format opencover --format lcov

默认情况下，Coverlet 将覆盖率结果文件输出到当前工作目录。您可以使用 --output 或 -o 选项来覆盖此行为。

coverlet <ASSEMBLY> --target <TARGET> --targetargs <TARGETARGS> --output "/custom/path/result.json"

上面的命令将结果写入指定的路径，如果未指定文件扩展名，它将使用所选输出格式的标准扩展名。要指定目录，只需在值末尾附加一个 /。

coverlet <ASSEMBLY> --target <TARGET> --targetargs <TARGETARGS> --output "/custom/directory/" -f json -f lcov

TeamCity 输出

Coverlet 可以使用 TeamCity 服务消息 输出基本的代码覆盖率统计数据。

coverlet <ASSEMBLY> --target <TARGET> --targetargs <TARGETARGS> --output teamcity

目前支持的 TeamCity 统计数据 包括：

TeamCity 统计数据键	描述
CodeCoverageL	代码覆盖率（行级）
CodeCoverageB	分支覆盖率
CodeCoverageM	方法覆盖率
CodeCoverageAbsLTotal	总行数
CodeCoverageAbsLCovered	已覆盖行数
CodeCoverageAbsBTotal	总分支数
CodeCoverageAbsBCovered	已覆盖分支数
CodeCoverageAbsMTotal	总方法数
CodeCoverageAbsMCovered	已覆盖方法数

合并结果

使用 Coverlet，您可以合并多个覆盖率运行的输出为一个单一的结果。

coverlet <ASSEMBLY> --target <TARGET> --targetargs <TARGETARGS> --merge-with "/path/to/result.json" --format opencover

给定给 --merge-with 的值 必须 是 Coverlet 自身的 json 结果格式的路径。

阈值

Coverlet 允许您指定一个覆盖率阈值，低于此阈值它返回非零退出代码。这允许您对所有项目的更改强制实施最低覆盖率百分比。

coverlet <ASSEMBLY> --target <TARGET> --targetargs <TARGETARGS> --threshold 80

上面的命令将自动失败构建，如果任何受监控模块的行、分支或方法覆盖率低于 80%。您可以使用 --threshold-type 选项指定应用阈值值的覆盖率类型。例如，仅针对 行 覆盖率应用阈值检查：

coverlet <ASSEMBLY> --target <TARGET> --targetargs <TARGETARGS> --threshold 80 --threshold-type line

您可以通过多次指定 --threshold-type 选项来实现。有效的值包括 line、branch 和 method。

coverlet <ASSEMBLY> --target <TARGET> --targetargs <TARGETARGS> --threshold 80 --threshold-type line --threshold-type method

默认情况下，Coverlet 将验证阈值值与每个模块的覆盖率结果。使用 --threshold-stat 选项可更改此行为，并可以具有以下任何值：

• 最小值（默认值）：确保每个模块的覆盖率结果不低于阈值
• 总计：确保所有模块的总覆盖结果不少于阈值
• 平均值：确保所有模块的平均覆盖结果不少于阈值

以下命令将对比阈值值与所有模块的总覆盖量

coverlet <ASSEMBLY> --target <TARGET> --targetargs <TARGETARGS> --threshold 80 --threshold-type line --threshold-stat total

排除覆盖

属性

您可以通过创建并应用 System.Diagnostics.CodeAnalysis 命名空间中存在的 ExcludeFromCodeCoverage 属性，从代码覆盖中忽略一个方法或整个类。

您也可以通过使用 ExcludeByAttribute 属性来忽略额外的属性

• 可以指定多次
• 使用属性名、属性全名或属性类型的完全限定名 (Obsolete、ObsoleteAttribute、System.ObsoleteAttribute)

coverlet <ASSEMBLY> --target <TARGET> --targetargs <TARGETARGS> --exclude-by-attribute 'Obsolete' --exclude-by-attribute 'GeneratedCode' --exclude-by-attribute 'CompilerGenerated'

源文件

您还可以使用 --exclude-by-file 选项从代码覆盖中忽略特定的源文件

• 可以指定多次
• 使用文件路径或目录路径，并使用通配符 (例如 dir1/*.cs)

coverlet <ASSEMBLY> --target <TARGET> --targetargs <TARGETARGS> --exclude-by-file "**/dir1/class1.cs"

过滤器

Coverlet 提供了使用“过滤器表达式”对排除内容进行细粒度控制的能力。

语法: --exclude '[Assembly-Filter]Type-Filter'

通配符

• * ∨ 匹配零个或多个字符
• ? ∨ 前缀字符是可选的

示例

• --exclude "[*]*" ∨ 排除所有程序集中的所有类型（没有进行注入）
• --exclude "[coverlet.*]Coverlet.Core.Coverage" ∨ 排除属于 Coverlet.Core 命名空间且匹配 coverlet.* 的任何程序集的 Coverage 类（例如 coverlet.core）
• --exclude "[*]Coverlet.Core.Instrumentation.*" ∨ 排除任何程序集中属于 Coverlet.Core.Instrumentation 命名空间的所有类型
• --exclude "[coverlet.*.tests?]*" ∨ 排除以 coverlet. 开头并以 .test 或 .tests 结尾的任何程序集中的所有类型（? 使得字母 s 可选）
• --exclude "[coverlet.*]" --exclude "[*]Coverlet.Core*" ∨ 排除匹配 coverlet.* 的程序集，并排除任何程序集中属于 Coverlet.Core 命名空间的所有类型

coverlet <ASSEMBLY> --target <TARGET> --targetargs <TARGETARGS> --exclude "[coverlet.*]Coverlet.Core.Coverage"

Coverlet 还允许您使用 --include 选项明确设置可包含的内容，进一步扩展了这一功能。

示例

• --include "[*]*" ∨ 包含所有程序集中的所有类型（所有内容都进行注入）
• --include "[coverlet.*]Coverlet.Core.Coverage" ∨ 包含属于 Coverlet.Core 命名空间且匹配 coverlet.* 的任何程序集的 Coverage 类（例如 coverlet.core）
• --include "[coverlet.*.tests?]*" ∨ 包含属于以 coverlet. 开头并以 .test 或 .tests 结尾的任何程序集中的所有类型（? 使得字母 s 可选）

您可以将 --exclude 和 --include 选项同时使用，但 --exclude 具有优先级。您可以通过指定多个过滤器表达式来多次指定 --exclude 和 --include 选项。

您还可以通过指定 --include-test-assembly 标志来包含测试程序集的覆盖率。

SourceLink

Coverlet 支持包含在 PDB 中的 SourceLink 自定义调试信息。当您指定 --use-source-link 标志时，Coverlet 将生成包含源文件 URL 的结果，而不是本地文件路径。

路径映射

Coverlet 有能力使用 --source-mapping-file 选项将调试源文件内部包含的路径映射到源文件当前所在的本地路径。这对于源文件使用确定性构建且路径设置为 /_/ 的情况或源文件在不同主机上构建（源文件位于不同路径）的情况非常有用。

--source-mapping-file 的值应该是每个行都是 |要映射的路径=调试符号中的路径 格式的文件。例如，要将项目的本地检查 C:\git\coverlet 映射到以 <Deterministic>true</Deterministic> 构建的对应项目，该配置将源设置为 /_/*，映射文件中必须包含以下行。

|C:\git\coverlet\=/_/

在收集覆盖率时，Coverlet 将以 /_/ 开头的任何路径转换为 C:\git\coverlet\，以便收集器能够找到源文件。

退出码

Coverlet 会输出特定退出码，以更好地支持构建自动化系统，以便确定失败的类型，从而采取相应的行动。

0 - Success.
1 - If any test fails.
2 - Coverage percentage is below threshold.
3 - Test fails and also coverage percentage is below threshold.
101 - General exception occurred during coverlet process.
102 - Missing options or invalid arguments for coverlet process.