tests.yml

name: Tests

on:
  push:
    branches: [main, master]
  pull_request:
    branches: [main, master]

jobs:
  tests:
    name: ${{ matrix.session }} ${{ matrix.python }} / ${{ matrix.os }}
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        include:
          - { python: "3.13", os: "ubuntu-latest", session: "pre-commit" }
          # `safety` retired (its CLI moved behind auth) -> pypa/pip-audit instead.
          - { python: "3.13", os: "ubuntu-latest", session: "pip-audit" }
          - { python: "3.13", os: "ubuntu-latest", session: "mypy" }
          - { python: "3.10", os: "ubuntu-latest", session: "mypy" }
          - { python: "3.13", os: "ubuntu-latest", session: "ty" }
          - { python: "3.13", os: "ubuntu-latest", session: "tests" }
          - { python: "3.12", os: "ubuntu-latest", session: "tests" }
          - { python: "3.11", os: "ubuntu-latest", session: "tests" }
          - { python: "3.10", os: "ubuntu-latest", session: "tests" }
          - { python: "3.12", os: "windows-latest", session: "tests" }
          # Strict Windows job: runs only the portable subset
          # (`pytest -m windows_strict` -- no poppler/tesseract/ImageMagick
          # binaries needed) with `continue-on-error` OFF, so the check
          # goes red on Windows regressions. The best-effort `tests`
          # session above stays green-washed for full-matrix visibility.
          - { python: "3.12", os: "windows-latest", session: "windows_strict" }
          - { python: "3.12", os: "macos-latest", session: "tests" }
          # - { python: "3.12", os: "ubuntu-latest", session: "typeguard" }
          - { python: "3.13", os: "ubuntu-latest", session: "xdoctest" }
          - { python: "3.13", os: "ubuntu-latest", session: "docs-build" }

    env:
      NOXSESSION: ${{ matrix.session }}
      FORCE_COLOR: "1"
      PRE_COMMIT_COLOR: "always"

    steps:
      - name: Check out the repository
        uses: actions/checkout@v7

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

      - name: Install uv
        uses: astral-sh/setup-uv@v7

      - name: Create uv environment
        run: uv venv

      - name: Install system dependencies (Linux)
        # poppler/tesseract/ocrmypdf are only exercised by sessions that actually
        # extract — skip the apt install on lint/type-check/docs jobs to shave
        # ~20s off most matrix runs. xdoctest runs the extract_data doctest, so
        # it needs them; mypy/ty/pre-commit/pip-audit/docs-build do not.
        if: matrix.os == 'ubuntu-latest' && (matrix.session == 'tests' || matrix.session == 'xdoctest' || matrix.session == 'typeguard')
        run: |
          sudo apt update
          sudo apt install tesseract-ocr poppler-utils imagemagick ghostscript
          uv pip install -U ocrmypdf

      - name: Install system dependencies (macos-latest)
        if: matrix.os == 'macos-latest'
        run: |
          brew update
          # install ocrmypdf dependencies first
          brew install \
            exempi \
            ghostscript \
            jbig2enc \
            openjpeg \
            pngquant \
            tesseract
          brew install \
            ocrmypdf \
            imagemagick \
            poppler
          pip install -U ocrmypdf
          mkdir -p ~/lib
          ln -s "$(brew --prefix gs)/lib/libgs.dylib" ~/lib

      - name: Install system dependencies (windows-latest)
        if: matrix.os == 'windows-latest'
        # Best-effort: the default backend (pypdfium2) needs no system binaries,
        # and the poppler/tesseract-dependent tests skip when their binary is
        # absent. So Chocolatey flakiness must not fail the Windows job — it just
        # means fewer tests run. Add what installs cleanly.
        continue-on-error: true
        run: |
          choco install --yes --no-progress --pre tesseract
          choco install --yes --no-progress --ignore-checksums ghostscript --version 9.56.1
          choco install --yes --no-progress --pre imagemagick
          refreshenv
          choco install --yes --no-progress --ignore-checksums poppler
          pip install -U ocrmypdf

      - name: Compute pre-commit cache key
        if: matrix.session == 'pre-commit'
        id: pre-commit-cache
        shell: python
        run: |
          import hashlib
          import sys

          python = "py{}.{}".format(*sys.version_info[:2])
          payload = sys.version.encode() + sys.executable.encode()
          digest = hashlib.sha256(payload).hexdigest()
          result = "${{ runner.os }}-{}-{}-pre-commit".format(python, digest[:8])

          print("::set-output name=result::{}".format(result))

      - name: Restore pre-commit cache
        uses: actions/cache@v6
        if: matrix.session == 'pre-commit'
        with:
          path: ~/.cache/pre-commit
          key: ${{ steps.pre-commit-cache.outputs.result }}-${{ hashFiles('.pre-commit-config.yaml') }}
          restore-keys: |
            ${{ steps.pre-commit-cache.outputs.result }}-

      - name: Run Nox
        # Windows is best-effort for the full `tests` session: chocolatey
        # poppler is flaky and the Windows poppler builds extract subtly
        # different text than Linux poppler, so the golden compare tests
        # don't always match bit-for-bit. `continue-on-error` on the STEP
        # (not the job) lets the JOB conclude as success. The
        # `windows_strict` session on Windows is the actual gate -- it
        # runs the portable subset (no external binaries) and MUST pass.
        continue-on-error: ${{ matrix.os == 'windows-latest' && matrix.session == 'tests' }}
        run: |
          uvx nox --python=${{ matrix.python }}  #noqa

      - name: Upload coverage data
        if: always() && matrix.session == 'tests'
        uses: "actions/upload-artifact@v7"
        with:
          name: coverage-data-${{ matrix.session }}-${{ matrix.python }}-${{ matrix.os }} # noqa
          path: ".coverage.*"
          if-no-files-found: ignore
          include-hidden-files: true

      - name: Upload documentation
        if: matrix.session == 'docs-build'
        uses: actions/upload-artifact@v7
        with:
          name: docs
          path: docs/_build

  coverage:
    runs-on: ubuntu-latest
    needs: tests
    permissions:
      # Needed by python-coverage-comment-action to post the PR comment and to
      # push the coverage badge/report to its data branch.
      pull-requests: write
      contents: write
    steps:
      - name: Check out the repository
        uses: actions/checkout@v7

      - name: Set up Python
        uses: actions/setup-python@v7
        with:
          python-version: "3.12"

      - name: Install uv
        uses: astral-sh/setup-uv@v7

      - name: Install dependencies
        run: |
          uv sync --group dev

      - name: Download coverage data
        uses: actions/download-artifact@v8
        with:
          pattern: coverage-data-*
          merge-multiple: true

      - name: Combine coverage data and display human readable report
        run: |
          uvx nox --session=coverage

      - name: Coverage comment
        id: coverage_comment
        uses: py-cov-action/python-coverage-comment-action@v3
        with:
          GITHUB_TOKEN: ${{ github.token }}

      - name: Store PR comment to be posted
        if: steps.coverage_comment.outputs.COMMENT_FILE_WRITTEN == 'true'
        uses: actions/upload-artifact@v7
        with:
          name: python-coverage-comment-action
          path: python-coverage-comment-action.txt