bot-bottle/.gitea/workflows/test.yml

# Run the project's test suite on every PR push and on push to main.
#
# The suite uses stdlib `unittest` discovery — no external Python
# dependencies are required to execute it. Tests are split by directory:
#
#   tests/unit/         — pure unit tests; always run
#   tests/integration/  — need a reachable backend; skip cleanly when
#                         the backend isn't available on the runner
#   tests/canaries/     — upstream regression canaries; run on a separate
#                         schedule (see canaries.yml), not here
#
# Integration tests run once per backend in separate jobs. Each job sets
# BOT_BOTTLE_BACKEND explicitly so the test suite uses the right backend.
# Backends that aren't available on the runner fail the preflight step
# rather than silently skipping inside the test output.

name: test

on:
  push:
    branches:
      - main
    paths:
      - '**.py'
      - '.gitea/workflows/**.yml'
      - 'scripts/**'
      - 'README.md'
      # Dockerfiles and pyproject.toml are baked into the infra rootfs; a
      # change here alters what the integration/coverage jobs build locally.
      - 'Dockerfile*'
      - 'pyproject.toml'
  pull_request:
    paths:
      - '**.py'
      - '.gitea/workflows/**.yml'
      - 'scripts/**'
      - 'README.md'
      - 'Dockerfile*'
      - 'pyproject.toml'
  workflow_dispatch:

jobs:
  stage-firecracker-inputs:
    runs-on: [self-hosted, kvm]
    # Same guard as the other KVM-runner jobs: don't spin the privileged
    # runner for fork PRs (this only copies a non-secret static binary, but
    # keep the posture consistent — build-infra/integration/coverage all
    # depend on it, so gating here gates the whole Firecracker chain).
    if: >-
      github.event_name == 'push' ||
      github.event_name == 'workflow_dispatch' ||
      (github.event_name == 'pull_request' &&
       github.event.pull_request.head.repo.full_name == github.repository)
    steps:
      - name: Stage the provisioned static dropbear
        run: |
          mkdir -p firecracker-inputs
          cp /var/cache/bot-bottle-fc/dropbear firecracker-inputs/dropbear

      - name: Upload Firecracker build inputs
        uses: actions/upload-artifact@v3
        with:
          name: firecracker-inputs
          path: firecracker-inputs/

  build-infra:
    needs: stage-firecracker-inputs
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Download Firecracker build inputs
        uses: actions/download-artifact@v3
        with:
          name: firecracker-inputs
          path: firecracker-inputs

      - name: Build infra candidate from this checkout
        env:
          BOT_BOTTLE_FC_DROPBEAR: ${{ github.workspace }}/firecracker-inputs/dropbear
        run: python3 -m bot_bottle.backend.firecracker.publish_infra --output infra-candidate

      - name: Upload infra candidate
        uses: actions/upload-artifact@v3
        with:
          name: infra-candidate
          path: infra-candidate/

  unit:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      # No actions/setup-python: the runner image already ships Python 3.12,
      # and older act_runner engines mishandle setup-python's PATH (coverage
      # lands in one interpreter, `python3` resolves to another). Install
      # straight into the ephemeral job container's system Python —
      # --break-system-packages is safe because the container is disposable.
      - name: Install dev requirements
        run: python3 -m pip install --break-system-packages -r requirements-dev.txt

      - name: Run unit tests
        run: python3 -m coverage run -m unittest discover -t . -s tests/unit -v

      - name: Report unit coverage
        run: python3 -m coverage report -m

  integration-docker:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      # No actions/setup-python (see the note in the `unit` job); the
      # container's system Python 3.12 runs the stdlib test suite directly.
      - name: Show environment
        run: |
          python3 --version
          if command -v docker >/dev/null 2>&1; then
            docker version || true
          else
            echo "docker not on PATH — integration tests will skip"
          fi

      - name: Run integration tests (docker)
        env:
          BOT_BOTTLE_BACKEND: docker
        run: python3 -m unittest discover -t . -s tests/integration -v

  # Integration tests against the Firecracker backend. Runs on a self-hosted
  # KVM runner (label `kvm`) where /dev/kvm and the TAP/nft pool are available.
  #
  # Restricted to same-repo PRs, push to main, and workflow_dispatch — fork
  # PRs don't execute untrusted code on the privileged runner.
  #
  # Runner prerequisites (provision once; see README "Firecracker on Linux"):
  # `firecracker` on PATH, `/dev/kvm` accessible, cached kernel +
  # static dropbear, and the pool as a persistent systemd unit.
  integration-firecracker:
    needs: build-infra
    runs-on: [self-hosted, kvm]
    if: >-
      github.event_name == 'push' ||
      github.event_name == 'workflow_dispatch' ||
      (github.event_name == 'pull_request' &&
       github.event.pull_request.head.repo.full_name == github.repository)
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Preflight — Firecracker host is ready
        run: |
          command -v firecracker >/dev/null || {
            echo "firecracker not on PATH — provision the runner (README: Firecracker on Linux)"; exit 1; }
          test -e /dev/kvm || { echo "/dev/kvm missing — KVM not available on this runner"; exit 1; }
          # `backend status` exits non-zero unless the TAP pool is up + no
          # range overlap; it prints the exact `backend setup` fix.
          python3 cli.py backend status --backend=firecracker

      - name: Download the candidate built from this checkout
        uses: actions/download-artifact@v3
        with:
          name: infra-candidate
          path: infra-candidate

      - name: Replace the persistent infra VM with the candidate
        run: python3 -c 'from bot_bottle.backend.firecracker import infra_vm; infra_vm.stop()'

      # No dev-requirements install: the integration suite runs on stdlib
      # `unittest` (pylint/pyright are lint.yml's concern, not this job's),
      # and the self-hosted runner's Nix python env has no `pip` module
      # (`python3 -m pip` → "No module named pip"). Nothing to install.
      - name: Run integration tests (firecracker)
        env:
          BOT_BOTTLE_BACKEND: firecracker
          BOT_BOTTLE_INFRA_ARTIFACT_DIR: ${{ github.workspace }}/infra-candidate
        run: python3 -m unittest discover -t . -s tests/integration -v

  # Combined unit+integration coverage + the diff-coverage gate (the hard
  # gate: new/changed lines >= 90%). See docs/decisions/0004-coverage-policy.md.
  #
  # This runs on a self-hosted KVM runner (label `kvm`), NOT ubuntu-latest,
  # because the Firecracker backend's subprocess/VM orchestration
  # (launch/boot/SSH/isolation-probe) is covered by the integration suite,
  # and that suite needs `/dev/kvm` + the provisioned TAP/nft pool — which a
  # container-based runner doesn't have. On such a runner the firecracker
  # integration test skips and its ~230 orchestration lines read as
  # uncovered, so the gate can't pass there.
  #
  # Restricted to the same events as integration-firecracker (same-repo PRs,
  # push, workflow_dispatch) for the same security reason.
  #
  # See #414 for the planned follow-up: artifact-based coverage combination
  # (run tests once in their respective jobs, combine .coverage files here).
  #
  # build-infra creates one candidate from the checkout. This job boots that
  # same candidate after integration-firecracker has exercised it; the main
  # push path publishes the identical bytes only after every required job.
  coverage:
    needs: [build-infra, integration-firecracker]
    timeout-minutes: 15
    runs-on: [self-hosted, kvm]
    if: >-
      github.event_name == 'push' ||
      github.event_name == 'workflow_dispatch' ||
      (github.event_name == 'pull_request' &&
       github.event.pull_request.head.repo.full_name == github.repository)
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Preflight — Firecracker host is ready
        run: |
          command -v firecracker >/dev/null || {
            echo "firecracker not on PATH — provision the runner (README: Firecracker on Linux)"; exit 1; }
          test -e /dev/kvm || { echo "/dev/kvm missing — KVM not available on this runner"; exit 1; }
          # `backend status` exits non-zero unless the TAP pool is up + no
          # range overlap; it prints the exact `backend setup` fix.
          python3 cli.py backend status --backend=firecracker

      - name: Download the candidate already exercised by integration
        uses: actions/download-artifact@v3
        with:
          name: infra-candidate
          path: infra-candidate

      # No dev-requirements install: `coverage` is already provided by the
      # self-hosted runner's Nix python env, and that env has no `pip`
      # module to install into anyway. `scripts/coverage.sh` +
      # `diff_coverage.py` need only `coverage` (not pylint/pyright).
      - name: Combined coverage (unit + integration, incl. firecracker)
        env:
          BOT_BOTTLE_CI_INFRA_ARTIFACT_DIR: ${{ github.workspace }}/infra-candidate
        run: PYTHON=python3 bash scripts/coverage.sh critical

      - name: Diff-coverage gate (changed lines >= 90%)
        run: |
          git fetch --no-tags origin main:refs/remotes/origin/main
          python3 scripts/diff_coverage.py --base origin/main --min 90

  publish-infra:
    needs: [stage-firecracker-inputs, build-infra, unit, integration-docker, integration-firecracker, coverage]
    runs-on: ubuntu-latest
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    steps:
      - name: Checkout the tested revision
        uses: actions/checkout@v4

      - name: Download the tested candidate
        uses: actions/download-artifact@v3
        with:
          name: infra-candidate
          path: infra-candidate

      # publish_infra re-derives the version from the checkout to confirm the
      # bundle matches before uploading, and the version hashes the dropbear
      # bytes. Stage the SAME dropbear build-infra used, or the recheck
      # computes a "<missing>"-dropbear version and rejects the candidate.
      - name: Download the staged dropbear (matches build-infra's version)
        uses: actions/download-artifact@v3
        with:
          name: firecracker-inputs
          path: firecracker-inputs

      - name: Publish the tested candidate
        env:
          BOT_BOTTLE_INFRA_ARTIFACT_TOKEN: ${{ secrets.BOT_BOTTLE_INFRA_ARTIFACT_TOKEN }}
          BOT_BOTTLE_FC_DROPBEAR: ${{ github.workspace }}/firecracker-inputs/dropbear
        run: python3 -m bot_bottle.backend.firecracker.publish_infra --publish-dir infra-candidate