--- read_when: - Изменение поведения обновления OpenClaw, doctor, приёмки пакетов или установки плагинов - Подготовка или утверждение кандидата на выпуск - Отладка обновления пакетов, очистки зависимостей плагинов или регрессий при установке плагинов sidebarTitle: Update and plugin tests summary: Как OpenClaw проверяет пути обновления, миграции пакетов и поведение при установке и обновлении плагинов title: 'Тестирование: обновления и плагины' x-i18n: generated_at: "2026-07-13T18:17:10Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 24 provider: openai source_hash: 4e930960b5819d2144467476cb473e62f236eca63e1d9941a6bc793b484e731c source_path: help/testing-updates-plugins.md workflow: 16 --- Контрольный список для проверки обновления и плагинов: докажите, что устанавливаемый пакет может обновлять реальное состояние пользователя, исправлять устаревшее состояние прежних версий с помощью `doctor` и при этом устанавливать, загружать, обновлять и удалять плагины из всех поддерживаемых источников. Общую карту средств запуска тестов см. в разделе [Тестирование](/ru/help/testing). Сведения о ключах рабочих провайдеров и наборах тестов, использующих сеть, см. в разделе [Тестирование в рабочей среде](/ru/help/testing-live). ## Что мы защищаем - Архив пакета полон, содержит допустимый `dist/postinstall-inventory.json` и не зависит от распакованных файлов репозитория. - Пользователь может перейти со старой опубликованной версии пакета на пакет-кандидат без потери конфигурации, агентов, сеансов, рабочих пространств, списков разрешённых плагинов или конфигурации каналов. - `openclaw doctor --fix --non-interactive` отвечает за пути очистки и исправления устаревшего состояния. При запуске не должны появляться скрытые миграции совместимости для устаревшего состояния плагинов. - Установка плагинов работает из локальных каталогов, репозиториев git, пакетов npm и через реестр ClawHub. - Зависимости npm плагина устанавливаются в одном управляемом проекте npm для каждого плагина, проверяются перед установлением доверия и удаляются с помощью `npm uninstall` при удалении плагина, чтобы поднятые зависимости не оставались. - Обновление плагина ничего не делает, если ничего не изменилось: записи установки, разрешённый источник, структура установленных зависимостей и состояние включения остаются неизменными. ## Локальная проверка во время разработки Начинайте с узкой области: ```bash pnpm changed:lanes --json pnpm check:changed pnpm test:changed ``` При изменениях установки, удаления, зависимостей или инвентаризации пакетов плагинов также запускайте целевые тесты, покрывающие изменённый стык: ```bash pnpm test src/plugins/uninstall.test.ts src/infra/package-dist-inventory.test.ts test/scripts/package-acceptance-workflow.test.ts ``` Прежде чем какой-либо Docker-контур пакета начнёт использовать архив, проверьте артефакт пакета: ```bash pnpm release:check ``` `release:check` выполняет проверки расхождений конфигурации, документации и API (схема конфигурации, базовый уровень документации конфигурации, базовый уровень API и экспорта SDK плагинов, версии и инвентаризация плагинов), записывает инвентаризацию дистрибутива пакета, запускает `npm pack --dry-run`, отклоняет запрещённые упакованные файлы, устанавливает архив во временный префикс, выполняет postinstall и проверяет точки входа встроенных каналов. ## Docker-контуры Docker-контуры обеспечивают проверку на уровне продукта. Они устанавливают или обновляют реальный пакет внутри контейнеров Linux и проверяют поведение с помощью команд CLI, запуска Gateway, HTTP-запросов, состояния RPC и состояния файловой системы. Во время итераций используйте целевые контуры: ```bash pnpm test:docker:plugins pnpm test:docker:plugin-lifecycle-matrix pnpm test:docker:plugin-update pnpm test:docker:upgrade-survivor pnpm test:docker:published-upgrade-survivor pnpm test:docker:update-restart-auth pnpm 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, запускает диагностику базовой версии, чтобы зависимости настроенных плагинов могли материализоваться, добавляет устаревшие остатки зависимостей плагина для настроенного упакованного плагина, обновляется до архива-кандидата и требует, чтобы диагностика после обновления удалила устаревшие корневые каталоги зависимостей. Полезные варианты проверки сохранности при обновлении опубликованной версии: ```bash 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 обновиться до этого кандидата и очистить остатки зависимостей плагинов?»: ```bash 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. Проверки выпуска вызывают приёмку пакета с набором тестов пакета, обновления, перезапуска и плагинов: ```text 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`), также передаются: ```text published_upgrade_survivor_baselines=last-stable-4 2026.4.23 2026.5.2 2026.4.15 published_upgrade_survivor_scenarios=reported-issues telegram_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-процесс распределяет каждую базовую версию в отдельное целевое задание средства запуска. Каждый сегмент базовой версии по-прежнему выполняет выбранный набор сценариев, но журналы и артефакты остаются разделёнными по базовым версиям, а общее время ограничивается самым медленным сегментом вместо одного большого последовательного задания. При проверке кандидата перед выпуском запустите профиль пакета вручную: ```bash 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`, включая исходную версию, версию-кандидат, сценарий, длительность этапов и покрытие рецептов конфигурации. Предпочитайте повторный запуск конкретного завершившегося сбоем сценария с тем же артефактом пакета повторному запуску всего набора проверок выпуска.