.. _gcovr-summary:

Gcovr Summary Template
======================

The ``gcovr-summary.yml`` template provides a standardized workflow for
aggregating coverage reports from multiple test jobs (:ref:`meson-test`) into a
single summary report in GitLab CI. It merges coverage data across
architectures, generates visualizations, and produces HTML and Cobertura
reports for CI dashboards.

It is particularly useful for applications and libraries which contain large
amounts of architecture-specific code.

Overview
--------

This template enables you to:

- Collect coverage reports from multiple test jobs and merge them into a
  unified summary.
- Generate Cobertura XML and HTML coverage reports for visualization.
- Integrate with GitLab's coverage reporting (total coverage figure and
  detailed coverage change in merge requests).

Usage in CI
-----------

This template is included in CI pipelines as the final stage to define a
summary job that runs after all relevant test jobs have completed. The job will
automatically discover coverage JSON files, merge them, and publish summary
artifacts. See :ref:`gcovr-summary-examples` for example usage.

.. note::

    The summary stage doesn't need to depend on all test jobs, only the ones
    that actively contribute to the coverage figure.

    Also, at the moment, coverage is collected only for GNU toolchain builds,
    so there is no need to include dependence on LLVM test jobs.

Inputs
------

The template accepts the following inputs:

Gcovr
^^^^^

- ``gcovr_flags``: Additional flags passed to the Gcovr tool. Default: ``""``.

CI Job
^^^^^^

- ``extends``: Array of jobs to extend this job template. Must include an OCI
  image template (see :ref:`top-level-reqs`) and can include target activation
  rule based on target activation pattern.

  .. note::

    The ``gcovr-summary`` job uses ``linux-native-amd64`` target, so in case
    you use the default activation pattern, remember to have it always active,
    otherwise the summary won't run.

  Default: ``[.ci-multiplatform-base]``.
- ``job_name_prefix``: Prefix for the job name. Useful for disabling or
  customizing jobs. Default: ``""``.
- ``job_name_suffix``: Suffix for the job name. Default: ``""``.
- ``needs``: Optional needs array allowing to execute this job as soon as all
  relevant stages (i.e., the ones which produce coverage report and actively
  contribute to the increase of coverage) are completed.

  When specifying dependencies for jobs using parallel matrices, ensure the
  following:

  - Mark dependent jobs as optional if you use activation rules based on targets.
  - Select only ``TOOLCHAIN=gnu`` from the parallel matrix to include relevant
    coverage jobs.
  - When referencing jobs with parallel matrix variables, list all variables in
    the exact order as declared in the test stage. Refer to the `GitLab CI
    documentation <https://docs.gitlab.com/ci/yaml/#needsparallelmatrix>`_ for
    details.

  Example:

  .. code-block:: yaml

      - job: test:linux-native-amd64
        optional: true
        parallel:
          matrix: [TOOLCHAIN: [gnu]]
      - job: test:linux-native-arm64-v8
        optional: true
        parallel:
          matrix: [TOOLCHAIN: [gnu]]
      - job: test:linux-native-riscv64
        optional: true
        parallel:
          matrix: [TOOLCHAIN: [gnu]]

  Default: ``[test:linux-native-amd64]``.
- ``stage``: CI stage name for the job. Default: ``summary``.
- ``runner_tag``: GitLab runner tag for this job. Default: ``""``.

Job Structure
-------------

Each job created by the template:

- Discovers and collects coverage JSON files from previous test jobs.
- Merges coverage data using ``gcovr`` and generates Cobertura XML and HTML
  reports.
- Publishes coverage reports and input files as CI artifacts for visualization
  and further processing.

Artifacts
---------

The summary job produces the following artifacts:

- All input coverage JSON files from ``coverage/``
- Cobertura XML report: ``coverage/summary/coverage.xml`` (used for GitLab
  coverage visualization)
- HTML coverage report: ``coverage/summary/coverage.html``

In order to generate coverage reports you need to enable them in the build
stage (:ref:`meson-build`) for GNU toolchain jobs by leaving
``enable_gnu_coverage`` enabled and executing the test stage
(:ref:`meson-test`). All of this requires an OCI image with all required tools
built in :ref:`oci-images` or by using the :ref:`oci-pre-built`.

.. _gcovr-summary-examples:

Examples
--------

Below is an example job definition using the template syntax:

.. code-block:: yaml

  spec:
    inputs:
      ci_path:
        description: Path to the gcovr-summary component with branch name.
        type: string
        default: gitlab.com/riseproject/ci/ci-multiplatform/gcovr-summary@main
      runner_tag_amd64:
        description: Regular x86 runner.
        type: string
        default: "saas-linux-medium-amd64"
  ---

  include:
    - component: $[[ inputs.ci_path ]]
      inputs:
        runner_tag: $[[ inputs.runner_tag_amd64 ]]
        needs:
          - job: test:linux-native-amd64
            optional: true
            parallel:
              matrix: [TOOLCHAIN: [gnu]]
          - job: test:linux-native-arm64-v8
            optional: true
            parallel:
              matrix: [TOOLCHAIN: [gnu]]
          - job: test:linux-native-riscv64
            optional: true
            parallel:
              matrix: [TOOLCHAIN: [gnu]]

For a full example, see :ref:`examples-meson`.

Another example is in the Pixman project in
:pixman_url:`.gitlab-ci.d/04-summary.yml
<-/blob/ci-external/.gitlab-ci.d/04-summary.yml>` file.