core.yml

name: Tests

on:
  push:
    branches:
      - main
      - '*_rel'
  schedule:
    # run daily at 5:00 am UTC (12 am ET/9 pm PT)
    - cron: '0 5 * * *'
  repository_dispatch:
    # to run this, send a POST API call at repos/IDAES/idaes-pse/dispatches with the specified event_type
    # e.g. `gh repos/IDAES/idaes-pse/dispatches -F event_type=ci_run_tests`
    types: [ci_run_tests]
  workflow_dispatch:
    inputs:
      git-ref:
        description: Git hash (optional)
        required: false
  pull_request:
    types:
      - opened
      # ready_for_review occurs when a draft PR is turned to non-draft
      - ready_for_review
      # synchronize occurs whenever commits are pushed to the PR branch
      - synchronize

concurrency:
  # NOTE: the value of `group` should be chosen carefully,
  # otherwise we might end up over- or under-canceling workflow runs
  # e.g. if we want to have Codecov results for each commit on `main`,
  # we should use something `github.sha` instead of `github.ref_name`
  # to avoid over-canceling runs from `main`
  # in which case we'd need to access the PR number from somewhere else rather than `github.ref_name`
  # to avoid under-canceling runs from PRs
  group: ${{ github.workflow }}-${{ github.ref_name }}
  cancel-in-progress: true

env:
  # default Python version to use for checks that do not require multiple versions
  DEFAULT_PYTHON_VERSION: '3.10'
  IDAES_CONDA_ENV_NAME_DEV: idaes-pse-dev
  PYTEST_ADDOPTS: "--color=yes"

defaults:
  run:
    # -l: login shell, needed when using Conda run:
    shell: bash -l {0}

jobs:
  code-formatting:
    name: Check code formatting (Black)
    # OS and/or Python version don't make a difference, so we choose ubuntu and 3.10 for performance
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
      - name: Install Black
        # unlike the other jobs, we don't need to install IDAES and/or all the dev dependencies,
        # but we still want to specify the Black version to use in requirements-dev.txt for local development
        # so we extract the relevant line and pass it to a simple `pip install`
        run: |
          # we store the version
          black_requirement="$(grep 'black==' requirements-dev.txt)"
          pip --no-cache-dir install --progress-bar off "$black_requirement"
      - name: Run Black to verify that the committed code is formatted
        run: |
          black --check .

  spell-check:
    name: Check Spelling
    runs-on: ubuntu-latest
    steps:
      - name: Checkout source
        uses: actions/checkout@v4
      - name: Run Spell Checker
        uses: crate-ci/typos@v1.24.5
        with: 
          config: ./.github/workflows/typos.toml

  pytest:
    # description: Run pytest with dev dependencies
    name: pytest (py${{ matrix.python-version }}/${{ matrix.os }})
    runs-on: ${{ matrix.runner-image }}
    needs: [code-formatting, spell-check]
    strategy:
      fail-fast: false
      matrix:
        python-version: ['3.9', '3.10', '3.11', '3.12']
        os:
          - linux
          - win64
        include:
          - os: linux
            runner-image: ubuntu-20.04
          - os: win64
            runner-image: windows-2022
          - python-version: '3.11'
            # only generate coverage report for a single python version in the matrix
            # to avoid overloading Codecov
            cov-report: true
    steps:
      - uses: actions/checkout@v4
      - uses: ./.github/actions/display-debug-info
      - name: Set up Conda environment
        uses: conda-incubator/setup-miniconda@v3
        with:
          activate-environment: ${{ env.IDAES_CONDA_ENV_NAME_DEV }}
          python-version: ${{ matrix.python-version }}
      - name: Set up idaes
        uses: ./.github/actions/setup-idaes
        with:
          install-target: -r requirements-dev.txt
      - name: Add pytest CLI options for coverage
        if: matrix.cov-report
        run: |
          echo PYTEST_ADDOPTS="$PYTEST_ADDOPTS --cov --cov-report=xml" >> "$GITHUB_ENV"
      - name: Run pytest (not integration)
        run: |
          pytest --pyargs idaes -m "not integration"
      - name: Upload coverage report as GHA workflow artifact
        if: matrix.cov-report
        uses: actions/upload-artifact@v4
        with:
          name: coverage-report-${{ matrix.os }}
          path: coverage.xml
          if-no-files-found: error

  upload-coverage:
    name: Upload coverage report (Codecov)
    needs: [pytest]
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        report-variant: ["linux", "win64"]
    steps:
      # the checkout step is needed to have access to codecov.yml
      - uses: actions/checkout@v4
      - uses: actions/download-artifact@v4
        with:
          name: coverage-report-${{ matrix.report-variant }}
      - name: Upload coverage report to Codecov
        uses: codecov/codecov-action@v4
        with:
          fail_ci_if_error: true
          verbose: true
          # NOTE: secrets are not available for pull_request workflows
          # However, as of 2024-02-10, Codecov is still allowing tokenless upload from PRs
          # but does require token for other workflows e.g. merge to `main`
          # see https://github.com/codecov/codecov-action/issues/1274#issuecomment-1934437359
          token: ${{ secrets.CODECOV_TOKEN }}
          # pinning version after v0.7.0 broke tokenless upload
          # see codecov/codecov-action#1487
          version: v0.7.1

  build-docs:
    name: Build Sphinx docs
    runs-on: ubuntu-latest
    needs: [code-formatting, spell-check]
    steps:
      - uses: actions/checkout@v4
      - name: Set up Conda environment
        uses: conda-incubator/setup-miniconda@v3
        with:
          activate-environment: ${{ env.IDAES_CONDA_ENV_NAME_DEV }}
          python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
      - name: Set up idaes
        uses: ./.github/actions/setup-idaes
        with:
          install-target: -r requirements-dev.txt
      - name: Build Sphinx docs
        run: |
          which python
          cd docs/
          python build.py --timeout 600
      - name: Publish built docs
        uses: actions/upload-artifact@v4
        with:
          name: idaes-pse-docs-html
          path: docs/build/html/
          retention-days: 7

  pylint:
    name: Pylint
    runs-on: ubuntu-latest
    needs: [code-formatting, spell-check]
    env:
      pylint_target_dir: idaes/
      pylint_output_path: pylint.json
      pylint_todo_sentinel: PYLINT-TODO
    steps:
      - uses: actions/checkout@v4
      # NOTE: using Conda instead of actions/setup-python in this job is not strictly necessary
      # as it doesn't need to run on Windows or use the setup-idaes local action,
      # but we do it for consistency with the other jobs
      - name: Set up Conda environment
        uses: conda-incubator/setup-miniconda@v3
        with:
          activate-environment: ${{ env.IDAES_CONDA_ENV_NAME_DEV }}
          python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
      - name: Set up idaes
        uses: ./.github/actions/setup-idaes
        with:
          install-target: -r requirements-dev.txt
      - name: Run pylint
        run: |
          echo "::group::Display pylint version"
          pip show pylint astroid
          echo "::endgroup::"
          pylint --rcfile=./.pylint/pylintrc --disable=R --output-format=idaes_reporters.DisplayProgress,colorized,idaes_reporters.GHACheckAnnotations:pylint.txt "$pylint_target_dir"
      - name: Generate GHA Check Annotations from Pylint report
        if: success() || failure()
        run: |
          cat pylint.txt || echo "GHA-compatible Pylint report not found"
      - name: Show PYLINT-TODO comments left in the codebase
        if: always()
        run: |
          # use a bash array to save options containing quotes to a variable, then use the double-quoted array expansion "${arr[@]}"
          grep_opts=( --recursive --include '*.py' --color=always --after-context=2 --line-number --initial-tab )

          grep "$pylint_todo_sentinel" "${grep_opts[@]}" "$pylint_target_dir" || echo "No \"$pylint_todo_sentinel\" comments found in $pylint_target_dir"

  compat:
    name: Compatibility tests
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v4
      - name: Set up Conda environment
        uses: conda-incubator/setup-miniconda@v3
        with:
          activate-environment: ${{ env.IDAES_CONDA_ENV_NAME_DEV }}
          python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
      - name: Set up idaes
        uses: ./.github/actions/setup-idaes
        with:
          install-target: -r requirements-dev.txt
      - name: Create empty pytest.ini file
        run: |
          echo "" > pytest.ini
      - name: Install and run compatibility tests
        run: |
          pip install "git+https://github.com/IDAES/idaes-compatibility@0.23.8"
          pytest --pyargs idaes_compatibility