.. include:: ../../../shared/integrations/plugins/plugins.rst

Visualize Code Coverage in CodeScene
------------------------------------

**Motivation**: Code coverage is a set of metrics that shows how much of your source code that gets executed by automated tests.
There is no such thing as a "good" coverage score -- it all depends on context. For example, in a critical hotspot, you need a
higher degree of coverage to refactor safely, whereas you can get away with a lower coverage in stable and well-understood
parts of the codebase. CodeScene provides those priorities to put coverage metrics into context.

Select your Code Coverage Metrics
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

There are multiple code coverage metrics, and the most popular are:

* Line coverage: which lines of code have been covered by automated tests?
* Branch coverage: which execution paths have been covered by automated tests? For example, a line of code like
  `if a && b` can have full line coverage, but only partial branch coverage.

.. figure:: code-coverage-interactive-map.png
   :alt: CodeScene visualizes code coverage in its interactive views. The more green, the higher the coverage of that module.
   :name: code-coverage-interactive-map

   CodeScene visualizes code coverage in its interactive views. The more green, the higher the coverage of that module.

Clicking on a specific module reveals the detailed metric (e.g. `Line coverage: 85%`).

The typical use cases are:

* **Mitigate risk**: identify feature areas with low coverage before planning refactoring tasks. For example, refactoring a
  complex hotspot that doesn't have adequate test coverage would be high risk.

.. figure:: no-code-coverage-in-views.png
   :alt: Visualize areas of the code that lack test coverage.
   :name: no-code-coverage-in-views

   Visualize areas of the code that lack test coverage (see the controller package in the image).

* **Detect deeper issues**: CodeScene lets you customize your own views. For example, you can identify hotspots that
  a) have low code coverage, b) have low code health, and c) have many defects. That way, you can communicate
  the needs for pro-active improvements.

.. figure:: code-coverage-customized-view.png
   :alt: Customize the interactive views to combine different aspects that highlights the perspective that's important to you.
   :name: code-coverage-customized-view

   Customize the interactive views to combine different aspects that highlights the perspective that's important to you.

Configure the Code Coverage Plugin
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You configure the code coverage plugin as part of your CodeScene project configuration, tab "Plugins."

CodeScene's code coverage plugin supports multiple coverage tools: OpenClover, Cobertura, JaCoCo, LCov, BullsEye, DotCover, OpenCover and NCover.

The plugin reads the metrics from the result files generated by these tools as part of a build pipeline:

.. figure:: code-coverage-process.png
   :alt: The coverage results are generated as part of a build pipeline and shared with CodeScene.
   :name: code-coverage-process

   The coverage results are generated as part of a build pipeline and shared with CodeScene.

CodeScene needs a way of accessing the result files, meaning you need to add a step to your build where the code coverage results are exported to a
file folder readable by your CodeScene instance. Specify that path inside your project configuration. The path specification is a glob pattern
*relative* to a global folder for code coverage metrics. Note that the global folder is an admin-level setting specified in the
top level Configuration tab of CodeScene:

.. figure:: code-coverage-global-config.png
   :alt: The root folder of all code coverage results is a global setting that applies across all CodeScene projects.
   :name: code-coverage-global-config

   The root folder of all code coverage results is a global setting that applies across all CodeScene projects.

From there, you select the test coverage metrics that you want to visualize. The available metrics depends on what the selected
code coverage tool supports:

.. figure:: configure-code-coverage-metrics.png
   :alt: Configure the code coverage metrics that you want to visualize and track inside CodeScene.
   :name: configure-code-coverage-metrics

   Configure the code coverage metrics that you want to visualize and track inside CodeScene.

You can add multiple coverage metrics, and each one of them will show up as a perspective on the interactive hotspot map.

Code Coverage: Limitations
~~~~~~~~~~~~~~~~~~~~~~~~~~

CodeScene supports analysis projects with multiple repositories. Since code coverage results don't contain any info
on repositories, CodeScene needs to match the directory structure of the coverage results to the corresponding Git repo.

This works well for programming languages that enforce unique paths (e.g. Java) but can lead to ambiguity in the rare
case where the exact same file path exists in multiple Git repositories.

