colcon-lcov-result 0.5.2

colcon-lcov-result

为colcon-core提供使用LCOV汇总覆盖率结果的扩展。

LCOV是GCC的覆盖率测试工具gcov的图形前端，生成以下覆盖率指标

• 语句覆盖率

• 函数覆盖率

• 分支覆盖率

有关更多信息，请参阅此论文和此维基百科页面。

用法

1. 使用 colcon 带覆盖率标志构建你的包

   $ colcon build \
         --symlink-install \
         --cmake-args \
             -DCMAKE_CXX_FLAGS='-fprofile-arcs -ftest-coverage' \
             -DCMAKE_C_FLAGS='-fprofile-arcs -ftest-coverage'

   • 参阅 colcon-mixin 和 colcon-mixin-repository 以使用快捷命令（--mixin coverage-gcc）

2. 为零覆盖率创建基线

   $ colcon lcov-result --initial

   • 此步骤是可选的，但将有助于揭示测试未触及的任何文件

3. 运行测试

   $ colcon test

4. 收集 lcov 结果

   $ colcon lcov-result
   Reading tracefile /home/user/workspace/my_cool_ws/lcov/total_coverage.info
   Summary coverage rate:
     lines......: 78.6% (44 of 56 lines)
     functions..: 94.4% (34 of 36 functions)
     branches...: 37.0% (34 of 92 branches)

5. 在浏览器中打开 lcov/index.html 以浏览覆盖率报告

6. 重置覆盖率计数器并重新运行测试

   $ colcon lcov-result --zero-counters
   $ colcon lcov-result --initial
   $ colcon test
   $ colcon lcov-result
   Reading tracefile /home/user/workspace/my_cool_ws/lcov/total_coverage.info
   Summary coverage rate:
     lines......: 78.6% (44 of 56 lines)
     functions..: 94.4% (34 of 36 functions)
     branches...: 37.0% (34 of 92 branches)

技巧和窍门

• 当本地运行时，使用 --packages-select 选项为相关包生成覆盖率信息

  • 这还将抑制未使用覆盖率标志构建或测试未运行的包的警告

• 可以使用 --verbose 标志在分析结果时打印每个单独包的覆盖率摘要

贡献

对于非平凡的贡献，建议首先创建一个问题来讨论你的想法。

以下为贡献的推荐工作流程

1. 在虚拟环境中安装 colcon 和扩展

   $ cd <workspace>
   $ python3 -m venv colcon-env
   $ source colcon-env/bin/activate
   $ pip3 install colcon-common-extensions

2. 以可编辑模式安装 colcon-lcov-result

   $ cd <workspace>
   $ python3 -m venv colcon-env
   $ source colcon-env/bin/activate
   $ cd path/to/colcon-lcov-result
   $ pip3 install -e .

3. 只要你在虚拟环境中，就对 colcon-lcov-result 进行更改，运行 colcon lcov-result，并查看更改的效果

4. 提交更改并提交 PR

   • 参阅 优秀的 Git 提交消息的七条规则

故障排除

• 运行 colcon lcov-result --initial 时出现的以下警告表示该包未使用正确的标志构建

  --- stderr: my_pkg
  geninfo: WARNING: no .gcno files found in /home/user/workspace/build/my_pkg - skipping!
  ---

  • 该包将不会出现在最终结果中。使用 --packages-skip 来抑制警告

• 运行 colcon lcov-result 时出现的以下警告表示该包没有运行测试

  [0.576s] ERROR:colcon.colcon_lcov_result.task.lcov:lcov:
  ERROR: no valid records found in tracefile /home/user/workspace/build/my_pkg/coverage.info
  --- stderr: my_pkg
  geninfo: WARNING: no .gcda files found in /home/user/workspace/build/my_pkg - skipping!
  ---

  • 该包将以 0% 覆盖率出现在最终结果中。使用 --packages-skip 来抑制这些包

已知问题

1. 聚合所有结果文件的最终步骤可能会很慢，具体取决于分析的包的数量