test-package.yml

name: Test Package

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
  workflow_dispatch:

env:
  PIP_DISABLE_PIP_VERSION_CHECK: "1"
  PIP_NO_PYTHON_VERSION_WARNING: "1"

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

permissions: {}

jobs:
  build-package:
    name: Build package
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          persist-credentials: false

      - uses: hynek/build-and-inspect-python-package@14c7e53f5d033cfa99f7af916fa59a6f7f356394
        id: baipp

    outputs:
      # Used to define the matrix for tests below. The value is based on
      # packaging metadata (trove classifiers).
      python-versions: ${{ steps.baipp.outputs.supported_python_classifiers_json_array }}

  tests:
    name: Test on ${{ matrix.os }} using Python ${{ matrix.python-version }}
    runs-on: ${{ matrix.os }}-latest
    needs: build-package

    strategy:
      fail-fast: false
      matrix:
        # TODO: add tests for 'Windows' and 'macOS'. Need to install Tesseract.
        os: ["ubuntu"]
        # Created by the build-and-inspect-python-package action above.
        python-version: ${{ fromJson(needs.build-package.outputs.python-versions) }}

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          persist-credentials: false

      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
          cache: pip
          allow-prereleases: true

      - name: Install Ubuntu dependencies
        if: matrix.os == 'ubuntu'
        run: sudo apt-get install tesseract-ocr

      - name: Install Windows dependencies
        if: matrix.os == 'windows'
        run: choco install tesseract

      - name: Install hatch
        run: pipx install hatch

      - name: Run tests
        run: hatch run cov

      - name: Upload coverage data
        uses: actions/upload-artifact@v4
        with:
          name: coverage-data-${{ matrix.os }}-${{ matrix.python-version }}
          path: .coverage*
          include-hidden-files: true
          if-no-files-found: ignore

  coverage:
    name: Check test coverage
    runs-on: ubuntu-latest
    needs: tests
    if: always()

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          persist-credentials: false

      - name: Set up Python 3.13
        uses: actions/setup-python@v5
        with:
          python-version: "3.13"
          cache: pip
          allow-prereleases: true

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

      - name: Combine coverage and fail if under expected percentage
        run: |
          # Install coverage packages
          pip install coverage

          # Combine the coverage from each Python version
          coverage combine || true
          
          # Generate the html coverage report
          coverage html --skip-covered --skip-empty

          # Generate the markdown coverage report to the GitHub step summary
          coverage report --format=markdown >> $GITHUB_STEP_SUMMARY

          # Generate the coverage report and fail if under expected percentage
          coverage report --fail-under=60

      - name: Upload HTML report if coverage under expected percentage
        uses: actions/upload-artifact@v4
        with:
          name: html-report
          path: htmlcov
        if: ${{ failure() }}

  lint:
    name: Run linters
    runs-on: ubuntu-latest
    needs:
      - build-package
      - tests

    strategy:
      fail-fast: false
      matrix:
        os: ["ubuntu"]
        python-version: ["3.13", "3.9"]

    steps:
      - name: Download pre-built packages
        uses: actions/download-artifact@v4
        with:
          name: Packages
          path: dist

      - name: Extract pre-built package
        run: tar xf dist/*.tar.gz --strip-components=1

      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
          cache: pip
          allow-prereleases: true

      - name: Install hatch
        run: pipx install hatch

      - name: Lint style
        run: hatch fmt --check || true

      - name: Lint docs
        if: matrix.python-version == '3.13'
        run: hatch run docs:lint || true