Actions/doc/JobTemplate/Publish/PublishTestResults.rst

.. _JOBTMPL/PublishTestResults:
.. index::
   single: CodeCov; PublishTestResults Template
   single: pyEDAA.Reports; PublishTestResults Template
   single: Test Reporter; PublishTestResults Template
   single: GitHub Action Reusable Workflow; PublishTestResults Template

PublishTestResults
##################

This job downloads all matching JUnit report artifacts, merged the reports into one single report and then publishes the
JUnit test summary reports to multiple services for visualization and longterm statistical tracking.

Supported services are:

* GitHub Actions job results using :term:`Test Reporter`
* :term:`Codecov`

.. topic:: Features

   * Merge multiple JUnit XML reports generated by pytest into a single JUnit XML report.
   * Publish unit test results to currently running pipeline as job result.
   * Publish unit test results to CodeCov.

.. topic:: Behavior

   1. Checkout repository
   2. Download multiple artifacts containing test report summaries in JUnit XML format conforming to an artifact name
      pattern (see :ref:`JOBTMPL/PublishTestResults/Input/unittest_artifacts_pattern`) for limiting the number of
      downloaded artifacts and the hereby generated traffic.
   3. Rename the found JUnit XML files.
   4. Merge all found JUnit XML files using :term:`pyEDAA.Reports` into a new JUnit XML file. |br|
      Optionally, apply certain transformation and cleanup operations to the JUnit report structure.
   5. Publish test results as a markdown report page to GitHub Actions using :term:`Test Reporter`.
   6. Publish test results to :term:`Codecov` using :gh:`codecov/test-results-action`.

.. topic:: Job Execution

   .. grid:: 2

      .. grid-item::
         :columns: 4

         .. rubric:: Job Steps

         .. image:: ../../_static/pyTooling-Actions-PublishTestResults.png
            :width: 500px

      .. grid-item::
         :columns: 4

         .. rubric:: Generated Dorny Report below Pipeline Graph

         .. image:: ../../_static/pyTooling-Actions-PublishTestResults-Dorny.png
            :width: 500px

.. topic:: Dependencies

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

     * :gh:`actions/download-artifact`

   * pip

     * :pypi:`pyEDAA.Reports`

   * :gh:`dorny/test-reporter`
   * :gh:`codecov/test-results-action`
   * :gh:`pyTooling/upload-artifact`

     * :gh:`actions/upload-artifact`



.. _JOBTMPL/PublishTestResults/Instantiation:

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

Simple Example
==============

.. code-block:: yaml

   jobs:
     PublishTestResults:
       uses: pyTooling/Actions/.github/workflows/PublishTestResults.yml@r6

Complex Example
===============

.. code-block:: yaml

   jobs:
     CodeCoverage:
       # ...

     UnitTesting:
       # ...

     PublishTestResults:
       uses: pyTooling/Actions/.github/workflows/PublishTestResults.yml@r6
       needs:
         - CodeCoverage
         - UnitTesting


.. _JOBTMPL/PublishTestResults/Parameters:

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

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

+---------------------------------------------------------------------+----------+----------+---------------------------------------------------------------------+
| Parameter Name                                                      | Required | Type     | Default                                                             |
+=====================================================================+==========+==========+=====================================================================+
| :ref:`JOBTMPL/PublishTestResults/Input/ubuntu_image_version`        | no       | string   | ``'24.04'``                                                         |
+---------------------------------------------------------------------+----------+----------+---------------------------------------------------------------------+
| :ref:`JOBTMPL/PublishTestResults/Input/unittest_artifacts_pattern`  | no       | string   | ``'*-UnitTestReportSummary-XML-*'``                                 |
+---------------------------------------------------------------------+----------+----------+---------------------------------------------------------------------+
| :ref:`JOBTMPL/PublishTestResults/Input/merged_junit_filename`       | no       | string   | ``'Unittesting.xml'``                                               |
+---------------------------------------------------------------------+----------+----------+---------------------------------------------------------------------+
| :ref:`JOBTMPL/PublishTestResults/Input/merged_junit_artifact`       | no       | string   | ``''``                                                              |
+---------------------------------------------------------------------+----------+----------+---------------------------------------------------------------------+
| :ref:`JOBTMPL/PublishTestResults/Input/merge-input-dialect`         | no       | string   | ``'pyTest-JUnit'``                                                  |
+---------------------------------------------------------------------+----------+----------+---------------------------------------------------------------------+
| :ref:`JOBTMPL/PublishTestResults/Input/merge-output-dialect`        | no       | string   | ``'pyTest-JUnit'``                                                  |
+---------------------------------------------------------------------+----------+----------+---------------------------------------------------------------------+
| :ref:`JOBTMPL/PublishTestResults/Input/additional_merge_args`       | no       | string   | ``'"--pytest=rewrite-dunder-init;reduce-depth:pytest.tests.unit"'`` |
+---------------------------------------------------------------------+----------+----------+---------------------------------------------------------------------+
| :ref:`JOBTMPL/PublishTestResults/Input/testsuite-summary-name`      | no       | string   | ``''``                                                              |
+---------------------------------------------------------------------+----------+----------+---------------------------------------------------------------------+
| :ref:`JOBTMPL/PublishTestResults/Input/publish`                     | no       | string   | ``'true'``                                                          |
+---------------------------------------------------------------------+----------+----------+---------------------------------------------------------------------+
| :ref:`JOBTMPL/PublishTestResults/Input/report_title`                | no       | string   | ``'Unit Test Results'``                                             |
+---------------------------------------------------------------------+----------+----------+---------------------------------------------------------------------+
| :ref:`JOBTMPL/PublishTestResults/Input/dorny`                       | no       | string   | ``'true'``                                                          |
+---------------------------------------------------------------------+----------+----------+---------------------------------------------------------------------+
| :ref:`JOBTMPL/PublishTestResults/Input/codecov`                     | no       | string   | ``'false'``                                                         |
+---------------------------------------------------------------------+----------+----------+---------------------------------------------------------------------+
| :ref:`JOBTMPL/PublishTestResults/Input/codecov_flags`               | no       | string   | ``'unittest'``                                                      |
+---------------------------------------------------------------------+----------+----------+---------------------------------------------------------------------+

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

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

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

This job template has no output parameters.


.. _JOBTMPL/PublishTestResults/Inputs:

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

.. _JOBTMPL/PublishTestResults/Input/ubuntu_image_version:

.. include:: ../_ubuntu_image_version.rst


.. _JOBTMPL/PublishTestResults/Input/unittest_artifacts_pattern:

unittest_artifacts_pattern
==========================

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


.. _JOBTMPL/PublishTestResults/Input/merged_junit_filename:

merged_junit_filename
=====================

:Type:            string
:Required:        no
:Default Value:   ``'Unittesting.xml'``
:Possible Values: Any valid filename suitable for a JUnit XML report.
:Description:     The filename for the merged JUnit report in XML format. |br|
                  See :ref:`JOBTMPL/PublishTestResults/Input/merge-output-dialect` for the used JUnit dialect in the
                  merged report file.


.. _JOBTMPL/PublishTestResults/Input/merged_junit_artifact:

merged_junit_artifact
=====================

:Type:            string
:Required:        no
:Default Value:   ``''``
:Possible Values: Any valid artifact name.
:Description:


.. _JOBTMPL/PublishTestResults/Input/merge-input-dialect:

merge-input-dialect
===================

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


.. _JOBTMPL/PublishTestResults/Input/merge-output-dialect:

merge-output-dialect
====================

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


.. _JOBTMPL/PublishTestResults/Input/additional_merge_args:

additional_merge_args
=====================

:Type:            string
:Required:        no
:Default Value:   ``'"--pytest=rewrite-dunder-init;reduce-depth:pytest.tests.unit"'``
:Possible Values: tbd
:Description:     tbd


.. _JOBTMPL/PublishTestResults/Input/testsuite-summary-name:

testsuite-summary-name
======================

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


.. _JOBTMPL/PublishTestResults/Input/publish:

publish
=======

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


.. _JOBTMPL/PublishTestResults/Input/report_title:

report_title
============

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


.. _JOBTMPL/PublishTestResults/Input/dorny:

dorny
=====

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


.. _JOBTMPL/PublishTestResults/Input/codecov:

codecov
=======

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


.. _JOBTMPL/PublishTestResults/Input/codecov_flags:

codecov_flags
=============

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


.. _JOBTMPL/PublishTestResults/Secrets:

Secrets
*******

.. _JOBTMPL/PublishTestResults/Secret/CODECOV_TOKEN:

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

:Type:            string
:Required:        no
:Default Value:   — — — —
:Description:     The token to publish unit test results on  :term:`CodeCov`.


.. _JOBTMPL/PublishTestResults/Outputs:

Outputs
*******

This job template has no output parameters.


.. _JOBTMPL/PublishTestResults/Optimizations:

Optimizations
*************

This template offers no optimizations (reduced job runtime).