From 8d21ca154d7691132de05204eac6cf63a6ef021f Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Sun, 30 Oct 2022 11:03:52 +0100 Subject: [PATCH] Documented Coverage Collection. --- .github/workflows/CoverageCollection.yml | 2 +- doc/JobTemplate/CoverageCollection.rst | 143 ++++++++++++++++++++--- doc/JobTemplate/PublishOnPyPI.rst | 26 ++++- 3 files changed, 153 insertions(+), 18 deletions(-) diff --git a/.github/workflows/CoverageCollection.yml b/.github/workflows/CoverageCollection.yml index 4a4462a..b5f6a97 100644 --- a/.github/workflows/CoverageCollection.yml +++ b/.github/workflows/CoverageCollection.yml @@ -28,7 +28,7 @@ on: python_version: description: 'Python version.' required: false - default: '3.10' + default: '3.11' type: string requirements: description: 'Python dependencies to be installed through pip.' diff --git a/doc/JobTemplate/CoverageCollection.rst b/doc/JobTemplate/CoverageCollection.rst index 8b505c9..da4ce14 100644 --- a/doc/JobTemplate/CoverageCollection.rst +++ b/doc/JobTemplate/CoverageCollection.rst @@ -1,11 +1,35 @@ CoverageCollection ################## -collect code coverage data (incl. branch coverage) - with `pytest`/`pytest-cov`/`coverage.py` using a single version of Python (latest). It generates HTML and Cobertura - (XML)reports, upload the HTML report as an artifact, and upload the test results to Codecov and Codacy. Configuration - options to `pytest` and `coverage.py` should be given via section `[tool.pytest.ini_options]` and `[tool.coverage.*]` - in a `pyproject.toml` file. +This jobs runs the specified unit tests with activated code coverage collection (incl. branch coverage). + +It uses pytest, pytest-cov and coverage.py in a single job run, thus it uses one fixed Python version (usually latest). +It generates HTML and Cobertura reports (XML), then it uploads the HTML report as an artifact and the jUnit test results +(XML) to `Codecov `__ and `Codacy `__. + +Configuration options to ``pytest`` and ``coverage.py`` should be given via sections ``[tool.pytest.ini_options]`` and +``[tool.coverage.*]`` in a ``pyproject.toml`` file. + +**Behavior:** + +1. Checkout repository +2. Setup Python and install dependencies +3. Extract configuration from ``pyproject.toml`` or ``.coveragerc``. +4. Run unit tests and collect code coverage +5. Convert coverage data to a Cobertura XML file +6. Convert coverage data to a HTML report +7. Publish Cobertura file to CodeCov +8. Publish Cobertura file to Codacy + +**Preconditions:** + +* A CodeCov account was created. +* A Codacy account was created. + +**Requirements:** + +Setup a secret (e.g. ``codacy_token``) in GitHub to handover the Codacy project token to the job. + Instantiation ************* @@ -15,29 +39,118 @@ Simple Example .. code-block:: yaml - TBD + jobs: + Coverage: + uses: pyTooling/Actions/.github/workflows/CoverageCollection.yml@r0 + with: + artifact: Coverage + secrets: + codacy_token: ${{ secrets.CODACY_PROJECT_TOKEN }} Complex Example =============== - - .. code-block:: yaml - TBD + jobs: + Coverage: + uses: pyTooling/Actions/.github/workflows/CoverageCollection.yml@r0 + needs: + - Params + with: + python_version: ${{ fromJson(needs.Params.outputs.params).python_version }} + artifact: ${{ fromJson(needs.Params.outputs.params).artifacts.Coverage }} + secrets: + codacy_token: ${{ secrets.CODACY_PROJECT_TOKEN }} Template Parameters ******************* -TBD 1 -===== +python_version +============== -TBD +Python version used for running unit tests. -TBD 1 -===== ++----------+----------+----------+ +| Required | Type | Default | ++==========+==========+==========+ +| optional | string | 3.11 | ++----------+----------+----------+ + + +requirements +============ + +Python dependencies to be installed through pip. + ++----------+----------+-------------------------------+ +| Required | Type | Default | ++==========+==========+===============================+ +| optional | string | ``-r tests/requirements.txt`` | ++----------+----------+-------------------------------+ + + +tests_directory +=============== + +Path to the directory containing tests (test working directory). + ++----------+----------+-----------+ +| Required | Type | Default | ++==========+==========+===========+ +| optional | string | ``tests`` | ++----------+----------+-----------+ + + +unittest_directory +================== + +Path to the directory containing unit tests (relative to test_directory). + ++----------+----------+-----------+ +| Required | Type | Default | ++==========+==========+===========+ +| optional | string | ``unit`` | ++----------+----------+-----------+ + + +coverage_config +=============== + +Path to the ``.coveragerc`` file. Use ``pyproject.toml`` by default. + ++----------+----------+--------------------+ +| Required | Type | Default | ++==========+==========+====================+ +| optional | string | ``pyproject.toml`` | ++----------+----------+--------------------+ + + +artifact +======== + +Name of the coverage artifact. + ++----------+----------+--------------+ +| Required | Type | Default | ++==========+==========+==============+ +| yes | string | — — — — | ++----------+----------+--------------+ + +Secrets +******* + +codacy_token +============ + +Token to push result to codacy. + ++----------+----------+--------------+ +| Required | Type | Default | ++==========+==========+==============+ +| yes | string | — — — — | ++----------+----------+--------------+ -TBD Template Results **************** diff --git a/doc/JobTemplate/PublishOnPyPI.rst b/doc/JobTemplate/PublishOnPyPI.rst index 137a750..f271960 100644 --- a/doc/JobTemplate/PublishOnPyPI.rst +++ b/doc/JobTemplate/PublishOnPyPI.rst @@ -77,20 +77,36 @@ python_version Python version used for uploading the package contents via `twine` to PyPI. -**Default:** 3.11 ++----------+----------+----------+ +| Required | Type | Default | ++==========+==========+==========+ +| optional | string | 3.11 | ++----------+----------+----------+ + requirements ============ List of requirements to be installed for uploading the package contents to PyPI. -**Default:** wheel, twine ++----------+----------+--------------+ +| Required | Type | Default | ++==========+==========+==============+ +| optional | string | wheel, twine | ++----------+----------+--------------+ + artifact ======== Name of the artifact containing the package(s). ++----------+----------+--------------+ +| Required | Type | Default | ++==========+==========+==============+ +| yes | string | — — — — | ++----------+----------+--------------+ + Secrets ******* @@ -99,6 +115,12 @@ PYPI_TOKEN The token to access the package at PyPI for uploading new data. ++----------+----------+--------------+ +| Required | Type | Default | ++==========+==========+==============+ +| yes | string | — — — — | ++----------+----------+--------------+ + Results *******