test.yml

name: "🔬 Test"

on:
  pull_request:
  push:
    branches:
      - "develop"
      - "master"
      - "main"
      - "releases"

jobs:
  test:
    strategy:
      fail-fast: false
      matrix:
        # macOS and Windows tests target only the upper and lower CPython versions.
        interpreter:
          - "CPython"
        os:
          - name: "macOS"
            runner: "macos-latest"
          - name: "Windows"
            interpreters: "CPython"
            runner: "windows-latest"
        cpythons:
          # The goal is to ensure that each individual runner
          # is paired with all Python versions simultaneously.
          # This nested-list syntax accomplishes that goal.
          - - "3.8"
            - "3.12"
        # These last two keys are placeholders to ensure consistency in matrix values.
        cpython-beta:
          - ""
        pypys:
          - []

        # The Linux runner tests all CPython and PyPy versions.
        # To reduce clock time, CPython and PyPy are tested separately.
        include:
          # CPython
          - interpreter: "CPython"
            os:
              name: "Linux (CPython)"
              runner: "ubuntu-latest"
            cpythons:
              - "3.8"
              - "3.9"
              - "3.10"
              - "3.11"
              - "3.12"
            cpython-beta: "3.13"
            pypys: []
          # PyPy
          - interpreter: "PyPy"
            os:
              name: "Linux (PyPy)"
              runner: "ubuntu-latest"
            cpythons: []
            cpython-beta: ""
            pypys:
              - "3.8"
              - "3.9"
              - "3.10"
            # NOTE: Tox only offers "best effort" support for PyPy.
            # To prevent installing tox on a PyPy interpreter,
            # a CPython version must be added to the end of the PyPy list.
            tox-python: "3.12"

    name: "${{ matrix.os.name }}"
    runs-on: "${{ matrix.os.runner }}"

    steps:
      - name: "Checkout the repo"
        uses: "actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11" # v4.1.1

      - name: "Setup Python"
        id: "setup-python"
        uses: "actions/setup-python@0a5c61591373683505ea898e09a3ea4f39ef2b9c" # v5.0.0
        with:
          python-version: "${{
            matrix.interpreter == 'PyPy'
            && format('pypy-{0}\n{1}', join(matrix.pypys, '\npypy-'), matrix.tox-python)
            || format('{0}\n{1}', matrix.cpython-beta, join(matrix.cpythons, '\n'))
            }}"
          allow-prereleases: true

      - name: "Detect Pythons"
        uses: "kurtmckee/detect-pythons@38187a5464f266e93e5c1467699f7be2bf521d2e" # v1.1.0

      - name: "Restore cache"
        id: "restore-cache"
        uses: "actions/cache@ab5e6d0c87105b4c9c2047343972218f562e4319" # v4.0.1
        with:
          # The cache key includes the following to ensure it busts correctly:
          #
          # * All Python versions (detected by kurtmckee/detect-pythons, above)
          #   This ensures that .venv/ symlinks to Python interpreters work.
          # * The tox configuration (tox.ini)
          # * The pytest configuration (pyproject.toml)
          #
          key: "test-os=${{ runner.os }}-interpreter=${{ matrix.interpreter }}-hash=${{ hashFiles('.python-identifiers', 'tox.ini', 'pyproject.toml') }}"
          path: |
            .tox/
            .venv/

      - name: "Determine venv path"
        shell: "bash"
        run: "echo 'venv-path=.venv/${{ runner.os == 'Windows' && 'Scripts' || 'bin' }}' >> $GITHUB_ENV"

      - name: "Create virtual environment"
        if: "steps.restore-cache.outputs.cache-hit == false"
        run: |
          python -m venv .venv
          ${{ env.venv-path }}/python -m pip install --upgrade pip setuptools wheel
          ${{ env.venv-path }}/python -m pip install tox

      - name: "Run tests (CPython interpreters)"
        if: "matrix.interpreter == 'CPython'"
        run: "${{ env.venv-path }}/tox run -e py${{ join(matrix.cpythons, '-chardet,py') }}-chardet${{ matrix.cpython-beta != '' && format(',py{0}-chardet', matrix.cpython-beta) || '' }}"

      - name: "Run tests (PyPy interpreters)"
        if: "matrix.interpreter == 'PyPy'"
        run: "${{ env.venv-path }}/tox run -e pypy${{ join(matrix.pypys, '-chardet,pypy') }}-chardet"

  lint:
    name: "Lint"
    runs-on: "ubuntu-latest"

    steps:
      - name: "Checkout the repo"
        uses: "actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11" # v4.1.1

      - name: "Setup Python"
        id: "setup-python"
        uses: "actions/setup-python@0a5c61591373683505ea898e09a3ea4f39ef2b9c" # v5.0.0
        with:
          python-version: "3.12"

      - name: "Detect Pythons"
        uses: "kurtmckee/detect-pythons@38187a5464f266e93e5c1467699f7be2bf521d2e" # v1.1.0

      - name: "Restore cache"
        id: "restore-cache"
        uses: "actions/cache@ab5e6d0c87105b4c9c2047343972218f562e4319" # v4.0.1
        with:
          # The cache key includes the following to ensure it busts correctly:
          #
          # * All Python versions (detected by kurtmckee/detect-pythons, above)
          #   This ensures that .venv/ symlinks to Python interpreters work.
          # * The tox config (tox.ini)
          # * The mypy config (pyproject.toml)
          # * The Sphinx config (docs/conf.py)
          # * The exact dependencies used during testing (requirements/*.txt)
          #
          key: "lint-hash=${{ hashFiles('.python-identifiers', 'tox.ini', 'pyproject.toml', 'docs/conf.py', 'requirements/*.txt') }}"
          path: |
            .mypy_cache/
            .tox/
            .venv/

      - name: "Create virtual environment"
        if: "steps.restore-cache.outputs.cache-hit == false"
        run: |
          python -m venv .venv
          .venv/bin/python -m pip install --upgrade pip setuptools wheel
          .venv/bin/python -m pip install tox

      - name: "Lint"
        run: ".venv/bin/tox run -e docs,mypy"