_python-react-tests.yml

name: Reusable Python+React Test Suite

# Internal building block: the backend/frontend/e2e/api-freshness test jobs
# shared by python-react-ci.yml and python-react-publish.yml. Each suite runs
# as a checks job plus N shard jobs, and one small keeper per suite holds the
# required check name and fails unless all of them passed. Consumers
# don't call this directly — the CI and publish workflows wrap it. The
# leading underscore marks it internal.
#
# python-react-ci.yml and python-react-publish.yml call this with a full
# owner/repo path pinned to their own release tag, NOT a `./` local path:
# a `./` reference inside a cross-repo-called reusable workflow resolves
# against the CONSUMER's repository (no such file) and 0s startup_failures.
# That @ref must be bumped on every release to stay in lockstep.

on:
  workflow_call:
    inputs:
      python-version:
        type: string
        default: "3.14"
      bun-version-file:
        type: string
        default: ".bun-version"
      bun-version:
        # Escape hatch — leave empty to use bun-version-file.
        type: string
        default: ""
      node-version-file:
        # vitest, eslint, tsc and Playwright run on Node even under `bun run`
        # (their bins are `#!/usr/bin/env node`). Without this they got the
        # runner image's default Node, which drifts from the consumer's.
        type: string
        default: ".nvmrc"
      node-version:
        # Escape hatch: leave empty to use node-version-file.
        type: string
        default: ""
      enable-e2e:
        type: boolean
        default: true
      enable-translations:
        type: boolean
        default: false
      enable-bootstrap-token:
        type: boolean
        default: false
      enable-api-freshness-check:
        type: boolean
        default: true
      backend-test-shards:
        # Runners the backend pytest run is split across, 1-6. Above 1 the
        # consumer's conftest needs the shard hook (README, "Test shards").
        type: number
        default: 1
      frontend-test-shards:
        # Runners vitest is split across, 1-6. Uses vitest's own --shard.
        type: number
        default: 1
      e2e-test-shards:
        # Runners Playwright is split across, 1-6. Uses Playwright's own --shard.
        type: number
        default: 1
      runner-os:
        type: string
        default: ubuntu-latest
      security-tripwire-script:
        type: string
        default: ""

permissions:
  contents: read

jobs:
  backend-checks:
    name: Backend Checks
    runs-on: ${{ inputs.runner-os }}
    timeout-minutes: 15

    steps:
      - name: Checkout code
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Set up Python
        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
        with:
          python-version: ${{ inputs.python-version }}

      - name: Install uv
        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v8
        with:
          enable-cache: true
          cache-dependency-glob: 'backend/uv.lock'

      - name: Install dependencies
        run: |
          cd backend
          uv sync --frozen --all-extras

      - name: Run ruff linter
        run: cd backend && uv run ruff check .

      - name: Run ruff formatter check
        run: cd backend && uv run ruff format --check .

      - name: Run pyright type checking
        run: cd backend && PYTHONPATH=. uv run pyright

      - name: Security tripwire
        if: inputs.security-tripwire-script != ''
        # Through env, like every other consumer input (R1-F4). v1.6.0
        # interpolated it straight into the shell.
        env:
          TRIPWIRE_SCRIPT: ${{ inputs.security-tripwire-script }}
        run: bash "$TRIPWIRE_SCRIPT"

  backend-tests:
    name: Backend Tests (${{ matrix.shard }}/${{ strategy.job-total }})
    runs-on: ${{ inputs.runner-os }}
    timeout-minutes: 25
    strategy:
      fail-fast: false
      matrix:
        # Expressions can't add, so the shard list is looked up. Slot 0 is
        # empty on purpose: zero shards fails the run instead of running nothing.
        shard: ${{ fromJSON('[[],[1],[1,2],[1,2,3],[1,2,3,4],[1,2,3,4,5],[1,2,3,4,5,6]]')[inputs.backend-test-shards] }}

    steps:
      - name: Checkout code
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Set up Python
        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
        with:
          python-version: ${{ inputs.python-version }}

      - name: Install uv
        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v8
        with:
          enable-cache: true
          cache-dependency-glob: 'backend/uv.lock'

      - name: Install dependencies
        run: |
          cd backend
          uv sync --frozen --all-extras

      - name: Run pytest
        env:
          PYTEST_SHARD_INDEX: ${{ matrix.shard }}
          PYTEST_SHARD_COUNT: ${{ strategy.job-total }}
          PYTEST_SHARD_REPORT: pytest-shard-report.json
        run: |
          cd backend
          timeout 20m uv run pytest tests/ -v --tb=short

      - name: Upload shard report
        if: ${{ !cancelled() && inputs.backend-test-shards > 1 }}
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7
        with:
          name: pytest-shard-report-backend-${{ matrix.shard }}
          path: backend/pytest-shard-report.json
          if-no-files-found: error
          # A "re-run failed jobs" shard uploads the same name again. The
          # shards that passed don't, so theirs has to last past a weekend.
          overwrite: true
          retention-days: 7

  test-backend:
    name: Backend Tests
    # Holds the required check. always() because a skipped job reports
    # Success, which would let a PR merge past red or cancelled shards.
    if: always()
    needs: [backend-checks, backend-tests]
    runs-on: ${{ inputs.runner-os }}
    timeout-minutes: 5

    steps:
      - name: Every backend job passed
        env:
          CHECKS: ${{ needs.backend-checks.result }}
          TESTS: ${{ needs.backend-tests.result }}
        run: |
          echo "Backend Checks: $CHECKS, Backend Tests shards: $TESTS"
          test "$CHECKS" = success && test "$TESTS" = success

      - name: Download shard reports
        if: inputs.backend-test-shards > 1
        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          pattern: pytest-shard-report-backend-*
          path: shard-reports

      - name: Every test module ran exactly once
        if: inputs.backend-test-shards > 1
        uses: $/.github/actions/verify-pytest-shards
        with:
          reports-dir: shard-reports
          count: ${{ inputs.backend-test-shards }}

  frontend-checks:
    name: Frontend Checks
    runs-on: ${{ inputs.runner-os }}
    timeout-minutes: 15

    steps:
      - name: Checkout code
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Set up Bun (from version-file)
        if: inputs.bun-version == ''
        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
        with:
          bun-version-file: ${{ inputs.bun-version-file }}

      - name: Set up Bun (from explicit override)
        if: inputs.bun-version != ''
        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
        with:
          bun-version: ${{ inputs.bun-version }}

      - name: Set up Node (from version-file)
        if: inputs.node-version == ''
        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version-file: ${{ inputs.node-version-file }}
          package-manager-cache: false

      - name: Set up Node (from explicit override)
        if: inputs.node-version != ''
        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version: ${{ inputs.node-version }}
          package-manager-cache: false

      - name: Install dependencies
        run: |
          cd frontend
          if [ "$GITHUB_ACTOR" = "dependabot[bot]" ]; then bun install; else bun install --frozen-lockfile; fi

      - name: Run TypeScript type checking
        run: cd frontend && bun run type-check

      - name: Run linter
        run: cd frontend && bun run lint

      - name: Validate translation keys
        if: inputs.enable-translations
        run: cd frontend && bun run validate:translations

  frontend-tests:
    name: Frontend Tests (${{ matrix.shard }}/${{ strategy.job-total }})
    runs-on: ${{ inputs.runner-os }}
    timeout-minutes: 15
    strategy:
      fail-fast: false
      matrix:
        shard: ${{ fromJSON('[[],[1],[1,2],[1,2,3],[1,2,3,4],[1,2,3,4,5],[1,2,3,4,5,6]]')[inputs.frontend-test-shards] }}

    steps:
      - name: Checkout code
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Set up Bun (from version-file)
        if: inputs.bun-version == ''
        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
        with:
          bun-version-file: ${{ inputs.bun-version-file }}

      - name: Set up Bun (from explicit override)
        if: inputs.bun-version != ''
        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
        with:
          bun-version: ${{ inputs.bun-version }}

      - name: Set up Node (from version-file)
        if: inputs.node-version == ''
        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version-file: ${{ inputs.node-version-file }}
          package-manager-cache: false

      - name: Set up Node (from explicit override)
        if: inputs.node-version != ''
        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version: ${{ inputs.node-version }}
          package-manager-cache: false

      - name: Install dependencies
        run: |
          cd frontend
          if [ "$GITHUB_ACTOR" = "dependabot[bot]" ]; then bun install; else bun install --frozen-lockfile; fi

      - name: Run tests
        env:
          SHARD: ${{ matrix.shard }}/${{ strategy.job-total }}
        run: cd frontend && bun run test:run --shard="$SHARD"

  test-frontend:
    name: Frontend Tests
    # Holds the required check; always() for the same reason as test-backend.
    if: always()
    needs: [frontend-checks, frontend-tests]
    runs-on: ${{ inputs.runner-os }}
    timeout-minutes: 5

    steps:
      - name: Every frontend job passed
        env:
          CHECKS: ${{ needs.frontend-checks.result }}
          TESTS: ${{ needs.frontend-tests.result }}
        run: |
          echo "Frontend Checks: $CHECKS, Frontend Tests shards: $TESTS"
          test "$CHECKS" = success && test "$TESTS" = success

  e2e-tests:
    name: E2E Tests (${{ matrix.shard }}/${{ strategy.job-total }})
    if: inputs.enable-e2e
    runs-on: ${{ inputs.runner-os }}
    timeout-minutes: 20
    # No needs. E2E builds everything it uses itself, so waiting on the unit
    # jobs only bought fail-fast, and put E2E after Frontend on every green run.
    strategy:
      fail-fast: false
      matrix:
        shard: ${{ fromJSON('[[],[1],[1,2],[1,2,3],[1,2,3,4],[1,2,3,4,5],[1,2,3,4,5,6]]')[inputs.e2e-test-shards] }}

    steps:
      - name: Checkout code
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Set up Python
        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
        with:
          python-version: ${{ inputs.python-version }}

      - name: Install uv
        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v8
        with:
          enable-cache: true
          cache-dependency-glob: 'backend/uv.lock'

      - name: Install backend dependencies
        run: cd backend && uv sync --frozen --all-extras

      - name: Set up Bun (from version-file)
        if: inputs.bun-version == ''
        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
        with:
          bun-version-file: ${{ inputs.bun-version-file }}

      - name: Set up Bun (from explicit override)
        if: inputs.bun-version != ''
        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
        with:
          bun-version: ${{ inputs.bun-version }}

      - name: Set up Node (from version-file)
        if: inputs.node-version == ''
        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version-file: ${{ inputs.node-version-file }}
          package-manager-cache: false

      - name: Set up Node (from explicit override)
        if: inputs.node-version != ''
        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version: ${{ inputs.node-version }}
          package-manager-cache: false

      - name: Install frontend dependencies
        run: |
          cd frontend
          if [ "$GITHUB_ACTOR" = "dependabot[bot]" ]; then bun install; else bun install --frozen-lockfile; fi

      - name: Install Playwright browsers
        run: cd frontend && bunx playwright install chromium --with-deps

      - name: Run E2E tests
        run: cd frontend && bun run e2e --shard="$SHARD"
        env:
          CI: true
          SHARD: ${{ matrix.shard }}/${{ strategy.job-total }}
          VULNFORGE_BOOTSTRAP_TOKEN: ${{ inputs.enable-bootstrap-token && 'e2e-ci-test-token' || '' }}

      - name: Upload Playwright report
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7
        if: ${{ !cancelled() }}
        with:
          name: playwright-report-${{ matrix.shard }}
          path: frontend/playwright-report/
          retention-days: 14

      - name: Upload test results
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7
        if: ${{ !cancelled() }}
        with:
          name: playwright-results-${{ matrix.shard }}
          path: frontend/test-results/
          retention-days: 7

  test-e2e:
    name: E2E Tests
    # Holds the required check; always() for the same reason as test-backend.
    if: always() && inputs.enable-e2e
    needs: [e2e-tests]
    runs-on: ${{ inputs.runner-os }}
    timeout-minutes: 5

    steps:
      - name: Every E2E shard passed
        env:
          TESTS: ${{ needs.e2e-tests.result }}
        run: |
          echo "E2E Tests shards: $TESTS"
          test "$TESTS" = success

  api-types-freshness:
    name: API Types Freshness
    if: inputs.enable-api-freshness-check
    runs-on: ${{ inputs.runner-os }}
    timeout-minutes: 15
    needs: [test-backend]

    steps:
      - name: Checkout code
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Set up Python
        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
        with:
          python-version: ${{ inputs.python-version }}

      - name: Install uv
        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v8
        with:
          enable-cache: true
          cache-dependency-glob: 'backend/uv.lock'

      - name: Install backend dependencies
        run: cd backend && uv sync --frozen --all-extras

      - name: Set up Bun (from version-file)
        if: inputs.bun-version == ''
        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
        with:
          bun-version-file: ${{ inputs.bun-version-file }}

      - name: Set up Bun (from explicit override)
        if: inputs.bun-version != ''
        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
        with:
          bun-version: ${{ inputs.bun-version }}

      - name: Set up Node (from version-file)
        if: inputs.node-version == ''
        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version-file: ${{ inputs.node-version-file }}
          package-manager-cache: false

      - name: Set up Node (from explicit override)
        if: inputs.node-version != ''
        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version: ${{ inputs.node-version }}
          package-manager-cache: false

      - name: Install frontend dependencies
        run: |
          cd frontend
          if [ "$GITHUB_ACTOR" = "dependabot[bot]" ]; then bun install; else bun install --frozen-lockfile; fi

      - name: Check API types freshness
        run: cd frontend && bun run check:api-freshness