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

Technical Design: Паттерн Self-Bootstrapping Sandbox

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

Self-Bootstrapping Sandbox (Самозагружающаяся песочница) — это подход к интеграционному тестированию, при котором тестовое окружение создается не вручную (через фикстуры или заранее подготовленные файлы), а с помощью самого тестируемого инструмента (CLI).

Это гарантирует, что:

  1. Инструмент может использовать то, что сам создает.
  2. Тесты имитируют реальный путь пользователя (End-to-End).
  3. Отсутствует "дрейф" между тестами и реальностью, так как нет искусственно созданных моков файловой системы.

2. Реализация и Изоляция​

Ключевым элементом песочницы является поддержка переменной окружения HSM_REGISTRY_PATH.

2.1. Изоляция реестра​

При инициализации HSMCore проверяет наличие HSM_REGISTRY_PATH. Если переменная установлена, HSM использует указанный путь вместо стандартного ./hsm-registry. Это позволяет тестам:

  1. Создавать временную директорию.
  2. Наполнять её тестовыми манифестами.
  3. Запускать команды HSM, будучи уверенными, что они не затронут реальный реестр.

3. Цикл полного пути (Full Path Cycle)​

В HSM этот паттерн реализуется через следующую последовательность действий, имитирующую реальный жизненный цикл разработки:

Шаг 1: Рождение Вселенной (Project & Registry Init)​

Тест инициализирует новый проект. Команда hsm init автоматически создает не только hsm.yaml, но и структуру локального реестра hsm-registry/.

hsm init --name sandbox-project
  • Результат: Созданы hsm.yaml и папки hsm-registry/{libraries,services,library_groups,service_groups}.

Шаг 2: Создание Кирпичиков (Library Init)​

Тест создает две реальные Python-библиотеки.

hsm library init lib-standalone --path ./libs/lib-standalone
hsm library init lib-in-group --path ./libs/lib-in-group
  • Действие: HSM вызывает uv init --lib, создавая валидные pyproject.toml.
  • Регистрация: Пути к библиотекам автоматически прописываются в hsm-registry/libraries/.

Шаг 3: Сборка Стэка (Project Configuration)​

Тест распределяет библиотеки и сервисы по структуре проекта.

  1. Библиотеки:
    • lib-standalone добавляется как прямая библиотека проекта.
    • lib-in-group добавляется в именованную группу (например, core-libs).
  2. Сервисы:
    • Регистрируется и добавляется standalone-сервис (например, redis).
    • Регистрируется и добавляется сервис в группу (например, db-cluster).

Шаг 4: Материализация (Sync & Validate)​

Вызов финальной синхронизации всего стэка.

hsm sync
  • Проверка Python: uv должен успешно создать .venv и установить обе библиотеки (одну напрямую, другую через группу).
  • Проверка Docker: Команда docker compose config должна подтвердить валидность сгенерированного docker-compose.hsm.yml, объединяющего standalone-сервис и сервисы из групп.

4. Преимущества для HSM​

  • High Fidelity: Мы уверены, что uv и docker понимают наши файлы.
  • Документация через тесты: Код тестов становится живым примером того, как пользоваться инструментом.
  • Легкая отладка: Если тест упал, в /tmp остается полностью готовый проект, в который можно зайти и запустить команды вручную.

5. Реализация в pytest​

Для поддержки этого паттерна используется фикстура hsm_sandbox, которая:

  1. Создает изолированную директорию.
  2. Устанавливает переменную окружения HSM_REGISTRY_PATH, чтобы команды по умолчанию работали с тестовым реестром.
  3. Предоставляет хелпер для запуска команд и проверки их вывода.