test.yml

---
# SPDX-FileCopyrightText: Jürgen Mülbert
#
# SPDX-License-Identifier: EUPL-1.2
#

# This workflow will install Python dependencies, run tests and lint with a single version of Python
# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python

name: "test"

on: # yamllint disable-line rule:truthy
  push:
    branches: [main, develop, release]
  pull_request:
    types: [opened, reopened]

permissions:
  contents: read

defaults:
  run:
    shell: bash

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
  cancel-in-progress: true

env:
  STABLE_PYTHON_VERSION: "3.11"
  PYTHONUNBUFFERED: "1"
  FORCE_COLOR: "1"

jobs:
  test-docs:
    name: "Test Docs"
    runs-on: ubuntu-latest
    steps:
      # Checkout the repository to the GitHub Actions runner
      - name: "🧰 Checkout Source Code"
        uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6

      - name: "⚙️️ Set up Python"
        uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d # v5.1.0
        with:
          # Read python version from a file .python-version
          python-version-file: ".standard-python-version"
          check-latest: true
          cache: pip

      - name: "Ensure latest pip"
        run: python -m pip install --upgrade pip

      - name: "Install Hatch"
        run: pip install --upgrade hatch

      - name: "Build Docs"
        run: hatch run docs:build

      - name: "Docs build-check"
        run: hatch run docs:build-check

      - name: "Docs links check"
        run: hatch run docs:validate-links

  test-python:
    name: "Python ${{ matrix.python-version }} on ${{ startsWith(matrix.os, 'macos-') && 'macOS' || startsWith(matrix.os, 'windows-') && 'Windows' || 'Linux' }}"
    runs-on: ${{ matrix.os }}
    needs: test-docs
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
        environment: [staging, production]
        exclude:
          - os: ubuntu-latest
            python-version: "3.12"
    steps:
      # Checkout the repository to the GitHub Actions runner
      - name: "🧰 Checkout Source Code"
        uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6

      - name: "Set up Python ${{ matrix.python-version }}"
        uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d # v5.1.0
        with:
          python-version: ${{ matrix.python-version }}
          cache: pip

      - name: "Ensure latest pip"
        run: python -m pip install --upgrade pip

      - name: "Install Hatch"
        run: pip install --upgrade hatch

      - name: "Run static analysis"
        run: hatch fmt --check

      - name: "Check types"
        run: hatch run types:check

      - name: "Run tests"
        run: hatch test --python ${{ matrix.python-version }} --cover-quiet --randomize --parallel --retries 5 --retry-delay 3

      - name: "Disambiguate coverage filename"
        run: mv .coverage ".coverage.${{ matrix.os }}.${{ matrix.python-version }}"

      - name: "Upload coverage data"
        uses: actions/upload-artifact@65462800fd760344b1a7b4382951275a0abb4808 # v4.3.3
        with:
          name: coverage-${{ matrix.os }}-${{ matrix.python-version }}
          path: .coverage*

  coverage:
    name: "Report coverage"
    runs-on: ubuntu-latest
    needs:
      - test-python

    steps:
      # Checkout the repository to the GitHub Actions runner
      - name: "🧰 Checkout Source Code"
        uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6

      - name: "Set up Python"
        uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d # v5.1.0
        with:
          # Read python version from a file .python-version
          python-version-file: ".standard-python-version"

      - name: "Get full Python version"
        id: full-python-version
        run: |
          echo version="$(python -c "import sys; print('-'.join(str(v) for v in sys.version_info))")" >> "$GITHUB_OUTPUT"

      - name: "Install Hatch"
        run: pip install hatch

      - name: "Trigger build for auto-generated files"
        run: hatch build --hooks-only

      - name: "Download coverage data"
        uses: actions/download-artifact@65a9edc5881444af0b9093a5e628f2fe47ea3b2e # v4.1.7
        with:
          pattern: coverage-*
          merge-multiple: true

      - name: "Combine coverage data"
        run: hatch run coverage:combine

      - name: "Export coverage reports"
        run: |
          hatch run coverage:report-xml
          hatch run coverage:report-uncovered-html

      - name: "Upload uncovered HTML report"
        uses: actions/upload-artifact@65462800fd760344b1a7b4382951275a0abb4808 # v4.3.3
        with:
          name: uncovered-html-report
          path: htmlcov

      - name: "Generate coverage summary"
        run: hatch run coverage:generate-summary

      - name: "Write coverage summary report"
        if: github.event_name == 'pull_request'
        run: hatch run coverage:write-summary-report

      - name: "Update coverage pull request comment"
        if: github.event_name == 'pull_request' && !github.event.pull_request.head.repo.fork
        uses: marocchino/sticky-pull-request-comment@331f8f5b4215f0445d3c07b4967662a32a2d3e31 # v2.9.0
        with:
          path: coverage-report.md

  # https://github.com/marketplace/actions/alls-green#why
  check: # This job does nothing and is only used for the branch protection
    if: always()

    needs:
      - coverage

    runs-on: ubuntu-latest

    steps:
      - name: "Decide whether the needed jobs succeeded or failed"
        uses: re-actors/alls-green@223e4bb7a751b91f43eda76992bcfbf23b8b0302 # v1.2.2
        with:
          jobs: ${{ toJSON(needs) }}