Metadata-Version: 2.1
Name: colcon-lcov-result
Version: 0.2.0
Summary: Extension for colcon to gather test results.
Home-page: https://colcon.readthedocs.io
Author: Juan Pablo Samper
Author-email: jp.samper@apex.ai
Maintainer: Juan Pablo Samper
Maintainer-email: jp.samper@apex.ai
License: Apache License, Version 2.0
Project-URL: GitHub, https://github.com/colcon/colcon-lcov-result/
Project-URL: Changelog, https://github.com/colcon/colcon-lcov-result/milestones?state=closed
Keywords: colcon
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Plugins
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Build Tools
Requires-Dist: colcon-core

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:

- Statement coverage
- Function coverage
- Branch coverage

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'

   * See also `colcon-mixin <https://github.com/colcon/colcon-mixin>`_ and 
     `colcon-mixin-repository <https://github.com/colcon/colcon-mixin-repository/blob/master/coverage.mixin>`_
     for a short-hand command (``--mixin coverage-gcc``)

#. Create a baseline for zero coverage:

   .. code-block:: shell

     $ colcon lcov-result --initial

   * This step is optional, but will help reveal any files that are untouched by
     tests

#. 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
===============

* When running locally, use the ``--packages-select`` option to generate
  coverage information for relevant packages

  * This will also suppress warnings for packages that were either not built
    with coverage flags or for which tests did not run

* The ``--verbose`` flag can be used to print the coverage summary of each
  individual package as the results are analyzed


Troubleshooting
===============

* The following warning when running ``colcon lcov-result --initial`` implies
  that the package was not built with the correct flags:

  .. code-block:: shell

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

  * The package will not show up in the final results. Use ``--packages-skip`` to suppress
    the warning

* The following warning when running ``colcon lcov-result`` implies that no tests
  ran for that package

  .. code-block:: shell

     [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!
     ---

  * The package will show up in the final results with 0% coverage. Use ``--packages-skip``
    to suppress these packages from the total


Known Issues
============

#. The final step of aggregating all the result files can be slow depending
   on the number of packages that were analyzed


