pyTooling/Actions
1
0
Fork 0
mirror of https://github.com/pyTooling/Actions.git synced 2026-02-12 02:56:56 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
57f88b158f56f68f3457aed3ee4e02733080324f
Actions/doc/JobTemplate/Publish/PublishCoverageResults.rst
Patrick Lehmann 57f88b158f Fine tuning documentation pages.
2025-09-10 07:49:11 +02:00

404 lines
16 KiB
ReStructuredText
Raw Blame History

.. _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.
Reference in New Issue View Git Blame Copy Permalink