tests.yaml

---
name: Tests
"on":
  push:
    branches:
      - main
  pull_request:
  schedule:
    # Run tests every Monday at 9:17 to catch regressions.
    - cron: "17 9 * * 1"

# XXX Concurrency detection sucks and jobs gets killed randonmly.
# concurrency:
#   # Group workflow jobs so new commits cancels in-progress execution triggered by previous commits.
#   # Source: https://mail.python.org/archives/list/pypa-committers@python.org/thread/PCBCQMJF64JGRBOX7E2EE4YLKHT4DI55/
#   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
#   cancel-in-progress: true

jobs:

  test-matrix:
    # There is no way to selective flags collections of elements in a matrix, without having to flag all combinations.
    # This will became unmaintainable and tedious so we use this job to pre-compute which jobs is going to get our
    # "stable" flag.
    name: "OS/Python/stable matrix pre-compute"
    runs-on: ubuntu-24.04
    outputs:
      test_matrix: ${{ steps.create_matrix.outputs.matrix }}
    steps:
      - name: Create JSON matrix
        id: create_matrix
        shell: python
        run: |
          import json
          import os
          from itertools import product
          from pathlib import Path

          variants: dict[str, set[str]] = {
              "os": {
                  # Available OSes: https://github.com/actions/runner-images#available-images
                  "ubuntu-24.04",
                  "ubuntu-22.04",
                  "macos-15",  # arm64
                  "macos-13",  # x86
                  "windows-2022",
                  "windows-2019",
              },
              "python-version": {
                  "3.10",
                  "3.11",
                  "3.12",
                  "3.13",
                  "3.14-dev",
              },
              "click-version": {
                  "released",
                  "stable",
                  "main",
              },
              "cloup-version": {
                  "released",
                  "master",
              }
          }
          # TODO: List of additional variants to include in the matrix.
          include: list[dict[str, str]] = []

          # List of variants to exclude from the matrix.
          exclude: list[dict[str, str]] = []

          # List of unstable criterions.
          unstable: list[dict[str, str]] = []

          # Removes from the matrix some combinations for development versions of Click and Cloup. This reduce the size
          # of the matrix for tests on non-released versions. While keeping the full exhaustive tests on the released
          # versions of Click and Cloup.
          for dev_version in (
              {"click-version": "stable"},
              {"click-version": "main"},
              {"cloup-version": "master"},
          ):
              for criterion in (
                  # Exclude old OSes. Only keeps the latest OSes of each family.
                  {"os": "ubuntu-22.04"},
                  {"os": "macos-13"},
                  {"os": "windows-2019"},
                  # Exclude Python's dev version.
                  {"python-version": "3.14-dev"},
                  # Exclude old Python version. Only test on latest stable release.
                  {"python-version": "3.10"},
                  {"python-version": "3.11"},
                  {"python-version": "3.12"},
              ):
                  exclude.append({**dev_version, **criterion})

          # Build the job matrix.
          jobs: list[dict[str, str]] = []
          for variants in product(*[{(key, value) for value in values} for key, values in variants.items()]):
              job = dict(variants)

              # Match the job against the exclude criterions.
              exclude_job = False
              for criterion in exclude:
                  if set(criterion.items()).issubset(job.items()):
                      exclude_job = True
                      break
              if exclude_job:
                  continue

              # Match the job against the unstable criterions.
              job["state"] = "stable"
              for criterion in unstable:
                  if set(criterion.items()).issubset(job.items()):
                      job["state"] = "unstable"
                      break

              jobs.append(job)

          matrix = json.dumps({"include": jobs})

          env_file = Path(os.getenv("GITHUB_OUTPUT"))
          env_file.write_text(f"matrix={matrix}")

      - name: Print JSON matrix
        run: |
          echo '${{ steps.create_matrix.outputs.matrix }}'
          jq -aR <<< echo '${{ steps.create_matrix.outputs.matrix }}'

  tests:
    needs:
      - test-matrix
    strategy:
      fail-fast: false
      matrix: ${{ fromJson(needs.test-matrix.outputs.test_matrix) }}
    name: |
      [${{ matrix.state }}]
      ${{ matrix.os }},
      Python ${{ matrix.python-version }},
      Click: ${{ matrix.click-version }},
      Cloup: ${{ matrix.cloup-version }}
    runs-on: ${{ matrix.os }}
    # We keep going when a job flagged as not stable fails.
    continue-on-error: ${{ matrix.state == 'unstable' }}
    steps:
      - uses: actions/checkout@v4.2.2

      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5.3.0
        with:
          python-version: ${{ matrix.python-version }}

      - name: Install uv
        run: |
          python -m pip install -r https://raw.githubusercontent.com/kdeldycke/workflows/v4.7.1/requirements/uv.txt
      - name: Install project
        run: |
          uv --no-progress venv
          uv --no-progress sync --extra test --extra pygments --extra sphinx --extra pytest

      - name: Unittests
        run: >
          uv --no-progress run
          ${{ matrix.click-version != 'released'
          && format('--with "git+https://github.com/pallets/click.git@{0}"', matrix.click-version) || '' }}
          ${{ matrix.cloup-version != 'released'
          && format('--with "git+https://github.com/janluke/cloup.git@{0}"', matrix.cloup-version) || ''}}
          --
          pytest

      - name: Codecov upload
        uses: codecov/codecov-action@v4.6.0
        with:
          token: ${{ secrets.CODECOV_TOKEN }}