UnitTesting.yml

# ==================================================================================================================== #
# Authors:                                                                                                             #
#   Patrick Lehmann                                                                                                    #
#   Unai Martinez-Corral                                                                                               #
#                                                                                                                      #
# ==================================================================================================================== #
# Copyright 2020-2026 The pyTooling Authors                                                                            #
#                                                                                                                      #
# Licensed under the Apache License, Version 2.0 (the "License");                                                      #
# you may not use this file except in compliance with the License.                                                     #
# You may obtain a copy of the License at                                                                              #
#                                                                                                                      #
#   http://www.apache.org/licenses/LICENSE-2.0                                                                         #
#                                                                                                                      #
# Unless required by applicable law or agreed to in writing, software                                                  #
# distributed under the License is distributed on an "AS IS" BASIS,                                                    #
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.                                             #
# See the License for the specific language governing permissions and                                                  #
# limitations under the License.                                                                                       #
#                                                                                                                      #
# SPDX-License-Identifier: Apache-2.0                                                                                  #
# ==================================================================================================================== #
name: Unit Testing (Matrix)

on:
  workflow_call:
    inputs:
      jobs:
        description: 'JSON list with environment fields, telling the system and Python versions to run tests with.'
        required: true
        type: string
      apt:
        description: 'Ubuntu dependencies to be installed through apt.'
        required: false
        default: ''
        type: string
      brew:
        description: 'macOS dependencies to be installed through brew.'
        required: false
        default: ''
        type: string
      pacboy:
        description: 'MSYS2 dependencies to be installed through pacboy (pacman).'
        required: false
        default: ''
        type: string
      requirements:
        description: 'Python dependencies to be installed through pip.'
        required: false
        default: '-r ./requirements.txt'
        type: string
      mingw_requirements:
        description: 'Override Python dependencies to be installed through pip on MSYS2 only.'
        required: false
        default: ''
        type: string
      macos_before_script:
        description: 'Scripts to execute before pytest on macOS (Intel).'
        required: false
        default: ''
        type: string
      macos_arm_before_script:
        description: 'Scripts to execute before pytest on macOS (ARM).'
        required: false
        default: ''
        type: string
      ubuntu_before_script:
        description: 'Scripts to execute before pytest on Ubuntu.'
        required: false
        default: ''
        type: string
      windows_before_script:
        description: 'Scripts to execute before pytest on Windows (x64-64).'
        required: false
        default: ''
        type: string
      windows_arm_before_script:
        description: 'Scripts to execute before pytest on Windows (aarch64).'
        required: false
        default: ''
        type: string
      ucrt64_before_script:
        description: 'Scripts to execute before pytest on Windows (x64-64) within MSYS2 UCRT64.'
        required: false
        default: ''
        type: string
      root_directory:
        description: 'Working directory for running tests.'
        required: false
        default: '.'
        type: string
      tests_directory:
        description: 'Path to the directory containing tests (relative from root_directory).'
        required: false
        default: 'tests'
        type: string
      unittest_directory:
        description: 'Path to the directory containing unit tests (relative from tests_directory).'
        required: false
        default: 'unit'
        type: string
      parallel:
        description: 'Number of pytest-xdist workers: ''auto'', a number, or ''false'' to run the tests serially.'
        required: false
        default: 'auto'
        type: string
      unittest_report_xml:
        description: 'JSON object describing the path where to save the unittest summary report XML.'
        required: false
        default: >-
          { "directory": "report/unit",
            "filename":  "TestReportSummary.xml",
            "fullpath":  "report/unit/TestReportSummary.xml"
          }
        type: string
      coverage_config:
        description: 'Path to the .coveragerc file. Use pyproject.toml by default.'
        required: false
        default: 'pyproject.toml'
        type: string
      coverage_report_xml:
        description: 'JSON object describing the path where the coverage report in XML format will be generated.'
        required: false
        default: >-
          { "directory": "report/coverage",
            "filename":  "coverage.xml",
            "fullpath":  "report/coverage/coverage.xml"
          }
        type: string
      coverage_report_json:
        description: 'JSON object describing the path where the coverage report in JSON format will be generated.'
        required: false
        default: >-
          { "directory": "report/coverage",
            "filename":  "coverage.json",
            "fullpath":  "report/coverage/coverage.json"
          }
        type: string
      coverage_report_html:
        description: 'JSON object describing the path where the coverage report in HTML format will be generated.'
        required: false
        default: >-
          { "directory": "report/coverage/html",
          }
#            "fullpath":  "report/coverage/html"
        type: string
      unittest_xml_artifact:
        description: "Generate unit test report with junitxml and upload results as an artifact."
        required: false
        default: ''
        type: string
      unittest_html_artifact:
        description: "Generate unit test report with html and upload results as an artifact."
        required: false
        default: ''
        type: string
      coverage_sqlite_artifact:
        description: 'Name of the SQLite coverage artifact.'
        required: false
        default: ''
        type: string
      coverage_xml_artifact:
        description: 'Name of the XML coverage artifact.'
        required: false
        default: ''
        type: string
      coverage_json_artifact:
        description: 'Name of the JSON coverage artifact.'
        required: false
        default: ''
        type: string
      coverage_html_artifact:
        description: 'Name of the HTML coverage artifact.'
        required: false
        default: ''
        type: string

jobs:
  UnitTesting:
    name: ${{ matrix.sysicon }} ${{ matrix.pyicon }} Unit Tests - Python ${{ matrix.python }}
    runs-on: ${{ matrix.runs-on }}

    strategy:
      fail-fast: false
      matrix:
        include: ${{ fromJson(inputs.jobs) }}

    defaults:
      run:
        shell: ${{ matrix.shell }}

    steps:
      - name: ⏬ Checkout repository
        uses: actions/checkout@v7
        with:
          lfs: true
          submodules: true

# Package Manager steps
      - name: 🔧 Install homebrew dependencies on macOS
        if: ( matrix.system == 'macos' || matrix.system == 'macos-arm' ) && inputs.brew != ''
        run: brew install ${{ inputs.brew }}

      - name: 🔧 Install apt dependencies on Ubuntu
        if: ( matrix.system == 'ubuntu' || matrix.system == 'ubuntu-arm' ) && inputs.apt != ''
        run: |
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends ${{ inputs.apt }}

# Compute Dependencies for MSYS2 steps

#      - name: 🔧 Install dependencies (system Python for Python shell)
#        if: matrix.system == 'msys2'
#        shell: pwsh
#        run: |
#          py -3.12 -m pip install --disable-pip-version-check --break-system-packages -U tomli

      - name: Compute path to requirements file
        id: requirements
        uses: pyTooling/Actions/.github/actions/ComputeRequirements@dev
        with:
          requirements:       ${{ inputs.requirements }}
          mingw_requirements: ${{ inputs.mingw_requirements }}
          base_directory:     ${{ inputs.root_directory || '.' }}/${{ inputs.tests_directory || '.' }}/${{ inputs.unittest_directory || '.' }}

      - name: Compute pacman/pacboy packages
        id: pacboy
        if: matrix.system == 'msys2'
        uses: pyTooling/Actions/.github/actions/ComputePacboyPackages@dev
        with:
          requirements: ${{ steps.requirements.outputs.mingw_requirements }}

# Python setup

      - name: '🟦 Setup MSYS2 for ${{ matrix.runtime }}'
        uses: msys2/setup-msys2@v2
        if: matrix.system == 'msys2'
        with:
          msystem: ${{ matrix.runtime }}
          update: true
          pacboy: >-
            ${{ steps.pacboy.outputs.pacboy_packages }}
            ${{ inputs.pacboy }}

      - name: 🐍 Setup Python ${{ matrix.python }}
        uses: actions/setup-python@v7
        if: matrix.system != 'msys2'
        with:
          python-version: ${{ matrix.python }}

# Python Dependency steps

      - name: 🔧 Install wheel and pip dependencies (native)
        if: matrix.system != 'msys2'
        run: |
          python -m pip install --disable-pip-version-check -U wheel
          python -m pip install --disable-pip-version-check ${{ steps.requirements.outputs.requirements }}

      - name: 🔧 Install pip dependencies (MSYS2)
        if: matrix.system == 'msys2'
        run: |
          python -m pip install --disable-pip-version-check --break-system-packages ${{ steps.requirements.outputs.mingw_requirements }}

# Before scripts

      - name: 🍎 macOS (Intel) before scripts
        if: matrix.system == 'macos' && inputs.macos_before_script != ''
        run: ${{ inputs.macos_before_script }}

      - name: 🍏 macOS (ARM) before scripts
        if: matrix.system == 'macos-arm' && inputs.macos_arm_before_script != ''
        run: ${{ inputs.macos_arm_before_script }}

      - name: 🐧 Ubuntu before scripts
        if: ( matrix.system == 'ubuntu' || matrix.system == 'ubuntu-arm' ) && inputs.ubuntu_before_script != ''
        run: ${{ inputs.ubuntu_before_script }}

      - name: 🪟 Windows (x86-64) before scripts
        if: matrix.system == 'windows' && inputs.windows_before_script != ''
        run: ${{ inputs.windows_before_script }}

      - name: 🏢 Windows (aarch64) before scripts
        if: matrix.system == 'windows-arm' && inputs.windows_arm_before_script != ''
        run: ${{ inputs.windows_arm_before_script }}

      - name: 🪟🟨 Windows (x86-64) + UCRT64 before scripts
        if: matrix.system == 'msys2' && matrix.runtime == 'UCRT64' && inputs.ucrt64_before_script != ''
        run: ${{ inputs.ucrt64_before_script }}

# Run pytests

      - name: ✅ Run unit tests (Ubuntu/macOS)
        id: pytest_bash
        if: ( matrix.system != 'windows' && matrix.system != 'windows-arm' )
        continue-on-error: true
        run: |
          export ENVIRONMENT_NAME="${{ matrix.envname }}"
          export PYTHONPATH=$(pwd)

          cd "${{ inputs.root_directory || '.' }}"

          if [[ "${{ inputs.parallel }}" == "false" ]]; then
            PARALLEL_JOBS=""
          elif [[ "$(python -c "from importlib.util import find_spec; print(find_spec('xdist') is None)")" == "True" ]]; then
            printf -- '::warning::%s\n' "pytest-xdist isn't installed: running the tests serially."
            PARALLEL_JOBS=""
          elif [[ -z "${{ inputs.parallel }}" ]]; then
            PARALLEL_JOBS="auto"
          elif [[ "${{ inputs.parallel }}" =~ ^(auto|[1-9][0-9]*)$ ]]; then
            PARALLEL_JOBS="${{ inputs.parallel }}"
          else
            printf -- '::error title=%s::%s\n' "parallel" "Input 'parallel' is '${{ inputs.parallel }}', but expected 'auto', a number of workers or 'false'."
            exit 1
          fi

          if [[ -n "${PARALLEL_JOBS}" && -n "${{ inputs.coverage_config }}" ]]; then
            if [[ "$(python -c "from coverage import Coverage; print('subprocess' not in getattr(Coverage(config_file='${{ inputs.coverage_config }}').config, 'patch', []))")" == "True" ]]; then
              printf -- '::warning::%s\n' "Coverage.py measures pytest-xdist workers only with 'patch = [\"subprocess\"]' in '[tool.coverage.run]': running the tests serially."
              PARALLEL_JOBS=""
            fi
          fi

          PYTEST_ARGS=""
          [[ -n "${PARALLEL_JOBS}" ]]                    && PYTEST_ARGS="${PYTEST_ARGS} -n ${PARALLEL_JOBS}"
          [[ -n '${{ inputs.unittest_xml_artifact }}' ]] && PYTEST_ARGS="${PYTEST_ARGS} --junitxml=${{ fromJson(inputs.unittest_report_xml).fullpath }}"

          if [[ -n '${{ inputs.coverage_config }}' ]]; then
            printf -- '%s\n' "coverage run --data-file=.coverage --rcfile=pyproject.toml -m pytest -raP ${PYTEST_ARGS} --color=yes ${{ inputs.tests_directory || '.' }}/${{ inputs.unittest_directory }}"
            coverage run --data-file=.coverage --rcfile=pyproject.toml -m pytest -raP ${PYTEST_ARGS} --color=yes ${{ inputs.tests_directory || '.' }}/${{ inputs.unittest_directory }}
          else
            printf -- '%s\n' "python -m pytest -raP ${PYTEST_ARGS} --color=yes ${{ inputs.tests_directory || '.' }}/${{ inputs.unittest_directory }}"
            python -m pytest -raP ${PYTEST_ARGS} --color=yes ${{ inputs.tests_directory || '.' }}/${{ inputs.unittest_directory }}
          fi

      - name: ✅ Run unit tests (Windows)
        id: pytest_posh
        if: ( matrix.system == 'windows' || matrix.system == 'windows-arm' )
        continue-on-error: true
        run: |
          $env:ENVIRONMENT_NAME = "${{ matrix.envname }}"
          $env:PYTHONPATH = (Get-Location).ToString()

          cd "${{ inputs.root_directory || '.' }}"

          if ("${{ inputs.parallel }}" -eq "false") {
            $PARALLEL_JOBS = ""
          } elseif ((python -c "from importlib.util import find_spec; print(find_spec('xdist') is None)") -eq "True") {
            Write-Host "::warning::pytest-xdist isn't installed: running the tests serially."
            $PARALLEL_JOBS = ""
          } elseif ("${{ inputs.parallel }}" -eq "") {
            $PARALLEL_JOBS = "auto"
          } elseif ("${{ inputs.parallel }}" -cmatch '^(auto|[1-9][0-9]*)$') {
            $PARALLEL_JOBS = "${{ inputs.parallel }}"
          } else {
            Write-Host "::error title=parallel::Input 'parallel' is '${{ inputs.parallel }}', but expected 'auto', a number of workers or 'false'."
            exit 1
          }

          if ($PARALLEL_JOBS -and "${{ inputs.coverage_config }}") {
            if ((python -c "from coverage import Coverage; print('subprocess' not in getattr(Coverage(config_file='${{ inputs.coverage_config }}').config, 'patch', []))") -eq "True") {
              Write-Host "::warning::Coverage.py measures pytest-xdist workers only with 'patch = [`"subprocess`"]' in '[tool.coverage.run]': running the tests serially."
              $PARALLEL_JOBS = ""
            }
          }

          $PYTEST_ARGS = @()
          if ($PARALLEL_JOBS)                        { $PYTEST_ARGS += "-n", $PARALLEL_JOBS }
          if ("${{ inputs.unittest_xml_artifact }}") { $PYTEST_ARGS += "--junitxml=${{ fromJson(inputs.unittest_report_xml).fullpath }}" }

          if ("${{ inputs.coverage_config }}") {
            Write-Host "coverage run --data-file=.coverage --rcfile=pyproject.toml -m pytest -raP $PYTEST_ARGS --color=yes ${{ inputs.tests_directory || '.' }}/${{ inputs.unittest_directory }}"
            coverage run --data-file=.coverage --rcfile=pyproject.toml -m pytest -raP $PYTEST_ARGS --color=yes ${{ inputs.tests_directory || '.' }}/${{ inputs.unittest_directory }}
          } else {
            Write-Host "python -m pytest -raP $PYTEST_ARGS --color=yes ${{ inputs.tests_directory || '.' }}/${{ inputs.unittest_directory }}"
            python -m pytest -raP $PYTEST_ARGS --color=yes ${{ inputs.tests_directory || '.' }}/${{ inputs.unittest_directory }}
          }

      - name: Combine coverage data
        id: combine
        if: inputs.coverage_config != '' && hashFiles('.coverage.*') != ''
        continue-on-error: true
        run: coverage combine --append --data-file=.coverage

      - name: Convert coverage to XML format (Cobertura)
        id: convert_xml
        if: inputs.coverage_xml_artifact != ''
        continue-on-error: true
        run: coverage xml --data-file=.coverage

      - name: Convert coverage to JSON format
        id: convert_json
        if: inputs.coverage_json_artifact != ''
        continue-on-error: true
        run: coverage json --data-file=.coverage

      - name: Convert coverage to HTML format
        id: convert_html
        if: inputs.coverage_html_artifact != ''
        continue-on-error: true
        run: |
          coverage html --data-file=.coverage -d ${{ fromJson(inputs.coverage_report_html).directory }}
          rm ${{ fromJson(inputs.coverage_report_html).directory }}/.gitignore

# Upload artifacts

      - name: 📤 Upload '${{ fromJson(inputs.unittest_report_xml).filename }}' artifact
        uses: pyTooling/upload-artifact@v7
        if: inputs.unittest_xml_artifact != ''
        continue-on-error: true
        with:
          name: ${{ inputs.unittest_xml_artifact }}-${{ matrix.system }}-${{ matrix.runtime }}-${{ matrix.python }}
          working-directory: ${{ fromJson(inputs.unittest_report_xml).directory }}
          path: ${{ fromJson(inputs.unittest_report_xml).filename }}
          if-no-files-found: error
          retention-days: 1

#      - name: 📤 Upload 'Unit Tests HTML Report' artifact
#        if: inputs.unittest_html_artifact != ''
#        continue-on-error: true
#        uses: pyTooling/upload-artifact@v7
#        with:
#          name: ${{ inputs.unittest_html_artifact }}-${{ matrix.system }}-${{ matrix.runtime }}-${{ matrix.python }}
#          path: ${{ inputs.unittest_report_html_directory }}
#          if-no-files-found: error
#          retention-days: 1

      - name: 📤 Upload 'Coverage SQLite Database' artifact
        if: inputs.coverage_sqlite_artifact != ''
        continue-on-error: true
        uses: pyTooling/upload-artifact@v7
        with:
          name: ${{ inputs.coverage_sqlite_artifact }}-${{ matrix.system }}-${{ matrix.runtime }}-${{ matrix.python }}
          path: .coverage
          include-hidden-files: true
          if-no-files-found: error
          retention-days: 1

      - name: 📤 Upload 'Coverage XML Report' artifact
        if: inputs.coverage_xml_artifact != '' && steps.convert_xml.outcome == 'success'
        continue-on-error: true
        uses: pyTooling/upload-artifact@v7
        with:
          name: ${{ inputs.coverage_xml_artifact }}-${{ matrix.system }}-${{ matrix.runtime }}-${{ matrix.python }}
          working-directory: ${{ fromJson(inputs.coverage_report_xml).directory }}
          path: ${{ fromJson(inputs.coverage_report_xml).filename }}
          if-no-files-found: error
          retention-days: 1

      - name: 📤 Upload 'Coverage JSON Report' artifact
        if: inputs.coverage_json_artifact != '' && steps.convert_json.outcome == 'success'
        continue-on-error: true
        uses: pyTooling/upload-artifact@v7
        with:
          name: ${{ inputs.coverage_json_artifact }}-${{ matrix.system }}-${{ matrix.runtime }}-${{ matrix.python }}
          working-directory: ${{ fromJson(inputs.coverage_report_json).directory }}
          path: ${{ fromJson(inputs.coverage_report_json).filename }}
          if-no-files-found: error
          retention-days: 1

      - name: 📤 Upload 'Coverage HTML Report' artifact
        if: inputs.coverage_html_artifact != '' && steps.convert_html.outcome == 'success'
        continue-on-error: true
        uses: pyTooling/upload-artifact@v7
        with:
          name: ${{ inputs.coverage_html_artifact }}-${{ matrix.system }}-${{ matrix.runtime }}-${{ matrix.python }}
          working-directory: ${{ fromJson(inputs.coverage_report_html).directory }}
          path: '*'
          if-no-files-found: error
          retention-days: 1

      - name: Generate error messages
        shell: bash
        run: |
          exitCode=0
          if [[ "${{ steps.pytest_bash.outcome }}" == "failure" || "${{ steps.pytest_posh.outcome }}" == "failure" ]]; then
            printf -- '❌ pytest: %s\n' "Error in pytest execution."
            printf -- '::error title=%s::%s\n' "pytest" "Error in pytest execution."
            exitCode=1
          else
            printf -- '✅ pytest: No errors.\n'
          fi

          exit ${exitCode}