Перейти к основному содержимому

Technical Design: High-Fidelity Testing & Canary Package Pattern

1. Мотивация​

При разработке системных инструментов, таких как HSM, критически важно гарантировать, что конфигурация (переменные окружения, зависимости) не просто «собрана в словарь», а реально доходит до конечного исполнителя:

  • менеджера библиотек (уровень 1)
  • системы сборки библиотек (уровень 2)
  • рантайма сервиса (уровень 3).

Традиционные Unit-тесты проверяют только «намерение» (Intent) — корректность формирования данных в коде.

При High-Fidelity Testing проверяется «эффект» (Effect) — реальное изменение состояния системы.

2. Паттерн «Библиотека-канарейка» (Canary Library)​

2.1. Концепция​

«Канарейка» — это минимальная Python-библиотека, которая служит индикатором целостности среды. Его единственная задача — вызвать ошибку сборки или запуска, если условия среды не соответствуют ожидаемым.

2.2. Уровни проверки​

Уровень 1: Intent (Намерение)​

Проверка формирования данных внутри кода HSM.

  • Инструмент: Стандартные Unit-тесты (pytest).
  • Цель: Убедиться, что SyncEngine правильно собрал итоговый словарь env_vars и список dependencies из всех источников (Manifest + Source + Implies), включая механизм Implication Merging.

Уровень 2: Build-time (Сборка) — High-Fidelity​

Проверяет путь переменных окружения через всю цепочку: HSM SyncEngine -> Adapter -> Subprocess -> uv/pixi -> Build Backend (Hatchling).

  • Зачем: Многие переменные (например, CUDA_HOME, API_KEYS для приватных индексов) нужны именно в момент установки. Если они не дойдут до процесса сборки, пакет не будет установлен.
  • Реализация: Использование бэкенда Hatchling с build-hooks. Код хука проверяет os.getenv() и выбрасывает RuntimeError, если переменная отсутствует.

Уровень 3: Runtime (Выполнение) — High-Fidelity​

Проверяет сохранность контекста после успешной установки.

  • Зачем: Убедиться, что рантайм сервиса (например, запущенный через uv run) наследует те же переменные, что были заданы при синхронизации.
  • Реализация: Проверка os.getenv() в entrypoint или __init__.py пакета.

3. Применимость для «закрытых» рантаймов​

Такие инструменты, как uv_build, могут не позволять запускать произвольный код во время сборки (для скорости). Однако:

  1. Если мы доказали на примере «прозрачного» Hatchling, что HSM корректно передает ENV в системный вызов subprocess.run.
  2. Значит, системная plumbing проложена верно.
  3. Любой другой инструмент (uv, docker), запущенный HSM, гарантированно получит тот же набор данных от ОС.

4. Паттерн Local-Remote (Git)​

Для тестирования материализации из Git используется создание временных локальных репозиториев.

  • Принцип: Git — распределенная система. Папка на диске с .git является полноценным «удаленным» сервером для команды clone.
  • Преимущества: 100% автономность тестов, отсутствие зависимости от сети, возможность имитировать любые состояния репозитория (ветки, теги, конфликты).

5. Заключение​

Комбинация Canary Package и Local-Remote позволяет HSM гарантировать работоспособность в реальных условиях эксплуатации, не полагаясь на хрупкие моки и предположения о поведении внешних инструментов.