diff --git a/docs/uk/help/testing-updates-plugins.md b/docs/uk/help/testing-updates-plugins.md index 13e868d6e..c0d86690b 100644 --- a/docs/uk/help/testing-updates-plugins.md +++ b/docs/uk/help/testing-updates-plugins.md @@ -1,48 +1,47 @@ --- read_when: - - Зміна поведінки оновлення OpenClaw, doctor, приймання пакетів або встановлення Plugin - - Підготовка або схвалення реліз-кандидата - - Налагодження оновлення пакета, очищення залежностей Plugin або регресій установлення Plugin + - Зміна поведінки оновлення, doctor, приймання пакетів або встановлення Plugin в OpenClaw + - Підготовка або затвердження реліз-кандидата + - Налагодження оновлення пакета, очищення залежностей Plugin або регресій встановлення Plugin sidebarTitle: Update and plugin tests -summary: Як OpenClaw перевіряє шляхи оновлення, міграції пакетів і поведінку встановлення та оновлення Plugin -title: 'Тестування: оновлення та Plugin' +summary: Як OpenClaw перевіряє шляхи оновлення, міграції пакетів і поведінку встановлення/оновлення Plugin +title: 'Тестування: оновлення та плагіни' x-i18n: - generated_at: "2026-05-01T23:38:43Z" + generated_at: "2026-05-02T02:02:09Z" model: gpt-5.5 provider: openai - source_hash: 4d4b52047b9b80273e2d93b97e647e5e9c93d93910828fdce010568f3ea81390 + source_hash: b1999106b52d2539a6ee0fd7cd88ebb3515c8726e080d4031d7bf421fb99de36 source_path: help/testing-updates-plugins.md workflow: 16 --- -Це спеціальний контрольний список для валідації оновлень і Plugin. Мета -проста: довести, що інстальований пакет може оновити реальний стан користувача, -відновити застарілий успадкований стан через `doctor` і все ще встановлювати, -завантажувати, оновлювати та видаляти plugins із підтримуваних джерел. +Це окремий контрольний список для перевірки оновлень і Plugin. Мета +проста: довести, що інстальований пакет може оновлювати реальний стан користувача, виправляти застарілий +legacy-стан через `doctor` і надалі встановлювати, завантажувати, оновлювати та видаляти +Plugin з підтримуваних джерел. -Ширшу карту тестового раннера див. у [Тестування](/uk/help/testing). Про ключі -live-провайдерів і набори тестів, що торкаються мережі, див. -[Live-тестування](/uk/help/testing-live). +Ширшу мапу засобів запуску тестів див. у [Тестування](/uk/help/testing). Для live-ключів провайдерів +і наборів тестів, що торкаються мережі, див. [Live-тестування](/uk/help/testing-live). ## Що ми захищаємо -Тести оновлення та Plugin захищають такі контракти: +Тести оновлень і Plugin захищають такі контракти: -- Tarball пакета повний, має чинний `dist/postinstall-inventory.json` і не - залежить від розпакованих файлів репозиторію. -- Користувач може перейти зі старішого опублікованого пакета на кандидатний - пакет без втрати конфігурації, агентів, сесій, робочих просторів, allowlist - Plugin або конфігурації каналу. -- `openclaw doctor --fix --non-interactive` володіє шляхами очищення та - відновлення успадкованого стану. Startup не має розростатися прихованими - міграціями сумісності для застарілого стану Plugin. -- Встановлення Plugin працює з локальних директорій, git-репозиторіїв, - npm-пакетів і шляху реєстру ClawHub. -- npm-залежності Plugin встановлюються в керований корінь npm, скануються перед - довірою та видаляються через npm під час uninstall, щоб підняті залежності не +- Tarball пакета повний, має чинний `dist/postinstall-inventory.json` + і не залежить від нерозпакованих файлів репозиторію. +- Користувач може перейти зі старішого опублікованого пакета на пакет-кандидат + без втрати конфігурації, агентів, сесій, робочих просторів, allowlist Plugin або + конфігурації каналів. +- `openclaw doctor --fix --non-interactive` відповідає за очищення та виправлення + legacy-шляхів. Запуск не повинен обростати прихованими міграціями сумісності для застарілого + стану Plugin. +- Встановлення Plugin працює з локальних каталогів, git-репозиторіїв, npm-пакетів і + шляху реєстру ClawHub. +- npm-залежності Plugin встановлюються в керований npm root, скануються перед + довірою й видаляються через npm під час деінсталяції, щоб hoisted-залежності не залишалися. -- Оновлення Plugin стабільне, коли нічого не змінилося: записи встановлення, - розв’язане джерело та ввімкнений стан залишаються неушкодженими. +- Оновлення Plugin стабільне, коли нічого не змінилося: записи встановлення, resolved + source, структура встановлених залежностей і ввімкнений стан залишаються незмінними. ## Локальне підтвердження під час розробки @@ -54,33 +53,31 @@ pnpm check:changed pnpm test:changed ``` -Для змін у встановленні, видаленні, залежностях Plugin або package-inventory -також запускайте сфокусовані тести, що покривають відредагований seam: +Для змін у встановленні, видаленні, залежностях Plugin або package-inventory також +запустіть цільові тести, що покривають відредаговану межу: ```bash 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, доведіть артефакт -пакета: +Перш ніж будь-яка package Docker lane використає tarball, перевірте артефакт пакета: ```bash pnpm release:check ``` -`release:check` запускає перевірки drift для config/docs/API, записує package -dist inventory, запускає `npm pack --dry-run`, відхиляє заборонені запаковані -файли, встановлює tarball у тимчасовий prefix, запускає postinstall і перевіряє -smoke для bundled channel entrypoints. +`release:check` запускає перевірки дрейфу config/docs/API, записує package dist +inventory, запускає `npm pack --dry-run`, відхиляє заборонені запаковані файли, встановлює +tarball у тимчасовий prefix, запускає postinstall і виконує smoke-перевірку bundled channel +entrypoints. ## Docker lanes -Docker lanes є підтвердженням продуктового рівня. Вони встановлюють або -оновлюють реальний пакет усередині Linux-контейнерів і перевіряють поведінку -через CLI-команди, startup Gateway, HTTP-проби, RPC-статус і стан файлової -системи. +Docker lanes є product-level підтвердженням. Вони встановлюють або оновлюють реальний +пакет у Linux-контейнерах і перевіряють поведінку через CLI-команди, +запуск Gateway, HTTP-проби, RPC-статус і стан файлової системи. -Під час ітерацій використовуйте сфокусовані lanes: +Під час ітерацій використовуйте цільові lanes: ```bash pnpm test:docker:plugins @@ -92,30 +89,28 @@ pnpm test:docker:update-migration Важливі lanes: -- `test:docker:plugins` валідує smoke встановлення Plugin, встановлення з - локальних папок, локальні папки з попередньо встановленими залежностями, - git-встановлення із залежностями пакета, встановлення залежностей npm-пакета, - встановлення з локальної ClawHub fixture, поведінку marketplace update, а - також enable/inspect для Claude-bundle. Установіть - `OPENCLAW_PLUGINS_E2E_CLAWHUB=0`, щоб блок ClawHub залишався - герметичним/offline. +- `test:docker:plugins` перевіряє smoke встановлення Plugin, встановлення з локальної папки, + skip-поведінку оновлення локальної папки, локальні папки з попередньо встановленими + залежностями, встановлення `file:` пакетів, git-встановлення з виконанням CLI, оновлення + moving-ref у git, встановлення з npm registry з hoisted transitive + dependencies, no-op оновлення npm, встановлення з локальної ClawHub fixture і no-op + оновлення, поведінку оновлення marketplace та ввімкнення/інспекцію Claude-bundle. Установіть + `OPENCLAW_PLUGINS_E2E_CLAWHUB=0`, щоб блок ClawHub залишався герметичним/offline. - `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, конфігурує його через baked рецепт `openclaw config set`, оновлює - його до кандидатного tarball, запускає doctor, перевіряє очищення - успадкованого стану, запускає Gateway і пробує `/healthz`, `/readyz` та - RPC-статус. -- `test:docker:update-migration` є cleanup-heavy lane для published-update. Вона - стартує з налаштованого користувацького стану в стилі Discord/Telegram, - запускає baseline doctor, щоб налаштовані залежності Plugin мали шанс - матеріалізуватися, засіває уламки успадкованих залежностей Plugin для - налаштованого packaged Plugin, оновлює до кандидатного tarball і вимагає, щоб - post-update doctor видалив legacy dependency roots. + перевстановлюється й не втрачає install metadata під час `openclaw plugins update`. +- `test:docker:upgrade-survivor` встановлює tarball-кандидат поверх dirty + 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-статус. +- `test:docker:update-migration` є cleanup-heavy published-update lane. Він + стартує з налаштованого Discord/Telegram-style стану користувача, запускає baseline + doctor, щоб налаштовані залежності Plugin мали шанс матеріалізуватися, сіє + legacy plugin dependency debris для налаштованого packaged plugin, оновлює до + tarball-кандидата й вимагає, щоб post-update doctor видалив legacy + dependency roots. Корисні варіанти published-upgrade survivor: @@ -131,13 +126,13 @@ pnpm test:docker:published-upgrade-survivor Доступні сценарії: `base`, `feishu-channel`, `bootstrap-persona`, `plugin-deps-cleanup`, `tilde-log-path` і `versioned-runtime-deps`. В aggregate runs -`OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues` розгортається в усі -сценарії, сформовані за reported issues. +`OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues` розгортається в усі reported +issue-shaped scenarios. -Повна update migration навмисно відокремлена від Full Release CI. Використовуйте -ручний workflow `Update Migration`, коли release-питання звучить так: "чи може -кожен опублікований stable release від 2026.4.23 і далі оновитися до цього -кандидата та очистити уламки залежностей Plugin?": +Повна міграція оновлень навмисно відокремлена від Full Release CI. Використовуйте +ручний workflow `Update Migration`, коли release-питання звучить так: "чи може кожен +опублікований stable release від 2026.4.23 і далі оновитися до цього кандидата та +очистити plugin dependency debris?": ```bash gh workflow run update-migration.yml \ @@ -150,23 +145,22 @@ gh workflow run update-migration.yml \ ## Package Acceptance -Package Acceptance є GitHub-native package gate. Він розв’язує один кандидатний -пакет у tarball `package-under-test`, записує версію та SHA-256, потім запускає -reusable Docker E2E lanes проти саме цього tarball. Workflow harness ref -відокремлений від package source ref, тому поточна тестова логіка може -валідувати старіші trusted releases. +Package Acceptance — це GitHub-native package gate. Він визначає один candidate +package у tarball `package-under-test`, записує version і SHA-256, а потім +запускає reusable Docker E2E lanes проти саме цього tarball. Workflow harness +ref відокремлений від package source ref, тому поточна логіка тестів може перевіряти +старіші trusted releases. -Джерела кандидата: +Джерела кандидатів: -- `source=npm`: валідувати `openclaw@beta`, `openclaw@latest` або точну +- `source=npm`: перевірити `openclaw@beta`, `openclaw@latest` або точну опубліковану версію. -- `source=ref`: запакувати trusted branch, tag або commit із вибраним поточним +- `source=ref`: запакувати trusted branch, tag або commit з вибраним поточним harness. -- `source=url`: валідувати HTTPS tarball з обов’язковим `package_sha256`. -- `source=artifact`: повторно використати tarball, завантажений іншим Actions - run. +- `source=url`: перевірити HTTPS tarball з обов’язковим `package_sha256`. +- `source=artifact`: повторно використати tarball, завантажений іншим Actions run. -Release checks викликають Package Acceptance з package/update/plugin set: +Release checks викликають Package Acceptance із набором package/update/plugin: ```text doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update @@ -180,16 +174,16 @@ published_upgrade_survivor_scenarios=reported-issues telegram_mode=mock-openai ``` -Це тримає package migration, перемикання каналу оновлень, очищення застарілих -залежностей Plugin, offline-покриття Plugin, поведінку оновлення Plugin і -Telegram package QA на одному розв’язаному артефакті. +Це тримає міграцію пакета, перемикання update channel, очищення застарілих plugin dependency, +offline-покриття Plugin, поведінку оновлення Plugin і Telegram package +QA на одному resolved artifact. -`release-history` є обмеженим release-check sample: останні шість stable -releases, `2026.4.23` і один старіший pre-date anchor. Для вичерпного покриття -published update migration використовуйте `all-since-2026.4.23` в окремому -workflow Update Migration замість Full Release CI. +`release-history` — це bounded release-check sample: останні шість stable releases, +`2026.4.23` і один старіший pre-date anchor. Для вичерпного покриття published update +migration використовуйте `all-since-2026.4.23` в окремому workflow Update Migration +замість Full Release CI. -Запустіть package profile вручну під час валідації кандидата перед release: +Запустіть package profile вручну під час перевірки кандидата перед релізом: ```bash gh workflow run package-acceptance.yml \ @@ -203,69 +197,71 @@ gh workflow run package-acceptance.yml \ -f telegram_mode=mock-openai ``` -Використовуйте `suite_profile=product`, коли release-питання включає MCP -channels, cron/subagent cleanup, OpenAI web search або OpenWebUI. Використовуйте -`suite_profile=full` лише тоді, коли потрібне повне покриття Docker release-path. +Використовуйте `suite_profile=product`, коли release-питання охоплює MCP channels, +cron/subagent cleanup, OpenAI web search або OpenWebUI. Використовуйте `suite_profile=full` +лише тоді, коли потрібне повне покриття Docker release-path. -## Типовий release +## Типовий варіант для релізу -Для release candidates типовий стек підтвердження такий: +Для release candidates типовий proof stack такий: 1. `pnpm check:changed` і `pnpm test:changed` для source-level регресій. 2. `pnpm release:check` для цілісності артефакту пакета. -3. Package Acceptance profile `package` або release-check custom package - lanes для контрактів install/update/plugin. +3. Package Acceptance `package` profile або release-check custom package + lanes для install/update/plugin contracts. 4. Cross-OS release checks для OS-specific installer, onboarding і platform behavior. -5. Live-набори лише тоді, коли змінена поверхня торкається поведінки провайдера - або hosted-service. +5. Live-набори лише тоді, коли змінена surface зачіпає provider або hosted-service + behavior. -На машинах мейнтейнерів broad gates і Docker/package product proof мають -запускатися в Testbox, якщо явно не виконується локальне підтвердження. +На maintainer machines broad gates і Docker/package product proof мають запускатися +в Testbox, якщо явно не виконується local proof. -## Успадкована сумісність +## Legacy-сумісність -Поблажливість сумісності вузька й обмежена в часі: +Compatibility leniency вузька й обмежена в часі: -- Пакети до `2026.4.25` включно, зокрема `2026.4.25-beta.*`, можуть терпіти - вже shipped gaps у package metadata в Package Acceptance. -- Опублікований пакет `2026.4.26` може попереджати про local build metadata - stamp files, які вже shipped. -- Пізніші пакети мають задовольняти сучасні контракти. Ті самі gaps мають - падати замість warning або skipping. +- Пакети до `2026.4.25` включно, зокрема `2026.4.25-beta.*`, можуть толерувати + вже випущені прогалини package metadata у Package Acceptance. +- Опублікований пакет `2026.4.26` може попереджати про local build metadata stamp + files, які вже були випущені. +- Пізніші пакети мають задовольняти сучасні контракти. Ті самі прогалини призводять до failure замість + warning або skipping. -Не додавайте нові startup migrations для цих старих форм. Додайте або розширте -doctor repair, потім доведіть це за допомогою `upgrade-survivor` або -`published-upgrade-survivor`. +Не додавайте нові startup migrations для цих старих форм. Додайте або розширте doctor +repair, а потім доведіть це через `upgrade-survivor` або `published-upgrade-survivor`. ## Додавання покриття -Коли змінюєте поведінку update або Plugin, додавайте покриття на найнижчому -рівні, який може впасти з правильної причини: +Коли змінюєте поведінку оновлення або Plugin, додавайте покриття на найнижчому рівні, який +може впасти з правильної причини: -- Чиста path або metadata logic: unit test поруч із джерелом. -- Поведінка package inventory або packed-file: `package-dist-inventory` або - tarball checker test. -- CLI install/update behavior: Docker lane assertion або fixture. +- Чиста логіка шляхів або metadata: unit test поруч із source. +- Поведінка package inventory або packed-file: `package-dist-inventory` або tarball + checker test. +- Поведінка CLI install/update: Docker lane assertion або fixture. - Поведінка published-release migration: сценарій `published-upgrade-survivor`. -- Поведінка registry/package source: fixture `test:docker:plugins` або сервер - ClawHub fixture. +- Поведінка registry/package source: fixture `test:docker:plugins` або ClawHub + fixture server. +- Поведінка dependency layout або cleanup: перевіряйте і runtime execution, і + filesystem boundary. npm-залежності можуть бути hoisted під managed npm + root, тому тести мають доводити, що root сканується/очищується, замість припущення про + package-local дерево `node_modules`. -Нові Docker fixtures за замовчуванням мають бути герметичними. Використовуйте -локальні fixture registries і fake packages, якщо метою тесту не є live registry -behavior. +Нові Docker fixtures за замовчуванням мають бути герметичними. Використовуйте локальні fixture registries і +fake packages, якщо метою тесту не є live registry behavior. ## Тріаж збоїв Починайте з ідентичності артефакту: -- Summary Package Acceptance `resolve_package`: source, version, SHA-256 і +- Summary `resolve_package` у Package Acceptance: source, version, SHA-256 і artifact name. - Docker artifacts: `.artifacts/docker-tests/**/summary.json`, `failures.json`, lane logs і rerun commands. -- Summary upgrade survivor: `.artifacts/upgrade-survivor/summary.json`, - включно з baseline version, candidate version, scenario, phase timings і +- Upgrade survivor summary: `.artifacts/upgrade-survivor/summary.json`, + зокрема baseline version, candidate version, scenario, phase timings і recipe steps. -Віддавайте перевагу повторному запуску саме failed exact lane з тим самим -package artifact, а не повторному запуску всієї release umbrella. +Надавайте перевагу повторному запуску exact lane, що впав, з тим самим package artifact замість +повторного запуску всього release umbrella. diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index 5ef21c111..875519437 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -2,209 +2,209 @@ read_when: - Запуск тестів локально або в CI - Додавання регресійних тестів для помилок моделей/провайдерів - - Налагодження поведінки Gateway та агента -summary: 'Набір для тестування: набори тестів unit/e2e/live, ранери Docker і що охоплює кожен тест' + - Налагодження поведінки Gateway + агента +summary: 'Набір для тестування: набори unit/e2e/live, Docker-ранери та що охоплює кожен тест' title: Тестування x-i18n: - generated_at: "2026-05-01T22:37:26Z" + generated_at: "2026-05-02T02:01:58Z" model: gpt-5.5 provider: openai - source_hash: 8f9f9731281267faa880da7c8b4dff27b05d9656c412b25e912fa464ed7d5472 + source_hash: 9778143e73683fde493e9652f20b8301455b53adbe6c70e997f5af2f54b3fe6b source_path: help/testing.md workflow: 16 --- -OpenClaw має три набори Vitest (модульний/інтеграційний, e2e, із реальними сервісами) і невеликий набір -ранерів Docker. Цей документ є посібником «як ми тестуємо»: +OpenClaw має три набори тестів Vitest (unit/integration, e2e, live) і невеликий набір +Docker-ранерів. Цей документ є посібником «як ми тестуємо»: -- Що охоплює кожен набір (і що він свідомо _не_ охоплює). -- Які команди запускати для типових робочих процесів (локально, перед надсиланням змін, під час налагодження). -- Як тести з реальними сервісами знаходять облікові дані та вибирають моделі/провайдерів. +- Що покриває кожен набір тестів (і що він навмисно _не_ покриває). +- Які команди запускати для типових робочих процесів (локально, перед push, налагодження). +- Як live-тести знаходять облікові дані та вибирають моделі/провайдерів. - Як додавати регресійні тести для реальних проблем моделей/провайдерів. -**Стек QA (qa-lab, qa-channel, маршрути транспорту з реальними сервісами)** задокументовано окремо: +**Стек QA (qa-lab, qa-channel, live transport lanes)** задокументовано окремо: -- [Огляд QA](/uk/concepts/qa-e2e-automation) — архітектура, поверхня команд, створення сценаріїв. -- [Matrix QA](/uk/concepts/qa-matrix) — довідка для `pnpm openclaw qa matrix`. -- [Канал QA](/uk/channels/qa-channel) — синтетичний транспортний плагін, який використовують сценарії, що спираються на репозиторій. +- [Огляд QA](/uk/concepts/qa-e2e-automation) — архітектура, поверхня команд, написання сценаріїв. +- [Matrix QA](/uk/concepts/qa-matrix) — довідник для `pnpm openclaw qa matrix`. +- [QA channel](/uk/channels/qa-channel) — синтетичний транспортний Plugin, який використовують сценарії з репозиторію. -Ця сторінка описує запуск звичайних наборів тестів і ранерів Docker/Parallels. Розділ нижче зі спеціальними ранeрами QA ([спеціальні ранери QA](#qa-specific-runners)) перелічує конкретні виклики `qa` і відсилає до наведених вище довідок. +Ця сторінка охоплює запуск звичайних наборів тестів і Docker/Parallels-ранерів. Розділ про специфічні для QA ранери нижче ([Специфічні для QA ранери](#qa-specific-runners)) перелічує конкретні виклики `qa` і відсилає до наведених вище довідників. ## Швидкий старт -У більшості випадків: +У більшість днів: -- Повна перевірка (очікується перед надсиланням змін): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` -- Швидший локальний запуск повного набору на машині з достатніми ресурсами: `pnpm test:max` -- Прямий цикл спостереження Vitest: `pnpm test:watch` -- Прямий вибір файлу тепер також обробляє шляхи розширень/каналів: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Коли ітеруєте над однією помилкою, спершу надавайте перевагу цільовим запускам. -- QA-сайт на базі Docker: `pnpm qa:lab:up` -- QA-маршрут на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- Повний gate (очікується перед push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` +- Швидший локальний запуск повного набору тестів на машині з достатніми ресурсами: `pnpm test:max` +- Прямий цикл Vitest watch: `pnpm test:watch` +- Пряме таргетування файлів тепер маршрутизує також шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- Коли ітеруєте над одним збоєм, спочатку надавайте перевагу таргетованим запускам. +- Docker-backed сайт QA: `pnpm qa:lab:up` +- Linux VM-backed QA lane: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` Коли змінюєте тести або хочете додаткової впевненості: -- Перевірка покриття: `pnpm test:coverage` +- Coverage gate: `pnpm test:coverage` - Набір E2E: `pnpm test:e2e` -Під час налагодження реальних провайдерів/моделей (потребує реальних облікових даних): +Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані): -- Набір тестів із реальними сервісами (моделі + перевірки інструментів/зображень Gateway): `pnpm test:live` -- Тихо запустити один файл із тестами реальних сервісів: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -- Docker-прогін реальних моделей: `pnpm test:docker:live-models` - - Для кожної вибраної моделі тепер запускається текстовий хід і невелика перевірка у стилі читання файлу. - Моделі, чиї метадані оголошують вхід `image`, також виконують короткий хід із зображенням. - Вимикайте додаткові перевірки за допомогою `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` або +- Live-набір (моделі + gateway tool/image probes): `pnpm test:live` +- Тихо націлити один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Docker live model sweep: `pnpm test:docker:live-models` + - Кожна вибрана модель тепер виконує текстовий turn плюс невелику пробу в стилі читання файлу. + Моделі, метадані яких оголошують вхід `image`, також виконують крихітний image turn. + Вимикайте додаткові проби через `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` або `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0`, коли ізолюєте збої провайдера. - Покриття CI: щоденний `OpenClaw Scheduled Live And E2E Checks` і ручний - `OpenClaw Release Checks` обидва викликають багаторазовий workflow live/E2E з - `include_live_suites: true`, що включає окремі Docker-завдання матриці реальних моделей, - розбиті за провайдерами. - - Для сфокусованих повторних запусків у CI запустіть `OpenClaw Live And E2E Checks (Reusable)` + `OpenClaw Release Checks` обидва викликають reusable live/E2E workflow з + `include_live_suites: true`, що включає окремі Docker live model + matrix jobs, розділені за провайдером. + - Для сфокусованих повторних запусків CI запустіть `OpenClaw Live And E2E Checks (Reusable)` з `include_live_suites: true` і `live_models_only: true`. - - Додавайте нові інформативні секрети провайдерів до `scripts/ci-hydrate-live-auth.sh`, - а також до `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` та його - запланованих/релізних викликачів. -- Базова перевірка нативного прив’язаного чату Codex: `pnpm test:docker:live-codex-bind` - - Запускає Docker-маршрут із реальними сервісами проти шляху app-server Codex, прив’язує синтетичний - Slack DM за допомогою `/codex bind`, виконує `/codex fast` і - `/codex permissions`, а потім перевіряє, що звичайна відповідь і вкладення зображення - проходять через нативну прив’язку плагіна замість ACP. -- Базова перевірка тестового стенда app-server Codex: `pnpm test:docker:live-codex-harness` - - Запускає ходи агента Gateway через тестовий стенд app-server Codex, яким володіє плагін, - перевіряє `/codex status` і `/codex models`, а за замовчуванням виконує перевірки зображення, - Cron MCP, дочірнього агента та Guardian. Вимикайте перевірку дочірнього агента за допомогою - `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0`, коли ізолюєте інші збої - app-server Codex. Для сфокусованої перевірки дочірнього агента вимкніть інші перевірки: + - Додавайте нові високосигнальні secrets провайдерів до `scripts/ci-hydrate-live-auth.sh` + плюс `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` і його + scheduled/release callers. +- Native Codex bound-chat smoke: `pnpm test:docker:live-codex-bind` + - Запускає Docker live lane проти шляху Codex app-server, прив’язує синтетичний + Slack DM через `/codex bind`, виконує `/codex fast` і + `/codex permissions`, а потім перевіряє, що звичайна відповідь і image attachment + проходять через native plugin binding замість ACP. +- Codex app-server harness smoke: `pnpm test:docker:live-codex-harness` + - Запускає turns агента Gateway через plugin-owned Codex app-server harness, + перевіряє `/codex status` і `/codex models` та за замовчуванням виконує image, + cron MCP, sub-agent і Guardian probes. Вимикайте sub-agent probe через + `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0`, коли ізолюєте інші збої Codex + app-server. Для сфокусованої перевірки sub-agent вимкніть інші probes: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=1 pnpm test:docker:live-codex-harness`. - Це завершується після перевірки дочірнього агента, якщо не встановлено + Це завершується після sub-agent probe, якщо не встановлено `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0`. -- Базова перевірка команди порятунку Crestodian: `pnpm test:live:crestodian-rescue-channel` - - Додаткова захисна перевірка за явним увімкненням для поверхні команди порятунку - каналу повідомлень. Вона виконує `/crestodian status`, ставить у чергу збережувану зміну - моделі, відповідає `/crestodian yes` і перевіряє шлях запису аудиту/конфігурації. -- Базова Docker-перевірка планувальника Crestodian: `pnpm test:docker:crestodian-planner` - - Запускає Crestodian у контейнері без конфігурації з фальшивим Claude CLI у `PATH` - і перевіряє, що нечіткий резервний механізм планувальника перетворюється на аудитований типізований - запис конфігурації. -- Базова Docker-перевірка першого запуску Crestodian: `pnpm test:docker:crestodian-first-run` - - Починає з порожнього каталогу стану OpenClaw, спрямовує чистий `openclaw` до - Crestodian, застосовує записи налаштування/моделі/агента/плагіна Discord + SecretRef, - перевіряє конфігурацію та записи аудиту. Той самий шлях налаштування Ring 0 - також покрито в QA Lab за допомогою +- Crestodian rescue command smoke: `pnpm test:live:crestodian-rescue-channel` + - Opt-in перевірка «belt-and-suspenders» для поверхні rescue command каналу повідомлень. + Вона виконує `/crestodian status`, ставить у чергу постійну зміну моделі, + відповідає `/crestodian yes` і перевіряє шлях запису audit/config. +- Crestodian planner Docker smoke: `pnpm test:docker:crestodian-planner` + - Запускає Crestodian у контейнері без конфігурації з фейковим Claude CLI у `PATH` + і перевіряє, що fuzzy planner fallback перетворюється на audited typed + config write. +- Crestodian first-run Docker smoke: `pnpm test:docker:crestodian-first-run` + - Починає з порожнього каталогу стану OpenClaw, маршрутизує bare `openclaw` до + Crestodian, застосовує setup/model/agent/Discord plugin + SecretRef writes, + валідує конфігурацію та перевіряє audit entries. Той самий шлях налаштування Ring 0 + також покрито в QA Lab через `pnpm openclaw qa suite --scenario crestodian-ring-zero-setup`. -- Базова перевірка вартості Moonshot/Kimi: зі встановленим `MOONSHOT_API_KEY` запустіть +- Moonshot/Kimi cost smoke: з установленим `MOONSHOT_API_KEY` запустіть `openclaw models list --provider moonshot --json`, потім запустіть ізольований `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` - для `moonshot/kimi-k2.6`. Перевірте, що JSON повідомляє Moonshot/K2.6, а - транскрипт асистента зберігає нормалізоване `usage.cost`. + проти `moonshot/kimi-k2.6`. Перевірте, що JSON повідомляє Moonshot/K2.6, а + транскрипт асистента зберігає нормалізований `usage.cost`. -Коли потрібен лише один проблемний випадок, звужуйте тести з реальними сервісами через змінні середовища списку дозволених, описані нижче. +Коли потрібен лише один збійний випадок, надавайте перевагу звуженню live-тестів через змінні середовища allowlist, описані нижче. -## Спеціальні ранери QA +## Специфічні для QA ранери -Ці команди доповнюють основні набори тестів, коли потрібна реалістичність QA-lab: +Ці команди розташовані поруч з основними наборами тестів, коли потрібна реалістичність QA-lab: -CI запускає QA Lab у спеціальних робочих процесах. `Parity gate` запускається для відповідних PR і -з ручного запуску з моковими провайдерами. `QA-Lab - All Lanes` запускається щоночі на -`main` і з ручного запуску з моковою перевіркою паритету, маршрутом Matrix із реальними сервісами, -керованим Convex маршрутом Telegram із реальними сервісами та керованим Convex маршрутом Discord із реальними сервісами як -паралельними завданнями. Заплановані перевірки QA і релізні перевірки явно передають Matrix `--profile fast`, -тоді як типове значення в Matrix CLI та ручному введенні workflow залишається -`all`; ручний запуск може розбити `all` на завдання `transport`, `media`, `e2ee-smoke`, -`e2ee-deep` і `e2ee-cli`. `OpenClaw Release Checks` перед затвердженням релізу запускає перевірку паритету плюс -швидкі маршрути Matrix і Telegram, використовуючи -`mock-openai/gpt-5.5` для релізних перевірок транспорту, щоб вони залишалися детермінованими -й уникали звичайного запуску плагіна провайдера. Ці Gateway-и транспорту з реальними сервісами вимикають -пошук у пам’яті; поведінка пам’яті залишається покритою наборами паритету QA. +CI запускає QA Lab у виділених workflows. `Parity gate` запускається на відповідних PR +і з ручного dispatch з mock-провайдерами. `QA-Lab - All Lanes` запускається щоночі на +`main` і з ручного dispatch з mock parity gate, live Matrix lane, +Convex-managed live Telegram lane і Convex-managed live Discord lane як +паралельні jobs. Заплановані QA та release checks явно передають Matrix `--profile fast`, +тоді як Matrix CLI і стандартне значення manual workflow input лишаються +`all`; manual dispatch може розбити `all` на jobs `transport`, `media`, `e2ee-smoke`, +`e2ee-deep` і `e2ee-cli`. `OpenClaw Release Checks` запускає parity плюс +fast Matrix і Telegram lanes перед release approval, використовуючи +`mock-openai/gpt-5.5` для release transport checks, щоб вони лишалися детермінованими +та уникали звичайного запуску provider-plugin. Ці live transport gateways вимикають +memory search; поведінка пам’яті лишається покритою QA parity suites. -Повні релізні шарди медіа з реальними сервісами використовують -`ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, де вже є -`ffmpeg` і `ffprobe`. Docker-шарди реальних моделей/бекендів використовують спільний -образ `ghcr.io/openclaw/openclaw-live-test:`, зібраний один раз для вибраного -коміту, а потім витягують його з `OPENCLAW_SKIP_DOCKER_BUILD=1` замість повторної збірки -всередині кожного шарду. +Full release live media shards використовують +`ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, який уже має +`ffmpeg` і `ffprobe`. Docker live model/backend shards використовують спільний образ +`ghcr.io/openclaw/openclaw-live-test:`, зібраний один раз для вибраного +commit, а потім завантажують його з `OPENCLAW_SKIP_DOCKER_BUILD=1` замість перебудови +всередині кожного shard. - `pnpm openclaw qa suite` - - Запускає QA-сценарії, що спираються на репозиторій, безпосередньо на хості. + - Запускає сценарії QA з репозиторію безпосередньо на host. - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими - воркерами Gateway. Типова конкурентність `qa-channel` дорівнює 4 (обмежено - кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати - кількість воркерів, або `--concurrency 1` для старішого послідовного маршруту. - - Завершується з ненульовим кодом, коли будь-який сценарій падає. Використовуйте `--allow-failures`, коли - потрібні артефакти без коду завершення з помилкою. - - Підтримує режими провайдерів `live-frontier`, `mock-openai` і `aimock`. - `aimock` запускає локальний сервер провайдера на базі AIMock для експериментального - покриття фікстур і моків протоколу, не замінюючи маршрут `mock-openai`, - обізнаний зі сценаріями. + gateway workers. `qa-channel` за замовчуванням має concurrency 4 (обмежену + кількістю вибраних сценаріїв). Використовуйте `--concurrency ` для налаштування + кількості workers або `--concurrency 1` для старішої serial lane. + - Завершується з ненульовим кодом, коли будь-який сценарій зазнає збою. Використовуйте `--allow-failures`, коли + хочете отримати artifacts без failing exit code. + - Підтримує provider modes `live-frontier`, `mock-openai` і `aimock`. + `aimock` запускає локальний AIMock-backed provider server для експериментального + покриття fixtures і protocol-mock без заміни scenario-aware + `mock-openai` lane. - `pnpm test:gateway:cpu-scenarios` - - Запускає тест продуктивності запуску Gateway плюс невеликий пакет мокових сценаріїв QA Lab + - Запускає gateway startup bench плюс невеликий пакет mock QA Lab scenarios (`channel-chat-baseline`, `memory-failure-fallback`, - `gateway-restart-inflight-run`) і записує зведений підсумок спостережень CPU - у `.artifacts/gateway-cpu-scenarios/`. - - За замовчуванням позначає лише тривалі спостереження високого завантаження CPU (`--cpu-core-warn` - плюс `--hot-wall-warn-ms`), тож короткі сплески під час запуску записуються як метрики - і не виглядають як регресія, де Gateway на кілька хвилин завантажує CPU до межі. - - Використовує зібрані артефакти `dist`; спершу запустіть збірку, якщо робоча копія ще не - має актуальних артефактів виконання. + `gateway-restart-inflight-run`) і записує об’єднаний CPU observation + summary у `.artifacts/gateway-cpu-scenarios/`. + - За замовчуванням позначає лише sustained hot CPU observations (`--cpu-core-warn` + плюс `--hot-wall-warn-ms`), тому короткі startup bursts записуються як metrics + і не виглядають як регресія minutes-long gateway peg. + - Використовує зібрані artifacts `dist`; спочатку запустіть build, якщо checkout ще не + має свіжого runtime output. - `pnpm openclaw qa suite --runner multipass` - - Запускає той самий набір QA всередині одноразової Linux VM Multipass. - - Зберігає таку саму поведінку вибору сценаріїв, як `qa suite` на хості. - - Повторно використовує ті самі прапорці вибору провайдера/моделі, що й `qa suite`. - - Запуски з реальними сервісами передають підтримувані автентифікаційні входи QA, практичні для гостьової системи: - ключі провайдера зі змінних середовища, шлях до live-конфігурації провайдера QA та `CODEX_HOME`, + - Запускає той самий набір QA всередині disposable Multipass Linux VM. + - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на host. + - Повторно використовує ті самі прапорці вибору provider/model, що й `qa suite`. + - Live-запуски передають підтримувані QA auth inputs, практичні для guest: + env-based provider keys, шлях QA live provider config і `CODEX_HOME`, коли він присутній. - - Каталоги виводу мають залишатися під коренем репозиторію, щоб гостьова система могла записувати назад через - змонтований робочий простір. - - Записує звичайний звіт QA + підсумок, а також журнали Multipass у + - Output dirs мають лишатися під коренем репозиторію, щоб guest міг записувати назад через + mounted workspace. + - Записує звичайний QA report + summary плюс Multipass logs у `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Запускає QA-сайт на базі Docker для операторської QA-роботи. + - Запускає Docker-backed QA site для operator-style QA work. - `pnpm test:docker:npm-onboard-channel-agent` - - Збирає tarball npm з поточної робочої копії, встановлює його глобально в - Docker, виконує неінтерактивне первинне налаштування з API-ключем OpenAI, за замовчуванням налаштовує Telegram, - перевіряє, що упакований runtime плагіна завантажується без виправлення залежностей під час запуску, - запускає doctor і виконує один локальний хід агента проти мокової - кінцевої точки OpenAI. - - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити той самий маршрут встановлення пакета - з Discord. + - Збирає npm tarball з поточного checkout, глобально встановлює його в + Docker, запускає non-interactive OpenAI API-key onboarding, за замовчуванням налаштовує Telegram, + перевіряє, що packaged plugin runtime завантажується без startup + dependency repair, запускає doctor і виконує один local agent turn проти + mocked OpenAI endpoint. + - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити ту саму packaged-install + lane з Discord. - `pnpm test:docker:session-runtime-context` - - Запускає детерміновану Docker-перевірку зібраного застосунку для транскриптів із вбудованим контекстом виконання. - Вона перевіряє, що прихований контекст виконання OpenClaw зберігається як - нестандартне повідомлення без відображення замість потрапляння у видимий хід користувача, - потім додає як початкові дані уражений пошкоджений JSONL сесії та перевіряє, що - `openclaw doctor --fix` переписує його до активної гілки з резервною копією. + - Запускає deterministic built-app Docker smoke для embedded runtime context + transcripts. Він перевіряє, що hidden OpenClaw runtime context зберігається як + non-display custom message замість витоку у видимий user turn, + потім засіває affected broken session JSONL і перевіряє, що + `openclaw doctor --fix` переписує його на active branch із backup. - `pnpm test:docker:npm-telegram-live` - - Встановлює кандидат пакета OpenClaw у Docker, виконує первинне налаштування встановленого пакета, - налаштовує Telegram через встановлений CLI, а потім повторно використовує - маршрут QA Telegram із реальними сервісами з цим установленим пакетом як Gateway системи під тестуванням. - - Типове значення: `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`; встановіть + - Встановлює package candidate OpenClaw у Docker, запускає installed-package + onboarding, налаштовує Telegram через встановлений CLI, потім повторно використовує + live Telegram QA lane з цим installed package як SUT Gateway. + - За замовчуванням використовує `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`; встановіть `OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz` або - `OPENCLAW_CURRENT_PACKAGE_TGZ`, щоб тестувати розв’язаний локальний tarball замість - встановлення з реєстру. - - Використовує ті самі облікові дані Telegram зі змінних середовища або джерело облікових даних Convex, що й - `pnpm openclaw qa telegram`. Для автоматизації CI/релізу встановіть + `OPENCLAW_CURRENT_PACKAGE_TGZ`, щоб тестувати resolved local tarball замість + встановлення з registry. + - Використовує ті самі Telegram env credentials або Convex credential source, що й + `pnpm openclaw qa telegram`. Для автоматизації CI/release встановіть `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex` плюс - `OPENCLAW_QA_CONVEX_SITE_URL` і секрет ролі. Якщо - `OPENCLAW_QA_CONVEX_SITE_URL` і секрет ролі Convex присутні в CI, - Docker-обгортка автоматично вибирає Convex. - - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` перевизначає спільний - `OPENCLAW_QA_CREDENTIAL_ROLE` лише для цього маршруту. - - GitHub Actions надає цей маршрут як ручний workflow мейнтейнера - `NPM Telegram Beta E2E`. Він не запускається під час злиття. Workflow використовує - середовище `qa-live-shared` і оренди облікових даних Convex CI. -- GitHub Actions також надає `Package Acceptance` для окремої продуктової перевірки - одного кандидата пакета. Він приймає довірений ref, опубліковану специфікацію npm, - HTTPS-URL tarball плюс SHA-256 або артефакт tarball з іншого запуску, завантажує + `OPENCLAW_QA_CONVEX_SITE_URL` і role secret. Якщо + `OPENCLAW_QA_CONVEX_SITE_URL` і Convex role secret присутні в CI, + Docker wrapper автоматично вибирає Convex. + - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` перевизначає спільну + `OPENCLAW_QA_CREDENTIAL_ROLE` лише для цієї lane. + - GitHub Actions надає цю lane як ручний maintainer workflow + `NPM Telegram Beta E2E`. Він не запускається під час merge. Workflow використовує + середовище `qa-live-shared` і Convex CI credential leases. +- GitHub Actions також надає `Package Acceptance` для side-run product proof + проти одного candidate package. Він приймає trusted ref, published npm spec, + HTTPS tarball URL плюс SHA-256 або tarball artifact з іншого run, завантажує нормалізований `openclaw-current.tgz` як `package-under-test`, а потім запускає - наявний планувальник Docker E2E з профілями маршрутів smoke, package, product, full або custom. + наявний Docker E2E scheduler з profiles lane smoke, package, product, full або custom. Встановіть `telegram_mode=mock-openai` або `live-frontier`, щоб запустити - workflow QA Telegram проти того самого артефакту `package-under-test`. - - Продуктова перевірка останньої beta: + Telegram QA workflow проти того самого artifact `package-under-test`. + - Latest beta product proof: ```bash gh workflow run package-acceptance.yml --ref main \ @@ -214,7 +214,7 @@ gh workflow run package-acceptance.yml --ref main \ -f telegram_mode=mock-openai ``` -- Перевірка за точною URL-адресою tarball потребує хешу: +- Доказ точного tarball URL потребує digest: ```bash gh workflow run package-acceptance.yml --ref main \ @@ -235,32 +235,32 @@ gh workflow run package-acceptance.yml --ref main \ ``` - `pnpm test:docker:plugins` - - Пакує й установлює поточну збірку OpenClaw у Docker, запускає Gateway - з налаштованим OpenAI, а потім вмикає вбудовані канали/plugins через - редагування конфігурації. - - Перевіряє, що виявлення налаштування залишає неналаштовані завантажувані plugins відсутніми, + - Пакує та встановлює поточну збірку OpenClaw у Docker, запускає Gateway + з налаштованим OpenAI, а потім вмикає вбудовані канали/плагіни через + зміни конфігурації. + - Перевіряє, що виявлення налаштування не показує неналаштовані завантажувані плагіни, перше налаштоване виправлення doctor явно встановлює кожен відсутній завантажуваний - plugin, а другий перезапуск не запускає приховане виправлення + плагін, а другий перезапуск не запускає приховане виправлення залежностей. - - Також установлює відомий старіший базовий варіант npm, вмикає Telegram перед запуском - `openclaw update --tag ` і перевіряє, що post-update doctor кандидата - очищає залишки застарілих залежностей plugin без - postinstall-виправлення з боку harness. + - Також встановлює відому старішу базову версію npm, вмикає Telegram перед запуском + `openclaw update --tag ` і перевіряє, що doctor кандидата + після оновлення очищає залишки залежностей застарілих плагінів без + виправлення postinstall з боку тестового стенда. - `pnpm test:parallels:npm-update` - - Запускає native smoke для оновлення packaged-install у гостьових системах Parallels. Кожна + - Запускає smoke-тест оновлення нативного пакетного встановлення на гостьових системах Parallels. Кожна вибрана платформа спочатку встановлює запитаний базовий пакет, потім запускає - встановлену команду `openclaw update` у тій самій гостьовій системі та перевіряє - встановлену версію, статус оновлення, готовність Gateway і один локальний хід - агента. + встановлену команду `openclaw update` у тій самій гостьовій системі й перевіряє + встановлену версію, статус оновлення, готовність gateway і один локальний + хід агента. - Використовуйте `--platform macos`, `--platform windows` або `--platform linux` під час - ітерацій на одній гостьовій системі. Використовуйте `--json` для шляху до підсумкового артефакта та - статусу кожної смуги. - - Смуга OpenAI за замовчуванням використовує `openai/gpt-5.5` для підтвердження live agent-turn. + ітерацій на одній гостьовій системі. Використовуйте `--json` для шляху до артефакту зведення та + статусу по кожній смузі. + - Смуга OpenAI типово використовує `openai/gpt-5.5` для live-підтвердження ходу агента. Передайте `--model ` або встановіть `OPENCLAW_PARALLELS_OPENAI_MODEL`, коли навмисно перевіряєте іншу модель OpenAI. - - Обгортайте довгі локальні запуски в timeout на хості, щоб зависання транспорту Parallels не могли - спожити решту вікна тестування: + - Обгорніть довгі локальні запуски в тайм-аут хоста, щоб зависання транспорту Parallels не могли + використати решту вікна тестування: ```bash timeout --foreground 150m pnpm test:parallels:npm-update -- --json @@ -268,70 +268,70 @@ gh workflow run package-acceptance.yml --ref main \ ``` - Скрипт записує вкладені журнали смуг у `/tmp/openclaw-parallels-npm-update.*`. - Перегляньте `windows-update.log`, `macos-update.log` або `linux-update.log`, + Перевірте `windows-update.log`, `macos-update.log` або `linux-update.log`, перш ніж припускати, що зовнішня обгортка зависла. - - Оновлення Windows може витратити від 10 до 15 хвилин на post-update doctor і роботу з - оновленням пакетів на холодній гостьовій системі; це все ще нормально, якщо вкладений npm + - Оновлення Windows може витрачати 10-15 хвилин на post-update doctor і роботу з + оновленням пакетів на холодній гостьовій системі; це все ще нормальний стан, коли вкладений npm debug-журнал просувається. - - Не запускайте цю агрегатну обгортку паралельно з окремими smoke-смугами Parallels + - Не запускайте цю агреговану обгортку паралельно з окремими smoke-смугами Parallels macOS, Windows або Linux. Вони спільно використовують стан VM і можуть конфліктувати під час - відновлення snapshot, обслуговування пакетів або стану Gateway у гостьовій системі. - - Post-update proof запускає звичайну вбудовану поверхню plugin, оскільки - capability facades, такі як speech, image generation і media - understanding, завантажуються через вбудовані runtime API, навіть коли сам хід агента + відновлення snapshot, обслуговування пакетів або стану gateway гостьової системи. + - Підтвердження після оновлення запускає звичайну поверхню вбудованих плагінів, оскільки + фасади можливостей, як-от мовлення, генерація зображень і розуміння медіа, + завантажуються через вбудовані runtime API, навіть коли сам хід агента перевіряє лише просту текстову відповідь. - `pnpm openclaw qa aimock` - Запускає лише локальний сервер провайдера AIMock для прямого smoke-тестування протоколу. - `pnpm openclaw qa matrix` - - Запускає live QA-смугу Matrix проти disposable Docker-backed homeserver Tuwunel. Лише source-checkout — packaged installs не постачають `qa-lab`. + - Запускає live-смугу QA Matrix проти одноразового Docker-backed homeserver Tuwunel. Тільки source-checkout — пакетні встановлення не постачають `qa-lab`. - Повний CLI, каталог профілів/сценаріїв, env vars і структура артефактів: [Matrix QA](/uk/concepts/qa-matrix). - `pnpm openclaw qa telegram` - - Запускає live QA-смугу Telegram проти реальної приватної групи, використовуючи токени driver і SUT bot з env. - - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Ідентифікатор групи має бути числовим ідентифікатором чату Telegram. - - Підтримує `--credential-source convex` для спільних pooled credentials. За замовчуванням використовуйте режим env або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути pooled leases. - - Завершується з ненульовим кодом, коли будь-який сценарій зазнає невдачі. Використовуйте `--allow-failures`, коли - потрібні артефакти без коду виходу, що означає невдачу. - - Потребує двох різних bot в одній приватній групі, причому SUT bot має відкривати Telegram username. - - Для стабільного спостереження bot-to-bot увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох bot і переконайтеся, що driver bot може спостерігати груповий bot-трафік. - - Записує звіт Telegram QA, підсумок і артефакт observed-messages у `.artifacts/qa-e2e/...`. Сценарії відповідей містять RTT від запиту надсилання driver до спостереженої відповіді SUT. + - Запускає live-смугу QA Telegram проти справжньої приватної групи, використовуючи токени бота-драйвера та SUT-бота з env. + - Потрібні `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Ідентифікатор групи має бути числовим chat id Telegram. + - Підтримує `--credential-source convex` для спільних пулованих облікових даних. Типово використовуйте режим env або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути пуловані lease. + - Завершується з ненульовим кодом, коли будь-який сценарій завершується невдало. Використовуйте `--allow-failures`, коли + потрібні артефакти без коду виходу з помилкою. + - Потребує двох різних ботів в одній приватній групі, причому SUT-бот має надавати Telegram username. + - Для стабільного спостереження bot-to-bot увімкніть Bot-to-Bot Communication Mode в `@BotFather` для обох ботів і переконайтеся, що бот-драйвер може спостерігати трафік ботів групи. + - Записує звіт Telegram QA, зведення та артефакт observed-messages у `.artifacts/qa-e2e/...`. Сценарії з відповідями включають RTT від запиту надсилання драйвера до спостереженої відповіді SUT. -Live transport lanes мають один стандартний контракт, щоб нові транспорти не розходилися; матриця покриття для кожної смуги розміщена в [Огляд QA → Покриття live transport](/uk/concepts/qa-e2e-automation#live-transport-coverage). `qa-channel` — це широкий synthetic suite, і він не є частиною цієї матриці. +Live-смуги транспорту спільно використовують один стандартний контракт, щоб нові транспорти не розходилися; матриця покриття по смугах розміщена в [Огляд QA → Покриття live-транспорту](/uk/concepts/qa-e2e-automation#live-transport-coverage). `qa-channel` — це широкий синтетичний набір і він не є частиною цієї матриці. ### Спільні облікові дані Telegram через Convex (v1) Коли `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) увімкнено для -`openclaw qa telegram`, QA lab отримує ексклюзивну lease з пулу на базі Convex, надсилає heartbeats -для цієї lease, поки смуга виконується, і звільняє lease під час завершення. +`openclaw qa telegram`, QA lab отримує ексклюзивний lease з пулу на базі Convex, надсилає Heartbeat +для цього lease, поки смуга працює, і звільняє lease під час завершення. -Еталонний scaffold проєкту Convex: +Еталонний каркас проєкту Convex: - `qa/convex-credential-broker/` Обов’язкові env vars: -- `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад, `https://your-deployment.convex.site`) -- Один secret для вибраної ролі: +- `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад `https://your-deployment.convex.site`) +- Один секрет для вибраної ролі: - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` для `maintainer` - `OPENCLAW_QA_CONVEX_SECRET_CI` для `ci` - Вибір ролі облікових даних: - CLI: `--credential-role maintainer|ci` - - Типове значення env: `OPENCLAW_QA_CREDENTIAL_ROLE` (за замовчуванням `ci` у CI, інакше `maintainer`) + - Типове значення env: `OPENCLAW_QA_CREDENTIAL_ROLE` (типово `ci` у CI, інакше `maintainer`) Необов’язкові env vars: -- `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (за замовчуванням `1200000`) -- `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (за замовчуванням `30000`) -- `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (за замовчуванням `90000`) -- `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (за замовчуванням `15000`) -- `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (за замовчуванням `/qa-credentials/v1`) +- `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (типово `1200000`) +- `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (типово `30000`) +- `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (типово `90000`) +- `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (типово `15000`) +- `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (типово `/qa-credentials/v1`) - `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (необов’язковий trace id) -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback `http://` URL Convex для розробки лише локально. +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback `http://` URL-адреси Convex лише для локальної розробки. `OPENCLAW_QA_CONVEX_SITE_URL` має використовувати `https://` у звичайній роботі. -Адміністративні команди maintainer (додавання/видалення/перелік пулу) потребують +Адміністративні команди maintainer (pool add/remove/list) потребують саме `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. CLI-помічники для maintainers: @@ -343,12 +343,12 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -Використовуйте `doctor` перед live-запусками, щоб перевірити URL сайту Convex, broker secrets, -endpoint prefix, HTTP timeout і доступність admin/list без друку -значень secret. Використовуйте `--json` для машинно-читаного виводу в scripts і CI -utilities. +Використовуйте `doctor` перед live-запусками, щоб перевірити URL сайту Convex, секрети брокера, +префікс endpoint, HTTP timeout і доступність admin/list без виведення +секретних значень. Використовуйте `--json` для machine-readable виводу в скриптах і CI +утилітах. -Контракт endpoint за замовчуванням (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): +Типовий контракт endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): - `POST /acquire` - Запит: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` @@ -360,32 +360,32 @@ utilities. - `POST /release` - Запит: `{ kind, ownerId, actorRole, credentialId, leaseToken }` - Успіх: `{ status: "ok" }` (або порожній `2xx`) -- `POST /admin/add` (лише maintainer secret) +- `POST /admin/add` (лише секрет maintainer) - Запит: `{ kind, actorId, payload, note?, status? }` - Успіх: `{ status: "ok", credential }` -- `POST /admin/remove` (лише maintainer secret) +- `POST /admin/remove` (лише секрет maintainer) - Запит: `{ credentialId, actorId }` - Успіх: `{ status: "ok", changed, credential }` - - Захист active lease: `{ status: "error", code: "LEASE_ACTIVE", ... }` -- `POST /admin/list` (лише maintainer secret) + - Захист активного lease: `{ status: "error", code: "LEASE_ACTIVE", ... }` +- `POST /admin/list` (лише секрет maintainer) - Запит: `{ kind?, status?, includePayload?, limit? }` - Успіх: `{ status: "ok", credentials, count }` -Форма payload для kind Telegram: +Форма payload для типу Telegram: - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` має бути рядком числового ідентифікатора чату Telegram. -- `admin/add` перевіряє цю форму для `kind: "telegram"` і відхиляє некоректні payloads. +- `groupId` має бути рядком числового chat id Telegram. +- `admin/add` перевіряє цю форму для `kind: "telegram"` і відхиляє malformed payloads. ### Додавання каналу до QA -Архітектура та імена scenario-helper для нових адаптерів каналів описані в [Огляд QA → Додавання каналу](/uk/concepts/qa-e2e-automation#adding-a-channel). Мінімальна вимога: реалізувати transport runner на спільному host seam `qa-lab`, оголосити `qaRunners` у маніфесті plugin, змонтувати як `openclaw qa ` і створити сценарії в `qa/scenarios/`. +Архітектура й назви scenario-helper для нових адаптерів каналів описані в [Огляд QA → Додавання каналу](/uk/concepts/qa-e2e-automation#adding-a-channel). Мінімальна планка: реалізувати transport runner на спільному host seam `qa-lab`, оголосити `qaRunners` у маніфесті плагіна, змонтувати як `openclaw qa ` і створити сценарії в `qa/scenarios/`. -## Тестові набори (що де запускається) +## Набори тестів (що де запускається) -Думайте про набори як про «зростання реалістичності» (і зростання нестабільності/вартості): +Сприймайте набори як «зростання реалістичності» (і зростання нестабільності/вартості): -### Unit / integration (за замовчуванням) +### Unit / integration (типово) - Команда: `pnpm test` - Конфігурація: нецільові запуски використовують shard-набір `vitest.full-*.config.ts` і можуть розгортати multi-project shards у per-project configs для паралельного планування @@ -396,79 +396,108 @@ utilities. - Детерміновані регресії для відомих помилок - Очікування: - Запускається в CI - - Реальні keys не потрібні + - Не потребує справжніх ключів - Має бути швидким і стабільним - Тести resolver і public-surface loader мають доводити широку fallback-поведінку `api.js` і - `runtime-api.js` за допомогою згенерованих малих fixtures plugin, а не - справжніх bundled plugin source APIs. Завантаження справжніх plugin API належать до - contract/integration suites, що належать plugin. + `runtime-api.js` із generated tiny plugin fixtures, а не + реальними source APIs вбудованих плагінів. Реальні завантаження API плагінів належать до + contract/integration suites, якими володіють плагіни. - + - - Ненацілений `pnpm test` запускає дванадцять менших shard-конфігурацій (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського нативного процесу кореневого проєкту. Це зменшує піковий RSS на завантажених машинах і запобігає тому, щоб робота auto-reply/extensions виснажувала непов’язані набори тестів. - - `pnpm test --watch` досі використовує нативний кореневий граф проєкту `vitest.config.ts`, бо цикл спостереження з кількома shard-ами непрактичний. - - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку спрямовують явні цілі файлів/каталогів через scoped lanes, тому `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` не сплачує повну вартість запуску кореневого проєкту. - - `pnpm test:changed` типово розгортає змінені git-шляхи в дешеві scoped lanes: прямі зміни тестів, сусідні файли `*.test.ts`, явні мапінги джерел і локальні залежні елементи import-graph. Зміни конфігурації/налаштувань/пакунків не запускають широкі тести, якщо ви явно не використаєте `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`. - - `pnpm check:changed` — звичайний розумний локальний check gate для вузької роботи. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, release metadata, live Docker tooling і tooling, а потім запускає відповідні команди typecheck, lint і guard. Він не запускає Vitest-тести; для тестового доказу викликайте `pnpm test:changed` або явний `pnpm test `. Підвищення версій лише в release metadata запускають цільові перевірки версії/конфігурації/кореневих залежностей із guard, який відхиляє зміни пакунків поза верхньорівневим полем version. - - Зміни live Docker ACP harness запускають сфокусовані перевірки: синтаксис shell для live Docker auth scripts і dry-run live Docker scheduler. Зміни `package.json` включаються лише тоді, коли diff обмежений `scripts["test:docker:live-*"]`; зміни залежностей, export, version та іншої поверхні пакунка досі використовують ширші guards. - - Легкі щодо імпортів модульні тести з agents, commands, plugins, auto-reply helpers, `plugin-sdk` та подібних чистих utility-зон спрямовуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних lanes. - - Вибрані вихідні helper-файли `plugin-sdk` і `commands` також маплять changed-mode запуски на явні сусідні тести в цих легких lanes, тому зміни helpers не перезапускають повний важкий набір для цього каталогу. - - `auto-reply` має окремі buckets для верхньорівневих core helpers, верхньорівневих інтеграційних тестів `reply.*` і піддерева `src/auto-reply/reply/**`. CI додатково розділяє піддерево reply на shards agent-runner, dispatch і commands/state-routing, щоб один import-heavy bucket не володів повним Node-хвостом. - - Звичайний CI для PR/main навмисно пропускає пакетний sweep extensions і release-only shard `agentic-plugins`. Full Release Validation запускає окремий дочірній workflow `Plugin Prerelease` для цих plugin/extension-heavy наборів на release candidates. + - Ненацілений `pnpm test` запускає дванадцять менших конфігурацій шардів (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського процесу нативного кореневого проєкту. Це зменшує пікове RSS на навантажених машинах і не дає роботі auto-reply/розширень виснажувати непов’язані набори тестів. + - `pnpm test --watch` усе ще використовує нативний граф проєктів кореневого `vitest.config.ts`, бо цикл спостереження з багатьма шардами непрактичний. + - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку спрямовують явні цілі файлів/каталогів через обмежені смуги, тож `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску кореневого проєкту. + - `pnpm test:changed` типово розгортає змінені git-шляхи в дешеві обмежені смуги: прямі зміни тестів, сусідні файли `*.test.ts`, явні зіставлення джерел і локальні залежні елементи графа імпортів. Зміни конфігурації/налаштування/пакунків не запускають тести широко, якщо ви явно не використаєте `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`. + - `pnpm check:changed` — це звичайний розумний локальний контрольний шлюз для вузької роботи. Він класифікує diff на core, тести core, розширення, тести розширень, застосунки, документацію, метадані релізу, live Docker tooling і tooling, а потім запускає відповідні команди перевірки типів, lint і guard. Він не запускає тести Vitest; викликайте `pnpm test:changed` або явний `pnpm test ` для доказу тестами. Підвищення версій лише в метаданих релізу запускає цільові перевірки версії/конфігурації/кореневих залежностей, із запобіжником, що відхиляє зміни пакунка поза верхньорівневим полем версії. + - Зміни в live Docker ACP harness запускають сфокусовані перевірки: синтаксис shell для live Docker auth-скриптів і dry-run live Docker scheduler. Зміни `package.json` включаються лише тоді, коли diff обмежений `scripts["test:docker:live-*"]`; зміни залежностей, export, версії та іншої поверхні пакунка все ще використовують ширші guard-перевірки. + - Легкі щодо імпортів unit-тести з agents, commands, plugins, auto-reply helpers, `plugin-sdk` і подібних зон чистих утиліт спрямовуються через смугу `unit-fast`, яка пропускає `test/setup-openclaw-runtime.ts`; файли зі станом або важкі щодо runtime залишаються на наявних смугах. + - Вибрані helper-файли джерел `plugin-sdk` і `commands` також зіставляють запуски changed-mode з явними сусідніми тестами в цих легких смугах, тож зміни helper уникають повторного запуску всього важкого набору для цього каталогу. + - `auto-reply` має окремі кошики для верхньорівневих core helpers, верхньорівневих інтеграційних тестів `reply.*` і піддерева `src/auto-reply/reply/**`. CI додатково розділяє піддерево reply на шарди agent-runner, dispatch і commands/state-routing, щоб один важкий щодо імпортів кошик не володів усім хвостом Node. + - Звичайний CI для PR/main навмисно пропускає пакетний sweep розширень і релізний shard `agentic-plugins`. Повна Release Validation запускає окремий дочірній workflow `Plugin Prerelease` для цих важких щодо Plugin/розширень наборів на реліз-кандидатах. - + - - Коли ви змінюєте вхідні дані discovery для message-tool або runtime-контекст compaction, зберігайте обидва рівні покриття. - - Додавайте сфокусовані helper-регресії для меж чистого routing і normalization. - - Підтримуйте справність інтеграційних наборів embedded runner: + - Коли ви змінюєте вхідні дані виявлення message-tool або runtime-контекст compaction, + зберігайте обидва рівні покриття. + - Додавайте сфокусовані регресійні helper-тести для меж чистої маршрутизації та нормалізації. + - Підтримуйте здоровими інтеграційні набори вбудованого runner: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` і `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Ці набори перевіряють, що scoped ids і поведінка compaction досі проходять - через реальні шляхи `run.ts` / `compact.ts`; helper-only тести не є - достатньою заміною для цих інтеграційних шляхів. + - Ці набори перевіряють, що scoped ids і поведінка compaction усе ще проходять + через реальні шляхи `run.ts` / `compact.ts`; тести лише helper + не є достатньою заміною для цих інтеграційних шляхів. - + - Базова конфігурація Vitest типово використовує `threads`. - Спільна конфігурація Vitest фіксує `isolate: false` і використовує - non-isolated runner у кореневих проєктах, e2e та live-конфігураціях. - - Кореневий UI lane зберігає своє налаштування `jsdom` та optimizer, але також працює на спільному non-isolated runner. - - Кожен shard `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` зі спільної конфігурації Vitest. - - `scripts/run-vitest.mjs` типово додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. + неізольований runner у кореневих проєктах, e2e та live-конфігураціях. + - Коренева UI-смуга зберігає своє налаштування `jsdom` і optimizer, але також працює на + спільному неізольованому runner. + - Кожен shard `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` + зі спільної конфігурації Vitest. + - `scripts/run-vitest.mjs` типово додає `--no-maglev` для дочірніх процесів Vitest у Node, + щоб зменшити churn компіляції V8 під час великих локальних запусків. Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти зі стандартною поведінкою V8. - + - - `pnpm changed:lanes` показує, які архітектурні lanes запускає diff. - - Pre-commit hook відповідає лише за форматування. Він повторно stage-ить відформатовані файли та не запускає lint, typecheck або тести. - - Явно запускайте `pnpm check:changed` перед передаванням або push, коли вам потрібен розумний локальний check gate. - - `pnpm test:changed` типово спрямовується через дешеві scoped lanes. Використовуйте `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` лише тоді, коли agent вирішує, що зміна harness, config, package або contract справді потребує ширшого покриття Vitest. - - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку routing, лише з вищим обмеженням workers. - - Локальне auto-scaling workers навмисно консервативне й зменшує навантаження, коли load average хоста вже високий, тому кілька паралельних запусків Vitest типово завдають менше шкоди. - - Базова конфігурація Vitest позначає проєкти/конфігураційні файли як `forceRerunTriggers`, щоб rerun у changed-mode залишалися коректними, коли змінюється test wiring. - - Конфігурація залишає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете одне явне розташування cache для прямого profiling. + - `pnpm changed:lanes` показує, які архітектурні смуги запускає diff. + - Pre-commit hook виконує лише форматування. Він повторно додає відформатовані файли до stage і + не запускає lint, перевірку типів або тести. + - Запускайте `pnpm check:changed` явно перед передаванням роботи або push, коли вам + потрібен розумний локальний контрольний шлюз. + - `pnpm test:changed` типово спрямовується через дешеві обмежені смуги. Використовуйте + `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` лише тоді, коли agent + вирішує, що зміна harness, конфігурації, пакунка або контракту справді потребує ширшого + покриття Vitest. + - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, + лише з вищою межею worker. + - Автомасштабування локальних worker навмисно консервативне і зменшує навантаження, + коли середнє навантаження хоста вже високе, тож кілька одночасних + запусків Vitest типово завдають меншої шкоди. + - Базова конфігурація Vitest позначає проєкти/конфігураційні файли як + `forceRerunTriggers`, щоб повторні запуски changed-mode залишалися коректними, коли змінюється + wiring тестів. + - Конфігурація тримає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних + хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете + одне явне розташування кешу для прямого профілювання. - + - - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість імпортів плюс вивід import-breakdown. - - `pnpm test:perf:imports:changed` звужує той самий profiling view до файлів, змінених відносно `origin/main`. + - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість імпортів плюс + вивід import-breakdown. + - `pnpm test:perf:imports:changed` обмежує той самий профілювальний перегляд + файлами, зміненими від `origin/main`. - Дані часу shard записуються в `.artifacts/vitest-shard-timings.json`. - Whole-config запуски використовують шлях конфігурації як ключ; include-pattern CI shards додають назву shard, щоб filtered shards можна було відстежувати окремо. - - Коли один hot test досі витрачає більшість часу на startup imports, тримайте важкі залежності за вузьким локальним seam `*.runtime.ts` і mock-айте цей seam напряму замість deep-importing runtime helpers лише для передавання їх через `vi.mock(...)`. - - `pnpm test:perf:changed:bench -- --ref ` порівнює routed `test:changed` із нативним шляхом root-project для цього committed diff і друкує wall time плюс macOS max RSS. - - `pnpm test:perf:changed:bench -- --worktree` вимірює поточне dirty tree, спрямовуючи список змінених файлів через `scripts/test-projects.mjs` і кореневу конфігурацію Vitest. - - `pnpm test:perf:profile:main` записує CPU profile головного потоку для startup Vitest/Vite і transform overhead. - - `pnpm test:perf:profile:runner` записує CPU+heap profiles runner для unit suite з вимкненим file parallelism. + Запуски всієї конфігурації використовують шлях конфігурації як ключ; include-pattern CI + shards додають назву shard, щоб відфільтровані shards можна було відстежувати + окремо. + - Коли один гарячий тест усе ще витрачає більшість часу на стартові імпорти, + тримайте важкі залежності за вузьким локальним seam `*.runtime.ts` і + mock-айте цей seam напряму замість deep-import runtime helpers лише + щоб передати їх через `vi.mock(...)`. + - `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований + `test:changed` із нативним шляхом кореневого проєкту для цього закоміченого + diff і виводить wall time плюс максимальне RSS на macOS. + - `pnpm test:perf:changed:bench -- --worktree` бенчмаркить поточне + брудне дерево, маршрутизуючи список змінених файлів через + `scripts/test-projects.mjs` і кореневу конфігурацію Vitest. + - `pnpm test:perf:profile:main` записує CPU-профіль головного потоку для + витрат запуску й transform у Vitest/Vite. + - `pnpm test:perf:profile:runner` записує CPU+heap профілі runner для + unit-набору з вимкненим файловим паралелізмом. @@ -477,142 +506,140 @@ utilities. - Команда: `pnpm test:stability:gateway` - Конфігурація: `vitest.gateway.config.ts`, примусово один worker -- Область: - - Типово запускає реальний loopback Gateway з увімкненою diagnostics - - Проганяє синтетичний churn gateway message, memory і large-payload через шлях diagnostic event +- Обсяг: + - Запускає реальний loopback Gateway із типово ввімкненою діагностикою + - Проганяє синтетичний gateway message, memory і large-payload churn через шлях діагностичних подій - Запитує `diagnostics.stability` через Gateway WS RPC - - Покриває helpers збереження diagnostic stability bundle - - Перевіряє, що recorder залишається обмеженим, синтетичні RSS samples залишаються нижче pressure budget, а per-session queue depths повертаються до нуля + - Покриває helper-и збереження diagnostic stability bundle + - Перевіряє, що recorder лишається обмеженим, синтетичні RSS-зразки залишаються в межах бюджету тиску, а глибини черг на сесію повертаються до нуля - Очікування: - - Безпечно для CI й без ключів - - Вузький lane для подальшої роботи над stability-regression, не заміна повного набору Gateway + - Безпечно для CI і без ключів + - Вузька смуга для подальшої роботи над регресіями стабільності, не заміна повного набору Gateway ### E2E (gateway smoke) - Команда: `pnpm test:e2e` - Конфігурація: `vitest.e2e.config.ts` -- Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і bundled-plugin E2E тести в `extensions/` -- Runtime defaults: - - Використовує Vitest `threads` з `isolate: false`, як і решта repo. - - Використовує adaptive workers (CI: до 2, локально: типово 1). - - Типово працює в silent mode, щоб зменшити overhead консольного I/O. +- Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і E2E-тести bundled-plugin у `extensions/` +- Типові runtime-параметри: + - Використовує `threads` Vitest з `isolate: false`, як і решта репозиторію. + - Використовує адаптивних worker (CI: до 2, локально: типово 1). + - Типово працює в тихому режимі, щоб зменшити витрати console I/O. - Корисні overrides: - - `OPENCLAW_E2E_WORKERS=` для примусового worker count (обмежено 16). - - `OPENCLAW_E2E_VERBOSE=1` для повторного ввімкнення verbose console output. -- Область: - - End-to-end поведінка multi-instance gateway - - WebSocket/HTTP surfaces, node pairing і важчий networking + - `OPENCLAW_E2E_WORKERS=` для примусового задання кількості worker (обмежено 16). + - `OPENCLAW_E2E_VERBOSE=1` для повторного ввімкнення докладного виводу консолі. +- Обсяг: + - Наскрізна поведінка Gateway з кількома інстансами + - Поверхні WebSocket/HTTP, pairing node і важчі мережеві частини - Очікування: - Запускається в CI (коли ввімкнено в pipeline) - Реальні ключі не потрібні - - Більше рухомих частин, ніж у unit tests (може бути повільніше) + - Більше рухомих частин, ніж в unit-тестах (може бути повільніше) -### E2E: OpenShell backend smoke +### E2E: smoke бекенду OpenShell - Команда: `pnpm test:e2e:openshell` - Файл: `extensions/openshell/src/backend.e2e.test.ts` -- Область: +- Обсяг: - Запускає ізольований OpenShell gateway на хості через Docker - Створює sandbox із тимчасового локального Dockerfile - - Перевіряє OpenClaw OpenShell backend через реальні `sandbox ssh-config` + SSH exec - - Перевіряє remote-canonical поведінку filesystem через sandbox fs bridge + - Перевіряє бекенд OpenClaw OpenShell через реальні `sandbox ssh-config` + SSH exec + - Перевіряє remote-canonical поведінку файлової системи через sandbox fs bridge - Очікування: - - Лише opt-in; не є частиною типового запуску `pnpm test:e2e` - - Потребує локального `openshell` CLI та робочого Docker daemon + - Лише opt-in; не входить до типового запуску `pnpm test:e2e` + - Потребує локального CLI `openshell` і робочого Docker daemon - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує тестовий gateway і sandbox - Корисні overrides: - - `OPENCLAW_E2E_OPENSHELL=1` для ввімкнення тесту під час ручного запуску ширшого e2e suite + - `OPENCLAW_E2E_OPENSHELL=1` для ввімкнення тесту під час ручного запуску ширшого e2e-набору - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` для вказання нестандартного CLI binary або wrapper script -### Live (реальні providers + реальні models) +### Live (реальні провайдери + реальні моделі) - Команда: `pnpm test:live` - Конфігурація: `vitest.live.config.ts` -- Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і live tests bundled-plugin у `extensions/` +- Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і live-тести bundled-plugin у `extensions/` - Типово: **увімкнено** через `pnpm test:live` (установлює `OPENCLAW_LIVE_TEST=1`) -- Область: - - “Чи цей provider/model справді працює _сьогодні_ з реальними creds?” - - Виявляє зміни format provider-ів, quirks tool-calling, проблеми auth і поведінку rate limit +- Обсяг: + - “Чи цей provider/model справді працює _сьогодні_ з реальними credentials?” + - Виявляє зміни форматів provider, особливості tool-calling, проблеми auth і поведінку rate limit - Очікування: - - Навмисно не CI-stable (реальні мережі, реальні policies providers, quotas, outages) + - За задумом не є стабільним для CI (реальні мережі, реальні політики provider, квоти, збої) - Коштує грошей / використовує rate limits - - Віддавайте перевагу запуску звужених subsets замість “усього” + - Надавайте перевагу запуску звужених підмножин замість “усього” - Live-запуски source-ять `~/.profile`, щоб підхопити відсутні API keys. -- Типово live-запуски все ще ізолюють `HOME` і копіюють config/auth material у тимчасовий test home, щоб unit fixtures не могли змінити ваш реальний `~/.openclaw`. -- Установлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли вам навмисно потрібно, щоб live tests використовували ваш реальний home directory. -- `pnpm test:live` тепер типово працює в тихішому режимі: зберігає progress output `[live] ...`, але приглушує додаткове повідомлення `~/.profile` і вимикає gateway bootstrap logs/Bonjour chatter. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні startup logs. -- Ротація API key (provider-specific): задайте `*_API_KEYS` у форматі з комами/крапками з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) чи per-live override через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу при rate limit responses. -- Progress/heartbeat output: - - Live suites тепер виводять progress lines у stderr, щоб довгі provider calls були помітно активними навіть коли Vitest console capture тихий. - - `vitest.live.config.ts` вимикає Vitest console interception, щоб provider/gateway progress lines одразу транслювалися під час live runs. - - Налаштуйте direct-model heartbeats через `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Налаштуйте gateway/probe heartbeats через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. +- Типово live-запуски все ще ізолюють `HOME` і копіюють config/auth material у тимчасовий тестовий home, щоб unit fixtures не могли змінити ваш реальний `~/.openclaw`. +- Установлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли навмисно потрібно, щоб live-тести використовували ваш реальний home directory. +- `pnpm test:live` тепер типово працює тихіше: він зберігає progress output `[live] ...`, але приглушує додаткове повідомлення `~/.profile` і вимикає gateway bootstrap logs/Bonjour chatter. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні startup logs. +- Ротація API key (залежно від provider): установіть `*_API_KEYS` у форматі з комами/крапками з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або override для окремого live через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу на відповідях rate limit. +- Вивід progress/heartbeat: + - Live-набори тепер виводять progress lines у stderr, щоб довгі виклики provider були видимо активними навіть коли Vitest console capture тихий. + - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, щоб progress lines provider/gateway передавалися одразу під час live-запусків. + - Налаштовуйте heartbeat direct-model через `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Налаштовуйте heartbeat gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. -## Який suite запускати? +## Який набір запускати? Використовуйте цю таблицю рішень: - Редагування логіки/тестів: запустіть `pnpm test` (і `pnpm test:coverage`, якщо ви змінили багато) -- Зміни в мережевій частині Gateway / протоколі WS / спарюванні: додайте `pnpm test:e2e` +- Зміни в мережевій частині gateway / протоколі WS / pairing: додайте `pnpm test:e2e` - Налагодження “мій бот не працює” / збоїв, специфічних для провайдера / виклику інструментів: запустіть звужений `pnpm test:live` -## Live-тести (що торкаються мережі) +## Живі (мережеві) тести -Для live-матриці моделей, smoke-тестів бекенду CLI, smoke-тестів ACP, стенда -app-server Codex і всіх live-тестів медіапровайдерів (Deepgram, BytePlus, ComfyUI, зображення, -музика, відео, медіастенд) — а також обробки облікових даних для live-запусків — див. -[Тестування live-наборів](/uk/help/testing-live). Для спеціального контрольного списку оновлень і -валідації плагінів див. -[Тестування оновлень і плагінів](/uk/help/testing-updates-plugins). +Про живу матрицю моделей, smoke-перевірки бекенда CLI, smoke-перевірки ACP, harness сервера застосунку Codex і всі живі тести медіапровайдерів (Deepgram, BytePlus, ComfyUI, зображення, музика, відео, медіа-harness) — а також обробку облікових даних для живих запусків — див. +[Тестування живих наборів](/uk/help/testing-live). Про спеціальний контрольний список перевірки оновлень і +Plugin див. +[Тестування оновлень і plugins](/uk/help/testing-updates-plugins). -## Docker-ранери (необов’язкові перевірки "працює в Linux") +## Docker runner-и (необов’язкові перевірки "працює в Linux") -Ці Docker-ранери поділяються на дві групи: +Ці Docker runner-и поділяються на дві групи: -- Ранери live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл profile-key всередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог конфігурації та робочу область (і виконують `~/.profile`, якщо він змонтований). Відповідні локальні точки входу: `test:live:models-profiles` і `test:live:gateway-profiles`. -- Docker live-ранери за замовчуванням мають менше обмеження для smoke-тестів, щоб повний Docker-прогін залишався практичним: - `test:docker:live-models` за замовчуванням використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а - `test:docker:live-gateway` за замовчуванням використовує `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, +- Runner-и живих моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний живий файл profile-key всередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог конфігурації та робочу область (і підвантажують `~/.profile`, якщо його змонтовано). Відповідні локальні точки входу: `test:live:models-profiles` і `test:live:gateway-profiles`. +- Живі Docker runner-и типово використовують менше обмеження для smoke-перевірок, щоб повний Docker-прогін залишався практичним: + `test:docker:live-models` типово має `OPENCLAW_LIVE_MAX_MODELS=12`, а + `test:docker:live-gateway` типово має `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` і - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці змінні середовища, коли - явно потрібне ширше вичерпне сканування. -- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, один раз пакує OpenClaw як npm-тарбол через `scripts/package-openclaw-for-docker.mjs`, а потім збирає/повторно використовує два образи `scripts/e2e/Dockerfile`. Базовий образ — це лише Node/Git-ранер для напрямів install/update/plugin-dependency; ці напрями монтують попередньо зібраний тарбол. Функціональний образ встановлює той самий тарбол у `/app` для напрямів функціональності зібраного застосунку. Визначення Docker-напрямів містяться в `scripts/lib/docker-e2e-scenarios.mjs`; логіка планувальника міститься в `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` виконує вибраний план. Агрегований запуск використовує зважений локальний планувальник: `OPENCLAW_DOCKER_ALL_PARALLELISM` керує слотами процесів, а обмеження ресурсів не дають важким live-, npm-install- і multi-service-напрямам запускатися одночасно. Якщо один напрям важчий за активні обмеження, планувальник усе одно може запустити його, коли пул порожній, і потім тримає його єдиним запущеним, доки знову не з’явиться місткість. Типові значення: 10 слотів, `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; налаштовуйте `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` або `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` лише тоді, коли Docker-хост має більший запас ресурсів. Ранер за замовчуванням виконує Docker preflight, видаляє застарілі OpenClaw E2E-контейнери, друкує статус кожні 30 секунд, зберігає тривалості успішних напрямів у `.artifacts/docker-tests/lane-timings.json` і використовує ці тривалості, щоб у наступних запусках першими стартували довші напрями. Використовуйте `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, щоб надрукувати зважений маніфест напрямів без збирання або запуску Docker, або `node scripts/test-docker-all.mjs --plan-json`, щоб надрукувати CI-план для вибраних напрямів, потреб у пакеті/образі та облікових даних. -- `Package Acceptance` — це нативний для GitHub пакетний gate для перевірки "чи працює цей установний тарбол як продукт?" Він визначає один пакет-кандидат із `source=npm`, `source=ref`, `source=url` або `source=artifact`, завантажує його як `package-under-test`, а потім запускає повторно використовувані Docker E2E-напрями саме проти цього тарбола замість повторного пакування вибраного ref. Профілі впорядковані за широтою: `smoke`, `package`, `product` і `full`. Див. [Тестування оновлень і плагінів](/uk/help/testing-updates-plugins) щодо контракту пакета/оновлення/плагіна, матриці виживання опублікованих оновлень, типових значень релізу та тріажу збоїв. -- Перевірки збірки й релізу запускають `scripts/check-cli-bootstrap-imports.mjs` після tsdown. Захист проходить статичним зібраним графом від `dist/entry.js` і `dist/cli/run-main.js` і завершується помилкою, якщо запуск до диспетчеризації команд імпортує залежності пакета, як-от Commander, prompt UI, undici або logging, до диспетчеризації команд; він також утримує зібраний chunk запуску Gateway в межах бюджету та відхиляє статичні імпорти відомих холодних шляхів Gateway. Smoke-тест упакованого CLI також охоплює кореневу довідку, довідку onboarding, довідку doctor, status, config schema і команду списку моделей. -- Зворотна сумісність Package Acceptance обмежена `2026.4.25` (включно з `2026.4.25-beta.*`). До цієї межі стенд допускає лише прогалини метаданих уже випущених пакетів: пропущені приватні записи QA-інвентарю, відсутній `gateway install --wrapper`, відсутні файли patch у git-фікстурі, отриманій із тарбола, відсутній збережений `update.channel`, застарілі розташування install-record плагінів, відсутнє збереження marketplace install-record і міграцію метаданих конфігурації під час `plugins update`. Для пакетів після `2026.4.25` ці шляхи є строгими збоями. -- Контейнерні smoke-ранери: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:update-channel-switch`, `test:docker:upgrade-survivor`, `test:docker:published-upgrade-survivor`, `test:docker:session-runtime-context`, `test:docker:agents-delete-shared-workspace`, `test:docker:gateway-network`, `test:docker:browser-cdp-snapshot`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update` і `test:docker:config-reload` запускають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env vars, коли ви + явно хочете більший вичерпний скан. +- `test:docker:all` один раз збирає живий Docker-образ через `test:docker:live-build`, один раз пакує OpenClaw як npm tarball через `scripts/package-openclaw-for-docker.mjs`, а потім збирає/повторно використовує два образи `scripts/e2e/Dockerfile`. Bare-образ — це лише Node/Git runner для напрямів install/update/plugin-dependency; ці напрями монтують попередньо зібраний tarball. Functional-образ встановлює той самий tarball у `/app` для напрямів функціональності зібраного застосунку. Визначення Docker-напрямів містяться в `scripts/lib/docker-e2e-scenarios.mjs`; логіка планувальника міститься в `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` виконує вибраний план. Агрегатор використовує зважений локальний планувальник: `OPENCLAW_DOCKER_ALL_PARALLELISM` керує слотами процесів, а обмеження ресурсів не дають важким живим, npm-install і multi-service напрямам стартувати одночасно. Якщо окремий напрям важчий за активні обмеження, планувальник усе одно може запустити його, коли пул порожній, а потім тримає його запущеним наодинці, доки місткість знову не стане доступною. Типові значення: 10 слотів, `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; налаштовуйте `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` або `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` лише тоді, коли Docker-хост має більше запасу ресурсів. Runner типово виконує Docker preflight, видаляє застарілі OpenClaw E2E контейнери, друкує статус кожні 30 секунд, зберігає таймінги успішних напрямів у `.artifacts/docker-tests/lane-timings.json` і використовує ці таймінги, щоб у наступних запусках спершу стартувати довші напрями. Використовуйте `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, щоб надрукувати зважений маніфест напрямів без збирання чи запуску Docker, або `node scripts/test-docker-all.mjs --plan-json`, щоб надрукувати CI-план для вибраних напрямів, потреб package/image та облікових даних. +- `Package Acceptance` — це GitHub-native package-gate для питання "чи працює цей installable tarball як продукт?" Він визначає один кандидатний package із `source=npm`, `source=ref`, `source=url` або `source=artifact`, завантажує його як `package-under-test`, а потім запускає багаторазові Docker E2E напрями проти саме цього tarball замість повторного пакування вибраного ref. Профілі впорядковано за широтою: `smoke`, `package`, `product` і `full`. Див. [Тестування оновлень і plugins](/uk/help/testing-updates-plugins) про контракт package/update/plugin, матрицю published-upgrade survivor, типові параметри релізу й triage збоїв. +- Перевірки збірки та релізу запускають `scripts/check-cli-bootstrap-imports.mjs` після tsdown. Guard проходить статичний зібраний граф від `dist/entry.js` і `dist/cli/run-main.js` та завершується помилкою, якщо startup до dispatch імпортує залежності package, як-от Commander, prompt UI, undici або logging до dispatch команди; він також утримує bundled Gateway run chunk у межах бюджету й відхиляє статичні імпорти відомих холодних Gateway шляхів. Packaged CLI smoke також покриває root help, onboard help, doctor help, status, config schema і команду model-list. +- Зворотна сумісність Package Acceptance обмежена `2026.4.25` (включно з `2026.4.25-beta.*`). До цієї межі harness допускає лише прогалини метаданих shipped-package: пропущені приватні QA inventory entries, відсутній `gateway install --wrapper`, відсутні patch-файли у tarball-derived git fixture, відсутній збережений `update.channel`, legacy розташування plugin install-record, відсутнє збереження marketplace install-record і міграцію метаданих конфігурації під час `plugins update`. Для package після `2026.4.25` ці шляхи є строгими помилками. +- Runner-и container smoke: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:update-channel-switch`, `test:docker:upgrade-survivor`, `test:docker:published-upgrade-survivor`, `test:docker:session-runtime-context`, `test:docker:agents-delete-shared-workspace`, `test:docker:gateway-network`, `test:docker:browser-cdp-snapshot`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update` і `test:docker:config-reload` завантажують один або кілька реальних контейнерів і перевіряють високорівневі інтеграційні шляхи. -Docker-ранери live-моделей також bind-mount лише потрібні домашні каталоги автентифікації CLI (або всі підтримувані, коли запуск не звужений), а потім копіюють їх у домашній каталог контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени без зміни сховища автентифікації хоста: +Docker runner-и живих моделей також bind-mount-ять лише потрібні домівки автентифікації CLI (або всі підтримувані, коли запуск не звужено), а потім копіюють їх у домівку контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени без зміни auth-сховища хоста: - Прямі моделі: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) -- Smoke-тест прив’язки ACP: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`; за замовчуванням охоплює Claude, Codex і Gemini, із суворим покриттям Droid/OpenCode через `pnpm test:docker:live-acp-bind:droid` і `pnpm test:docker:live-acp-bind:opencode`) -- Smoke-тест бекенду CLI: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) -- Smoke-тест тестового каркаса сервера застосунку Codex: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) -- Gateway + агент розробки: `pnpm test:docker:live-gateway` (скрипт: `scripts/test-live-gateway-models-docker.sh`) -- Smoke-тест спостережуваності: `pnpm qa:otel:smoke` є приватною лінією QA для перевірки вихідного checkout. Він навмисно не входить до ліній Docker-релізу пакета, оскільки npm-тарбол не містить QA Lab. -- Live smoke-тест Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) -- Майстер онбордингу (TTY, повне створення каркаса): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) -- Smoke-тест онбордингу/каналу/агента для npm-тарбола: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює запакований тарбол OpenClaw у Docker, налаштовує OpenAI через env-ref онбординг і Telegram за замовчуванням, запускає doctor і виконує один змокований хід агента OpenAI. Повторно використайте попередньо зібраний тарбол із `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть перебудову на хості з `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` або змініть канал за допомогою `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. -- Smoke-тест перемикання каналу оновлень: `pnpm test:docker:update-channel-switch` глобально встановлює запакований тарбол OpenClaw у Docker, перемикає з пакета `stable` на git `dev`, перевіряє збережений канал і роботу Plugin після оновлення, потім перемикає назад на пакет `stable` і перевіряє статус оновлення. -- Smoke-тест виживання після оновлення: `pnpm test:docker:upgrade-survivor` встановлює запакований тарбол OpenClaw поверх брудної фікстури старого користувача з агентами, конфігурацією каналу, allowlist Plugin, застарілим станом залежностей Plugin і наявними файлами workspace/session. Він запускає оновлення пакета та неінтерактивний doctor без живих ключів провайдера чи каналу, потім запускає loopback Gateway і перевіряє збереження конфігурації/стану, а також бюджети запуску/статусу. -- Smoke-тест виживання після оновлення опублікованої версії: `pnpm test:docker:published-upgrade-survivor` за замовчуванням встановлює `openclaw@latest`, засіває реалістичні файли наявного користувача, налаштовує цей базовий стан за допомогою вбудованого рецепта команд, перевіряє отриману конфігурацію, оновлює це опубліковане встановлення до тарбола-кандидата, запускає неінтерактивний doctor, записує `.artifacts/upgrade-survivor/summary.json`, потім запускає loopback Gateway і перевіряє налаштовані intents, збереження стану, запуск, `/healthz`, `/readyz` і бюджети статусу RPC. Перевизначте один базовий стан через `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, попросіть агрегований планувальник розгорнути точні базові стани через `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` і розгорніть фікстури у формі issue через `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS`, наприклад `reported-issues`; Package Acceptance відкриває їх як `published_upgrade_survivor_baseline`, `published_upgrade_survivor_baselines` і `published_upgrade_survivor_scenarios`. -- Smoke-тест runtime-контексту сесії: `pnpm test:docker:session-runtime-context` перевіряє збереження прихованого runtime-контексту в transcript, а також repair через doctor для зачеплених дубльованих гілок prompt-rewrite. -- Smoke-тест глобального встановлення Bun: `bash scripts/e2e/bun-global-install-smoke.sh` пакує поточне дерево, встановлює його через `bun install -g` в ізольованому home і перевіряє, що `openclaw infer image providers --json` повертає bundled image providers замість зависання. Повторно використайте попередньо зібраний тарбол із `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть збірку на хості через `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` або скопіюйте `dist/` із зібраного Docker-образу через `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. -- Docker smoke-тест інсталятора: `bash scripts/test-install-sh-docker.sh` спільно використовує один npm-кеш для своїх root, update і direct-npm контейнерів. Smoke-тест оновлення за замовчуванням використовує npm `latest` як стабільний базовий стан перед оновленням до тарбола-кандидата. Перевизначте локально через `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22` або через input `update_baseline_version` workflow Install Smoke на GitHub. Перевірки інсталятора без root використовують ізольований npm-кеш, щоб записи кешу, власником яких є root, не маскували поведінку встановлення у користувацькому просторі. Установіть `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати кеш root/update/direct-npm під час локальних повторних запусків. -- Install Smoke CI пропускає дубльоване глобальне оновлення direct-npm через `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; запускайте скрипт локально без цієї змінної середовища, коли потрібне покриття прямого `npm install -g`. -- Smoke-тест CLI видалення спільного workspace агентами: `pnpm test:docker:agents-delete-shared-workspace` (скрипт: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) за замовчуванням збирає образ із кореневого Dockerfile, засіває двох агентів з одним workspace в ізольованому home контейнера, запускає `agents delete --json` і перевіряє валідний JSON та поведінку зі збереженим workspace. Повторно використайте install-smoke образ із `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1`. +- Smoke-перевірка прив’язки ACP: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`; типово охоплює Claude, Codex і Gemini, зі строгим покриттям Droid/OpenCode через `pnpm test:docker:live-acp-bind:droid` і `pnpm test:docker:live-acp-bind:opencode`) +- Smoke-перевірка бекенда CLI: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) +- Smoke-перевірка harness app-server Codex: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) +- Gateway + dev-агент: `pnpm test:docker:live-gateway` (скрипт: `scripts/test-live-gateway-models-docker.sh`) +- Smoke-перевірка спостережуваності: `pnpm qa:otel:smoke` — це приватна QA-ланка для checkout вихідного коду. Вона навмисно не входить до ланок Docker-релізу пакета, бо npm tarball не містить QA Lab. +- Live smoke Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) +- Майстер onboarding (TTY, повний scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) +- Smoke-перевірка onboarding/channel/agent для npm tarball: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює запакований tarball OpenClaw у Docker, налаштовує OpenAI через onboarding з env-ref і типово Telegram, запускає doctor і виконує один мокований хід агента OpenAI. Повторно використайте попередньо зібраний tarball через `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть перебудову на хості через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` або перемкніть канал через `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. +- Smoke-перевірка перемикання каналу оновлень: `pnpm test:docker:update-channel-switch` глобально встановлює запакований tarball OpenClaw у Docker, перемикається з пакетного `stable` на git `dev`, перевіряє збережений канал і роботу Plugin після оновлення, потім перемикається назад на пакетний `stable` і перевіряє статус оновлення. +- Smoke-перевірка збереження після upgrade: `pnpm test:docker:upgrade-survivor` встановлює запакований tarball OpenClaw поверх забрудненої фікстури старого користувача з агентами, конфігурацією каналів, allowlist-ами Plugin, застарілим станом залежностей Plugin і наявними файлами workspace/session. Вона запускає оновлення пакета та неінтерактивний doctor без live-ключів provider або channel, потім запускає loopback Gateway і перевіряє збереження config/state, а також бюджети startup/status. +- Smoke-перевірка збереження після опублікованого upgrade: `pnpm test:docker:published-upgrade-survivor` типово встановлює `openclaw@latest`, засіває реалістичні файли наявного користувача, налаштовує цей baseline вбудованим рецептом команд, перевіряє отриману конфігурацію, оновлює це опубліковане встановлення до candidate tarball, запускає неінтерактивний doctor, записує `.artifacts/upgrade-survivor/summary.json`, потім запускає loopback Gateway і перевіряє налаштовані intents, збереження стану, запуск, `/healthz`, `/readyz` і бюджети RPC-статусу. Перевизначте один baseline через `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, попросіть aggregate scheduler розгорнути точні baselines через `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` і розгорніть фікстури у формі issue через `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS`, наприклад `reported-issues`; Package Acceptance надає це як `published_upgrade_survivor_baseline`, `published_upgrade_survivor_baselines` і `published_upgrade_survivor_scenarios`. +- Smoke-перевірка runtime context сесії: `pnpm test:docker:session-runtime-context` перевіряє збереження прихованого transcript runtime context і repair через doctor для уражених дубльованих гілок prompt-rewrite. +- Smoke-перевірка глобального встановлення Bun: `bash scripts/e2e/bun-global-install-smoke.sh` пакує поточне дерево, встановлює його через `bun install -g` в ізольованому home і перевіряє, що `openclaw infer image providers --json` повертає bundled image providers, а не зависає. Повторно використайте попередньо зібраний tarball через `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть build на хості через `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` або скопіюйте `dist/` із зібраного Docker-образу через `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. +- Smoke-перевірка Docker installer: `bash scripts/test-install-sh-docker.sh` спільно використовує один npm cache для своїх root-, update- і direct-npm-контейнерів. Smoke-перевірка update типово використовує npm `latest` як stable baseline перед upgrade до candidate tarball. Перевизначте через `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22` локально або через input `update_baseline_version` workflow Install Smoke на GitHub. Перевірки installer без root зберігають ізольований npm cache, щоб root-owned cache entries не маскували user-local install behavior. Установіть `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати root/update/direct-npm cache між локальними повторними запусками. +- Install Smoke CI пропускає дубльоване direct-npm global update через `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; запускайте скрипт локально без цього env, коли потрібне покриття прямого `npm install -g`. +- Smoke-перевірка CLI для видалення агентами спільного workspace: `pnpm test:docker:agents-delete-shared-workspace` (скрипт: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) типово збирає образ root Dockerfile, засіває двох агентів з одним workspace в ізольованому container home, запускає `agents delete --json` і перевіряє валідний JSON та поведінку збереженого workspace. Повторно використайте install-smoke image через `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1`. - Мережа Gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) -- Smoke-тест snapshot браузерного CDP: `pnpm test:docker:browser-cdp-snapshot` (скрипт: `scripts/e2e/browser-cdp-snapshot-docker.sh`) збирає source E2E образ плюс шар Chromium, запускає Chromium із сирим CDP, виконує `browser doctor --deep` і перевіряє, що snapshots ролей CDP охоплюють URL посилань, clickables, підвищені курсором, refs iframe і метадані frame. -- Регресія мінімального reasoning для OpenAI Responses web_search: `pnpm test:docker:openai-web-search-minimal` (скрипт: `scripts/e2e/openai-web-search-minimal-docker.sh`) запускає змокований сервер OpenAI через Gateway, перевіряє, що `web_search` підвищує `reasoning.effort` з `minimal` до `low`, потім примусово викликає відхилення schema провайдера й перевіряє, що сирі деталі з’являються в логах Gateway. -- Міст MCP каналів (засіяний Gateway + stdio-міст + сирий smoke-тест notification-frame Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) -- MCP tools бандла Pi (реальний stdio MCP server + smoke-тест allow/deny вбудованого профілю Pi): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) -- Очищення MCP для Cron/subagent (реальний Gateway + демонтаж дочірнього stdio MCP після ізольованого cron і одноразових запусків subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) -- Plugins (install smoke, встановлення/видалення ClawHub kitchen-sink, оновлення marketplace і ввімкнення/inspect Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) - Установіть `OPENCLAW_PLUGINS_E2E_CLAWHUB=0`, щоб пропустити блок ClawHub, або перевизначте стандартну пару package/runtime для kitchen-sink через `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` і `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID`. Без `OPENCLAW_CLAWHUB_URL`/`CLAWHUB_URL` тест використовує герметичний локальний сервер фікстури ClawHub. -- Smoke-тест незміненого оновлення Plugin: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`) -- Smoke-тест метаданих перезавантаження конфігурації: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) -- Plugins: `pnpm test:docker:plugins` охоплює install smoke, встановлення з локальної фікстури ClawHub, оновлення marketplace, встановлення залежностей npm-пакетів і ввімкнення/inspect Claude-bundle. `pnpm test:docker:plugin-update` охоплює поведінку незміненого оновлення для встановлених plugins. +- Smoke-перевірка Browser CDP snapshot: `pnpm test:docker:browser-cdp-snapshot` (скрипт: `scripts/e2e/browser-cdp-snapshot-docker.sh`) збирає source E2E image плюс шар Chromium, запускає Chromium із raw CDP, виконує `browser doctor --deep` і перевіряє, що CDP role snapshots охоплюють URL посилань, clickables, promoted курсором, iframe refs і frame metadata. +- Регресія мінімального reasoning для OpenAI Responses web_search: `pnpm test:docker:openai-web-search-minimal` (скрипт: `scripts/e2e/openai-web-search-minimal-docker.sh`) проганяє мокований сервер OpenAI через Gateway, перевіряє, що `web_search` підвищує `reasoning.effort` з `minimal` до `low`, потім примусово викликає відхилення provider schema і перевіряє, що raw detail з’являється в логах Gateway. +- MCP-міст каналів (засіяний Gateway + stdio bridge + raw Claude notification-frame smoke): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- MCP tools Pi bundle (реальний stdio MCP server + smoke-перевірка allow/deny вбудованого профілю Pi): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) +- Очищення MCP для Cron/subagent (реальний Gateway + teardown дочірнього stdio MCP після ізольованих cron і one-shot subagent запусків): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) +- Plugins (smoke-перевірка install/update для локального шляху, `file:`, npm registry з hoisted dependencies, git moving refs, ClawHub kitchen-sink, marketplace updates і enable/inspect Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) + Установіть `OPENCLAW_PLUGINS_E2E_CLAWHUB=0`, щоб пропустити блок ClawHub, або перевизначте типову пару kitchen-sink package/runtime через `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` і `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID`. Без `OPENCLAW_CLAWHUB_URL`/`CLAWHUB_URL` тест використовує hermetic локальний fixture server ClawHub. +- Smoke-перевірка незміненого оновлення Plugin: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`) +- Smoke-перевірка metadata reload config: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) +- Plugins: `pnpm test:docker:plugins` охоплює smoke-перевірку install/update для локального шляху, `file:`, npm registry з hoisted dependencies, git moving refs, фікстур ClawHub, marketplace updates і enable/inspect Claude-bundle. `pnpm test:docker:plugin-update` охоплює поведінку unchanged update для встановлених plugins. Щоб вручну попередньо зібрати та повторно використати спільний функціональний образ: @@ -621,111 +648,111 @@ OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local pnpm test:docker: OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels ``` -Специфічні для suite перевизначення образів, як-от `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, усе одно мають пріоритет, якщо задані. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на віддалений спільний образ, скрипти завантажують його, якщо він ще не є локальним. QR і Docker-тести інсталятора зберігають власні Dockerfile, оскільки вони перевіряють поведінку package/install, а не спільний runtime зібраного застосунку. +Suite-specific перевизначення образів, як-от `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, усе одно мають пріоритет, якщо задані. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` указує на віддалений спільний образ, скрипти підтягують його, якщо він ще не локальний. QR- і installer Docker tests зберігають власні Dockerfiles, бо вони перевіряють поведінку package/install, а не спільний runtime зібраної app. -Docker runner-и live-model також монтують поточний checkout лише для читання та -розміщують його в тимчасовому workdir усередині контейнера. Це зберігає runtime -образ компактним, водночас запускаючи Vitest проти вашого точного локального source/config. -Крок staging пропускає великі локальні кеші та вихідні дані збірки застосунків, як-от -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, а також локальні для застосунку `.build` або -каталоги вихідних даних Gradle, щоб Docker live runs не витрачали хвилини на копіювання -машинно-специфічних артефактів. -Вони також установлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live probes Gateway не запускали -реальні workers каналів Telegram/Discord/etc. усередині контейнера. +Docker runners для live-model також bind-mount-ять поточний checkout read-only і +переносять його в тимчасовий workdir усередині контейнера. Це зберігає runtime +image компактним, але все одно запускає Vitest проти вашого точного локального source/config. +Етап staging пропускає великі локальні-only caches і outputs build застосунків, як-от +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, а також локальні для app `.build` або +директорії output Gradle, щоб live-запуски Docker не витрачали хвилини на копіювання +machine-specific artifacts. +Вони також задають `OPENCLAW_SKIP_CHANNELS=1`, щоб gateway live probes не запускали +реальні Telegram/Discord/тощо channel workers усередині контейнера. `test:docker:live-models` усе ще запускає `pnpm test:live`, тож також передавайте -`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити live-покриття Gateway -із цієї Docker lane. -`test:docker:openwebui` — це smoke-тест сумісності вищого рівня: він запускає -контейнер Gateway OpenClaw з увімкненими OpenAI-сумісними HTTP endpoints, -запускає pinned контейнер Open WebUI проти цього Gateway, виконує вхід через -Open WebUI, перевіряє, що `/api/models` відкриває `openclaw/default`, а потім надсилає +`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити gateway +live coverage з цієї Docker-ланки. +`test:docker:openwebui` — це вищорівнева smoke-перевірка сумісності: вона запускає +контейнер OpenClaw gateway з увімкненими OpenAI-сумісними HTTP endpoints, +запускає pinned контейнер Open WebUI проти цього gateway, входить через +Open WebUI, перевіряє, що `/api/models` надає `openclaw/default`, а потім надсилає реальний chat request через proxy `/api/chat/completions` Open WebUI. -Перший запуск може бути помітно повільнішим, оскільки Docker може потребувати завантаження -образу Open WebUI, а Open WebUI може потребувати завершення власного cold-start налаштування. -Ця lane очікує придатний live model key, а `OPENCLAW_PROFILE_FILE` -(`~/.profile` за замовчуванням) є основним способом надати його в Dockerized runs. +Перший запуск може бути помітно повільнішим, бо Docker може мати потребу підтягнути +образ Open WebUI, а Open WebUI може мати потребу завершити власний cold-start setup. +Ця ланка очікує придатний live model key, а `OPENCLAW_PROFILE_FILE` +(типово `~/.profile`) є основним способом надати його в Dockerized runs. Успішні запуски друкують невеликий JSON payload на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. `test:docker:mcp-channels` навмисно детермінований і не потребує -реального облікового запису Telegram, Discord або iMessage. Він завантажує засіяний контейнер Gateway, -запускає другий контейнер, який породжує `openclaw mcp serve`, потім -перевіряє виявлення маршрутизованих розмов, читання transcript, метадані вкладень, -поведінку live event queue, маршрутизацію вихідного надсилання та Claude-style channel + +реального облікового запису Telegram, Discord або iMessage. Він запускає засіяний Gateway +container, запускає другий контейнер, який породжує `openclaw mcp serve`, потім +перевіряє routed conversation discovery, читання transcript, attachment metadata, +поведінку live event queue, маршрутизацію outbound send і Claude-style channel + permission notifications через реальний stdio MCP bridge. Перевірка notification -інспектує сирі stdio MCP frames напряму, щоб smoke-тест перевіряв те, що -міст фактично емітує, а не лише те, що випадково показує конкретний client SDK. -`test:docker:pi-bundle-mcp-tools` є детермінованим і не потребує live -model key. Він збирає Docker-образ репозиторію, запускає реальний stdio MCP probe server -усередині контейнера, матеріалізує цей server через вбудований MCP runtime бандла Pi, -виконує tool, а потім перевіряє, що `coding` і `messaging` зберігають -`bundle-mcp` tools, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` їх фільтрують. -`test:docker:cron-mcp-cleanup` є детермінованим і не потребує live model +безпосередньо інспектує raw stdio MCP frames, тож smoke перевіряє те, що +bridge фактично emitting, а не лише те, що випадково поверхнює конкретний client SDK. +`test:docker:pi-bundle-mcp-tools` детермінований і не потребує live +model key. Він збирає repo Docker image, запускає реальний stdio MCP probe server +усередині контейнера, materializes цей server через runtime вбудованого Pi bundle +MCP, виконує tool, а потім перевіряє, що `coding` і `messaging` зберігають +tools `bundle-mcp`, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` фільтрують їх. +`test:docker:cron-mcp-cleanup` детермінований і не потребує live model key. Він запускає засіяний Gateway із реальним stdio MCP probe server, виконує -ізольований cron turn і одноразовий дочірній turn `/subagents spawn`, а потім перевіряє, -що дочірній процес MCP завершується після кожного запуску. +ізольований cron turn і one-shot child turn `/subagents spawn`, а потім перевіряє, +що дочірній MCP process завершується після кожного запуску. -Ручний smoke-тест plain-language thread ACP (не CI): +Ручна plain-language thread smoke-перевірка ACP (не CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для регресійних/debug workflow. Він може знову знадобитися для перевірки маршрутизації ACP thread, тож не видаляйте його. +- Збережіть цей скрипт для regression/debug workflows. Він може знову знадобитися для валідації routing thread ACP, тож не видаляйте його. -Корисні змінні середовища: +Корисні env vars: -- `OPENCLAW_CONFIG_DIR=...` (типово: `~/.openclaw`) монтується в `/home/node/.openclaw` -- `OPENCLAW_WORKSPACE_DIR=...` (типово: `~/.openclaw/workspace`) монтується в `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується в `/home/node/.profile` і завантажується перед запуском тестів -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевіряти лише змінні середовища, завантажені з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові каталоги конфігурації/робочої області та без зовнішніх монтувань автентифікації CLI -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих установок CLI всередині Docker -- Зовнішні каталоги/файли автентифікації CLI під `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед запуском тестів +- `OPENCLAW_CONFIG_DIR=...` (типово: `~/.openclaw`) монтується до `/home/node/.openclaw` +- `OPENCLAW_WORKSPACE_DIR=...` (типово: `~/.openclaw/workspace`) монтується до `/home/node/.openclaw/workspace` +- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується до `/home/node/.profile` і підвантажується перед запуском тестів +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевіряти лише змінні середовища, підвантажені з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові каталоги config/workspace і без зовнішніх монтувань автентифікації CLI +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується до `/home/node/.npm-global` для кешованих встановлень CLI усередині Docker +- Зовнішні каталоги/файли автентифікації CLI під `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються до `/home/node/...` перед початком тестів - Типові каталоги: `.minimax` - Типові файли: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Звужені запуски провайдера монтують лише потрібні каталоги/файли, визначені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - Звужені запуски провайдерів монтують лише потрібні каталоги/файли, виведені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - Перевизначте вручну за допомогою `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або списку через кому на кшталт `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...`, щоб звузити запуск -- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб фільтрувати провайдерів усередині контейнера -- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використати наявний образ `openclaw:local-live` для повторних запусків, які не потребують перебудови +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб фільтрувати провайдерів у контейнері +- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використовувати наявний образ `openclaw:local-live` для повторних запусків, яким не потрібна перебудова - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб переконатися, що облікові дані надходять зі сховища профілю (а не з env) -- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку Gateway надає для smoke-тесту Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити prompt перевірки nonce, який використовується smoke-тестом Open WebUI +- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку Gateway надає для smoke Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити prompt перевірки nonce, який використовує smoke Open WebUI - `OPENWEBUI_IMAGE=...`, щоб перевизначити закріплений тег образу Open WebUI ## Перевірка документації -Запускайте перевірки документації після редагувань документації: `pnpm check:docs`. -Запускайте повну перевірку anchors Mintlify, коли також потрібні перевірки заголовків на сторінці: `pnpm docs:check-links:anchors`. +Запускайте перевірки документації після редагувань документів: `pnpm check:docs`. +Запускайте повну валідацію anchor Mintlify, коли також потрібні перевірки заголовків на сторінці: `pnpm docs:check-links:anchors`. ## Офлайн-регресія (безпечна для CI) Це регресії «реального pipeline» без реальних провайдерів: -- Виклик інструментів Gateway (mock OpenAI, реальний gateway + цикл агента): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Майстер Gateway (WS `wizard.start`/`wizard.next`, записує конфігурацію + забезпечує автентифікацію): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") +- Виклик інструментів Gateway (mock OpenAI, реальний gateway + цикл агента): `src/gateway/gateway.test.ts` (кейс: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Майстер Gateway (WS `wizard.start`/`wizard.next`, записує config + примусова автентифікація): `src/gateway/gateway.test.ts` (кейс: "runs wizard over ws and writes auth token config") ## Оцінювання надійності агента (skills) У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агента»: -- Mock-виклик інструментів через реальний gateway + цикл агента (`src/gateway/gateway.test.ts`). -- End-to-end потоки майстра, які перевіряють зв’язування сесії та ефекти конфігурації (`src/gateway/gateway.test.ts`). +- Mock виклику інструментів через реальний gateway + цикл агента (`src/gateway/gateway.test.ts`). +- End-to-end потоки майстра, які перевіряють зв’язування сесії та ефекти config (`src/gateway/gateway.test.ts`). -Чого ще бракує для Skills (див. [Skills](/uk/tools/skills)): +Чого ще бракує для skills (див. [Skills](/uk/tools/skills)): - **Ухвалення рішень:** коли skills перелічені в prompt, чи вибирає агент правильний skill (або уникає нерелевантних)? -- **Відповідність:** чи читає агент `SKILL.md` перед використанням і чи виконує потрібні кроки/аргументи? +- **Відповідність:** чи читає агент `SKILL.md` перед використанням і чи дотримується обов’язкових кроків/аргументів? - **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. -Майбутні evals насамперед мають залишатися детермінованими: +Майбутні evals мають спершу залишатися детермінованими: -- Runner сценаріїв із mock-провайдерами для перевірки викликів інструментів + порядку, читання файлів skill і зв’язування сесії. -- Невеликий набір сценаріїв, сфокусованих на skill (використати чи уникнути, gating, prompt injection). -- Необов’язкові live evals (opt-in, керовані env) лише після того, як буде створено безпечний для CI набір. +- Запускач сценаріїв із mock провайдерами для перевірки викликів інструментів + порядку, читання файлів skill і зв’язування сесії. +- Невеликий набір сценаріїв, зосереджених на skill (використати чи уникнути, gating, prompt injection). +- Необов’язкові live evals (opt-in, керовані env) лише після появи безпечного для CI набору. -## Контрактні тести (форма Plugin і каналу) +## Контрактні тести (форма plugin і каналу) -Контрактні тести перевіряють, що кожен зареєстрований Plugin і канал відповідає своєму +Контрактні тести перевіряють, що кожен зареєстрований plugin і канал відповідає своєму контракту інтерфейсу. Вони проходять по всіх виявлених plugins і запускають набір -перевірок форми та поведінки. Типова unit-лінія `pnpm test` навмисно -пропускає ці спільні seam- і smoke-файли; запускайте контрактні команди явно, +перевірок форми та поведінки. Типова unit-ланка `pnpm test` навмисно +пропускає ці спільні seam і smoke-файли; запускайте контрактні команди явно, коли змінюєте спільні поверхні каналів або провайдерів. ### Команди @@ -738,56 +765,56 @@ key. Він запускає засіяний Gateway із реальним stdi Розташовані в `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - базова форма Plugin (id, назва, можливості) -- **setup** - контракт майстра налаштування -- **session-binding** - поведінка зв’язування сесії -- **outbound-payload** - структура payload повідомлення -- **inbound** - обробка вхідних повідомлень -- **actions** - обробники дій каналу -- **threading** - обробка ID thread -- **directory** - API каталогу/roster -- **group-policy** - застосування політики груп +- **plugin** - Базова форма plugin (id, назва, можливості) +- **setup** - Контракт майстра налаштування +- **session-binding** - Поведінка зв’язування сесії +- **outbound-payload** - Структура payload повідомлення +- **inbound** - Обробка вхідних повідомлень +- **actions** - Обробники дій каналу +- **threading** - Обробка ID гілки +- **directory** - API каталогу/реєстру +- **group-policy** - Застосування групової політики -### Контракти статусу провайдера +### Контракти статусу провайдерів Розташовані в `src/plugins/contracts/*.contract.test.ts`. -- **status** - проби статусу каналу -- **registry** - форма реєстру Plugin +- **status** - Перевірки статусу каналу +- **registry** - Форма реєстру Plugin ### Контракти провайдерів Розташовані в `src/plugins/contracts/*.contract.test.ts`: -- **auth** - контракт потоку автентифікації -- **auth-choice** - вибір автентифікації +- **auth** - Контракт потоку автентифікації +- **auth-choice** - Вибір автентифікації - **catalog** - API каталогу моделей -- **discovery** - виявлення Plugin -- **loader** - завантаження Plugin -- **runtime** - runtime провайдера -- **shape** - форма/інтерфейс Plugin -- **wizard** - майстер налаштування +- **discovery** - Виявлення Plugin +- **loader** - Завантаження Plugin +- **runtime** - Runtime провайдера +- **shape** - Форма/інтерфейс Plugin +- **wizard** - Майстер налаштування ### Коли запускати -- Після зміни експортів або subpaths plugin-sdk -- Після додавання або змінення каналу чи provider plugin -- Після рефакторингу реєстрації або виявлення Plugin +- Після зміни експортів plugin-sdk або subpaths +- Після додавання чи зміни каналу або provider plugin +- Після рефакторингу реєстрації або виявлення plugin -Контрактні тести запускаються в CI й не потребують реальних API-ключів. +Контрактні тести запускаються в CI і не потребують реальних API-ключів. ## Додавання регресій (настанови) Коли ви виправляєте проблему провайдера/моделі, виявлену в live: - Додайте безпечну для CI регресію, якщо можливо (mock/stub провайдер або зафіксуйте точне перетворення форми запиту) -- Якщо це за своєю суттю лише live-випадок (rate limits, політики автентифікації), залишайте live-тест вузьким і opt-in через env vars -- Віддавайте перевагу найменшому шару, який ловить помилку: - - помилка перетворення/відтворення запиту провайдера → прямий тест моделей - - помилка pipeline сесії/історії/інструментів Gateway → gateway live smoke або безпечний для CI mock-тест gateway -- Guardrail обходу SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибрану ціль для кожного класу SecretRef з metadata реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec ids із traversal-сегментами відхиляються. - - Якщо ви додаєте нову родину цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target ids, щоб нові класи не можна було тихо пропустити. +- Якщо це за своєю природою лише live-only (обмеження швидкості, політики автентифікації), тримайте live-тест вузьким і opt-in через env vars +- Надавайте перевагу найменшому шару, який ловить баг: + - баг перетворення/відтворення запиту провайдера → прямий тест моделей + - баг pipeline сесії/історії/інструментів gateway → gateway live smoke або безпечний для CI mock-тест gateway +- Захисне обмеження обходу SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибрану ціль для кожного класу SecretRef з метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec ids із traversal-segment відхиляються. + - Якщо ви додаєте нову сім’ю цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target ids, щоб нові класи не можна було мовчки пропустити. ## Пов’язане diff --git a/docs/uk/plugins/dependency-resolution.md b/docs/uk/plugins/dependency-resolution.md index d05db9390..cc72476fc 100644 --- a/docs/uk/plugins/dependency-resolution.md +++ b/docs/uk/plugins/dependency-resolution.md @@ -1,75 +1,81 @@ --- read_when: - - Ви налагоджуєте встановлення пакетів Plugin + - Ви налагоджуєте встановлення пакетів плагінів - Ви змінюєте поведінку запуску Plugin, doctor або встановлення через менеджер пакетів - - Ви підтримуєте пакетовані інсталяції OpenClaw або маніфести вбудованих Plugin + - Ви супроводжуєте пакетовані інсталяції OpenClaw або маніфести Plugin, що постачаються в комплекті sidebarTitle: Dependencies -summary: Як OpenClaw встановлює пакети Plugin і розв’язує залежності Plugin +summary: Як OpenClaw встановлює Plugin-пакети та розв’язує залежності Plugin title: Розв’язання залежностей Plugin x-i18n: - generated_at: "2026-05-02T01:52:11Z" + generated_at: "2026-05-02T02:02:07Z" model: gpt-5.5 provider: openai - source_hash: 296263808a080909e6dbf0000a764d7539a7065f86772f7fcf5a86c1f11e1906 + source_hash: 43d8008c837d519fd7c886f9615ad53941da340d753b559dfb0a32877716bc1f source_path: plugins/dependency-resolution.md workflow: 16 --- # Розв’язання залежностей Plugin -OpenClaw виконує роботу із залежностями Plugin під час встановлення/оновлення. Завантаження під час виконання -не запускає менеджери пакетів, не відновлює дерева залежностей і не змінює каталог +OpenClaw виконує роботу із залежностями Plugin під час установлення/оновлення. Завантаження під час виконання +не запускає менеджери пакетів, не ремонтує дерева залежностей і не змінює каталог пакета OpenClaw. ## Розподіл відповідальності Пакети Plugin відповідають за власний граф залежностей: -- залежності часу виконання містяться в `dependencies` або +- залежності часу виконання розміщуються в `dependencies` або `optionalDependencies` пакета Plugin -- імпорти SDK/core є peer-залежностями або наданими імпортами OpenClaw -- локальні Plugin для розробки приносять власні вже встановлені залежності -- npm- і git-Plugin встановлюються в корені пакетів, керовані OpenClaw +- імпорти SDK/ядра є peer-імпортами або наданими імпортами OpenClaw +- локальні Plugin для розробки постачаються зі своїми вже встановленими залежностями +- npm і git Plugin установлюються в корені пакетів, що належать OpenClaw OpenClaw відповідає лише за життєвий цикл Plugin: - виявити джерело Plugin -- встановити або оновити пакет за явним запитом +- установити або оновити пакет, коли це явно запитано - записати метадані встановлення - завантажити точку входу Plugin -- завершитися з дієвою помилкою, коли бракує залежностей +- завершити роботу з дієвою помилкою, коли залежності відсутні ## Корені встановлення OpenClaw використовує стабільні корені для кожного джерела: -- npm-пакети встановлюються в `~/.openclaw/npm` -- git-пакети клонуються в `~/.openclaw/git` -- локальні/path/archive встановлення копіюються або посилаються без відновлення залежностей +- пакети npm установлюються в `~/.openclaw/npm` +- пакети git клонуються в `~/.openclaw/git` +- локальні/шляхові/архівні встановлення копіюються або використовуються за посиланням без ремонту залежностей -npm-встановлення виконуються в npm-корені з: +Встановлення npm виконуються в корені npm за допомогою: ```bash npm install --prefix ~/.openclaw/npm --omit=dev --ignore-scripts --no-audit --no-fund ``` -git-встановлення клонують або оновлюють репозиторій, а потім виконують: +npm може підняти транзитивні залежності до `~/.openclaw/npm/node_modules` поруч із +пакетом Plugin. OpenClaw сканує керований корінь npm перед тим, як довіряти +встановленню, і використовує npm для видалення керованих npm пакетів під час деінсталяції, тож підняті +залежності часу виконання залишаються всередині керованої межі очищення. + +Встановлення git клонують або оновлюють репозиторій, а потім виконують: ```bash npm install --omit=dev --ignore-scripts --no-audit --no-fund ``` Після цього встановлений Plugin завантажується з каталогу цього пакета, тому розв’язання -`node_modules` у межах пакета працює так само, як для звичайного пакета Node. +локальних для пакета та батьківських `node_modules` працює так само, як для звичайного +пакета Node. ## Локальні Plugin -Локальні Plugin розглядаються як каталоги під контролем розробника. OpenClaw не -запускає `npm install`, `pnpm install` або відновлення залежностей для них. Якщо локальний -Plugin має залежності, встановіть їх у цьому Plugin перед його завантаженням. +Локальні Plugin розглядаються як каталоги, керовані розробником. OpenClaw не +виконує для них `npm install`, `pnpm install` або ремонт залежностей. Якщо локальний +Plugin має залежності, установіть їх у цьому Plugin перед його завантаженням. -Сторонні локальні Plugin на TypeScript можуть використовувати аварійний шлях Jiti. Запаковані -JavaScript Plugin і вбудовані внутрішні Plugin завантажуються через нативний +Сторонні локальні Plugin TypeScript можуть використовувати аварійний шлях Jiti. Запаковані +JavaScript Plugin і вбудовані внутрішні Plugin завантажуються через нативні import/require замість Jiti. ## Запуск і перезавантаження @@ -78,7 +84,7 @@ import/require замість Jiti. записи встановлення Plugin, обчислюють точку входу та завантажують її. Якщо залежність відсутня під час виконання, Plugin не завантажується, а помилка -має вказати оператору на явне виправлення: +має вказати оператору явне виправлення: ```bash openclaw plugins update @@ -87,37 +93,37 @@ openclaw doctor --fix ``` `doctor --fix` може очистити застарілий стан залежностей, згенерований OpenClaw, і встановити -налаштовані завантажувані Plugin, яких бракує в локальних записах встановлення. -Він не відновлює залежності для вже встановленого локального Plugin. +налаштовані завантажувані Plugin, яких немає в локальних записах встановлення. +Він не ремонтує залежності для вже встановленого локального Plugin. ## Вбудовані Plugin Легкі та критично важливі для ядра вбудовані Plugin постачаються як частина OpenClaw. -Вони мають або не мати важкого дерева залежностей часу виконання, або бути винесені до -завантажуваного пакета на ClawHub/npm. +Вони мають або не мати важкого дерева залежностей часу виконання, або бути винесені в +завантажуваний пакет на ClawHub/npm. -Маніфести вбудованих Plugin не повинні запитувати staging залежностей. Велика або необов’язкова -функціональність Plugin має пакуватися як звичайний Plugin і встановлюватися через +Маніфести вбудованих Plugin не повинні запитувати підготовку залежностей. Велику або необов’язкову +функціональність Plugin слід пакувати як звичайний Plugin і встановлювати через той самий шлях npm/git/ClawHub, що й сторонні Plugin. У вихідних checkout OpenClaw розглядає репозиторій як pnpm-монорепозиторій. Після `pnpm install` вбудовані Plugin завантажуються з `extensions/`, тож локальні для пакета -workspace-залежності доступні, а зміни підхоплюються напряму. Розробка у вихідному -checkout підтримується лише через pnpm; звичайний `npm install` у корені репозиторію +залежності workspace доступні, а зміни підхоплюються напряму. Розробка з вихідного +checkout підтримується лише з pnpm; звичайний `npm install` у корені репозиторію не є підтримуваним способом підготувати залежності вбудованих Plugin. -| Форма встановлення | Розташування вбудованого Plugin | Власник залежностей | +| Форма встановлення | Розташування вбудованого Plugin | Власник залежностей | | -------------------------------- | ------------------------------------- | -------------------------------------------------------------------- | -| `npm install -g openclaw` | Зібране дерево часу виконання всередині пакета | Пакет OpenClaw і явні потоки встановлення/оновлення/doctor для Plugin | -| Git checkout плюс `pnpm install` | Workspace-пакети `extensions/` | pnpm-workspace, включно з власними залежностями кожного пакета Plugin | +| `npm install -g openclaw` | Побудоване дерево часу виконання всередині пакета | Пакет OpenClaw і явні потоки встановлення/оновлення/doctor для Plugin | +| Git checkout плюс `pnpm install` | Пакети workspace `extensions/` | pnpm workspace, включно з власними залежностями кожного пакета Plugin | | `openclaw plugins install ...` | Керований корінь Plugin npm/git/ClawHub | Потік встановлення/оновлення Plugin | -## Очищення застарілого +## Очищення застарілого стану Старіші версії OpenClaw генерували корені залежностей вбудованих Plugin під час запуску або -під час виправлення doctor. Поточне очищення doctor видаляє ці застарілі каталоги та -симлінки, коли використано `--fix`, включно зі старими коренями `plugin-runtime-deps`, +під час ремонту doctor. Поточне очищення doctor видаляє ці застарілі каталоги та +символьні посилання, коли використовується `--fix`, включно зі старими коренями `plugin-runtime-deps`, маніфестами `.openclaw-runtime-deps*`, згенерованими `node_modules` Plugin, каталогами -етапу встановлення та локальними pnpm-сховищами пакетів. +етапів встановлення та локальними для пакета сховищами pnpm. -Ці шляхи є лише застарілими залишками. Нові встановлення не повинні створювати їх. +Ці шляхи є лише застарілими залишками. Нові встановлення не повинні їх створювати. diff --git a/docs/uk/reference/test.md b/docs/uk/reference/test.md index f9a610e46..b9bddbc2f 100644 --- a/docs/uk/reference/test.md +++ b/docs/uk/reference/test.md @@ -1,62 +1,63 @@ --- read_when: - Запуск або виправлення тестів -summary: Як запускати тести локально (vitest) і коли використовувати режими примусового запуску/покриття +summary: Як запускати тести локально (vitest) і коли використовувати режими force/coverage title: Тести x-i18n: - generated_at: "2026-05-01T23:38:24Z" + generated_at: "2026-05-02T02:01:42Z" model: gpt-5.5 provider: openai - source_hash: b2bf9cf1024d78747d97b5f4fb41ae42fe6cba547db023b78f3d0dcd4ba5128d + source_hash: 1100eb4c5990de1a56c8fd65c6152318316232414078cdaad122d4525bf27fee source_path: reference/test.md workflow: 16 --- -- Повний набір для тестування (набори тестів, live, Docker): [Тестування](/uk/help/testing) -- Перевірка оновлень і пакетів Plugin: [Тестування оновлень і Plugin](/uk/help/testing-updates-plugins) +- Повний набір для тестування (набори, live, Docker): [Тестування](/uk/help/testing) +- Перевірка оновлень і пакета Plugin: [Тестування оновлень і plugins](/uk/help/testing-updates-plugins) -- `pnpm test:force`: Завершує будь-який залишковий процес gateway, що утримує типовий контрольний порт, а потім запускає повний набір Vitest з ізольованим портом gateway, щоб серверні тести не конфліктували із запущеним екземпляром. Використовуйте це, коли попередній запуск gateway залишив порт 18789 зайнятим. -- `pnpm test:coverage`: Запускає unit-набір із покриттям V8 (через `vitest.unit.config.ts`). Це gate покриття завантажених unit-файлів, а не покриття всіх файлів усього репозиторію. Пороги: 70% для рядків/функцій/інструкцій і 55% для гілок. Оскільки `coverage.all` має значення false, gate вимірює файли, завантажені unit-набором покриття, замість того щоб вважати кожен split-lane вихідний файл непокритим. -- `pnpm test:coverage:changed`: Запускає unit-покриття лише для файлів, змінених відносно `origin/main`. -- `pnpm test:changed`: дешевий розумний запуск тестів за змінами. Він запускає точні цілі з прямих змін тестів, сусідніх файлів `*.test.ts`, явних мапінгів вихідних файлів і локального графа імпортів. Широкі зміни конфігурації/пакетів пропускаються, якщо вони не мапляться на точні тести. -- `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`: явний широкий запуск тестів за змінами. Використовуйте його, коли зміна тестового harness/config/package має повертатися до ширшої поведінки Vitest для changed-test. -- `pnpm changed:lanes`: показує архітектурні lanes, які запускає diff відносно `origin/main`. -- `pnpm check:changed`: запускає розумний gate перевірки змін для diff відносно `origin/main`. Він запускає typecheck, lint і guard-команди для зачеплених архітектурних lanes, але не запускає тести Vitest. Використовуйте `pnpm test:changed` або явний `pnpm test ` для тестового підтвердження. -- `pnpm test`: спрямовує явні цілі файлів/каталогів через scoped Vitest lanes. Запуски без цілі використовують фіксовані групи shards і розгортаються до leaf configs для локального паралельного виконання; група extension завжди розгортається до per-extension shard configs замість одного гігантського root-project процесу. -- Запуски test wrapper завершуються коротким підсумком `[test] passed|failed|skipped ... in ...`. Власний рядок тривалості Vitest залишається деталлю per-shard. -- Спільний тестовий стан OpenClaw: використовуйте `src/test-utils/openclaw-test-state.ts` з Vitest, коли тесту потрібні ізольовані `HOME`, `OPENCLAW_STATE_DIR`, `OPENCLAW_CONFIG_PATH`, config fixture, workspace, agent dir або сховище auth-profile. -- Process E2E helpers: використовуйте `test/helpers/openclaw-test-instance.ts`, коли Vitest process-level E2E тесту потрібні запущений Gateway, CLI env, захоплення логів і cleanup в одному місці. -- Docker/Bash E2E helpers: lanes, які source `scripts/lib/docker-e2e-image.sh`, можуть передавати `docker_e2e_test_state_shell_b64