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

Technical Design: Стратегия тестирования HSM CLI (2026)

1. Обзор​

Для обеспечения надежности HSM при сохранении высокой скорости разработки принята многоуровневая стратегия тестирования. Она базируется на принципах High-Fidelity Integration Testing (высокоточное интеграционное тестирование), что является стандартом для системных инструментов в 2026 году.

Основная цель — гарантировать, что HSM корректно генерирует конфигурации, которые принимаются реальными инструментами (uv, docker), не превращая тесты в "проверку моков". Она разделяет быстрое модульное тестирование логики и глубокое интеграционное тестирование интерфейса в реальном окружении (Linux Ubuntu 24.04).

2. Почему выбран этот подход?​

На основе глубокого исследования практик 2026 года, мы отказались от тотального мокинга (mocking) в пользу реальных системных вызовов по следующим причинам:

  1. Симметрия API: Тесты должны подтверждать, что данные, записанные одной командой (например, registry library add или registry library implies add), могут быть корректно прочитаны и использованы другой (sync).
  2. Валидация внешними инструментами: Только реальный uv или docker compose config могут подтвердить, что сгенерированные файлы синтаксически верны и работоспособны.
  3. Скорость современных инструментов: Благодаря экстремальной производительности uv, запуск реальных команд в изолированных песочницах занимает миллисекунды, что сопоставимо со скоростью unit-тестов.

3. Уровни тестирования​

1. Функциональные тесты (Functional)​

1.1 Logic Level (CliRunner)​

Быстрая проверка парсинга аргументов, валидации ввода и корректности вызова внутренних функций.

  • Инструмент: typer.testing.CliRunner.
  • Особенности: Используется для проверки граничных случаев парсинга и базовых кодов возврата.

1.2 System Level (Subprocess)​

Вызов реального бинарника hsm (через uv run hsm).

  • Цель: Проверка entry_points, корректности путей импорта и взаимодействия с системным PATH.
  • Особенности: Гарантирует, что установленный пакет работает так же, как код в репозитории.

1.3 Environment Level (Sandbox) — КЛЮЧЕВОЙ УРОВЕНЬ​

Проверка взаимодействия HSM с файловой системой и внешними инструментами.

  • Паттерн: Self-Bootstrapping Sandbox.
  • Инструменты: Реальные uv и docker (с использованием docker compose config для валидации без запуска).
  • Изоляция: Реализована через поддержку HSM_REGISTRY_PATH, что позволяет тестам работать с временными реестрами.

2. UX тесты​

2.1 Интерактивный режим (Эмуляция человека)​

Тестирование команд, требующих ввода данных (prompts) или навигации.

  • Инструмент: pexpect. Позволяет эмулировать терминал (PTY) и проверять реакцию на вывод.

2.2 Тестирование автодополнения (Autocompletion)​

Проверка генерации вариантов Tab-completion для Bash/Zsh/Fish.

  • Механизм: Использование переменных окружения _{PROG_NAME}_COMPLETE.

4. Окружение и Кроссплатформенность​

Хотя основной средой разработки является Linux Ubuntu 24.04 LTS, HSM стремится к кроссплатформенности.

  • Правило: Все операции с файловой системой в тестах и коде должны выполняться через pathlib и shutil.
  • Запрет: Прямое использование системных команд (rm, mkdir) через os.system.

5. Запуск тестов​

# Обычный запуск (артефакты в /tmp)
uv run pytest -v

# Режим отладки (артефакты в ./debug_tests с версионированием)
HSM_DEBUG_TESTS=1 uv run pytest -v

6. Отладка и инспекция (Debugging)​

Для глубокого анализа поведения HSM внедрена система версионированных песочниц.

6.1 Режим HSM_DEBUG_TESTS=1​

При включении этого режима:

  1. Артефакты сохраняются в директории debug_tests/ в корне проекта.
  2. Для каждого теста создается подпапка с его именем.
  3. Внутри используется версионирование: run_1/, run_2/ и т.д.
  4. Файл LATEST.txt всегда содержит номер последнего запуска.
  5. Количество хранимых запусков ограничено (по умолчанию 10), старые удаляются автоматически.

6.2 Ручная песочница (Manual Sandbox)​

Для проведения ручных экспериментов с использованием всей мощи тестовых фикстур (изолированный реестр, настроенный CLI) используйте специальный "тест":

HSM_DEBUG_TESTS=1 uv run pytest tests/test_sandbox.py

Это создаст новое окружение в debug_tests/manual_sandbox/run_N/, где вы сможете безопасно запускать любые команды hsm.

7. Методология тестирования Git и ENV​

7.1 Тестирование Git-клонирования (Local-Remote Pattern)​

Для проверки материализации сервисов из Git без зависимости от сети используется паттерн Local-Remote. Согласно принципам распределенности Git, любая локальная директория может выступать в роли удаленного сервера.

  • Паттерн: Local-Remote Pattern.
  • Методология:
    • Ephemeral Remotes: Для каждого теста создается временная директория, которая инициализируется как Git-репозиторий, добавляются файлы и делается коммит.
    • State Simulation: Имитация различных состояний «удаленного» сервера (пустой репозиторий, разные ветки, разные git tags).
    • Action: В реестре HSM библиотека или сервис регистрируется с использованием протокола file:// (например, url: file:///tmp/fake-remote).
    • Verify: Проверка наличия файлов в services/<name> или packages/<name> после hsm sync. Проверка наличия пакета в виртуальном окружении менеджера пакетов.
    • No-Network Guarantee: Тесты гарантированно не используют сеть, что делает их быстрыми и стабильными.
  • Реализация:
    1. Setup: Инициализация Git в tmp_path, добавление pyproject.toml и коммит.
    2. Action: Регистрация сервиса в HSM через file:// протокол.
    3. Verify: Проверка наличия файлов в services/<name> после hsm sync.

7.2 Тестирование проброса ENV (Canary Package Pattern)​

Для подтверждения того, что переменные окружения (включая implies) корректно доходят до изолированных рантаймов, используется подход High-Fidelity Verification с применением «пакета-канарейки».

  • Паттерн: The "Canary" Package.
  • Методология:
    • The "Canary" Package: Минимальный Python-пакет, единственная задача которого — упасть при установке, если в окружении нет нужной переменной.
    • Build-Time Validation: Проверка os.getenv() внутри build-system. Согласно документации uv 0.9.26, стандартный бэкенд uv_build поддерживает только чистый Python. Для реализации кастомных проверок на этапе сборки рекомендуется использовать Hatchling с механизмом build-hooks.
    • End-to-End Proof: Проверка не просто «намерения» (словаря в коде), а реального «эффекта» в дочернем процессе.
  • Реализация:
    1. Unit Level: Проверка формирования итогового словаря env_vars в SyncEngine.
    2. Integration Level: Успешное завершение hsm sync для сервиса, зависящего от «канарейки», доказывает корректность проброса через всю цепочку: SyncEngine -> Adapter -> Subprocess -> uv -> Build Process.