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

Це спеціальний контрольний список для валідації оновлень і Plugin. Мета проста: довести, що інстальований пакет може оновлювати реальний стан користувача, відновлювати застарілий спадковий стан через doctor і все ще встановлювати, завантажувати, оновлювати та видаляти plugins із підтримуваних джерел.

Ширшу карту засобу запуску тестів див. у Тестування. Про ключі live-провайдерів і набори тестів, що торкаються мережі, див. Live-тестування.

# Що ми захищаємо

Тести оновлення і Plugin захищають такі контракти:

• Tarball пакета повний, має чинний dist/postinstall-inventory.json і не залежить від розпакованих файлів репозиторію.
• Користувач може перейти зі старішого опублікованого пакета на кандидатний пакет без втрати конфігурації, agents, sessions, workspaces, списків дозволених plugins або конфігурації каналів.
• openclaw doctor --fix --non-interactive володіє шляхами очищення і відновлення спадкового стану. Запуск не має нарощувати приховані міграції сумісності для застарілого стану plugins.
• Встановлення Plugin працює з локальних директорій, git-репозиторіїв, npm-пакетів і шляху реєстру ClawHub.
• npm-залежності Plugin встановлюються в керований npm root, скануються перед довірою і видаляються через npm під час деінсталяції, щоб hoisted-залежності не залишалися.
• Оновлення Plugin стабільне, коли нічого не змінилося: записи встановлення, resolved source, розкладка встановлених залежностей і ввімкнений стан залишаються незмінними.

# Локальне підтвердження під час розробки

Починайте вузько:

pnpm changed:lanes --json
pnpm check:changed
pnpm test:changed

Для змін у встановленні Plugin, видаленні, залежностях або package-inventory також запустіть сфокусовані тести, що покривають відредагований seam:

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

Перш ніж будь-яка package Docker lane використає tarball, підтвердьте артефакт пакета:

pnpm release:check

release:check запускає перевірки дрейфу config/docs/API, записує package dist inventory, запускає npm pack --dry-run, відхиляє заборонені запаковані файли, встановлює tarball у тимчасовий prefix, запускає postinstall і smoke-перевіряє entrypoints вбудованих каналів.

# Docker lanes

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

Під час ітерацій використовуйте сфокусовані lanes:

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

Важливі lanes:

• test:docker:plugins валідує smoke встановлення Plugin, встановлення з локальної папки, поведінку пропуску оновлення локальної папки, локальні папки з попередньо встановленими залежностями, встановлення file: пакетів, git-встановлення з виконанням CLI, оновлення рухомого git ref, встановлення з npm registry із hoisted transitive залежностями, npm update no-ops, встановлення з локального fixture ClawHub і update no-ops, поведінку marketplace update та Claude-bundle enable/inspect. Встановіть OPENCLAW_PLUGINS_E2E_CLAWHUB=0, щоб блок ClawHub залишався герметичним/offline.
• test:docker:plugin-lifecycle-matrix встановлює кандидатний пакет у bare контейнері, проводить npm Plugin через install, inspect, disable, enable, explicit upgrade, explicit downgrade і uninstall після видалення коду Plugin. Він логує метрики RSS і CPU для кожної фази.
• test:docker:plugin-update перевіряє, що незмінений установлений Plugin не перевстановлюється і не втрачає метадані встановлення під час openclaw plugins update.
• test:docker:upgrade-survivor встановлює кандидатний tarball поверх брудного old-user fixture, запускає оновлення пакета разом із non-interactive doctor, потім запускає loopback Gateway і перевіряє збереження стану.
• test:docker:published-upgrade-survivor спочатку встановлює опублікований baseline, конфігурує його через вбудований рецепт openclaw config set, оновлює його до кандидатного tarball, запускає doctor, перевіряє legacy cleanup, запускає Gateway і пробує /healthz, /readyz та RPC status.
• test:docker:update-restart-auth встановлює кандидатний пакет, запускає керований token-auth Gateway, скидає caller gateway auth env для openclaw update --yes --json і вимагає, щоб кандидатна команда оновлення перезапустила Gateway перед звичайними пробами.
• test:docker:update-migration є cleanup-heavy published-update lane. Він стартує з налаштованого Discord/Telegram-style стану користувача, запускає baseline doctor, щоб залежності налаштованих plugins мали шанс матеріалізуватися, засіває legacy plugin dependency debris для налаштованого packaged plugin, оновлює до кандидатного tarball і вимагає, щоб post-update doctor видалив legacy dependency roots.

Корисні варіанти published-upgrade survivor:

[email protected] \
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, feishu-channel, bootstrap-persona, plugin-deps-cleanup, configured-plugin-installs, stale-source-plugin-shadow, tilde-log-path і versioned-runtime-deps. В aggregate runs OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues розгортається в усі reported issue-shaped сценарії, включно з міграцією configured-plugin install.

Повна міграція оновлення навмисно відокремлена від Full Release CI. Використовуйте ручний workflow Update Migration, коли питання релізу звучить так: "чи може кожен опублікований stable release від 2026.4.23 і далі оновитися до цього кандидата та очистити plugin dependency debris?":

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

# Package Acceptance

Package Acceptance є GitHub-native package gate. Він resolve один кандидатний пакет у tarball package-under-test, записує версію і SHA-256, а потім запускає reusable Docker E2E lanes проти саме цього tarball. Workflow harness ref відокремлений від package source ref, тож поточна тестова логіка може валідувати старіші trusted releases.

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

• source=npm: валідувати openclaw@beta, openclaw@latest або точну опубліковану версію.
• source=ref: запакувати trusted branch, tag або commit із вибраним поточним harness.
• source=url: валідувати HTTPS tarball з обов’язковим package_sha256.
• source=artifact: повторно використати tarball, завантажений іншим Actions run.

Full Release Validation за замовчуванням використовує source=artifact, створений із resolved release SHA. Для post-publish proof передайте [email protected], щоб та сама upgrade matrix цілилася в поставлений npm-пакет натомість.

Release checks викликають Package Acceptance із набором package/update/restart/plugin:

doctor-switch update-channel-switch update-corrupt-plugin upgrade-survivor published-upgrade-survivor update-restart-auth plugins-offline plugin-update

Коли release soak увімкнено, вони також передають:

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

Це тримає package migration, update channel switching, toleration corrupt managed-plugin, cleanup застарілих plugin dependency, offline plugin coverage, поведінку plugin update і Telegram package QA на одному resolved artifact без примусу стандартного release package gate проходити кожен опублікований release.

last-stable-4 resolve до чотирьох найновіших stable npm-published OpenClaw releases. Release package acceptance pin-ить 2026.4.23 як першу межу сумісності plugin-update, 2026.5.2 як межу churn plugin-architecture, і 2026.4.15 як старіший published-update baseline 2026.4.1x; resolver dedupe-ить pins, які вже входять до найновіших чотирьох. Для вичерпного покриття published update migration використовуйте all-since-2026.4.23 в окремому workflow Update Migration замість Full Release CI. release-history залишається доступним для ручного ширшого sampling, коли вам також потрібен legacy pre-date anchor.

Коли вибрано кілька published-upgrade survivor baselines, reusable Docker workflow розбиває кожен baseline в окреме targeted runner job. Кожен baseline shard усе ще запускає вибраний набір сценаріїв, але логи й артефакти залишаються per-baseline, а wall time обмежується найповільнішим shard замість одного великого serial job.

Запустіть package profile вручну під час валідації кандидата перед релізом:

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

Використовуйте suite_profile=product, коли питання релізу включає MCP channels, cron/subagent cleanup, OpenAI web search або OpenWebUI. Використовуйте suite_profile=full лише тоді, коли потрібне повне покриття Docker release-path.

# Стандарт релізу

Для release candidates стандартний proof stack такий:

1. pnpm check:changed і pnpm test:changed для source-level regressions.
2. pnpm release:check для цілісності package artifact.
3. Package Acceptance package profile або release-check custom package lanes для контрактів install/update/restart/plugin.
4. Cross-OS release checks для OS-specific installer, onboarding і platform behavior.
5. Live suites лише коли змінена поверхня торкається provider або hosted-service behavior.

На maintainer machines broad gates і Docker/package product proof мають запускатися в Testbox, якщо явно не виконується local proof.

# Legacy compatibility

Послаблення сумісності вузьке і time boxed:

• Пакети до 2026.4.25 включно, зокрема 2026.4.25-beta.*, можуть tolerate already-shipped прогалини package metadata у Package Acceptance.
• Опублікований пакет 2026.4.26 може warn щодо local build metadata stamp files, які вже були поставлені.
• Пізніші пакети мають задовольняти сучасні контракти. Ті самі прогалини fail замість warning або skipping.

Не додавайте нові startup migrations для цих старих форм. Додайте або розширте doctor repair, потім доведіть це через upgrade-survivor, published-upgrade-survivor або update-restart-auth, коли команда update володіє restart.

# Додавання покриття

Коли змінюєте поведінку update або plugin, додавайте покриття на найнижчому рівні, який може fail з правильної причини:

• Pure path або metadata logic: unit test поруч із source.
• Package inventory або packed-file behavior: package-dist-inventory або tarball checker test.
• CLI install/update behavior: Docker lane assertion або fixture.
• Published-release migration behavior: сценарій published-upgrade-survivor.
• Update-owned restart behavior: update-restart-auth.
• Registry/package source behavior: fixture test:docker:plugins або fixture server ClawHub.
• Dependency layout або cleanup behavior: assert і runtime execution, і filesystem boundary. npm dependencies можуть бути hoisted під managed npm root, тож тести мають доводити, що root сканується/очищається, замість припускати package-local дерево node_modules.

Тримайте нові Docker fixtures герметичними за замовчуванням. Використовуйте локальні fixture registries і fake packages, якщо суть тесту не полягає в live registry behavior.

# Тріаж збоїв

Почніть з identity артефакту:

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

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