Тестирование: обновления и плагины

Контрольный список для проверки обновления и плагинов: докажите, что устанавливаемый пакет может обновлять реальное состояние пользователя, исправлять устаревшее состояние прежних версий с помощью doctor и при этом устанавливать, загружать, обновлять и удалять плагины из всех поддерживаемых источников.

Общую карту средств запуска тестов см. в разделе Тестирование. Сведения о ключах рабочих провайдеров и наборах тестов, использующих сеть, см. в разделе Тестирование в рабочей среде.

Что мы защищаем

• Архив пакета полон, содержит допустимый dist/postinstall-inventory.json и не зависит от распакованных файлов репозитория.
• Пользователь может перейти со старой опубликованной версии пакета на пакет-кандидат без потери конфигурации, агентов, сеансов, рабочих пространств, списков разрешённых плагинов или конфигурации каналов.
• openclaw doctor --fix --non-interactive отвечает за пути очистки и исправления устаревшего состояния. При запуске не должны появляться скрытые миграции совместимости для устаревшего состояния плагинов.
• Установка плагинов работает из локальных каталогов, репозиториев git, пакетов npm и через реестр ClawHub.
• Зависимости npm плагина устанавливаются в одном управляемом проекте npm для каждого плагина, проверяются перед установлением доверия и удаляются с помощью npm uninstall при удалении плагина, чтобы поднятые зависимости не оставались.
• Обновление плагина ничего не делает, если ничего не изменилось: записи установки, разрешённый источник, структура установленных зависимостей и состояние включения остаются неизменными.

Локальная проверка во время разработки

Начинайте с узкой области:

pnpm changed:lanes --jsonpnpm check:changedpnpm test:changed

При изменениях установки, удаления, зависимостей или инвентаризации пакетов плагинов также запускайте целевые тесты, покрывающие изменённый стык:

pnpm test src/plugins/uninstall.test.ts src/infra/package-dist-inventory.test.ts test/scripts/package-acceptance-workflow.test.ts

Прежде чем какой-либо Docker-контур пакета начнёт использовать архив, проверьте артефакт пакета:

pnpm release:check

release:check выполняет проверки расхождений конфигурации, документации и API (схема конфигурации, базовый уровень документации конфигурации, базовый уровень API и экспорта SDK плагинов, версии и инвентаризация плагинов), записывает инвентаризацию дистрибутива пакета, запускает npm pack --dry-run, отклоняет запрещённые упакованные файлы, устанавливает архив во временный префикс, выполняет postinstall и проверяет точки входа встроенных каналов.

Docker-контуры

Docker-контуры обеспечивают проверку на уровне продукта. Они устанавливают или обновляют реальный пакет внутри контейнеров Linux и проверяют поведение с помощью команд CLI, запуска Gateway, HTTP-запросов, состояния RPC и состояния файловой системы.

Во время итераций используйте целевые контуры:

pnpm test:docker:pluginspnpm test:docker:plugin-lifecycle-matrixpnpm test:docker:plugin-updatepnpm test:docker:upgrade-survivorpnpm test:docker:published-upgrade-survivorpnpm test:docker:update-restart-authpnpm test:docker:update-migration

Важные контуры:

• test:docker:plugins охватывает базовую проверку установки плагинов, установку из локальных папок, пропуск обновления локальных папок при отсутствии изменений, локальные папки с предварительно установленными зависимостями, установку пакетов file:, установку из git с выполнением CLI, обновление перемещаемых ссылок git, установку из реестра npm с поднятыми транзитивными зависимостями, отсутствие действий при обновлении npm без изменений, отклонение некорректных метаданных пакета npm, установку из локального тестового реестра ClawHub и отсутствие действий при обновлении без изменений, поведение обновления из магазина, а также включение и инспекцию пакета Claude. Установите OPENCLAW_PLUGINS_E2E_CLAWHUB=0, чтобы блок ClawHub оставался герметичным и автономным.
• test:docker:plugin-lifecycle-matrix устанавливает пакет-кандидат в пустой контейнер, проводит плагин npm через установку, инспекцию, отключение, включение, явное повышение версии, явное понижение версии и удаление после удаления кода плагина. Для каждого этапа записываются метрики RSS и CPU.
• test:docker:plugin-update проверяет, что установленный плагин без изменений не переустанавливается и не теряет метаданные установки во время openclaw plugins update.
• test:docker:upgrade-survivor устанавливает архив-кандидат поверх загрязнённого тестового состояния старого пользователя, выполняет обновление пакета и неинтерактивную диагностику, затем запускает Gateway с обратной петлёй и проверяет сохранность состояния.
• test:docker:published-upgrade-survivor сначала устанавливает опубликованную базовую версию, настраивает её с помощью встроенного рецепта openclaw config set, обновляет до архива-кандидата, запускает диагностику, проверяет очистку устаревшего состояния, запускает Gateway и проверяет /healthz, /readyz и состояние RPC.
• test:docker:update-restart-auth устанавливает пакет-кандидат, запускает управляемый Gateway с аутентификацией по токену, удаляет переменные среды аутентификации Gateway вызывающей стороны для openclaw update --yes --json и требует, чтобы команда обновления пакета-кандидата перезапустила Gateway перед обычными проверками.
• test:docker:update-migration — контур обновления опубликованной версии с упором на очистку. Он начинает с настроенного пользовательского состояния в стиле Discord/Telegram, запускает диагностику базовой версии, чтобы зависимости настроенных плагинов могли материализоваться, добавляет устаревшие остатки зависимостей плагина для настроенного упакованного плагина, обновляется до архива-кандидата и требует, чтобы диагностика после обновления удалила устаревшие корневые каталоги зависимостей.

Полезные варианты проверки сохранности при обновлении опубликованной версии:

OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC=openclaw@2026.4.23 \OPENCLAW_UPGRADE_SURVIVOR_SCENARIO=versioned-runtime-deps \pnpm test:docker:published-upgrade-survivor OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC=openclaw@latest \OPENCLAW_UPGRADE_SURVIVOR_SCENARIO=bootstrap-persona \pnpm test:docker:published-upgrade-survivor

Доступные сценарии: base, acpx-openclaw-tools-bridge, feishu-channel, bootstrap-persona, channel-post-core-restore, plugin-deps-cleanup, configured-plugin-installs, stale-source-plugin-shadow, tilde-log-path и versioned-runtime-deps. При совокупных запусках OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues (псевдоним far-reaching) разворачивается во все сценарии, включая миграцию установки настроенного плагина.

Полная миграция обновлений намеренно отделена от полной проверки CI выпуска. Используйте ручной процесс Update Migration, когда вопрос выпуска звучит так: «может ли каждый опубликованный стабильный выпуск начиная с 2026.4.23 обновиться до этого кандидата и очистить остатки зависимостей плагинов?»:

gh workflow run update-migration.yml \  --ref main \  -f workflow_ref=main \  -f package_ref=main \  -f baselines=all-since-2026.4.23 \  -f scenarios=plugin-deps-cleanup

Приёмка пакета

Приёмка пакета — это встроенный в GitHub шлюз проверки пакета. Он преобразует один пакет-кандидат в архив package-under-test, записывает версию и SHA-256, а затем запускает повторно используемые Docker-контуры E2E для этого конкретного архива. Ссылка на среду процесса отделена от ссылки на источник пакета, поэтому текущая логика тестирования может проверять старые доверенные выпуски.

Источники кандидатов:

• source=npm: проверяет openclaw@extended-stable, openclaw@beta, openclaw@latest или точную опубликованную версию.
• source=ref: упаковывает доверенную ветвь, тег или коммит с выбранной текущей средой.
• source=url: проверяет общедоступный архив HTTPS с обязательным package_sha256. Этот путь отклоняет учётные данные в URL, нестандартные порты HTTPS, частные или внутренние имена хостов или результаты DNS/IP, диапазоны IP специального назначения и небезопасные перенаправления.
• source=trusted-url: проверяет архив HTTPS с обязательными package_sha256 и trusted_source_id согласно политике сопровождающих в .github/package-trusted-sources.json. Используйте этот вариант для корпоративных или частных зеркал вместо ослабления source=url переключателем разрешения частных ресурсов на уровне входных данных. Аутентификация Bearer, если она настроена политикой, использует фиксированный секрет OPENCLAW_TRUSTED_PACKAGE_TOKEN.
• source=artifact: повторно использует архив, загруженный другим запуском Actions.

Полная проверка выпуска по умолчанию использует source=artifact, собранный из разрешённого SHA выпуска. Для проверки после публикации передайте package_acceptance_package_spec=openclaw@YYYY.M.PATCH, чтобы та же матрица обновления проверяла выпущенный пакет npm.

Проверки выпуска вызывают приёмку пакета с набором тестов пакета, обновления, перезапуска и плагинов:

doctor-switch update-channel-switch skill-install update-corrupt-plugin upgrade-survivor published-upgrade-survivor root-managed-vps-upgrade update-restart-auth plugins-offline plugin-update plugin-binding-command-escape

Когда включена длительная проверка выпуска (принудительно для release_profile=stable и full), также передаются:

published_upgrade_survivor_baselines=last-stable-4 2026.4.23 2026.5.2 2026.4.15published_upgrade_survivor_scenarios=reported-issuestelegram_mode=mock-openai

Это позволяет проверять миграцию пакета, переключение канала обновлений, устойчивость к повреждённым управляемым плагинам, очистку устаревших зависимостей плагинов, автономную проверку плагинов, поведение обновления плагинов и контроль качества пакета Telegram на одном и том же разрешённом артефакте, не заставляя стандартный шлюз проверки пакета выпуска проходить по всем опубликованным выпускам.

last-stable-4 разрешается в четыре последних стабильных выпуска OpenClaw, опубликованных в npm. Приёмка пакета выпуска фиксирует 2026.4.23 как первую границу совместимости обновления плагинов, 2026.5.2 как границу изменений архитектуры плагинов и 2026.4.15 как более старую базовую версию обновления опубликованного выпуска серии 2026.4.1x; средство разрешения удаляет дубликаты зафиксированных версий, уже входящих в последние четыре. Для исчерпывающего покрытия миграции обновлений опубликованных версий используйте all-since-2026.4.23 в отдельном процессе миграции обновлений вместо полной проверки CI выпуска. release-history остаётся доступным для ручной более широкой выборки, когда также нужна опорная версия до указанной даты.

Если выбрано несколько базовых версий проверки сохранности при обновлении опубликованной версии, повторно используемый Docker-процесс распределяет каждую базовую версию в отдельное целевое задание средства запуска. Каждый сегмент базовой версии по-прежнему выполняет выбранный набор сценариев, но журналы и артефакты остаются разделёнными по базовым версиям, а общее время ограничивается самым медленным сегментом вместо одного большого последовательного задания.

При проверке кандидата перед выпуском запустите профиль пакета вручную:

gh workflow run package-acceptance.yml \  --ref main \  -f workflow_ref=main \  -f source=npm \  -f package_spec=openclaw@beta \  -f suite_profile=package \  -f published_upgrade_survivor_baselines="last-stable-4 2026.4.23 2026.5.2 2026.4.15" \  -f published_upgrade_survivor_scenarios=reported-issues \  -f telegram_mode=mock-openai

Для опубликованной канареечной версии с расширенной стабильностью задайте package_spec=openclaw@extended-stable. Приёмка пакета преобразует этот селектор в конкретный архив до запуска Docker-контуров.

Используйте suite_profile=product, если вопрос выпуска включает каналы MCP, очистку cron/подагентов, веб-поиск OpenAI или OpenWebUI. Используйте suite_profile=full только тогда, когда требуется полное покрытие пути выпуска в Docker.

Стандартная проверка выпуска

Для кандидатов на выпуск стандартный набор проверок таков:

1. pnpm check:changed и pnpm test:changed для регрессий на уровне исходного кода.
2. pnpm release:check для проверки целостности артефакта пакета.
3. Профиль package приёмки пакета или специальные пакетные контуры проверки выпуска для контрактов установки, обновления, перезапуска и плагинов.
4. Кроссплатформенные проверки выпуска для установщика, первоначальной настройки и поведения, зависящего от ОС и платформы.
5. Рабочие наборы тестов — только если изменённая область затрагивает поведение провайдера или размещённой службы.

На компьютерах сопровождающих широкие шлюзы и проверки продукта с помощью Docker и пакетов должны выполняться в Testbox, если явно не проводится локальная проверка.

Совместимость с устаревшими версиями

Послабления совместимости узки и ограничены по времени:

• Пакеты вплоть до 2026.4.25, включая 2026.4.25-beta.*, могут допускать уже выпущенные пробелы в метаданных пакетов при приёмке пакета.
• Опубликованный пакет 2026.4.26 может выдавать предупреждения для уже выпущенных файлов меток метаданных локальной сборки.
• Более поздние пакеты должны соответствовать современным контрактам. Те же пробелы приводят к ошибке, а не к предупреждению или пропуску.

Не добавляйте новые миграции при запуске для этих старых форматов. Добавьте или расширьте исправление в диагностике, а затем проверьте его с помощью upgrade-survivor, published-upgrade-survivor или update-restart-auth, если команда обновления отвечает за перезапуск.

Добавление покрытия

При изменении поведения обновления или плагина добавляйте покрытие на самом низком уровне, который может завершиться сбоем по нужной причине:

• Чистая логика путей или метаданных: модульный тест рядом с исходным кодом.
• Состав пакета или поведение упакованных файлов: package-dist-inventory или тест проверки tarball.
• Поведение установки/обновления через CLI: проверка или фикстура в Docker-сценарии.
• Поведение миграции опубликованного выпуска: сценарий published-upgrade-survivor.
• Поведение перезапуска, контролируемого обновлением: update-restart-auth.
• Поведение источника реестра/пакета: фикстура test:docker:plugins или сервер фикстур ClawHub.
• Поведение структуры зависимостей или очистки: проверяйте как выполнение во время работы, так и границу файловой системы. Зависимости npm могут подниматься внутри управляемого npm-проекта плагина, поэтому тесты должны подтверждать, что этот проект сканируется/очищается, а не предполагать, что существует только локальное для пакета плагина дерево node_modules.

По умолчанию сохраняйте новые Docker-фикстуры герметичными. Используйте локальные реестры фикстур и фиктивные пакеты, если только целью теста не является проверка поведения реального реестра.

Разбор сбоев

Начните с идентификации артефакта:

• Сводка Package Acceptance resolve_package: источник, версия, SHA-256 и имя артефакта.
• Артефакты Docker: .artifacts/docker-tests/**/summary.json, failures.json, журналы сценария и команды повторного запуска.
• Сводка сохранности после обновления: .artifacts/upgrade-survivor/summary.json, включая исходную версию, версию-кандидат, сценарий, длительность этапов и покрытие рецептов конфигурации.

Предпочитайте повторный запуск конкретного завершившегося сбоем сценария с тем же артефактом пакета повторному запуску всего набора проверок выпуска.