deepagents/.github/workflows/_test.yml

# Reusable workflow for running unit tests

name: "🧪 Unit Testing"

on:
  workflow_call:
    inputs:
      working-directory:
        required: true
        type: string
        description: "From which folder this pipeline executes"
      python-versions:
        required: true
        type: string
        description: "JSON array of Python versions (must be quoted strings; e.g. '[\"3.11\",\"3.12\"]' — NOT '[3.11, 3.12]') to test on the primary OS"
      os:
        required: false
        type: string
        default: "ubuntu-latest"
        description: "Primary runner OS (e.g. ubuntu-latest); paired with every python-versions entry"
      extra-configurations:
        required: false
        type: string
        default: "[]"
        description: "JSON array of additional {python-version, os} legs (e.g. '[{\"python-version\":\"3.13\",\"os\":\"windows-latest\"}]')"
      coverage-python-version:
        required: false
        type: string
        default: ""
        description: "Python version of the leg on which to collect coverage; empty disables coverage for all legs"
      coverage-os:
        required: false
        type: string
        default: ""
        description: "Runner OS of the coverage leg; empty defaults to the primary 'os' input"

permissions:
  contents: read

env:
  UV_NO_SYNC: "true"
  UV_FROZEN: "true"

jobs:
  validate-inputs:
    runs-on: ubuntu-latest
    timeout-minutes: 1
    steps:
      - name: "🔍 Validate matrix inputs and coverage leg"
        shell: bash
        env:
          VERSIONS: ${{ inputs.python-versions }}
          EXTRAS: ${{ inputs.extra-configurations }}
          PRIMARY_OS: ${{ inputs.os }}
          COV_PY: ${{ inputs.coverage-python-version }}
          COV_OS: ${{ inputs.coverage-os || inputs.os }}
        run: |
          if ! echo "$VERSIONS" | jq -e 'type == "array" and all(.[]; type == "string")' > /dev/null; then
            echo "::error::python-versions must be a JSON array of quoted strings (got: $VERSIONS)"
            exit 1
          fi
          if ! echo "$EXTRAS" | jq -e 'type == "array" and all(.[]; has("python-version") and has("os") and (.["python-version"] | type == "string") and (.os | type == "string"))' > /dev/null; then
            echo "::error::extra-configurations must be a JSON array of objects each with string 'python-version' and 'os' keys (got: $EXTRAS)"
            exit 1
          fi
          if [ -z "$COV_PY" ]; then
            echo "coverage-python-version is empty; coverage disabled for all legs"
            exit 0
          fi
          LEGS=$(jq -nc \
            --argjson versions "$VERSIONS" \
            --arg primary_os "$PRIMARY_OS" \
            --argjson extras "$EXTRAS" \
            '($versions | map({"python-version": ., "os": $primary_os})) + $extras')
          if ! echo "$LEGS" | jq -e --arg py "$COV_PY" --arg os "$COV_OS" \
            'any(.[]; .["python-version"] == $py and .os == $os)' > /dev/null; then
            echo "::error::coverage leg (python=$COV_PY, os=$COV_OS) is not among configured legs: $LEGS"
            exit 1
          fi
          echo "Coverage will be collected on Python $COV_PY / $COV_OS"

  build:
    needs: validate-inputs
    defaults:
      run:
        working-directory: ${{ inputs.working-directory }}
    runs-on: ${{ matrix.os }}
    timeout-minutes: 20
    strategy:
      matrix:
        python-version: ${{ fromJSON(inputs.python-versions) }}
        os:
          - ${{ inputs.os }}
        include: ${{ fromJSON(inputs.extra-configurations) }}
      fail-fast: false
    name: "Python ${{ matrix.python-version }} (${{ matrix.os }})"
    steps:
      - name: "📋 Checkout Code"
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

      - name: "🐍 Set up Python ${{ matrix.python-version }} + UV"
        uses: "./.github/actions/uv_setup"
        id: setup-python
        with:
          python-version: ${{ matrix.python-version }}
          cache-suffix: test-${{ inputs.working-directory }}
          working-directory: ${{ inputs.working-directory }}

      - name: "📦 Install Test Dependencies"
        shell: bash
        run: uv sync --group test

      - name: "🔍 Install ripgrep"
        if: runner.os == 'Linux'
        shell: bash
        run: sudo apt-get update && sudo apt-get install -y ripgrep

      - name: "🧪 Run Unit Tests"
        if: runner.os != 'Windows'
        shell: bash
        env:
          RUN_SANDBOX_TESTS: "true"
          PY: ${{ matrix.python-version }}
          PY_OS: ${{ matrix.os }}
          COV_PY: ${{ inputs.coverage-python-version }}
          COV_OS: ${{ inputs.coverage-os || inputs.os }}
        run: |
          if [ -n "$COV_PY" ] && [ "$PY" = "$COV_PY" ] && [ "$PY_OS" = "$COV_OS" ]; then
            make test PYTEST_EXTRA=-q
          else
            echo "Coverage disabled for Python $PY / $PY_OS (target=$COV_PY / $COV_OS)"
            make test COV_ARGS= PYTEST_EXTRA=-q
          fi

      # Windows cannot run `make test` because `LocalShellBackend` requires POSIX
      # `sh`, so the sandbox matrix is skipped here (`RUN_SANDBOX_TESTS` is
      # unset) and pytest is invoked directly instead of via the Makefile.
      # Non-sandbox unit tests must still pass cross-platform; any new flags
      # added to `make test` should be mirrored here if they are expected to
      # apply on Windows.
      - name: "🧪 Run Unit Tests (Windows)"
        if: runner.os == 'Windows'
        shell: bash
        env:
          PY: ${{ matrix.python-version }}
          PY_OS: ${{ matrix.os }}
          COV_PY: ${{ inputs.coverage-python-version }}
          COV_OS: ${{ inputs.coverage-os || inputs.os }}
        run: |
          if [ -n "$COV_PY" ] && [ "$PY" = "$COV_PY" ] && [ "$PY_OS" = "$COV_OS" ]; then
            uv run --group test pytest -n auto -vvv tests/unit_tests/ --cov=deepagents --cov-report=term-missing
          else
            echo "Coverage disabled for Python $PY / $PY_OS (target=$COV_PY / $COV_OS)"
            uv run --group test pytest -n auto -vvv tests/unit_tests/
          fi

      - name: "🧹 Verify Clean Working Directory"
        shell: bash
        run: |
          set -eu
          STATUS="$(git status)"
          echo "$STATUS"
          echo "$STATUS" | grep 'nothing to commit, working tree clean'