.. _JOBTMPL/PublishCoverageResults:

PublishCoverageResults
######################

The ``PublishCoverageResults`` job template downloads artifacts provided by :ref:`JOBTMPL/UnitTesting` containing code
coverage databases created by `Coverage.py <https://coverage.readthedocs.io/>`__. These databases are then merged and
converted into various output formats like Cobertura XML, JSON or HTML. These outputs are either uploaded as a new
artifact or can be published to cloud services like `CodeCov <https://about.codecov.io//>`__ or
`Codacy <https://www.codacy.com/>`__.

.. topic:: Features

   * Merge SQLite code coverage databases generated by Coverage.py into a single
     SQLite database.
   * Convert SQLite database to Cobertura XML format.
   * Convert SQLite database to Coverage.py JSON format.
   * Convert SQLite database to HTML code coverage report.
   * Publish code coverage at CodeCov.
   * Publish code coverage as Codacy.

.. topic:: Behavior

   1. Checkout repository.
   2. Download artifact matching the :ref:`JOBTMPL/PublishCoverageResults/Input/coverage_artifacts_pattern`.
   3. Install Python dependencies especially :pypi:`coverage`.
   4. Rename SQLite database files within artifact download directory to match the required filename pattern for
      Coverage.py's merge operation.
   5. Report code coverage as table into job log.
   6. Convert code coverage to Cobertura XML format.
   7. Convert code coverage to JSON format.
   8. Convert code coverage to HTML report (website).
   9. Upload merged SQLite database as artifact.
   10. Upload Cobertura XML file as artifact.
   11. Upload JSON file as artifact.
   12. Upload HTML report as artifact.
   13. Publish Cobertura report to CodeCov.
   14. Publish Cobertura report to Codacy.

.. topic:: Job Execution

   .. image:: ../../_static/pyTooling-Actions-PublishCoverageResults.png
      :width: 600px

.. topic:: Dependencies

   * :gh:`actions/checkout`
   * :gh:`pyTooling/download-artifact`

     * :gh:`actions/download-artifact`

   * pip

     * :pypi:`coverage`
     * :pypi:`tomli`

   * :gh:`pyTooling/upload-artifact`

     * :gh:`actions/upload-artifact`

   * :gh:`codecov/codecov-action`
   * :gh:`codacy/codacy-coverage-reporter-action`


.. _JOBTMPL/PublishCoverageResults/Instantiation:

Instantiation
*************

The following

.. code-block:: yaml

   name: Pipeline

   on:
     push:
     workflow_dispatch:

   jobs:
     ConfigParams:
       uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5
       with:
         package_name: myPackage

     UnitTestingParams:
       uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5
       with:
         package_name: myPackage

     UnitTesting:
       uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@r5
       needs:
         - ConfigParams
         - UnitTestingParams
       with:
         jobs:                     ${{ needs.UnitTestingParams.outputs.python_jobs }}
         coverage_sqlite_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).codecoverage_sqlite }}

     PublishCoverageResults:
       uses: pyTooling/Actions/.github/workflows/PublishCoverageResults.yml@r5
       needs:
         - ConfigParams
         - UnitTestingParams
         - UnitTesting
       with:
         coverage_json_artifact:         ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).codecoverage_json }}
         coverage_report_json_directory: ${{ needs.ConfigParams.outputs.coverage_report_json_directory }}
         coverage_report_json_filename:  ${{ needs.ConfigParams.outputs.coverage_report_json_filename }}
         coverage_html_artifact:         ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).codecoverage_html }}
         coverage_report_html_directory: ${{ needs.ConfigParams.outputs.coverage_report_html_directory }}
         codecov:                        'true'
         codacy:                         'true'
       secrets:
         CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
         CODACY_TOKEN:  ${{ secrets.CODACY_TOKEN }}


.. _JOBTMPL/PublishCoverageResults/Parameters:

Parameter Summary
*****************

.. rubric:: Goto :ref:`input parameters <JOBTMPL/PublishCoverageResults/Inputs>`

+-----------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| Parameter Name                                                              | Required | Type     | Default                                                           |
+=============================================================================+==========+==========+===================================================================+
| :ref:`JOBTMPL/PublishCoverageResults/Input/ubuntu_image_version`            | no       | string   | ``'24.04'``                                                       |
+-----------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PublishCoverageResults/Input/coverage_artifacts_pattern`      | no       | string   | ``'*-CodeCoverage-SQLite-*'``                                     |
+-----------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PublishCoverageResults/Input/coverage_config`                 | no       | string   | ``'pyproject.toml'``                                              |
+-----------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PublishCoverageResults/Input/coverage_sqlite_artifact`        | no       | string   | ``''``                                                            |
+-----------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PublishCoverageResults/Input/coverage_xml_artifact`           | no       | string   | ``''``                                                            |
+-----------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PublishCoverageResults/Input/coverage_report_xml_directory`   | no       | string   | ``'report/coverage'``                                             |
+-----------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PublishCoverageResults/Input/coverage_report_xml_filename`    | no       | string   | ``'coverage.xml'``                                                |
+-----------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PublishCoverageResults/Input/coverage_json_artifact`          | no       | string   | ``''``                                                            |
+-----------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PublishCoverageResults/Input/coverage_report_json_directory`  | no       | string   | ``'report/coverage'``                                             |
+-----------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PublishCoverageResults/Input/coverage_report_json_filename`   | no       | string   | ``'coverage.json'``                                               |
+-----------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PublishCoverageResults/Input/coverage_html_artifact`          | no       | string   | ``''``                                                            |
+-----------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PublishCoverageResults/Input/coverage_report_html_directory`  | no       | string   | ``'report/coverage/html'``                                        |
+-----------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PublishCoverageResults/Input/codecov`                         | no       | string   | ``'false'``                                                       |
+-----------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PublishCoverageResults/Input/codacy`                          | no       | string   | ``'false'``                                                       |
+-----------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+


.. rubric:: Goto :ref:`secrets <JOBTMPL/PublishCoverageResults/Secrets>`

+-----------------------------------------------------------+----------+----------+--------------+
| Token Name                                                | Required | Type     | Default      |
+===========================================================+==========+==========+==============+
| :ref:`JOBTMPL/PublishCoverageResults/Secret/CODECOV_TOKEN`| no       | string   | — — — —      |
+-----------------------------------------------------------+----------+----------+--------------+
| :ref:`JOBTMPL/PublishCoverageResults/Secret/CODACY_TOKEN` | no       | string   | — — — —      |
+-----------------------------------------------------------+----------+----------+--------------+

.. rubric:: Goto :ref:`output parameters <JOBTMPL/PublishCoverageResults/Outputs>`

This job template has no output parameters.


.. _JOBTMPL/PublishCoverageResults/Inputs:

Input Parameters
****************

.. _JOBTMPL/PublishCoverageResults/Input/ubuntu_image_version:

.. include:: ../_ubuntu_image_version.rst


.. _JOBTMPL/PublishCoverageResults/Input/coverage_artifacts_pattern:

coverage_artifacts_pattern
==========================

:Type:            string
:Required:        no
:Default Value:   ``'*-CodeCoverage-SQLite-*'``
:Possible Values: Any valid artifact matching pattern using fixed text and ``*`` characters.
:Description:     tbd


.. _JOBTMPL/PublishCoverageResults/Input/coverage_config:

coverage_config
===============

:Type:            string
:Required:        no
:Default Value:   ``'pyproject.toml'``
:Possible Values: Any valid path to a :file:`pyproject.toml` file. |br|
                  Alternatively, path to a :file:`.coveragerc` file (deprecated).
:Description:     Path to a Python project configuration file for extraction of project settings.
:Example:
                  .. grid:: 2

                     .. grid-item::
                        :columns: 5

                        .. rubric:: Extracted values from :file:`pyproject.toml`

                        .. code-block:: toml

                           [tool.pytest]
                           junit_xml = "report/unit/UnittestReportSummary.xml"

                           [tool.pyedaa-reports]
                           junit_xml = "report/unit/unittest.xml"

                           [tool.coverage.xml]
                           output = "report/coverage/coverage.xml"

                           [tool.coverage.json]
                           output = "report/coverage/coverage.json"

                           [tool.coverage.html]
                           directory = "report/coverage/html"
                           title="Code Coverage of pyDummy"


.. _JOBTMPL/PublishCoverageResults/Input/coverage_sqlite_artifact:

coverage_sqlite_artifact
========================

:Type:            string
:Required:        no
:Default Value:   ``''``
:Possible Values: Any valid artifact name.
:Description:     Name of the artifact containing the merged SQLite code coverage database.


.. _JOBTMPL/PublishCoverageResults/Input/coverage_xml_artifact:

coverage_xml_artifact
=====================

:Type:            string
:Required:        no
:Default Value:   ``''``
:Possible Values: Any valid artifact name.
:Description:     Name of the artifact containing the merged code coverage report as Cobertura XML file.


.. _JOBTMPL/PublishCoverageResults/Input/coverage_report_xml_directory:

coverage_report_xml_directory
=============================

:Type:            string
:Required:        no
:Default Value:   ``'report/coverage'``
:Possible Values: tbd
:Description:     tbd


.. _JOBTMPL/PublishCoverageResults/Input/coverage_report_xml_filename:

coverage_report_xml_filename
============================

:Type:            string
:Required:        no
:Default Value:   ``'coverage.xml'``
:Possible Values: tbd
:Description:     tbd


.. _JOBTMPL/PublishCoverageResults/Input/coverage_json_artifact:

coverage_json_artifact
======================

:Type:            string
:Required:        no
:Default Value:   ``''``
:Possible Values: Any valid artifact name.
:Description:     Name of the artifact containing the merged code coverage report as Coverage.py JSON file.


.. _JOBTMPL/PublishCoverageResults/Input/coverage_report_json_directory:

coverage_report_json_directory
==============================

:Type:            string
:Required:        no
:Default Value:   ``'report/coverage'``
:Possible Values: tbd
:Description:     tbd


.. _JOBTMPL/PublishCoverageResults/Input/coverage_report_json_filename:

coverage_report_json_filename
=============================

:Type:            string
:Required:        no
:Default Value:   ``'coverage.json'``
:Possible Values: tbd
:Description:     tbd


.. _JOBTMPL/PublishCoverageResults/Input/coverage_html_artifact:

coverage_html_artifact
======================

:Type:            string
:Required:        no
:Default Value:   ``'report/coverage/html'``
:Possible Values: Any valid artifact name.
:Description:     Name of the artifact containing the merged code coverage report as HTML report.


.. _JOBTMPL/PublishCoverageResults/Input/coverage_report_html_directory:

coverage_report_html_directory
==============================

:Type:            string
:Required:        no
:Default Value:   ``''``
:Possible Values: tbd
:Description:     tbd


.. _JOBTMPL/PublishCoverageResults/Input/codecov:

codecov
=======

:Type:            string
:Required:        no
:Default Value:   ``'false'``
:Possible Values: ``'true'``, ``'false'``
:Description:     If *true*, publish code coverage results to CodeCov.


.. _JOBTMPL/PublishCoverageResults/Input/codacy:

codacy
======

:Type:            string
:Required:        no
:Default Value:   ``'false'``
:Possible Values: ``'true'``, ``'false'``
:Description:     If *true*, publish code coverage results to Codacy.




.. _JOBTMPL/PublishCoverageResults/Secrets:

Secrets
*******

The workflow template uses the following secrets to publish results to other services.

.. _JOBTMPL/PublishCoverageResults/Secret/CODECOV_TOKEN:

CODECOV_TOKEN
=============

:Type:            string
:Required:        no
:Default Value:   — — — —
:Description:     The token to publish code coverage and unit test results to `CodeCov <https://about.codecov.io//>`__.


.. _JOBTMPL/PublishCoverageResults/Secret/CODACY_TOKEN:

CODACY_TOKEN
============

:Type:            string
:Required:        no
:Default Value:   — — — —
:Description:     The token to publish code coverage results to `Codacy <https://www.codacy.com/>`__.



.. _JOBTMPL/PublishCoverageResults/Outputs:

Outputs
*******

This job template has no output parameters.