python-tests.yml

name: Python Unit Tests

on:
  push:
    branches:
      - "develop"
  pull_request:
    types: [opened, synchronize, reopened]

  # Allows workflow to be called from other workflows
  workflow_call:
    inputs:
      ref:
        required: true
        type: string
    secrets:
      SNOWFLAKE_ACCOUNT:
        description: "Snowflake account passed from caller workflows for snowflake integration tests"
        required: true
      SNOWFLAKE_PASSWORD:
        description: "Snowflake account password passed from caller workflows for snowflake integration tests"
        required: true

# Avoid duplicate workflows on same branch
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}-python
  cancel-in-progress: true

defaults:
  run:
    shell: bash

env:
  FORCE_COLOR: "1"

jobs:
  build_info:
    runs-on: ubuntu-latest

    name: "Build info"

    steps:
      - name: Checkout Streamlit code
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ inputs.ref }}
          persist-credentials: false
          submodules: "recursive"
          fetch-depth: 2
      - name: Set Python version vars
        id: build_info
        uses: ./.github/actions/build_info

    outputs:
      PYTHON_VERSIONS: ${{ steps.build_info.outputs.PYTHON_VERSIONS }}
      PYTHON_MIN_VERSION: ${{ steps.build_info.outputs.PYTHON_MIN_VERSION }}
      PYTHON_MAX_VERSION: ${{ steps.build_info.outputs.PYTHON_MAX_VERSION }}

  py-unit-tests:
    needs:
      - build_info

    runs-on: ubuntu-latest

    strategy:
      fail-fast: false
      matrix:
        python_version: "${{ fromJson(needs.build_info.outputs.PYTHON_VERSIONS) }}"

    env:
      PYTHON_VERSION: >-
        ${{
          (
            matrix.python_version == 'min' && needs.build_info.outputs.PYTHON_MIN_VERSION ||
            (matrix.python_version == 'max' && needs.build_info.outputs.PYTHON_MAX_VERSION || matrix.python_version)
          )
        }}
      COVERAGE_FILE: .coverage.${{ matrix.python_version }}

    steps:
      - name: Checkout Streamlit code
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ inputs.ref }}
          persist-credentials: false
          submodules: "recursive"

      - name: Setup virtual env
        uses: ./.github/actions/make_init
        with:
          python_version: ${{ env.PYTHON_VERSION }}
      - name: Run Linters
        run: make python-lint
        env:
          RUFF_OUTPUT_FORMAT: github
      # NumPy >=2.5 stubs use Python 3.12 syntax, and mypy/ty type-check as 3.11,
      # so interpreters that install that floor skip make python-types. Keep
      # this condition aligned with the numpy>=2.5 marker in pyproject.toml
      # (Python 3.15 today). 3.11-3.14 still run the type checkers.
      - name: Run Type Checkers
        if: env.PYTHON_VERSION != '3.15'
        run: make python-types
        env:
          TY_OUTPUT_FORMAT: github
      - name: Run Python Tests
        run: make python-tests
      - name: CLI Smoke Tests
        run: make cli-smoke-tests
      - name: Upload coverage data
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: coverage_data_${{ matrix.python_version }}
          path: ${{ env.COVERAGE_FILE }}
          include-hidden-files: true
          if-no-files-found: ignore

  py-integration-tests:
    needs:
      - build_info

    runs-on: ubuntu-latest

    env:
      COVERAGE_FILE: .coverage.integration

    steps:
      - name: Checkout Streamlit code
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ inputs.ref }}
          persist-credentials: false
          submodules: "recursive"
      - name: Setup virtual env
        uses: ./.github/actions/make_init
        with:
          python_version: "3.12"
          # Deactivate usage of cached venv to avoid interfering with other Python
          # version jobs. The key generation for the cache could resolve to the same key,
          # which might cause some unexpected issues with dependencies.
          use_cached_venv: false
      - name: Install integration dependencies
        run: uv sync --python python --locked --no-default-groups --group integration
      - name: Run Python integration tests
        run: make python-integration-tests
        env:
          UV_NO_SYNC: 1
          SNOWFLAKE_ACCOUNT: ${{ secrets.SNOWFLAKE_ACCOUNT }}
          SNOWFLAKE_PASSWORD: ${{ secrets.SNOWFLAKE_PASSWORD }}
      - name: Upload coverage data
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: coverage_data_integration
          path: ${{ env.COVERAGE_FILE }}
          include-hidden-files: true
          if-no-files-found: ignore

  py-min-deps-test:
    needs:
      - build_info

    runs-on: ubuntu-latest

    strategy:
      fail-fast: false

    env:
      COVERAGE_FILE: .coverage.min_deps

    steps:
      - name: Checkout Streamlit code
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ inputs.ref }}
          persist-credentials: false
          submodules: "recursive"
          fetch-depth: 2
      - name: Setup virtual env
        uses: ./.github/actions/make_init
        with:
          python_version: ${{ needs.build_info.outputs.PYTHON_MIN_VERSION }}
          use_cached_venv: false
      - name: Validate min-constraints-gen
        run: |
          make update-min-deps

          git_status=$(git status --porcelain -- scripts/assets/min-constraints-gen.txt)
          if [[ -n $git_status ]]; then
            echo "::error::The min constraints file is out of date! Please run \`make update-min-deps\` and commit the result."
            echo "::group::git diff scripts/assets/min-constraints-gen.txt"
            git diff scripts/assets/min-constraints-gen.txt
            echo "::endgroup::"
            exit 1
          else
            echo "min constraints file is up to date."
          fi
      - name: Install min dependencies (force reinstall)
        run: uv pip install --no-config -r scripts/assets/min-constraints-gen.txt --force-reinstall
      - name: Make local modules visible
        run: uv pip install --editable ./lib --no-deps
      - name: Verify minimum dependency versions
        env:
          UV_NO_SYNC: 1
        run: |
          uv run python - <<'PY'
          from importlib.metadata import version
          from pathlib import Path

          from packaging.requirements import Requirement
          from packaging.version import Version

          constraints = Path("scripts/assets/min-constraints-gen.txt")
          for line in constraints.read_text().splitlines():
              line = line.strip()
              if not line or line.startswith("#"):
                  continue

              requirement = Requirement(line)
              if requirement.marker and not requirement.marker.evaluate():
                  continue

              actual_version = Version(version(requirement.name))
              assert actual_version in requirement.specifier, (
                  f"{requirement.name}: expected {requirement.specifier}, "
                  f"found {actual_version}"
              )
              print(f"{requirement.name}=={actual_version}")
          PY
      - name: Import standard-generated Python protobufs
        env:
          UV_NO_SYNC: 1
        run: |
          uv run python - <<'PY'
          import importlib
          from pathlib import Path

          modules = sorted(Path("lib/streamlit/proto").glob("*_pb2.py"))
          for module in modules:
              importlib.import_module(f"streamlit.proto.{module.stem}")
          print(f"Imported {len(modules)} generated protobuf modules")
          PY
      - name: Run Python Tests
        run: make python-tests
        env:
          UV_NO_SYNC: 1
      - name: CLI Smoke Tests
        run: make cli-smoke-tests
        env:
          UV_NO_SYNC: 1
      - name: Upload coverage data
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: coverage_data_min_deps
          path: ${{ env.COVERAGE_FILE }}
          include-hidden-files: true
          if-no-files-found: ignore

  py-coverage-report:
    needs:
      - py-unit-tests
      - py-integration-tests
      - py-min-deps-test
    runs-on: ubuntu-latest
    permissions:
      # Required for downloading artifacts
      actions: read
      # Required for creating/updating PR comments
      pull-requests: write

    steps:
      - name: Checkout Streamlit code
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ inputs.ref }}
          persist-credentials: false
          submodules: "recursive"

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

      - name: Download all coverage files
        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          pattern: coverage_data_*
          merge-multiple: true
          path: lib

      - name: Combine coverage & generate report
        run: |
          python -m pip install --upgrade coverage[toml]

          # Combine all coverage files
          python -m coverage combine

          # Generate JSON report
          python -m coverage json -o coverage.json

          # Generate HTML report
          python -m coverage html --directory=htmlcov

          # Save report to a file first
          python -m coverage report --format=markdown > coverage-report.md

          # Set as environment variable with proper delimiter syntax for multiline content
          echo "COVERAGE_REPORT<<EOF" >> $GITHUB_ENV
          cat coverage-report.md >> $GITHUB_ENV
          echo "EOF" >> $GITHUB_ENV

          # Also write to summary
          cat coverage-report.md >> $GITHUB_STEP_SUMMARY
        working-directory: lib

      - name: Upload combined coverage data
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: combined_coverage_data
          path: lib/.coverage
          include-hidden-files: true
      - name: Upload combined coverage JSON
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: combined_coverage_json
          path: lib/coverage.json
      - name: Upload combined coverage HTML report
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: combined_coverage_report
          path: lib/htmlcov
          retention-days: 14

      - name: Find latest develop coverage
        if: github.event_name == 'pull_request'
        id: get-latest-run
        uses: ./.github/actions/find_latest_workflow_artifact
        with:
          workflow: python-tests.yml
          artifact_name: combined_coverage_json

      - name: Download develop coverage
        if: github.event_name == 'pull_request' && steps.get-latest-run.outputs.run_id != ''
        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          repository: streamlit/streamlit
          run-id: ${{ steps.get-latest-run.outputs.run_id }}
          name: combined_coverage_json
          path: /tmp/develop_coverage
          # Needs a token to download the artifact from another
          # workflow run:
          github-token: ${{ secrets.GITHUB_TOKEN }}

      - name: Check coverage changes and comment
        if: github.event_name == 'pull_request' && steps.get-latest-run.outputs.run_id != ''
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
        with:
          script: |
            const COVERAGE_CHANGE_THRESHOLD = 0.05; // 0.05%

            try {
              // Read current coverage from the existing file
              const currentCoverage = require('./lib/coverage.json');

              // Read develop coverage from downloaded artifact
              const developCoverage = require('/tmp/develop_coverage/coverage.json');

              // Calculate total coverage
              const currentTotal = currentCoverage.totals.percent_covered;
              const developTotal = developCoverage.totals.percent_covered;

              // Calculate percentage difference
              const diffPercent = currentTotal - developTotal;
              const absDiffPercent = Math.abs(diffPercent);

              console.log(`Current coverage: ${currentTotal.toFixed(4)}%`);
              console.log(`Develop coverage: ${developTotal.toFixed(4)}%`);
              console.log(`Coverage difference: ${diffPercent.toFixed(4)}%`);

            // Check if this PR is from a fork - fork PRs have limited GITHUB_TOKEN permissions
            // and cannot post comments to the PR
            const isForkPR = context.payload.pull_request?.head?.repo?.fork === true;
            if (isForkPR) {
              console.log('PR is from a fork - skipping coverage comment (insufficient permissions)');
              console.log('Coverage information is available in the job summary above.');
              return;
            }

              const changeType = diffPercent > 0 ? 'increased' : 'decreased';
              const emoji = diffPercent > 0 ? '📈' : '📉';

              const commentBody = `### ${emoji} Python coverage change detected

              The Python unit test coverage has **${changeType} by ${Math.abs(diffPercent).toFixed(4)}%**

              - Current PR: ${currentTotal.toFixed(4)}% (${currentCoverage.totals.num_statements} statements, ${currentCoverage.totals.missing_lines} missed)
              - Latest develop: ${developTotal.toFixed(4)}% (${developCoverage.totals.num_statements} statements, ${developCoverage.totals.missing_lines} missed)

              ${absDiffPercent >= COVERAGE_CHANGE_THRESHOLD
                ? (diffPercent > 0
                    ? '🎉 Great job on improving test coverage!'
                    : '💡 Consider adding more unit tests to maintain or improve coverage.'
                  )
                : '✅ Coverage change is within normal range.'
              }

              <details>
              <summary>Coverage by files</summary>

              ${process.env.COVERAGE_REPORT}
              </details>

              📊 [View detailed coverage comparison](https://issues.streamlit.app/Test_Coverage_(Python)?pr=${context.issue.number})`;


              // Unique identifier for our comment
              const commentIdentifier = '<!-- STREAMLIT-PYTHON-COVERAGE-CHECK -->';
              const fullCommentBody = `${commentIdentifier}\n${commentBody}`;

              // Get all comments on the PR
              const { data: comments } = await github.rest.issues.listComments({
                owner: context.repo.owner,
                repo: context.repo.repo,
                issue_number: context.issue.number,
              });

              // Look for our previous coverage comment
              const coverageComment = comments.find(comment => comment.body.includes(commentIdentifier));

              if (coverageComment) {
                // Update existing comment
                await github.rest.issues.updateComment({
                  owner: context.repo.owner,
                  repo: context.repo.repo,
                  comment_id: coverageComment.id,
                  body: fullCommentBody
                });
                console.log('Updated existing coverage comment');
              } else if (absDiffPercent >= COVERAGE_CHANGE_THRESHOLD) {
                // Only create new comment for significant changes
                await github.rest.issues.createComment({
                  owner: context.repo.owner,
                  repo: context.repo.repo,
                  issue_number: context.issue.number,
                  body: fullCommentBody
                });
                console.log('Created new coverage comment');
              } else {
                console.log('Coverage change is not significant and no existing comment found, skipping comment');
              }
            } catch (error) {
              console.error(`Error checking coverage changes: ${error.message}`);
              throw error;
            }