Тестування: оновлення та плагіни

Контрольний список для перевірки оновлень і Plugin: доведіть, що пакет, який можна встановити, здатний оновлювати реальний стан користувача, виправляти застарілий стан через 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 встановлює архів-кандидат поверх тестової фікстури зі забрудненим станом старого користувача, запускає оновлення пакета та неінтерактивний doctor, а потім запускає Gateway через local loopback і перевіряє збереження стану.
• test:docker:published-upgrade-survivor спочатку встановлює опубліковану базову версію, налаштовує її за допомогою вбудованого сценарію openclaw config set, оновлює її до архіву-кандидата, запускає doctor, перевіряє очищення застарілого стану, запускає Gateway і перевіряє /healthz, /readyz та стан RPC.
• test:docker:update-restart-auth встановлює пакет-кандидат, запускає керований Gateway з автентифікацією за токеном, скасовує змінну середовища автентифікації Gateway виклику для openclaw update --yes --json і вимагає, щоб команда оновлення кандидата перезапустила Gateway до виконання звичайних перевірок.
• test:docker:update-migration — це напрям оновлення опублікованої версії з інтенсивним очищенням. Він починає з налаштованого стану користувача в стилі Discord/Telegram, запускає doctor базової версії, щоб залежності налаштованих плагінів могли матеріалізуватися, створює застаріле сміття залежностей плагіна для налаштованого пакетного плагіна, оновлює до архіву-кандидата й вимагає, щоб doctor після оновлення видалив застарілі корені залежностей.

Корисні варіанти перевірки оновлення опублікованої версії:

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-напрями для цього конкретного архіву. Посилання на обв’язку робочого процесу відокремлене від посилання на джерело пакета, тому поточна логіка тестування може перевіряти старіші довірені випуски.

Джерела кандидатів:

• 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 може попереджати про вже опубліковані локальні файли позначок метаданих збірки.
• Пізніші пакети мають відповідати сучасним контрактам. Ті самі прогалини призводять до помилки, а не до попередження чи пропуску.

Не додавайте нових міграцій під час запуску для цих старих форм. Додайте або розширте виправлення doctor, а потім перевірте його за допомогою 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-фікстур. Використовуйте локальні реєстри фікстур і фіктивні пакети, якщо метою тесту не є поведінка реального реєстру.

Аналіз причин збоїв

Починайте з ідентифікації артефакту:

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

Надавайте перевагу повторному запуску саме невдалого каналу з тим самим артефактом пакета, а не повторному запуску всього комплексу перевірок випуску.