Flutter代码覆盖率插件pull_request_coverage的使用

Motivation

CI工具中的覆盖率阈值是鼓励开发者编写测试的常见方法。然而，仅基于整个项目的覆盖率来判断拉取请求（PR）并不总是公平的，特别是在进行重大重构任务时，这可能会自然地降低覆盖率。

pull_request_coverage包采用了一种不同的方法来分析测试覆盖率：它专门关注检查PR中添加的行。通过将未覆盖的新行数除以新行总数来计算覆盖率。此外，您还可以设置导致CI工具测试失败的阈值。该包还可以生成突出显示未覆盖代码的报告，使识别需要额外测试的区域变得更加容易。

Installing

有两种方式可以安装pull_request_coverage包：

• 从命令行激活它：dart pub global activate pull_request_coverage。这将允许您在命令行界面（CLI）上将其作为独立程序使用。
• 添加到项目pubspec.yaml文件的dev_dependencies部分。

Example of pubspec.yaml

dev_dependencies:
  pull_request_coverage: ^latest_version

Usage

Generating the lcov.info file

运行以下命令以生成coverage/lcov.info文件：

flutter test --coverage

如果是在Dart项目而不是Flutter项目中使用，请参考coverage package。

Running pull_request_coverage

要检查PR的代码，pull_request_coverage需要获取当前分支与目标分支之间的差异。可以通过管道操作符|将差异输入到pull_request_coverage中：

git diff repository/main | flutter pub run pull_request_coverage

如果您使用dart pub global activate激活了pull_request_coverage，可以直接调用它：

git diff repository/main | pull_request_coverage

更多输出示例请参见Example。

Settings

配置执行pull_request_coverage有两种方式：使用CLI参数或YAML配置文件。推荐对于大型团队使用YAML文件，因为可以在CI脚本中一致地共享这些设置，而不需要每个开发人员手动复制和粘贴参数。

默认情况下，pull_request_coverage会查找./pull_request_coverage.yaml文件加载其设置。您可以使用config-file参数覆盖此路径。

CLI args Example

git diff origin/main | flutter pub run pull_request_coverage --maximum-uncovered-lines 5 --ignore '/lib/di/**','**/gen.dart' --ignore-lines "^.*@override.*$"

YAML config file Example

maximum-uncovered-lines: 5
ignore:
  - /lib/di/**
  - "**/gen.dart"
ignore-lines:
  - "^.*@override.*$"

Available Options

Input

• lcov-file (coverage/lcov.info)：由flutter test --coverage命令生成的lcov.info文件路径。
• config-file (pull_request_coverage.yaml)：YAML设置文件路径。

Threshold

• minimum-coverage ：指定测试通过所需的最小覆盖率。
• maximum-uncovered-lines ：指定允许的最大未覆盖行数，超过此数值则测试失败。
• approval-requirement (lines-and-rate)：当同时指定了minimum-coverage和maximum-uncovered-lines时，确定测试通过的条件。
  • lines-and-rate：两个条件都必须满足才能通过测试。
  • lines-or-rate：只需要满足一个条件即可通过测试。

Filters

• ignore：忽略的文件列表，使用广泛熟知的Bash glob语法。
• ignore-lines：用于过滤源代码行的正则表达式列表。
• ignore-known-generated-files (true)：忽略以.g.dart, .pb.dart, .pbenum.dart, .pbserver.dart或.pbjson.dart结尾的文件路径。
• add-to-known-generated-files：扩展ignore-known-generated-files中指定的列表的glob匹配器列表。与ignore不同，这些模式匹配的行将完全排除在报告之外。

Presentation

• output-mode (cli)：指定输出格式。
  • cli：这种输出格式设计为在命令行界面（CLI）上阅读。
  • markdown：这种输出使用Markdown语法格式化，适用于由机器人发布在PR评论中显示。
• markdown-mode (diff)：指定Markdown输出格式。
  • diff：使用diff语法高亮未覆盖行。
  • dart：使用Dart语法显示代码，并在未覆盖行末尾添加注释。
• report-fully-covered-files (true)：打印每个完全覆盖文件的文件路径作为庆祝消息。
• show-uncovered-code (true)：设置为true时，将以红色字体颜色打印未覆盖行的源代码，便于识别缺失的测试；若设置为false，日志中只显示文件路径。
• use-colorful-output (true)：默认情况下，pull_request_coverage使用彩色字体高亮未覆盖行。可以设置此参数为false禁用此功能。请注意，此选项仅在输出模式设置为cli时可用。
• print-emojis (true)：启用或禁用输出中的表情符号。
• fraction-digits (2)：指定覆盖率中小数点后的位数。
• fully-tested-message：当没有未测试行时，用自定义消息替换最终表格报告。

Under the hood

• stdin-timeout (1)：pull_request_coverage从标准输入读取差异。在某些情况下，标准输入流可能永远不会关闭，导致分析卡住。默认情况下，如果在一秒钟内没有接收到数据，pull_request_coverage认为已经到达EOF。
• log-level (none)：内部日志级别。可能的值有none, error, warning, info, debug和verbose。

Exit code

• 0 - 测试通过。
• 1 - 测试失败（仅当设置了阈值时）。
• 255 - 执行失败且测试未执行。

示例demo

CLI output

flutter test --coverage
git diff origin/main | pull_request_coverage  --maximum-uncovered-lines 5 --minimum-coverage 99

Markdown output

flutter test --coverage
git diff origin/main | pull_request_coverage  --maximum-uncovered-lines 5 --minimum-coverage 99 --output-mode markdown

Markdown output using dart mode

flutter test --coverage
git diff origin/main | pull_request_coverage  --maximum-uncovered-lines 5 --minimum-coverage 99 --output-mode markdown --markdown-mode dart

以上内容提供了关于如何在Flutter项目中使用pull_request_coverage插件的详细说明。希望对您有所帮助！