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
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:
* See `The seven rules of a great Git commit message`_
.. _The seven rules of a great Git commit message: https://chris.beams.io/posts/git-commit/#seven-rules
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
Developing
==========
See `DEVELOPING.md <DEVELOPING.md>`_.
Raw data
{
"_id": null,
"home_page": "https://colcon.readthedocs.io",
"name": "colcon-lcov-result",
"maintainer": "Christophe Bedard",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "bedard.christophe@gmail.com",
"keywords": "colcon",
"author": "Juan Pablo Samper",
"author_email": "jp.samper@apex.ai",
"download_url": "https://files.pythonhosted.org/packages/31/92/da94528d5c90e376744e14320eb2460b3c6356757ca7e00b64758d0074f4/colcon_lcov_result-0.5.3.tar.gz",
"platform": null,
"description": "colcon-lcov-result\n==================\n\nAn extension for `colcon-core <https://github.com/colcon/colcon-core>`_ to provide aggregate\ncoverage results using `LCOV <http://ltp.sourceforge.net/coverage/lcov.php>`_.\n\nLCOV is a graphical front-end for GCC's coverage testing tool\n`gcov <https://gcc.gnu.org/onlinedocs/gcc/Gcov.html>`_, producing the following\ncoverage metrics:\n\n- Statement coverage\n- Function coverage\n- Branch coverage\n\nFor more information, see `this paper\n<http://ltp.sourceforge.net/documentation/technical_papers/gcov-ols2003.pdf>`_\nand `this Wikipedia page <https://en.wikipedia.org/wiki/Code_coverage>`_.\n\n\nUsage\n=====\n#. Build your packages with coverage flags, using ``colcon``:\n\n .. code-block:: shell\n\n $ colcon build \\\n --symlink-install \\\n --cmake-args \\\n -DCMAKE_CXX_FLAGS='-fprofile-arcs -ftest-coverage' \\\n -DCMAKE_C_FLAGS='-fprofile-arcs -ftest-coverage'\n\n * See also `colcon-mixin <https://github.com/colcon/colcon-mixin>`_ and \n `colcon-mixin-repository <https://github.com/colcon/colcon-mixin-repository/blob/master/coverage.mixin>`_\n for a short-hand command (``--mixin coverage-gcc``)\n \n#. Create a baseline for zero coverage:\n\n .. code-block:: shell\n\n $ colcon lcov-result --initial\n \n * This step is optional, but will help reveal any files that are untouched by\n tests\n\n#. Run tests:\n\n .. code-block:: shell\n\n $ colcon test\n\n#. Gather the ``lcov`` results:\n\n .. code-block:: shell\n\n $ colcon lcov-result\n Reading tracefile /home/user/workspace/my_cool_ws/lcov/total_coverage.info\n Summary coverage rate:\n lines......: 78.6% (44 of 56 lines)\n functions..: 94.4% (34 of 36 functions)\n branches...: 37.0% (34 of 92 branches)\n\n#. Browse the coverage report by opening ``lcov/index.html`` in a browser\n\n#. Zero the coverage counters and re-run tests:\n\n .. code-block:: shell\n\n $ colcon lcov-result --zero-counters\n $ colcon lcov-result --initial\n $ colcon test\n $ colcon lcov-result\n Reading tracefile /home/user/workspace/my_cool_ws/lcov/total_coverage.info\n Summary coverage rate:\n lines......: 78.6% (44 of 56 lines)\n functions..: 94.4% (34 of 36 functions)\n branches...: 37.0% (34 of 92 branches)\n\n\nTips and Tricks\n===============\n\n* When running locally, use the ``--packages-select`` option to generate\n coverage information for relevant packages\n \n * This will also suppress warnings for packages that were either not built\n with coverage flags or for which tests did not run\n\n* The ``--verbose`` flag can be used to print the coverage summary of each\n individual package as the results are analyzed\n\n\nContributing\n============\n\nFor non-trivial contributions, it is recommended to first create an issue to discuss\nyour ideas.\n\nThe following is the recommended workflow for contributing:\n\n#. Install ``colcon`` and extensions in a virtual environment:\n\n .. code-block:: shell\n\n $ cd <workspace>\n $ python3 -m venv colcon-env\n $ source colcon-env/bin/activate\n $ pip3 install colcon-common-extensions\n\n#. Install ``colcon-lcov-result`` in editable mode:\n\n .. code-block:: shell\n\n $ cd <workspace>\n $ python3 -m venv colcon-env\n $ source colcon-env/bin/activate\n $ cd path/to/colcon-lcov-result\n $ pip3 install -e .\n\n#. As long as you are in the virtual environment, make changes to ``colcon-lcov-result``\n run ``colcon lcov-result``, and see the effect of the changes\n\n#. Commit changes and submit a PR:\n\n * See `The seven rules of a great Git commit message`_\n\n.. _The seven rules of a great Git commit message: https://chris.beams.io/posts/git-commit/#seven-rules\n\n\nTroubleshooting\n===============\n\n* The following warning when running ``colcon lcov-result --initial`` implies\n that the package was not built with the correct flags:\n\n .. code-block:: shell\n \n --- stderr: my_pkg \n geninfo: WARNING: no .gcno files found in /home/user/workspace/build/my_pkg - skipping!\n ---\n\n * The package will not show up in the final results. Use ``--packages-skip`` to suppress\n the warning\n\n* The following warning when running ``colcon lcov-result`` implies that no tests\n ran for that package\n \n .. code-block:: shell\n\n [0.576s] ERROR:colcon.colcon_lcov_result.task.lcov:lcov:\n ERROR: no valid records found in tracefile /home/user/workspace/build/my_pkg/coverage.info\n --- stderr: my_pkg\n geninfo: WARNING: no .gcda files found in /home/user/workspace/build/my_pkg - skipping!\n ---\n\n * The package will show up in the final results with 0% coverage. Use ``--packages-skip``\n to suppress these packages from the total\n\n\nKnown Issues\n============\n\n#. The final step of aggregating all the result files can be slow depending\n on the number of packages that were analyzed\n\nDeveloping\n==========\n\nSee `DEVELOPING.md <DEVELOPING.md>`_.\n",
"bugtrack_url": null,
"license": "Apache License, Version 2.0",
"summary": "Extension for colcon to gather test results.",
"version": "0.5.3",
"project_urls": {
"Changelog": "https://github.com/colcon/colcon-lcov-result/milestones?state=closed",
"GitHub": "https://github.com/colcon/colcon-lcov-result/",
"Homepage": "https://colcon.readthedocs.io"
},
"split_keywords": [
"colcon"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5958329ca3d1591a21d570ce5926def9a7be4124b5648168ab50f6ec88339054",
"md5": "33d4bf62a117a9a8424df617d9cdb7e0",
"sha256": "de643660ddf356fbbeae0eabefb6a9c70f30979ddb1759e638f2660581a34fb8"
},
"downloads": -1,
"filename": "colcon_lcov_result-0.5.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "33d4bf62a117a9a8424df617d9cdb7e0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 14367,
"upload_time": "2024-11-05T22:55:13",
"upload_time_iso_8601": "2024-11-05T22:55:13.988157Z",
"url": "https://files.pythonhosted.org/packages/59/58/329ca3d1591a21d570ce5926def9a7be4124b5648168ab50f6ec88339054/colcon_lcov_result-0.5.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3192da94528d5c90e376744e14320eb2460b3c6356757ca7e00b64758d0074f4",
"md5": "90b5d6f35ade0bb5e4729db165f5ee85",
"sha256": "4cbf83bbf0e1e82b22e95ce2d76b667fdaaca2cda6ecf77bd46a03dfc98c047d"
},
"downloads": -1,
"filename": "colcon_lcov_result-0.5.3.tar.gz",
"has_sig": false,
"md5_digest": "90b5d6f35ade0bb5e4729db165f5ee85",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 15603,
"upload_time": "2024-11-05T22:55:15",
"upload_time_iso_8601": "2024-11-05T22:55:15.086310Z",
"url": "https://files.pythonhosted.org/packages/31/92/da94528d5c90e376744e14320eb2460b3c6356757ca7e00b64758d0074f4/colcon_lcov_result-0.5.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-05 22:55:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "colcon",
"github_project": "colcon-lcov-result",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "colcon-lcov-result"
}
JSON
