colcon / colcon-lcov-result

A colcon extension for collecting lcov output
http://colcon.readthedocs.io
Apache License 2.0
7 stars 5 forks source link
colcon

colcon-lcov-result

An extension for colcon-core <https://github.com/colcon/colcon-core> to provide aggregate coverage results using LCOV <http://ltp.sourceforge.net/coverage/lcov.php>.

LCOV is a graphical front-end for GCC's coverage testing tool gcov <https://gcc.gnu.org/onlinedocs/gcc/Gcov.html>_, producing the following coverage metrics:

For more information, see this paper <http://ltp.sourceforge.net/documentation/technical_papers/gcov-ols2003.pdf>_ and this Wikipedia page <https://en.wikipedia.org/wiki/Code_coverage>_.

Usage

. Build your packages with coverage flags, using colcon:

.. code-block:: shell

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

. Create a baseline for zero coverage:

.. code-block:: shell

 $ colcon lcov-result --initial

. Run tests:

.. code-block:: shell

 $ colcon test

. Gather the lcov results:

.. code-block:: shell

 $ 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)

. Browse the coverage report by opening lcov/index.html in a browser

. Zero the coverage counters and re-run tests:

.. code-block:: shell

 $ 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)

Tips and Tricks

Contributing

For non-trivial contributions, it is recommended to first create an issue to discuss your ideas.

The following is the recommended workflow for contributing:

. Install colcon and extensions in a virtual environment:

.. code-block:: shell

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

. Install colcon-lcov-result in editable mode:

.. code-block:: shell

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

. As long as you are in the virtual environment, make changes to colcon-lcov-result

run colcon lcov-result, and see the effect of the changes

. Commit changes and submit a PR:

.. _The seven rules of a great Git commit message: https://chris.beams.io/posts/git-commit/#seven-rules

Troubleshooting

Known Issues

. The final step of aggregating all the result files can be slow depending

on the number of packages that were analyzed

Developing

See DEVELOPING.md <DEVELOPING.md>_.