From 4a9ba5ad6f4fbaa8bb2fb026ca318c8eda0de7c0 Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Sun, 30 Oct 2022 20:28:22 +0100 Subject: [PATCH] Documented UnitTesting. --- doc/JobTemplate/Parameters.rst | 45 +++++----- doc/JobTemplate/PublishOnPyPI.rst | 28 +++--- doc/JobTemplate/UnitTesting.rst | 144 ++++++++++++++++++++++++++---- 3 files changed, 163 insertions(+), 54 deletions(-) diff --git a/doc/JobTemplate/Parameters.rst b/doc/JobTemplate/Parameters.rst index 26e27f6..e2a714c 100644 --- a/doc/JobTemplate/Parameters.rst +++ b/doc/JobTemplate/Parameters.rst @@ -38,28 +38,27 @@ systems (Windows, Ubuntu, MacOS, MinGW64) and the given list of Python versions addition a list of excludes (marked as :deletion:`deletions`) and includes (marked as :addition:`additions`) is handed over resulting in the following combinations: -+---------+-------------+-------------+-------------+--------------+-------------------------+---------+----------+------------------------------+------------------------------+ -| Version | 3.7 | 3.8 | 3.9 | 3.10 | 3.11 | 3.12.a1 | mypy-3.7 | mypy-3.8 | mypy-3.9 | -+=========+=============+=============+=============+==============+=========================+=========+==========+==============================+==============================+ -| Windows | windows:3.7 | windows:3.8 | windows:3.9 | windows:3.10 | | | | :deletion:`windows:mypy-3.8` | :deletion:`windows:mypy-3.9` | -+---------+-------------+-------------+-------------+--------------+-------------------------+---------+----------+------------------------------+------------------------------+ -| Ubuntu | ubuntu:3.7 | ubuntu:3.8 | ubuntu:3.9 | ubuntu:3.10 | :addition:`ubuntu:3.11` | | | ubuntu:mypy-3.8 | ubuntu:mypy-3.9 | -+---------+-------------+-------------+-------------+--------------+-------------------------+---------+----------+------------------------------+------------------------------+ -| MacOS | macos:3.7 | macos:3.8 | macos:3.9 | macos:3.10 | :addition:`macos:3.11` | | | macos:mypy-3.8 | macos:mypy-3.9 | -+---------+-------------+-------------+-------------+--------------+-------------------------+---------+----------+------------------------------+------------------------------+ -| MSYS | | | | | | | | | | -+---------+-------------+-------------+-------------+--------------+-------------------------+---------+----------+------------------------------+------------------------------+ -| MinGW32 | | | | | | | | | | -+---------+-------------+-------------+-------------+--------------+-------------------------+---------+----------+------------------------------+------------------------------+ -| MinGW64 | | | | mingw64:3.10 | | | | | | -+---------+-------------+-------------+-------------+--------------+-------------------------+---------+----------+------------------------------+------------------------------+ -| Clang32 | | | | | | | | | | -+---------+-------------+-------------+-------------+--------------+-------------------------+---------+----------+------------------------------+------------------------------+ -| Clang64 | | | | | | | | | | -+---------+-------------+-------------+-------------+--------------+-------------------------+---------+----------+------------------------------+------------------------------+ -| UCRT64 | | | | | | | | | | -+---------+-------------+-------------+-------------+--------------+-------------------------+---------+----------+------------------------------+------------------------------+ - ++------------+-------------+-------------+-------------+--------------+-------------------------+------------+-------------+------------------------------+------------------------------+ +| Version | 3.7 🔴 | 3.8 🟠 | 3.9 🟡 | 3.10 🟢 | 3.11 🟢 | 3.12.a1 🟣 | mypy-3.7 🔴 | mypy-3.8 🟠 | mypy-3.9 🟡 | ++============+=============+=============+=============+==============+=========================+============+=============+==============================+==============================+ +| Windows 🧊 | windows:3.7 | windows:3.8 | windows:3.9 | windows:3.10 | | | | :deletion:`windows:mypy-3.8` | :deletion:`windows:mypy-3.9` | ++------------+-------------+-------------+-------------+--------------+-------------------------+------------+-------------+------------------------------+------------------------------+ +| Ubuntu 🐧 | ubuntu:3.7 | ubuntu:3.8 | ubuntu:3.9 | ubuntu:3.10 | :addition:`ubuntu:3.11` | | | ubuntu:mypy-3.8 | ubuntu:mypy-3.9 | ++------------+-------------+-------------+-------------+--------------+-------------------------+------------+-------------+------------------------------+------------------------------+ +| MacOS 🍎 | macos:3.7 | macos:3.8 | macos:3.9 | macos:3.10 | :addition:`macos:3.11` | | | macos:mypy-3.8 | macos:mypy-3.9 | ++------------+-------------+-------------+-------------+--------------+-------------------------+------------+-------------+------------------------------+------------------------------+ +| MSYS 🟪 | | | | | | | | | | ++------------+-------------+-------------+-------------+--------------+-------------------------+------------+-------------+------------------------------+------------------------------+ +| MinGW32 ⬛ | | | | | | | | | | ++------------+-------------+-------------+-------------+--------------+-------------------------+------------+-------------+------------------------------+------------------------------+ +| MinGW64 🟦 | | | | mingw64:3.10 | | | | | | ++------------+-------------+-------------+-------------+--------------+-------------------------+------------+-------------+------------------------------+------------------------------+ +| Clang32 🟫 | | | | | | | | | | ++------------+-------------+-------------+-------------+--------------+-------------------------+------------+-------------+------------------------------+------------------------------+ +| Clang64 🟧 | | | | | | | | | | ++------------+-------------+-------------+-------------+--------------+-------------------------+------------+-------------+------------------------------+------------------------------+ +| UCRT64 🟨 | | | | | | | | | | ++------------+-------------+-------------+-------------+--------------+-------------------------+------------+-------------+------------------------------+------------------------------+ .. code-block:: yaml @@ -127,7 +126,7 @@ Space separated list of Python versions to run tests with. Possible values: -* ``3.7``, ``3.8``, ..., ``3.11``, ``3.12`` +* ``3.6`` (outdated), ``3.7``, ..., ``3.11``, ``3.12`` * ``mypy-3.7``, ``mypy-3.8``, ``mypy-3.9`` For ``3.12``, Python 3.12 alpha will be used. diff --git a/doc/JobTemplate/PublishOnPyPI.rst b/doc/JobTemplate/PublishOnPyPI.rst index f271960..00d0ee5 100644 --- a/doc/JobTemplate/PublishOnPyPI.rst +++ b/doc/JobTemplate/PublishOnPyPI.rst @@ -18,6 +18,13 @@ A PyPI account was created and the package name is either not occupied or the us Setup a secret (e.g. ``PYPI_TOKEN``) in GitHub to handover the PyPI token to the job. +**Dependencies:** + +* actions/download-artifact +* actions/setup-python +* geekyeggo/delete-artifact + + Instantiation ************* @@ -80,7 +87,7 @@ Python version used for uploading the package contents via `twine` to PyPI. +----------+----------+----------+ | Required | Type | Default | +==========+==========+==========+ -| optional | string | 3.11 | +| optional | string | ``3.11`` | +----------+----------+----------+ @@ -89,11 +96,11 @@ requirements List of requirements to be installed for uploading the package contents to PyPI. -+----------+----------+--------------+ -| Required | Type | Default | -+==========+==========+==============+ -| optional | string | wheel, twine | -+----------+----------+--------------+ ++----------+----------+-----------------+ +| Required | Type | Default | ++==========+==========+=================+ +| optional | string | ``wheel twine`` | ++----------+----------+-----------------+ artifact @@ -124,11 +131,4 @@ The token to access the package at PyPI for uploading new data. Results ******* -*None* - -Dependencies -************ - -* actions/download-artifact -* actions/setup-python -* geekyeggo/delete-artifact +This job template has no output parameters. diff --git a/doc/JobTemplate/UnitTesting.rst b/doc/JobTemplate/UnitTesting.rst index 7255f9c..50dc15b 100644 --- a/doc/JobTemplate/UnitTesting.rst +++ b/doc/JobTemplate/UnitTesting.rst @@ -1,9 +1,24 @@ UnitTesting ########### -run unit test with `pytest` using multiple versions of Python, and - optionally upload results as XML reports. Configuration options to `pytest` should be given via section - `[tool.pytest.ini_options]` in a `pyproject.toml` file. +This template runs multiple jobs from a matrix as a cross of Python versions and systems. The summary report in junit +XML format is optionally uploaded as an artifact. + +Configuration options to ``pytest`` should be given via section ``[tool.pytest.ini_options]`` in a ``pyproject.toml`` +file. + +**Behavior:** + +1. Checkout repository +2. Setup Python and install dependencies +3. Run unit tests using ``pytest``. +4. Upload junit test summary as an artifact + +**Dependencies:** + +* actions/checkout@v2 +* actions/setup-python@v2 +* actions/upload-artifact@v2 Instantiation ************* @@ -13,31 +28,126 @@ Simple Example .. code-block:: yaml - TBD + jobs: + Params: + # ... + + UnitTesting: + uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@r0 + needs: + - Params + with: + jobs: ${{ needs.Params.outputs.python_jobs }} + artifact: ${{ fromJson(needs.Params.outputs.params).artifacts.Unittesting }} + Complex Example =============== - - .. code-block:: yaml TBD -Template Parameters -******************* +Parameters +********** -TBD 1 -===== +jobs +==== -TBD +JSON list with environment fields, telling the system and Python versions to run tests with. -TBD 1 -===== ++----------+----------+--------------+ +| Required | Type | Default | ++==========+==========+==============+ +| yes | string | — — — — | ++----------+----------+--------------+ -TBD +requirements +============ -Template Results -**************** +Python dependencies to be installed through pip. -*None* ++----------+----------+----------+ +| Required | Type | Default | ++==========+==========+==========+ +| optional | string | ``-r tests/requirements.txt`` | ++----------+----------+----------+ + + +pacboy +====== + +MSYS2 dependencies to be installed through pacboy (pacman). + ++----------+----------+-----------------------------------------------------------------+ +| Required | Type | Default | ++==========+==========+=================================================================+ +| optional | string | ``python-pip:p python-wheel:p python-coverage:p python-lxml:p`` | ++----------+----------+-----------------------------------------------------------------+ + +.. code-block:: yaml + + pacboy: >- + python-pip:p + python-wheel:p + python-coverage:p + python-lxml:p + + +mingw_requirements +================== + +Override Python dependencies to be installed through pip on MSYS2 (MINGW64) only. + ++----------+----------+----------+ +| Required | Type | Default | ++==========+==========+==========+ +| optional | string | ``""`` | ++----------+----------+----------+ + + +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 tests_directory). + ++----------+----------+----------+ +| Required | Type | Default | ++==========+==========+==========+ +| optional | string | ``unit`` | ++----------+----------+----------+ + + +artifact +======== + +Generate unit test report with junitxml and upload results as an artifact. + ++----------+----------+----------+ +| Required | Type | Default | ++==========+==========+==========+ +| optional | string | ``""`` | ++----------+----------+----------+ + + +Secrets +******* + +This job template needs no secrets. + +Results +******* + +This job template has no output parameters.