py-tests.yml

# Workflow that runs python tests
name: Run Python Tests

# The jobs in this workflow are required, so they must run at all times
# * Always run on "main"
# * Always run on PRs
on:
  push:
    branches:
      - main
  pull_request:
  workflow_dispatch:

permissions:
  contents: read
  id-token: write

env:
  # GitHub-hosted runners default to Node 24 for actions starting 2026-06-16; opt in
  # explicitly so checkout/setup steps do not recycle mid-job on Node 20 actions.
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true

# If triggered by a PR, it will be in the same group. However, each commit on main will be in its own unique group
concurrency:
  group: ${{ github.workflow }}-${{ (github.head_ref && github.ref) || github.run_id }}
  cancel-in-progress: true

# CI tiers (see docs/CI.md):
# - gates-on-linux-coverage-{a,b,d,g,e,c,report}: unit tests sharded for coverage on Linux.
#   Execution shards (d,g) skip compileall; syntax is still gated on a/b/c/e shards.
# - gates-on-linux-extended: integration/e2e/stress after coverage gate passes.
# - gates-on-windows / gates-on-macos: required unit PR gates for cross-platform smoke.
# - gates-on-windows-extended / gates-on-macos-extended: integration/e2e/stress after unit gates pass.
# - heavy-tests: marker-filtered heavy | integration | benchmark (schedule, main, manual).
jobs:
  gates-on-linux-coverage-a:
    name: Python Gates on Linux (coverage A)
    runs-on: ubuntu-24.04
    timeout-minutes: 30
    strategy:
      matrix:
        python-version: ['3.12']
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
      - name: Install uv
        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9
        with:
          version: '0.9.15'
          enable-cache: false
      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
        with:
          python-version: ${{ matrix.python-version }}
      - name: Resolve lockfile for runner
        run: uv lock
      - name: Install Python dependencies
        run: python scripts/bootstrap_env.py dev-test
      - name: Verify optional imports
        run: python backend/scripts/verify/verify_optional_imports.py
      - name: Compile backend (syntax gate)
        run: uv run python -m compileall backend
      - name: Run unit tests shard A with coverage
        run: >-
          PYTHONPATH=".:$PYTHONPATH" uv run pytest --maxfail=1 -q
          --cov=backend --cov-fail-under=0
          backend/tests/unit/cli backend/tests/unit/client backend/tests/unit/context
          backend/tests/unit/engine
      - name: Stage coverage data
        run: cp .coverage coverage-shard-a.dat
      - name: Upload coverage data
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
        with:
          name: coverage-linux-a
          path: coverage-shard-a.dat
          if-no-files-found: error

  gates-on-linux-coverage-b:
    name: Python Gates on Linux (coverage B)
    runs-on: ubuntu-24.04
    timeout-minutes: 30
    strategy:
      matrix:
        python-version: ['3.12']
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
      - name: Install uv
        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9
        with:
          version: '0.9.15'
          enable-cache: false
      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
        with:
          python-version: ${{ matrix.python-version }}
      - name: Resolve lockfile for runner
        run: uv lock
      - name: Install Python dependencies
        run: python scripts/bootstrap_env.py dev-test
      - name: Verify optional imports
        run: python backend/scripts/verify/verify_optional_imports.py
      - name: Compile backend (syntax gate)
        run: uv run python -m compileall backend
      - name: Run unit tests shard B with coverage
        run: >-
          PYTHONPATH=".:$PYTHONPATH" uv run pytest --maxfail=1 -q
          --cov=backend --cov-fail-under=0
          backend/tests/unit/core
          backend/tests/unit/test_bounded_pipeline.py backend/tests/unit/test_backend_conftest.py
          backend/tests/unit/test_package_version.py backend/tests/unit/test_start_server.py
      - name: Stage coverage data
        run: cp .coverage coverage-shard-b.dat
      - name: Upload coverage data
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
        with:
          name: coverage-linux-b
          path: coverage-shard-b.dat
          if-no-files-found: error

  gates-on-linux-coverage-d:
    name: Python Gates on Linux (coverage D)
    runs-on: ubuntu-24.04
    timeout-minutes: 30
    strategy:
      matrix:
        python-version: ['3.12']
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
      - name: Install uv
        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9
        with:
          version: '0.9.15'
          enable-cache: false
      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
        with:
          python-version: ${{ matrix.python-version }}
      - name: Resolve lockfile for runner
        run: uv lock
      - name: Install Python dependencies
        run: python scripts/bootstrap_env.py dev-test
      - name: Verify optional imports
        run: python backend/scripts/verify/verify_optional_imports.py
      - name: Run unit tests shard D with coverage
        run: |
          mapfile -t tests < <(find backend/tests/unit/execution -name 'test_*.py' | sort)
          half=$((${#tests[@]} / 2))
          for attempt in 1 2 3; do
            if PYTHONPATH=".:$PYTHONPATH" uv run pytest --maxfail=1 -q \
              --cov=backend --cov-fail-under=0 \
              "${tests[@]:0:$half}"; then
              exit 0
            fi
            echo "Shard D attempt ${attempt} failed; retrying in 15s..."
            sleep 15
          done
          exit 1
      - name: Stage coverage data
        run: cp .coverage coverage-shard-d.dat
      - name: Upload coverage data
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
        with:
          name: coverage-linux-d
          path: coverage-shard-d.dat
          if-no-files-found: error

  gates-on-linux-coverage-g:
    name: Python Gates on Linux (coverage G)
    runs-on: ubuntu-24.04
    timeout-minutes: 30
    strategy:
      matrix:
        python-version: ['3.12']
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
      - name: Install uv
        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9
        with:
          version: '0.9.15'
          enable-cache: false
      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
        with:
          python-version: ${{ matrix.python-version }}
      - name: Resolve lockfile for runner
        run: uv lock
      - name: Install Python dependencies
        run: python scripts/bootstrap_env.py dev-test
      - name: Verify optional imports
        run: python backend/scripts/verify/verify_optional_imports.py
      - name: Run unit tests shard G with coverage
        run: |
          mapfile -t tests < <(find backend/tests/unit/execution -name 'test_*.py' | sort)
          half=$((${#tests[@]} / 2))
          for attempt in 1 2 3; do
            if PYTHONPATH=".:$PYTHONPATH" uv run pytest --maxfail=1 -q \
              --cov=backend --cov-fail-under=0 \
              "${tests[@]:$half}"; then
              exit 0
            fi
            echo "Shard G attempt ${attempt} failed; retrying in 15s..."
            sleep 15
          done
          exit 1
      - name: Stage coverage data
        run: cp .coverage coverage-shard-g.dat
      - name: Upload coverage data
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
        with:
          name: coverage-linux-g
          path: coverage-shard-g.dat
          if-no-files-found: error

  gates-on-linux-coverage-e:
    name: Python Gates on Linux (coverage E)
    runs-on: ubuntu-24.04
    timeout-minutes: 30
    strategy:
      matrix:
        python-version: ['3.12']
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
      - name: Install uv
        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9
        with:
          version: '0.9.15'
          enable-cache: false
      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
        with:
          python-version: ${{ matrix.python-version }}
      - name: Resolve lockfile for runner
        run: uv lock
      - name: Install Python dependencies
        run: python scripts/bootstrap_env.py dev-test
      - name: Verify optional imports
        run: python backend/scripts/verify/verify_optional_imports.py
      - name: Compile backend (syntax gate)
        run: uv run python -m compileall backend
      - name: Run unit tests shard E with coverage
        run: >-
          PYTHONPATH=".:$PYTHONPATH" uv run pytest --maxfail=1 -q
          --cov=backend --cov-fail-under=0
          backend/tests/unit/inference
      - name: Stage coverage data
        run: cp .coverage coverage-shard-e.dat
      - name: Upload coverage data
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
        with:
          name: coverage-linux-e
          path: coverage-shard-e.dat
          if-no-files-found: error

  gates-on-linux-coverage-c:
    name: Python Gates on Linux (coverage C)
    runs-on: ubuntu-24.04
    timeout-minutes: 30
    strategy:
      matrix:
        python-version: ['3.12']
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
      - name: Install uv
        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9
        with:
          version: '0.9.15'
          enable-cache: false
      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
        with:
          python-version: ${{ matrix.python-version }}
      - name: Resolve lockfile for runner
        run: uv lock
      - name: Install Python dependencies
        run: python scripts/bootstrap_env.py dev-test
      - name: Verify optional imports
        run: python backend/scripts/verify/verify_optional_imports.py
      - name: Compile backend (syntax gate)
        run: uv run python -m compileall backend
      - name: Run unit tests shard C with coverage
        run: >-
          PYTHONPATH=".:$PYTHONPATH" uv run pytest --maxfail=1 -q
          --cov=backend --cov-fail-under=0
          backend/tests/unit/integrations backend/tests/unit/knowledge backend/tests/unit/ledger
          backend/tests/unit/orchestration backend/tests/unit/persistence backend/tests/unit/playbooks
          backend/tests/unit/security backend/tests/unit/telemetry backend/tests/unit/tools
          backend/tests/unit/utils backend/tests/unit/validation
      - name: Stage coverage data
        run: cp .coverage coverage-shard-c.dat
      - name: Upload coverage data
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
        with:
          name: coverage-linux-c
          path: coverage-shard-c.dat
          if-no-files-found: error

  gates-on-linux-coverage-report:
    name: Python Gates on Linux (coverage report)
    runs-on: ubuntu-24.04
    timeout-minutes: 15
    needs:
      - gates-on-linux-coverage-a
      - gates-on-linux-coverage-b
      - gates-on-linux-coverage-c
      - gates-on-linux-coverage-d
      - gates-on-linux-coverage-g
      - gates-on-linux-coverage-e
      - gates-on-linux-extended
    strategy:
      matrix:
        python-version: ['3.12']
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
      - name: Install uv
        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9
        with:
          version: '0.9.15'
          enable-cache: false
      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
        with:
          python-version: ${{ matrix.python-version }}
      - name: Install Python dependencies
        run: python scripts/bootstrap_env.py dev-test
      - name: Download coverage shards
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c
        with:
          path: coverage-shards
      - name: Combine coverage and enforce threshold
        run: |
          cp coverage-shards/coverage-linux-a/coverage-shard-a.dat .coverage.a
          cp coverage-shards/coverage-linux-b/coverage-shard-b.dat .coverage.b
          cp coverage-shards/coverage-linux-c/coverage-shard-c.dat .coverage.c
          cp coverage-shards/coverage-linux-d/coverage-shard-d.dat .coverage.d
          cp coverage-shards/coverage-linux-g/coverage-shard-g.dat .coverage.g
          cp coverage-shards/coverage-linux-e/coverage-shard-e.dat .coverage.e
          cp coverage-shards/coverage-linux-extended/coverage-shard-extended.dat .coverage.extended
          uv run coverage combine .coverage.a .coverage.b .coverage.c .coverage.d .coverage.g .coverage.e .coverage.extended
          uv run coverage report --fail-under=74
          uv run coverage xml -o coverage.xml
      - name: Upload coverage to Codecov
        if: always()
        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f
        with:
          use_oidc: true
          files: ./coverage.xml
          flags: python-linux
          name: python-linux
          fail_ci_if_error: false
          verbose: true

  gates-on-linux-extended:
    name: Python Gates on Linux (extended)
    runs-on: ubuntu-24.04
    timeout-minutes: 30
    strategy:
      matrix:
        python-version: ['3.12']
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
      - name: Install uv
        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9
        with:
          version: '0.9.15'
          enable-cache: false
      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
        with:
          python-version: ${{ matrix.python-version }}
      - name: Resolve lockfile for runner
        run: uv lock
      - name: Install Python dependencies
        run: python scripts/bootstrap_env.py dev-test
      - name: Verify optional imports
        run: python backend/scripts/verify/verify_optional_imports.py
      - name: Compile backend (syntax gate)
        run: uv run python -m compileall backend
      - name: Run integration, e2e, and stress tests
        run: >-
          PYTHONPATH=".:$PYTHONPATH" uv run pytest --maxfail=1 -q -n 2
          --cov=backend --cov-fail-under=0
          backend/tests/integration backend/tests/e2e backend/tests/stress
      - name: Stage coverage data
        run: cp .coverage coverage-shard-extended.dat
      - name: Upload coverage data
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
        with:
          name: coverage-linux-extended
          path: coverage-shard-extended.dat
          if-no-files-found: error

  gates-on-linux-py313:
    name: Python Gates on Linux (3.13 unit)
    runs-on: ubuntu-24.04
    timeout-minutes: 30
    needs: gates-on-linux-extended
    strategy:
      matrix:
        python-version: ['3.13']
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
      - name: Install uv
        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9
        with:
          version: '0.9.15'
          enable-cache: false
      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
        with:
          python-version: ${{ matrix.python-version }}
      - name: Resolve lockfile for runner
        run: uv lock
      - name: Install Python dependencies
        run: python scripts/bootstrap_env.py dev-test
      - name: Verify optional imports
        run: python backend/scripts/verify/verify_optional_imports.py
      - name: Compile backend (syntax gate)
        run: uv run python -m compileall backend
      - name: Run unit tests (Python 3.13)
        run: PYTHONPATH=".:$PYTHONPATH" uv run pytest -q backend/tests/unit

  gates-on-windows:
    name: Python Gates on Windows
    runs-on: windows-latest
    strategy:
      fail-fast: false
      matrix:
        python-version: ['3.12', '3.13']
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
      - name: Install uv
        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9
        with:
          version: '0.9.15'
          enable-cache: true
      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
        with:
          python-version: ${{ matrix.python-version }}
      - name: Resolve lockfile for runner
        run: uv lock
      - name: Install Python dependencies
        run: python scripts/bootstrap_env.py dev-test
      - name: Verify optional imports
        run: python backend/scripts/verify/verify_optional_imports.py
      - name: Compile backend (syntax gate)
        run: uv run python -m compileall backend
      - name: Run unit tests (full corpus)
        run: uv run pytest -q backend/tests/unit
        env:
          PYTHONPATH: '.;$env:PYTHONPATH'

  gates-on-windows-extended:
    name: Python Gates on Windows (extended)
    runs-on: windows-latest
    timeout-minutes: 45
    needs: gates-on-windows
    strategy:
      matrix:
        python-version: ['3.12']
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
      - name: Install uv
        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9
        with:
          version: '0.9.15'
          enable-cache: true
      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
        with:
          python-version: ${{ matrix.python-version }}
      - name: Resolve lockfile for runner
        run: uv lock
      - name: Install Python dependencies
        run: python scripts/bootstrap_env.py dev-test
      - name: Verify optional imports
        run: python backend/scripts/verify/verify_optional_imports.py
      - name: Compile backend (syntax gate)
        run: uv run python -m compileall backend
      - name: Run integration, e2e, and stress tests
        run: uv run pytest --maxfail=1 -q -n 2 backend/tests/integration backend/tests/e2e backend/tests/stress
        env:
          PYTHONPATH: '.;$env:PYTHONPATH'

  heavy-tests:
    name: Heavy / Integration Tests
    runs-on: ubuntu-24.04
    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' || github.ref == 'refs/heads/main'
    strategy:
      matrix:
        python-version: ['3.12']
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
      - name: Install uv
        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9
        with:
          version: '0.9.15'
          enable-cache: true
      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
        with:
          python-version: ${{ matrix.python-version }}
      - name: Install Python dependencies
        run: python scripts/bootstrap_env.py dev-test
      - name: Resolve lockfile for runner
        run: uv lock
      - name: Verify optional imports
        run: python backend/scripts/verify/verify_optional_imports.py
      - name: Compile backend (syntax gate)
        run: uv run python -m compileall backend
      - name: Run heavy / integration tests
        run: PYTHONPATH=".:$PYTHONPATH" uv run pytest backend/tests -m "heavy or integration or benchmark" -vv

  gates-on-macos:
    name: Python Gates on macOS
    runs-on: macos-latest
    timeout-minutes: 30
    strategy:
      fail-fast: false
      matrix:
        python-version: ['3.12']
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
      - name: Install uv
        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9
        with:
          version: '0.9.15'
          enable-cache: true
      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
        with:
          python-version: ${{ matrix.python-version }}
      - name: Resolve lockfile for runner
        run: uv lock
      - name: Install Python dependencies
        run: python scripts/bootstrap_env.py dev-test
      - name: Verify optional imports
        run: python backend/scripts/verify/verify_optional_imports.py
      - name: Compile backend (syntax gate)
        run: uv run python -m compileall backend
      - name: Run unit tests (full corpus)
        run: PYTHONPATH=".:$PYTHONPATH" uv run pytest -q backend/tests/unit

  gates-on-macos-extended:
    name: Python Gates on macOS (extended)
    runs-on: macos-latest
    timeout-minutes: 45
    needs: gates-on-macos
    strategy:
      matrix:
        python-version: ['3.12']
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
      - name: Install uv
        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9
        with:
          version: '0.9.15'
          enable-cache: true
      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
        with:
          python-version: ${{ matrix.python-version }}
      - name: Resolve lockfile for runner
        run: uv lock
      - name: Install Python dependencies
        run: python scripts/bootstrap_env.py dev-test
      - name: Verify optional imports
        run: python backend/scripts/verify/verify_optional_imports.py
      - name: Compile backend (syntax gate)
        run: uv run python -m compileall backend
      - name: Run integration, e2e, and stress tests
        run: PYTHONPATH=".:$PYTHONPATH" uv run pytest --maxfail=1 -q -n 2 backend/tests/integration backend/tests/e2e backend/tests/stress