test.yml

# SPDX-FileCopyrightText: PyPSA Contributors
#
# SPDX-License-Identifier: MIT

name: Tests

on:
  push:
    branches:
    - master
    - release-branch-v*
  pull_request:
    branches: ["*"]
  schedule:
  - cron: "0 5 * * *"
  workflow_call:

# Cancel any in-progress runs when a new run is triggered
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

env:
  # PRs use the committed lockfile, master/nightly resolve fresh
  UV_LOCK_ARG: ${{ github.event_name == 'pull_request' && '--locked' || '--upgrade' }}

jobs:
  build:
    # Build the Python SDist and wheel, performs metadata and readme linting
    name: Build and verify package
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      with:
        fetch-depth: 0   # Needed for setuptools_scm
    - uses: hynek/build-and-inspect-python-package@2abe76da66d0a6a4a227101f9348ee855797cfa5 # v3.0.1
      id: baipp

    - name: Compute reduced PR python versions
      id: pr-versions
      env:
        ALL: ${{ steps.baipp.outputs.supported_python_classifiers_json_array }}
      run: echo "python-versions-pr=$(jq -cn --argjson a "$ALL" '[$a[0], $a[-1]] | unique')" >> "$GITHUB_OUTPUT"

    outputs:
      python-versions: ${{ steps.baipp.outputs.supported_python_classifiers_json_array }}
      python-versions-pr: ${{ steps.pr-versions.outputs.python-versions-pr }}

  test:
    # Test package build in matrix of OS and Python versions
    name: Test package
    needs: [build]
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        # lean matrix on PRs and master pushes (min+max Python, ubuntu only), full matrix for daily runs and releases
        python-version: ${{ (github.event_name == 'schedule' || startsWith(github.ref, 'refs/tags/')) && fromJSON(needs.build.outputs.python-versions) || fromJSON(needs.build.outputs.python-versions-pr) }}
        os: ${{ (github.event_name == 'schedule' || startsWith(github.ref, 'refs/tags/')) && fromJSON('["ubuntu-latest","macos-latest","windows-latest"]') || fromJSON('["ubuntu-latest"]') }}
        api: [default, new_api]
        exclude:
        - os: macos-latest
          api: new_api
        - os: windows-latest
          api: new_api
        include: ${{ (github.event_name == 'schedule' || startsWith(github.ref, 'refs/tags/')) && fromJSON('[{"python-version":"3.13","os":"ubuntu-latest","api":"pandas3"}]') || fromJSON('[]') }}

    env:
      MPLBACKEND: Agg # https://github.com/orgs/community/discussions/26434
    steps:
    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      with:
        fetch-depth: 0   # Needed for setuptools_scm

    - name: Set up Python ${{ matrix.python-version }} on ${{ matrix.os }}
      uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
      with:
        python-version: ${{ matrix.python-version }}

    - name: Install macos dependencies
      if: matrix.os == 'macos-latest'
      run: |
        brew update
        # pkg-config is deprecated but still installed in runner
        # Can be removed once it is removed from the runner
        brew unlink pkg-config@0.29.2 || true
        brew install hdf5

    - name: Download package
      uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
      with:
        name: Packages
        path: dist

    - name: Install package and dependencies
      if: matrix.python-version != '3.14'
      run: |
        python -m pip install uv
        uv sync --all-extras --no-install-project $UV_LOCK_ARG
        uv pip install "$(ls dist/*.whl)"

    - name: Install package and dependencies (Python 3.14)
      if: matrix.python-version == '3.14'
      run: |
        python -m pip install uv
        uv sync --extra dev --no-install-project $UV_LOCK_ARG
        uv pip install "$(ls dist/*.whl)"

    - name: Install pandas 3
      if: matrix.api == 'pandas3'
      run: uv pip install 'pandas>=3.0'

    - name: Run unit tests (old API)
      if: matrix.api == 'default'
      run: >
        uv run pytest
        --cov=pypsa --junitxml=junit.xml -o junit_family=legacy
        && uv run coverage xml

    - name: Run unit tests (pandas 3)
      if: matrix.api == 'pandas3'
      run: >
        uv run --no-sync pytest
        --cov=pypsa --junitxml=junit.xml -o junit_family=legacy
        && uv run --no-sync coverage xml

    - name: Run unit tests (new API)
      if: matrix.api == 'new_api'
      run: >
        uv run pytest
        --new-components-api
        --cov=pypsa --junitxml=junit.xml -o junit_family=legacy
        && uv run coverage xml

    - name: Upload code coverage report
      if: ${{ !cancelled() }}
      uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
      with:
        token: ${{ secrets.CODECOV_TOKEN }}
        flags: >
          unit-tests,
          os-${{ matrix.os }},
          python${{ matrix.python-version }},
          api-${{ matrix.api }}

    - name: Upload test results to Codecov
      if: ${{ !cancelled() }}
      uses: codecov/test-results-action@0fa95f0e1eeaafde2c782583b36b28ad0d8c77d3 # v1.2.1
      with:
        token: ${{ secrets.CODECOV_TOKEN }}
        flags: >
          unit-tests,
          os-${{ matrix.os }},
          python${{ matrix.python-version }},
          api-${{ matrix.api }}

  test-plots:
    # Run the matplotlib image-comparison tests once, on a single instance.
    # Baselines are generated on Linux; see test/test_statistics_plot.py.
    name: Test plots
    needs: [build]
    runs-on: ubuntu-latest
    env:
      MPLBACKEND: Agg # https://github.com/orgs/community/discussions/26434
    steps:
    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      with:
        fetch-depth: 0   # Needed for setuptools_scm

    - name: Set up Python 3.13
      uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
      with:
        python-version: 3.13

    - name: Download package
      uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
      with:
        name: Packages
        path: dist

    - name: Install package and dependencies
      run: |
        python -m pip install uv
        uv sync --all-extras --no-install-project $UV_LOCK_ARG
        uv pip install "$(ls dist/*.whl)"

    - name: Run image comparison tests
      run: >
        uv run pytest --run-plot-tests -m mpl_image_compare
        --mpl --mpl-generate-summary=html --mpl-results-path=mpl-results

    - name: Upload artifacts
      if: ${{ !cancelled() }}
      uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
      with:
        name: results-plotting
        path: |
          mpl-results
        retention-days: 14
        if-no-files-found: ignore

  check-docs:
    name: Check docs
    needs: [build]
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      with:
        fetch-depth: 0   # Needed for setuptools_scm

    - name: Set up Python 3.13
      uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
      with:
        python-version: 3.13

    - name: Download package
      uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
      with:
        name: Packages
        path: dist

    - name: Install package and dependencies
      run: |
        python -m pip install uv
        uv sync --all-extras --no-install-project $UV_LOCK_ARG
        uv pip install "$(ls dist/*.whl)"

    - name: Run doc tests
      run: >
        uv run pytest
        test/test_docs.py --test-docs
        --cov=pypsa --junitxml=junit.xml -o junit_family=legacy
        && uv run coverage xml

    - name: Check external links
      # Flaky external hosts, run on the daily schedule only, not PRs/master
      if: ${{ !cancelled() && github.event_name == 'schedule' }}
      uses: lycheeverse/lychee-action@e7477775783ea5526144ba13e8db5eec57747ce8 # v2.9.0
      with:
        args: "--config .lychee.toml --no-progress './**/*.md'"
        fail: true
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

    - name: Upload code coverage report
      if: ${{ !cancelled() }}
      uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
      with:
        token: ${{ secrets.CODECOV_TOKEN }}
        flags: >
          doc-tests,
          os-ubuntu-latest,
          python3.13,
          api-old-api

    - name: Upload test results to Codecov
      if: ${{ !cancelled() }}
      uses: codecov/test-results-action@0fa95f0e1eeaafde2c782583b36b28ad0d8c77d3 # v1.2.1
      with:
        token: ${{ secrets.CODECOV_TOKEN }}
        flags: >
          doc-tests,
          os-ubuntu-latest,
          python3.13,
          api-old-api

  check-types:
    name: Check types
    needs: [build]
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      with:
        fetch-depth: 0   # Needed for setuptools_scm

    - name: Set up Python 3.13
      uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
      with:
        python-version: 3.13

    - name: Download package
      uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
      with:
        name: Packages
        path: dist

    - name: Install package and dependencies
      run: |
        python -m pip install uv
        uv sync --all-extras --no-install-project $UV_LOCK_ARG
        uv pip install "$(ls dist/*.whl)"

    - name: Run type checker (mypy)
      run: |
        uv run mypy .