From 437d4782e6047f90fa472aaf74ce3c3a59d02be2 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Fri, 24 Apr 2026 06:17:48 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/help/testing.md | 677 ++++++++++++++++++++-------------------- 1 file changed, 341 insertions(+), 336 deletions(-) diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index 72010fc60..287f50ff4 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -1,167 +1,169 @@ --- read_when: - Запуск тестів локально або в CI - - Додавання регресійних тестів для помилок моделей/провайдерів - - Налагодження поведінки Gateway + агентів + - Додавання регресійних тестів для багів моделей/провайдерів + - Налагодження поведінки Gateway + агента summary: 'Набір для тестування: набори unit/e2e/live, Docker-ранери та що охоплює кожен тест' title: Тестування x-i18n: - generated_at: "2026-04-24T05:03:58Z" + generated_at: "2026-04-24T06:14:23Z" model: gpt-5.4 provider: openai - source_hash: 3b3aa0a785daa5d43dfd2b352cf8c3013c408231c000ff40852bac534211ec54 + source_hash: b825d25da0eb504dfc19e5dcf18b50e8c3bf07e616d0be82d096f3973dbbd785 source_path: help/testing.md workflow: 15 --- -OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір Docker-ранерів. Цей документ — посібник «як ми тестуємо»: +OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір +Docker-ранерів. Цей документ — посібник «як ми тестуємо»: - Що охоплює кожен набір (і що він навмисно _не_ охоплює). -- Які команди запускати для типових сценаріїв роботи (локально, перед push, налагодження). +- Які команди запускати для поширених сценаріїв (локально, перед push, налагодження). - Як live-тести знаходять облікові дані та вибирають моделі/провайдерів. -- Як додавати регресійні тести для реальних проблем моделей/провайдерів. +- Як додавати регресійні тести для реальних проблем із моделями/провайдерами. ## Швидкий старт У більшості випадків: -- Повний набір перевірок (очікується перед push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` -- Швидший локальний запуск усього набору на потужній машині: `pnpm test:max` +- Повна перевірка (очікується перед push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` +- Швидший локальний запуск повного набору на потужній машині: `pnpm test:max` - Прямий цикл спостереження Vitest: `pnpm test:watch` - Пряме націлювання на файл тепер також маршрутизує шляхи extension/channel: `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` +- QA-ланка на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Коли ви змінюєте тести або хочете більше впевненості: +Коли ви змінюєте тести або хочете додаткової впевненості: - Перевірка покриття: `pnpm test:coverage` - Набір E2E: `pnpm test:e2e` Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані): -- Набір live (моделі + перевірки інструментів/зображень Gateway): `pnpm test:live` -- Точково запустити один live-файл тихо: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Live-набір (моделі + перевірки інструментів/зображень Gateway): `pnpm test:live` +- Тихо націлити один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts` - Docker-прогін live-моделей: `pnpm test:docker:live-models` - - Для кожної вибраної моделі тепер запускається текстовий хід плюс невелика перевірка у стилі читання файлу. - Моделі, у чиїх метаданих заявлено вхід `image`, також запускають невеликий хід із зображенням. + - Кожна вибрана модель тепер виконує текстовий хід плюс невелику перевірку у стилі читання файлу. + Моделі, чиї метадані оголошують вхід `image`, також виконують невеликий хід із зображенням. Вимкніть додаткові перевірки через `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-завдання live-моделей, + - Покриття в CI: щоденний `OpenClaw Scheduled Live And E2E Checks` і ручний + `OpenClaw Release Checks` обидва викликають повторно використовуваний live/E2E workflow з + `include_live_suites: true`, що включає окремі Docker matrix jobs для live-моделей, розбиті за провайдером. - - Для точкових повторних запусків у CI запускайте `OpenClaw Live And E2E Checks (Reusable)` з - `include_live_suites: true` і `live_models_only: true`. + - Для цільових повторних запусків у 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 bound-chat: `pnpm test:docker:live-codex-bind` - - Запускає Docker live-лінію проти шляху app-server Codex, прив’язує синтетичний +- Native Codex bind-chat smoke: `pnpm test:docker:live-codex-bind` + - Запускає Docker live-ланку проти шляху Codex app-server, прив’язує синтетичний Slack DM через `/codex bind`, виконує `/codex fast` і - `/codex permissions`, потім перевіряє, що звичайна відповідь і вкладення із зображенням - проходять через нативну прив’язку plugin, а не через ACP. -- Димовий тест вартості Moonshot/Kimi: якщо встановлено `MOONSHOT_API_KEY`, виконайте - `openclaw models list --provider moonshot --json`, а потім ізольований + `/codex permissions`, а потім перевіряє, що звичайна відповідь і вкладення-зображення + маршрутизуються через native Plugin binding, а не через ACP. +- Moonshot/Kimi перевірка вартості: якщо встановлено `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`. -Порада: якщо вам потрібен лише один збійний випадок, надавайте перевагу звуженню live-тестів через змінні середовища allowlist, описані нижче. +Порада: коли вам потрібен лише один збійний випадок, віддавайте перевагу звуженню live-тестів через змінні середовища allowlist, описані нижче. ## QA-специфічні ранери -Ці команди існують поруч з основними наборами тестів, коли вам потрібен реалізм QA lab: +Ці команди розташовані поруч з основними наборами тестів, коли вам потрібен реалізм QA-lab: -CI запускає QA Lab в окремих workflow. `Parity gate` запускається для відповідних PR і -через ручний запуск із mock-провайдерами. `QA-Lab - All Lanes` запускається щоночі на -`main` і через ручний запуск із mock parity gate, live-лінією Matrix та -керованою Convex live-лінією Telegram як паралельними завданнями. `OpenClaw Release Checks` -запускає ті самі лінії перед погодженням релізу. +CI запускає QA Lab в окремих workflow. `Parity gate` запускається для відповідних PR +і через ручний запуск із mock-провайдерами. `QA-Lab - All Lanes` запускається щоночі на +`main` і через ручний запуск із mock parity gate, live Matrix lane та +live Telegram lane під керуванням Convex як паралельні jobs. `OpenClaw Release Checks` +запускає ті самі ланки перед погодженням релізу. - `pnpm openclaw qa suite` - - Запускає сценарії QA на базі репозиторію безпосередньо на хості. + - Запускає QA-сценарії на основі репозиторію безпосередньо на хості. - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими - worker-процесами Gateway. `qa-channel` за замовчуванням використовує конкурентність 4 - (обмежену кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати кількість worker-процесів, - або `--concurrency 1` для старішої послідовної лінії. - - Завершується з ненульовим кодом, якщо будь-який сценарій завершується помилкою. Використовуйте `--allow-failures`, коли + працівниками Gateway. Для `qa-channel` типовою є конкуренція 4 (обмежена + кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати + кількість працівників, або `--concurrency 1` для старішої послідовної ланки. + - Завершується з ненульовим кодом, якщо збій трапляється в будь-якому сценарії. Використовуйте `--allow-failures`, якщо вам потрібні артефакти без коду завершення з помилкою. - Підтримує режими провайдерів `live-frontier`, `mock-openai` і `aimock`. - `aimock` запускає локальний AIMock-сервер провайдера для експериментального - покриття фікстур і моків протоколу без заміни лінії `mock-openai`, - яка знає про сценарії. + `aimock` запускає локальний сервер провайдера на базі AIMock для експериментального + покриття фікстур і моків протоколу без заміни сценарно-орієнтованої + ланки `mock-openai`. - `pnpm openclaw qa suite --runner multipass` - - Запускає той самий набір QA у тимчасовій Linux VM Multipass. - - Зберігає таку саму поведінку вибору сценаріїв, як і `qa suite` на хості. + - Запускає той самий QA-набір усередині одноразової Linux VM Multipass. + - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. - Повторно використовує ті самі прапорці вибору провайдера/моделі, що й `qa suite`. - - Live-запуски передають підтримувані вхідні дані автентифікації QA, практичні для гостьової системи: - ключі провайдерів на основі env, шлях до конфігурації live-провайдера QA і `CODEX_HOME`, якщо він є. + - Live-запуски пересилають підтримувані вхідні дані автентифікації QA, які практичні для гостьової системи: + ключі провайдера на основі env, шлях до конфігурації QA live provider і `CODEX_HOME`, якщо він присутній. - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб гостьова система могла записувати назад через - змонтований workspace. - - Записує звичайний QA-звіт і підсумок, а також журнали Multipass у + змонтований робочий простір. + - Записує звичайний QA-звіт + підсумок, а також журнали Multipass у `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Запускає QA-сайт на базі Docker для операторської роботи з QA. + - Запускає QA-сайт на базі Docker для QA-роботи в операторському стилі. - `pnpm test:docker:npm-onboard-channel-agent` - Збирає npm tarball з поточного checkout, глобально встановлює його в - Docker, запускає неінтерактивний онбординг із ключем API OpenAI, за замовчуванням налаштовує Telegram, - перевіряє, що ввімкнення plugin встановлює runtime-залежності за потреби, - запускає doctor і виконує один локальний хід агента проти змоканого endpoint OpenAI. - - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити ту саму лінію - інсталяції з пакета з Discord. + Docker, запускає неінтерактивний онбординг OpenAI API key, типово налаштовує Telegram, + перевіряє, що ввімкнення Plugin встановлює runtime-залежності за потреби, + запускає doctor і виконує один локальний хід агента проти змоканого OpenAI endpoint. + - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити ту саму + ланку встановлення з пакета з Discord. - `pnpm test:docker:npm-telegram-live` - - Встановлює опублікований пакет OpenClaw у Docker, запускає онбординг установленого пакета, - налаштовує Telegram через встановлений CLI, а потім повторно використовує - live-лінію QA Telegram з цим установленим пакетом як SUT Gateway. - - За замовчуванням використовує `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`. - - Використовує ті самі env-облікові дані Telegram або джерело облікових даних Convex, що й + - Встановлює опублікований пакет OpenClaw у Docker, виконує онбординг + встановленого пакета, налаштовує Telegram через встановлений CLI, а потім повторно використовує + Telegram live QA lane з цим встановленим пакетом як SUT Gateway. + - Типове значення: `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`. + - Використовує ті самі облікові дані Telegram із env або джерело облікових даних Convex, що й `pnpm openclaw qa telegram`. - `pnpm test:docker:bundled-channel-deps` - - Пакує й встановлює поточну збірку OpenClaw у Docker, запускає Gateway з налаштованим OpenAI, - а потім вмикає вбудовані channel/plugin через зміни конфігурації. - - Перевіряє, що виявлення під час налаштування залишає runtime-залежності - неналаштованих plugin відсутніми, що перший налаштований запуск Gateway або doctor - встановлює runtime-залежності кожного вбудованого plugin за потреби, і що другий перезапуск не перевстановлює залежності, які вже були активовані. - - Також встановлює відомий старіший npm baseline, вмикає Telegram перед запуском - `openclaw update --tag `, і перевіряє, що doctor після оновлення - у candidate відновлює runtime-залежності вбудованих channel без виправлення postinstall на боці harness. + - Пакує та встановлює поточну збірку OpenClaw у Docker, запускає Gateway з налаштованим OpenAI, + а потім вмикає вбудовані channel/Plugins через редагування конфігурації. + - Перевіряє, що виявлення налаштування залишає відсутніми runtime-залежності + неналаштованих Plugins, що перший налаштований запуск Gateway або doctor встановлює + runtime-залежності кожного вбудованого Plugin за потреби, і що другий перезапуск не + перевстановлює залежності, які вже були активовані. + - Також встановлює відому старішу npm-базову версію, вмикає Telegram перед виконанням + `openclaw update --tag ` і перевіряє, що + `doctor` кандидата після оновлення відновлює runtime-залежності вбудованого channel без + відновлення postinstall на боці harness. - `pnpm openclaw qa aimock` - - Запускає лише локальний AIMock-сервер провайдера для безпосереднього димового - тестування протоколу. + - Запускає лише локальний сервер провайдера AIMock для прямого smoke-тестування протоколу. - `pnpm openclaw qa matrix` - - Запускає live-лінію QA Matrix проти тимчасового homeserver Tuwunel на базі Docker. - - Цей QA-хост наразі доступний лише для repo/dev. Пакетні інсталяції OpenClaw не постачають + - Запускає Matrix live QA lane проти одноразового homeserver Tuwunel на базі Docker. + - Цей QA-хост наразі призначений лише для репозиторію/розробки. Пакетні встановлення OpenClaw не постачають `qa-lab`, тому вони не надають `openclaw qa`. - - Checkout репозиторію напряму завантажують вбудований раннер; окремий крок установлення plugin не потрібен. - - Створює трьох тимчасових користувачів Matrix (`driver`, `sut`, `observer`) плюс одну приватну кімнату, а потім запускає дочірній QA gateway із реальним plugin Matrix як транспортом SUT. - - За замовчуванням використовує зафіксований стабільний образ Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Перевизначайте через `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, коли потрібно протестувати інший образ. - - Matrix не надає спільних прапорців джерела облікових даних, оскільки ця лінія локально створює тимчасових користувачів. - - Записує QA-звіт Matrix, підсумок, артефакт observed-events і комбінований журнал виводу stdout/stderr у `.artifacts/qa-e2e/...`. + - Checkout репозиторію завантажують вбудований раннер безпосередньо; окремий крок встановлення Plugin не потрібен. + - Надає три тимчасові користувачі Matrix (`driver`, `sut`, `observer`) і одну приватну кімнату, а потім запускає дочірній QA gateway з реальним Matrix Plugin як транспортом SUT. + - Типово використовує зафіксований стабільний образ Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Перевизначайте через `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, коли потрібно протестувати інший образ. + - Matrix не надає спільних прапорців джерела облікових даних, оскільки ця ланка локально надає одноразових користувачів. + - Записує Matrix QA report, summary, observed-events artifact і об’єднаний журнал виводу stdout/stderr у `.artifacts/qa-e2e/...`. - `pnpm openclaw qa telegram` - - Запускає live-лінію QA Telegram проти реальної приватної групи, використовуючи токени bot driver і SUT з env. - - Потрібні `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Ідентифікатор групи має бути числовим Telegram chat id. - - Підтримує `--credential-source convex` для спільних пулів облікових даних. За замовчуванням використовуйте режим env, або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб перейти на спільні lease. - - Завершується з ненульовим кодом, якщо будь-який сценарій завершується помилкою. Використовуйте `--allow-failures`, коли + - Запускає Telegram live QA lane проти реальної приватної групи, використовуючи токени ботів driver і SUT з env. + - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Ідентифікатор групи має бути числовим Telegram chat id. + - Підтримує `--credential-source convex` для спільних пулових облікових даних. Типово використовуйте режим env або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути спільні оренди. + - Завершується з ненульовим кодом, якщо збій трапляється в будь-якому сценарії. Використовуйте `--allow-failures`, якщо вам потрібні артефакти без коду завершення з помилкою. - - Потрібні два різні bot в одній приватній групі, причому bot SUT має мати доступне ім’я користувача Telegram. - - Для стабільного спостереження bot-to-bot увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох bot і переконайтеся, що bot driver може спостерігати за трафіком bot у групі. - - Записує QA-звіт Telegram, підсумок і артефакт observed-messages у `.artifacts/qa-e2e/...`. Сценарії з відповідями включають RTT від запиту на надсилання від driver до спостереженої відповіді SUT. + - Потребує двох різних ботів в одній приватній групі, причому бот SUT має надавати Telegram username. + - Для стабільного спостереження бот-за-ботом увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що бот driver може спостерігати трафік ботів у групі. + - Записує Telegram QA report, summary і observed-messages artifact у `.artifacts/qa-e2e/...`. Сценарії відповіді включають RTT від запиту надсилання driver до спостережуваної відповіді SUT. -Live-транспортні лінії спільно використовують один стандартний контракт, щоб нові транспорти не розходилися в поведінці: +Live transport lanes використовують один стандартний контракт, щоб нові транспорти не дрейфували: -`qa-channel` залишається широким синтетичним набором QA і не входить до матриці покриття live-транспорту. +`qa-channel` залишається широким синтетичним QA-набором і не є частиною матриці покриття live transport. -| Лінія | Canary | Гейтінг згадок | Блокування allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальше повідомлення в треді | Ізоляція тредів | Спостереження реакцій | Команда допомоги | -| -------- | ------ | -------------- | -------------------- | ------------------------- | ----------------------------- | ----------------------------- | --------------- | --------------------- | ---------------- | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Ланка | Canary | Mention gating | Allowlist block | Top-level reply | Restart resume | Thread follow-up | Thread isolation | Reaction observation | Команда help | +| -------- | ------ | -------------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | ### Спільні облікові дані Telegram через Convex (v1) Коли для `openclaw qa telegram` увімкнено `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`), -QA lab отримує ексклюзивний lease із пулу на базі Convex, надсилає Heartbeat цього -lease, поки лінія виконується, і вивільняє lease під час завершення роботи. +QA lab отримує ексклюзивну оренду з пулу на базі Convex, надсилає Heartbeat +для цієї оренди, поки ланка виконується, і звільняє оренду під час завершення роботи. Еталонний каркас проєкту Convex: @@ -185,14 +187,14 @@ lease, поки лінія виконується, і вивільняє lease - `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://`. +У звичайному режимі `OPENCLAW_QA_CONVEX_SITE_URL` має використовувати `https://`. -Адміністративні команди maintainer (додавання/видалення/перелік пулу) вимагають +Команди адміністрування для maintainers (додавання/видалення/перелік пулу) потребують саме `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. -Допоміжні команди CLI для maintainer: +CLI-хелпери для maintainers: ```bash pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json @@ -200,28 +202,28 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -Використовуйте `--json` для машинозчитуваного виводу в скриптах і утилітах CI. +Використовуйте `--json` для машиночитного виводу в скриптах і утилітах CI. Типовий контракт endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): - `POST /acquire` - Запит: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` - Успіх: `{ status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }` - - Пул вичерпано/можна повторити: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` + - Вичерпано/можна повторити: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` - `POST /heartbeat` - Запит: `{ kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }` - Успіх: `{ status: "ok" }` (або порожній `2xx`) - `POST /release` - Запит: `{ kind, ownerId, actorRole, credentialId, leaseToken }` - Успіх: `{ status: "ok" }` (або порожній `2xx`) -- `POST /admin/add` (лише для секрету maintainer) +- `POST /admin/add` (лише секрет maintainer) - Запит: `{ kind, actorId, payload, note?, status? }` - Успіх: `{ status: "ok", credential }` -- `POST /admin/remove` (лише для секрету maintainer) +- `POST /admin/remove` (лише секрет maintainer) - Запит: `{ credentialId, actorId }` - Успіх: `{ status: "ok", changed, credential }` - - Захист активного lease: `{ status: "error", code: "LEASE_ACTIVE", ... }` -- `POST /admin/list` (лише для секрету maintainer) + - Захист активної оренди: `{ status: "error", code: "LEASE_ACTIVE", ... }` +- `POST /admin/list` (лише секрет maintainer) - Запит: `{ kind?, status?, includePayload?, limit? }` - Успіх: `{ status: "ok", credentials, count }` @@ -233,55 +235,55 @@ pnpm openclaw qa credentials remove --credential-id ### Додавання channel до QA -Додавання channel до markdown-системи QA вимагає рівно двох речей: +Додавання channel до markdown-системи QA потребує рівно двох речей: -1. Адаптер транспорту для channel. -2. Набір сценаріїв, який перевіряє контракт channel. +1. Транспортного адаптера для channel. +2. Пакета сценаріїв, який перевіряє контракт channel. Не додавайте новий кореневий QA-командний простір верхнього рівня, якщо спільний хост `qa-lab` може -керувати цим процесом. +керувати цим потоком. `qa-lab` керує спільною механікою хоста: -- кореневою командою `openclaw qa` +- коренем команд `openclaw qa` - запуском і завершенням набору -- конкурентністю worker-процесів +- конкуренцією працівників - записом артефактів - генерацією звітів - виконанням сценаріїв -- псевдонімами сумісності для старих сценаріїв `qa-channel` +- alias сумісності для старіших сценаріїв `qa-channel` -Runner plugin керують транспортним контрактом: +Runner Plugins відповідають за транспортний контракт: - як `openclaw qa ` монтується під спільним коренем `qa` -- як Gateway налаштовується для цього транспорту +- як налаштовується gateway для цього транспорту - як перевіряється готовність -- як ін’єктуються вхідні події +- як інжектуються вхідні події - як спостерігаються вихідні повідомлення - як надаються транскрипти й нормалізований стан транспорту -- як виконуються дії, підкріплені транспортом -- як обробляються специфічні для транспорту reset або cleanup +- як виконуються дії на базі транспорту +- як обробляється специфічний для транспорту reset або cleanup -Мінімальний поріг упровадження для нового channel: +Мінімальний поріг впровадження для нового channel: -1. Залишайте `qa-lab` власником спільного кореня `qa`. -2. Реалізуйте transport runner на межі спільного хоста `qa-lab`. -3. Залишайте специфічну для транспорту механіку всередині runner plugin або harness channel. -4. Монтуйте runner як `openclaw qa `, а не реєструйте конкуруючу кореневу команду. - Runner plugin мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` з `runtime-api.ts`. - Зберігайте `runtime-api.ts` легким; ледаче виконання CLI і runner має залишатися за окремими entrypoint. -5. Створюйте або адаптуйте markdown-сценарії в тематичних каталогах `qa/scenarios/`. -6. Використовуйте загальні helper-функції сценаріїв для нових сценаріїв. -7. Зберігайте чинні псевдоніми сумісності працездатними, якщо тільки репозиторій не виконує навмисну міграцію. +1. Залишити `qa-lab` власником спільного кореня `qa`. +2. Реалізувати transport runner на спільному хостовому seam `qa-lab`. +3. Зберігати специфічну для транспорту механіку всередині runner Plugin або harness channel. +4. Монтувати runner як `openclaw qa `, а не реєструвати конкуруючу кореневу команду. + Runner Plugins мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` з `runtime-api.ts`. + Залишайте `runtime-api.ts` легким; ліниве виконання CLI і runner має залишатися за окремими entrypoint. +5. Створювати або адаптувати markdown-сценарії в тематичних каталогах `qa/scenarios/`. +6. Використовувати загальні хелпери сценаріїв для нових сценаріїв. +7. Зберігати наявні alias сумісності працездатними, якщо тільки репозиторій не виконує навмисну міграцію. -Правило прийняття рішення суворе: +Правило ухвалення рішення є суворим: - Якщо поведінку можна один раз виразити в `qa-lab`, розміщуйте її в `qa-lab`. -- Якщо поведінка залежить від одного транспорту channel, залишайте її в цьому runner plugin або harness plugin. +- Якщо поведінка залежить від одного транспорту channel, залишайте її в цьому runner Plugin або harness Plugin. - Якщо сценарію потрібна нова можливість, яку може використовувати більше ніж один channel, додайте загальний helper замість branch, специфічного для channel, у `suite.ts`. -- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій специфічним для цього транспорту й явно вказуйте це в контракті сценарію. +- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій специфічним для цього транспорту і явно вказуйте це в контракті сценарію. -Бажані назви загальних helper-функцій для нових сценаріїв: +Бажані назви загальних helper для нових сценаріїв: - `waitForTransportReady` - `waitForChannelReady` @@ -296,7 +298,7 @@ Runner plugin керують транспортним контрактом: - `formatTransportTranscript` - `resetTransport` -Псевдоніми сумісності залишаються доступними для чинних сценаріїв, зокрема: +Alias сумісності залишаються доступними для наявних сценаріїв, зокрема: - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -304,402 +306,405 @@ Runner plugin керують транспортним контрактом: - `formatConversationTranscript` - `resetBus` -Нова робота з channel має використовувати загальні назви helper-функцій. -Псевдоніми сумісності існують, щоб уникнути одночасної міграції всього, а не як модель для +Нова робота над channel має використовувати загальні назви helper. +Alias сумісності існують, щоб уникнути міграції одним днем, а не як модель для створення нових сценаріїв. ## Набори тестів (що де запускається) -Сприймайте набори як «зростання реалізму» (і зростання нестабільності/вартості): +Думайте про набори як про «зростання реалізму» (і зростання нестабільності/вартості): ### Unit / integration (типово) - Команда: `pnpm test` -- Конфігурація: ненаправлені запуски використовують набір шардів `vitest.full-*.config.ts` і можуть розгортати multi-project shards у конфігурації по одному проєкту для паралельного планування -- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і whitelist node-тестів `ui`, охоплених `vitest.unit.config.ts` +- Конфігурація: нецільові запуски використовують набір шардів `vitest.full-*.config.ts` і можуть розгортати multi-project шарди в конфігурації на рівні окремих проєктів для паралельного планування +- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і внесені до allowlist node-тести `ui`, охоплені `vitest.unit.config.ts` - Обсяг: - Чисті unit-тести - - Інтеграційні тести в межах процесу (автентифікація Gateway, маршрутизація, tooling, parsing, config) - - Детерміновані регресійні тести для відомих помилок + - In-process integration-тести (автентифікація gateway, маршрутизація, tooling, parsing, config) + - Детерміновані регресії для відомих багів - Очікування: - Запускається в CI - Реальні ключі не потрібні - Має бути швидким і стабільним - - Ненаправлений `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`) замість одного великого нативного процесу root-project. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension блокувати непов’язані набори. - `pnpm test --watch` усе ще використовує нативний граф проєктів root `vitest.config.ts`, оскільки multi-shard цикл watch не є практичним. - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файлів/каталогів через scoped lanes, тому `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску root project. - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped lanes, коли diff зачіпає лише маршрутизовані файли source/test; редагування config/setup усе ще повертаються до широкого повторного запуску root-project. - `pnpm check:changed` — це звичайний розумний локальний набір перевірок для вузьких змін. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, release metadata і tooling, а потім запускає відповідні лінії typecheck/lint/test. Зміни публічного Plugin SDK і plugin-contract включають один додатковий прохід перевірки extension, оскільки extensions залежать від цих контрактів core. Зміни версій лише в release metadata запускають цільові перевірки version/config/root-dependency замість повного набору, із захистом, який відхиляє зміни package поза полем версії верхнього рівня. - Легкі за імпортами unit-тести з agents, commands, plugins, helper-функцій auto-reply, `plugin-sdk` та подібних чистих утилітних областей маршрутизуються через лінію `unit-fast`, яка пропускає `test/setup-openclaw-runtime.ts`; файли зі станом/важким runtime залишаються на чинних лініях. - Вибрані вихідні helper-файли `plugin-sdk` і `commands` також у режимі changed зіставляються з явними сусідніми тестами в цих легких лініях, тож зміни helper-функцій уникають повторного запуску всього важкого набору для цього каталогу. - `auto-reply` має три окремі категорії: helper-функції core верхнього рівня, інтеграційні тести `reply.*` верхнього рівня та піддерево `src/auto-reply/reply/**`. Це не дає найважчій роботі harness reply потрапляти в дешеві тести status/chunk/token. + - Нецільовий `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`) замість одного великого native root-project process. Це зменшує піковий RSS на завантажених машинах і запобігає тому, щоб робота auto-reply/extension витісняла непов’язані набори. - `pnpm test --watch` усе ще використовує native root `vitest.config.ts` project graph, оскільки multi-shard цикл watch непрактичний. - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файлів/каталогів через scoped lanes, тож `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску root project. - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped lanes, коли diff торкається лише routable source/test файлів; редагування config/setup все ще повертаються до широкого повторного запуску root project. - `pnpm check:changed` — це звичайна розумна локальна перевірка для вузької роботи. Вона класифікує diff на core, core tests, extensions, extension tests, apps, docs, release metadata і tooling, а потім запускає відповідні ланки typecheck/lint/test. Зміни в публічному Plugin SDK і plugin-contract включають один прохід валідації extension, оскільки extensions залежать від цих core-контрактів. Підвищення версії лише в release metadata запускають цільові перевірки version/config/root-dependency замість повного набору, із захистом, який відхиляє зміни package поза полем версії верхнього рівня. - Легкі щодо імпорту unit-тести з agents, commands, plugins, auto-reply helpers, `plugin-sdk` та подібних чистих утилітних областей маршрутизуються через ланку `unit-fast`, яка пропускає `test/setup-openclaw-runtime.ts`; файли зі станом/важким runtime залишаються на наявних ланках. - Вибрані файли вихідного коду helper у `plugin-sdk` і `commands` також зіставляють запуски в режимі changed з явними sibling-тестами в цих легких ланках, тож зміни helper уникають повторного запуску повного важкого набору для цього каталогу. - `auto-reply` має три окремі кошики: helper верхнього рівня core, integration-тести верхнього рівня `reply.*` і піддерево `src/auto-reply/reply/**`. Це утримує найважчу роботу harness reply подалі від дешевих тестів status/chunk/token. - - Коли ви змінюєте входи виявлення message-tool або runtime-контекст Compaction, зберігайте обидва рівні покриття. - - Додавайте цільові helper-регресії для чистих меж маршрутизації та нормалізації. - - Підтримуйте здоровий стан інтеграційних наборів embedded runner: + - Коли ви змінюєте вхідні дані виявлення message-tool або runtime-контекст compaction, + зберігайте обидва рівні покриття. + - Додавайте цільові регресії helper для чистих меж маршрутизації та нормалізації. + - Підтримуйте здоровий стан integration-наборів embedded 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 id і поведінка compaction як і раніше проходять - через реальні шляхи `run.ts` / `compact.ts`; лише helper-тести не є достатньою заміною для цих інтеграційних шляхів. + - Ці набори перевіряють, що scoped id і поведінка compaction, як і раніше, проходять + через реальні шляхи `run.ts` / `compact.ts`; helper-only тести не є + достатньою заміною для цих integration-шляхів. - + - Базова конфігурація Vitest типово використовує `threads`. - Спільна конфігурація Vitest фіксує `isolate: false` і використовує - runner без ізоляції в root projects, e2e і live configs. - - Коренева лінія UI зберігає своє налаштування `jsdom` і optimizer, але теж працює на - спільному runner без ізоляції. - - Кожен шард `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` + неізольований runner у root projects, конфігураціях e2e та live. + - Коренева ланка UI зберігає свій `jsdom` setup і optimizer, але теж працює на + спільному неізольованому runner. + - Кожен shard `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` зі спільної конфігурації Vitest. - `scripts/run-vitest.mjs` типово додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. - Встановіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти з типовою поведінкою V8. + Встановіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти зі стандартною поведінкою V8. - - `pnpm changed:lanes` показує, які архітектурні лінії запускає diff. - - Pre-commit hook лише форматує. Він повторно додає відформатовані файли до staging і + - `pnpm changed:lanes` показує, які архітектурні ланки запускає diff. + - Pre-commit hook виконує лише форматування. Він повторно додає відформатовані файли до stage і не запускає lint, typecheck або тести. - Явно запускайте `pnpm check:changed` перед передачею або push, коли - вам потрібен розумний локальний набір перевірок. Зміни публічного Plugin SDK і plugin-contract - включають один додатковий прохід перевірки extension. + вам потрібна розумна локальна перевірка. Зміни в публічному Plugin SDK і plugin-contract + включають один прохід валідації extension. - `pnpm test:changed` маршрутизує через scoped lanes, коли змінені шляхи - чисто відображаються на менший набір. - - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму логіку маршрутизації, - лише з вищою межею кількості worker-процесів. - - Автомасштабування локальних worker-процесів навмисно консервативне й зменшує навантаження, - коли середнє навантаження хоста вже високе, тому кілька одночасних + чітко відповідають меншому набору. + - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, + лише з вищою межею кількості працівників. + - Автомасштабування локальних працівників навмисно є консервативним і зменшується, + коли середнє навантаження хоста вже високе, тож кілька одночасних запусків Vitest за замовчуванням завдають менше шкоди. - Базова конфігурація Vitest позначає файли projects/config як - `forceRerunTriggers`, щоб повторні запуски в режимі changed залишалися коректними, коли змінюється схема тестів. + `forceRerunTriggers`, щоб повторні запуски в режимі changed залишалися коректними, коли змінюється + зв’язування тестів. - Конфігурація зберігає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних - хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете + хостах; встановіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете одну явну локацію кешу для прямого профілювання. - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість імпорту, а також - вивід розбивки імпортів. - - `pnpm test:perf:imports:changed` обмежує той самий профільований перегляд + вивід розбивки імпорту. + - `pnpm test:perf:imports:changed` обмежує той самий вигляд профілювання файлами, зміненими від `origin/main`. - - Коли один гарячий тест усе ще витрачає більшість часу на стартові імпорти, - тримайте важкі залежності за вузькою локальною межею `*.runtime.ts` і - мокуйте цю межу безпосередньо, а не deep-import runtime helper-функцій лише + - Коли один гарячий тест усе ще витрачає більшість часу на імпорти під час запуску, + тримайте важкі залежності за вузьким локальним seam `*.runtime.ts` і + мокуйте цей seam безпосередньо, а не deep-import runtime helper лише для того, щоб передати їх через `vi.mock(...)`. - `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований - `test:changed` з нативним шляхом root-project для цього зафіксованого diff і виводить wall time та macOS max RSS. + `test:changed` із native root-project path для цього закоміченого diff і виводить wall time та macOS max RSS. - `pnpm test:perf:changed:bench -- --worktree` виконує benchmark поточного брудного дерева, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і кореневу конфігурацію Vitest. - `pnpm test:perf:profile:main` записує профіль CPU головного потоку для - старту Vitest/Vite і накладних витрат transform. + накладних витрат запуску і трансформації Vitest/Vite. - `pnpm test:perf:profile:runner` записує профілі CPU+heap runner для - unit-набору з вимкненим файловим паралелізмом. + unit-набору з вимкненим паралелізмом файлів. -### Стабільність (Gateway) +### Stability (gateway) - Команда: `pnpm test:stability:gateway` -- Конфігурація: `vitest.gateway.config.ts`, примусово один worker-процес +- Конфігурація: `vitest.gateway.config.ts`, примусово один працівник - Обсяг: - - Запускає реальний loopback Gateway з увімкненою діагностикою за замовчуванням - - Проганяє синтетичне навантаження на повідомлення Gateway, пам’ять і великі payload через шлях діагностичних подій - - Опитує `diagnostics.stability` через WS RPC Gateway - - Охоплює helper-функції збереження пакета діагностики стабільності - - Перевіряє, що recorder залишається обмеженим, синтетичні зразки RSS не перевищують бюджет тиску, а глибина черг на рівні сесій знову зменшується до нуля + - Запускає реальний loopback Gateway з діагностикою, увімкненою за замовчуванням + - Проганяє синтетичне навантаження повідомлень gateway, пам’яті та великих payload через шлях діагностичних подій + - Виконує запити до `diagnostics.stability` через Gateway WS RPC + - Охоплює helper збереження набору діагностики стабільності + - Перевіряє, що recorder залишається обмеженим, синтетичні вибірки RSS лишаються в межах бюджету тиску, а глибина черг для кожної сесії повертається до нуля - Очікування: - Безпечно для CI і без ключів - - Вузька лінія для подальшої перевірки регресій стабільності, а не заміна повного набору Gateway + - Вузька ланка для подальшої роботи над регресіями стабільності, а не заміна повного набору Gateway -### E2E (димовий тест Gateway) +### E2E (gateway smoke) - Команда: `pnpm test:e2e` - Конфігурація: `vitest.e2e.config.ts` -- Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і E2E-тести вбудованих plugin у `extensions/` +- Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і E2E-тести вбудованих Plugins у `extensions/` - Типові параметри runtime: - Використовує Vitest `threads` з `isolate: false`, як і решта репозиторію. - - Використовує адаптивну кількість worker-процесів (CI: до 2, локально: 1 за замовчуванням). - - За замовчуванням працює в тихому режимі, щоб зменшити накладні витрати на консольний I/O. + - Використовує адаптивну кількість працівників (CI: до 2, локально: 1 за замовчуванням). + - За замовчуванням працює в тихому режимі, щоб зменшити накладні витрати на console I/O. - Корисні перевизначення: - - `OPENCLAW_E2E_WORKERS=` щоб примусово встановити кількість worker-процесів (не більше 16). - - `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути докладний консольний вивід. + - `OPENCLAW_E2E_WORKERS=`, щоб примусово задати кількість працівників (не більше 16). + - `OPENCLAW_E2E_VERBOSE=1`, щоб знову ввімкнути докладний вивід у console. - Обсяг: - - Наскрізна поведінка Gateway з кількома екземплярами - - Поверхні WebSocket/HTTP, спарювання вузлів і складніша мережева взаємодія + - End-to-end поведінка gateway з кількома інстансами + - Поверхні WebSocket/HTTP, pairing вузлів і складніша мережева взаємодія - Очікування: - - Запускається в CI (коли це ввімкнено в pipeline) + - Запускається в CI (коли увімкнено в pipeline) - Реальні ключі не потрібні - - Більше рухомих частин, ніж у unit-тестів (може бути повільнішим) + - Більше рухомих частин, ніж у unit-тестах (може бути повільніше) -### E2E: димовий тест бекенду OpenShell +### E2E: smoke для backend OpenShell - Команда: `pnpm test:e2e:openshell` - Файл: `extensions/openshell/src/backend.e2e.test.ts` - Обсяг: - Запускає ізольований Gateway OpenShell на хості через Docker - Створює sandbox із тимчасового локального Dockerfile - - Перевіряє бекенд OpenShell в OpenClaw через реальні `sandbox ssh-config` + SSH exec - - Перевіряє поведінку файлової системи з remote-canonical semantics через міст fs sandbox + - Перевіряє backend OpenShell в OpenClaw через реальні `sandbox ssh-config` + виконання через SSH + - Перевіряє поведінку файлової системи в remote-canonical режимі через sandbox fs bridge - Очікування: - - Лише opt-in; не входить до типового запуску `pnpm test:e2e` - - Потрібен локальний CLI `openshell` і працездатний демон Docker - - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, після чого знищує тестовий Gateway і sandbox + - Лише за запитом; не входить до типового запуску `pnpm test:e2e` + - Потребує локального CLI `openshell` і працездатного Docker daemon + - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує test gateway і sandbox - Корисні перевизначення: - - `OPENCLAW_E2E_OPENSHELL=1` щоб увімкнути тест під час ручного запуску ширшого набору e2e - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` щоб указати нестандартний бінарний файл CLI або wrapper-скрипт + - `OPENCLAW_E2E_OPENSHELL=1`, щоб увімкнути тест під час ручного запуску ширшого набору e2e + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`, щоб указати нестандартний CLI binary або wrapper script ### Live (реальні провайдери + реальні моделі) - Команда: `pnpm test:live` - Конфігурація: `vitest.live.config.ts` -- Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і live-тести вбудованих plugin у `extensions/` +- Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і live-тести вбудованих Plugins у `extensions/` - Типово: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) - Обсяг: - - «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?» + - «Чи цей провайдер/модель справді працює _сьогодні_ з реальними обліковими даними?» - Виявлення змін формату провайдера, особливостей виклику інструментів, проблем автентифікації та поведінки rate limit - Очікування: - - За задумом не є стабільним для CI (реальні мережі, реальні політики провайдерів, квоти, збої) + - За задумом не є стабільним для CI (реальні мережі, реальні політики провайдерів, квоти, відмови) - Коштує грошей / витрачає rate limit - Краще запускати звужені підмножини, а не «все» -- Live-запуски використовують `~/.profile`, щоб підхопити відсутні API-ключі. -- За замовчуванням live-запуски все ще ізолюють `HOME` і копіюють матеріали config/auth у тимчасовий домашній каталог тесту, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. -- Встановлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли свідомо хочете, щоб live-тести використовували ваш реальний домашній каталог. -- `pnpm test:live` тепер за замовчуванням працює в тихішому режимі: він зберігає вивід прогресу `[live] ...`, але приховує додаткове повідомлення про `~/.profile` і приглушує журнали старту Gateway/шум Bonjour. Встановіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете знову бачити повні стартові журнали. -- Ротація API-ключів (залежить від провайдера): встановіть `*_API_KEYS` у форматі з комами/крапками з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або окреме live-перевизначення через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу у відповідь на rate limit. +- Live-запуски використовують `~/.profile`, щоб підхопити відсутні API key. +- За замовчуванням live-запуски все ще ізолюють `HOME` і копіюють матеріали config/auth у тимчасовий test home, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. +- Встановлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли вам навмисно потрібно, щоб live-тести використовували ваш реальний домашній каталог. +- `pnpm test:live` тепер за замовчуванням працює в тихішому режимі: він зберігає вивід прогресу `[live] ...`, але приховує додаткове повідомлення про `~/.profile` і вимикає журнали bootstrap gateway/шум Bonjour. Встановіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете знову бачити повні журнали запуску. +- Ротація API key (залежно від провайдера): встановіть `*_API_KEYS` у форматі через кому/крапку з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або перевизначення для конкретного live-запуску через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу у відповідь на rate limit. - Вивід прогресу/Heartbeat: - - Live-набори тепер виводять рядки прогресу в stderr, щоб було видно, що довгі виклики провайдера активні, навіть коли перехоплення консолі Vitest працює тихо. - - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, щоб рядки прогресу провайдера/Gateway одразу транслювалися під час live-запусків. - - Налаштовуйте Heartbeat для прямої моделі через `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Налаштовуйте Heartbeat для Gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Live-набори тепер виводять рядки прогресу в stderr, тож довгі виклики провайдерів помітно активні, навіть коли захоплення console у Vitest тихе. + - `vitest.live.config.ts` вимикає перехоплення console у Vitest, щоб рядки прогресу провайдера/gateway відразу передавалися під час live-запусків. + - Налаштовуйте Heartbeat для direct-model через `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Налаштовуйте Heartbeat для gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Який набір мені запускати? -Скористайтеся цією таблицею рішень: +Використовуйте цю таблицю рішень: -- Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змінили багато) -- Торкаєтесь мережевої взаємодії Gateway / протоколу WS / спарювання: додайте `pnpm test:e2e` -- Налагоджуєте «мій bot не працює» / збої, специфічні для провайдера / виклик інструментів: запустіть звужений `pnpm test:live` +- Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо ви багато що змінили) +- Торкаєтесь мережевої взаємодії gateway / протоколу WS / pairing: додайте `pnpm test:e2e` +- Налагоджуєте «мій бот не працює» / збої, специфічні для провайдера / виклик інструментів: запускайте звужений `pnpm test:live` -## Live-тести (що торкаються мережі) +## Live-тести (із доступом до мережі) -Для live-матриці моделей, димових тестів бекенду CLI, димових тестів ACP, harness -app-server Codex і всіх live-тестів медіапровайдерів (Deepgram, BytePlus, ComfyUI, image, -music, video, media harness), а також обробки облікових даних для live-запусків, див. -[Тестування — live-набори](/uk/help/testing-live). +Для live-матриці моделей, smoke-тестів CLI backend, smoke-тестів ACP, harness +Codex app-server і всіх live-тестів медіапровайдерів (Deepgram, BytePlus, ComfyUI, image, +music, video, media harness) — а також обробки облікових даних для live-запусків — див. +[Testing — live suites](/uk/help/testing-live). ## Docker-ранери (необов’язкові перевірки «працює в Linux») -Ці Docker-ранери поділяються на дві категорії: +Ці Docker-ранери поділяються на дві групи: -- Ранери live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл ключа профілю всередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог config і workspace (і використовують `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoint — `test:live:models-profiles` і `test:live:gateway-profiles`. -- Docker-live-ранери за замовчуванням мають менше обмеження для димового тесту, щоб повний Docker-прогін залишався практичним: - `test:docker:live-models` за замовчуванням використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а - `test:docker:live-gateway` — `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, +- Ранери live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл профілю-ключа всередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог config і workspace (і використовують `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoint — `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`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` і - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env-змінні, коли - вам явно потрібне більше вичерпне сканування. -- `test:docker:all` один раз збирає Docker-образ live через `test:docker:live-build`, а потім повторно використовує його для двох Docker-ліній live. Він також збирає один спільний образ `scripts/e2e/Dockerfile` через `test:docker:e2e-build` і повторно використовує його для E2E-ранерів контейнерних димових тестів, які перевіряють зібрану програму. -- Ранери контейнерних димових тестів: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:gateway-network`, `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` один раз збирає live Docker-образ через `test:docker:live-build`, а потім повторно використовує його для двох Docker-ланок live. Він також збирає один спільний образ `scripts/e2e/Dockerfile` через `test:docker:e2e-build` і повторно використовує його для smoke-ранерів E2E у контейнерах, які перевіряють зібраний застосунок. +- Container smoke-ранери: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:gateway-network`, `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-моделей також монтують лише потрібні домашні каталоги CLI auth (або всі підтримувані, якщо запуск не звужено), а потім копіюють їх у домашній каталог контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени, не змінюючи сховище auth на хості: +Docker-ранери live-моделей також bind-mount лише потрібні CLI auth home (або всі підтримувані, якщо запуск не звужено), а потім копіюють їх до home контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени без змін у host auth store: -- Прямі моделі: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) -- Димовий тест ACP bind: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) -- Димовий тест бекенду CLI: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) -- Димовий тест harness app-server Codex: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) +- Direct models: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) +- Smoke для ACP bind: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) +- Smoke для CLI backend: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) +- Smoke для harness Codex app-server: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) - Gateway + dev agent: `pnpm test:docker:live-gateway` (скрипт: `scripts/test-live-gateway-models-docker.sh`) -- Live-дімовий тест Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) -- Майстер онбордингу (TTY, повне scaffold): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) -- Димовий тест онбордингу/channel/agent через npm tarball: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює упакований tarball OpenClaw у Docker, налаштовує OpenAI через онбординг env-ref і за замовчуванням Telegram, перевіряє, що ввімкнення plugin встановлює його runtime-залежності за потреби, запускає doctor і виконує один змоканий хід агента OpenAI. Використовуйте вже зібраний tarball повторно через `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть перебудову на хості через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` або змініть channel через `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. -- Димовий тест глобального встановлення Bun: `bash scripts/e2e/bun-global-install-smoke.sh` пакує поточне дерево, встановлює його через `bun install -g` в ізольованому домашньому каталозі та перевіряє, що `openclaw infer image providers --json` повертає вбудовані image-провайдери замість зависання. Використовуйте вже зібраний tarball через `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-дімовий тест інсталятора: `bash scripts/test-install-sh-docker.sh` використовує один спільний кеш npm у своїх контейнерах root, update і direct-npm. Димовий тест оновлення за замовчуванням використовує npm `latest` як стабільний baseline перед оновленням до candidate tarball. Перевірки інсталятора без root зберігають ізольований кеш npm, щоб записи кешу, створені root, не маскували поведінку локальної інсталяції користувача. Встановіть `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати кеш root/update/direct-npm під час локальних повторних запусків. -- Install Smoke CI пропускає дубльований прямий глобальний update npm через `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; запускайте скрипт локально без цього env, коли потрібне покриття прямого `npm install -g`. +- Live smoke Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) +- Майстер онбордингу (TTY, повне scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) +- Smoke для онбордингу/channel/agent через npm tarball: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює запакований tarball OpenClaw у Docker, налаштовує OpenAI через онбординг env-ref плюс Telegram за замовчуванням, перевіряє, що doctor відновлює активовані runtime deps Plugin, і виконує один змоканий хід агента OpenAI. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть перебудову на хості через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` або змініть channel через `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. +- Smoke для глобального встановлення Bun: `bash scripts/e2e/bun-global-install-smoke.sh` пакує поточне дерево, встановлює його через `bun install -g` в ізольованому home і перевіряє, що `openclaw infer image providers --json` повертає вбудованих image-провайдерів замість зависання. Повторно використовуйте попередньо зібраний tarball через `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`. +- Installer Docker smoke: `bash scripts/test-install-sh-docker.sh` використовує спільний npm cache для своїх контейнерів root, update і direct-npm. Smoke оновлення за замовчуванням використовує npm `latest` як стабільну базову версію перед оновленням до tarball кандидата. Перевірки installer без root зберігають ізольований npm cache, щоб записи кешу, створені root, не маскували поведінку локального встановлення користувача. Встановіть `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати root/update/direct-npm cache між локальними повторними запусками. +- CI для Install Smoke пропускає дубльований direct-npm global update через `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; запускайте скрипт локально без цього env, коли потрібне покриття прямого `npm install -g`. - Мережева взаємодія Gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) -- Регресійний тест OpenAI Responses web_search з мінімальним reasoning: `pnpm test:docker:openai-web-search-minimal` (скрипт: `scripts/e2e/openai-web-search-minimal-docker.sh`) запускає змоканий сервер OpenAI через Gateway, перевіряє, що `web_search` підвищує `reasoning.effort` з `minimal` до `low`, потім примусово викликає відмову схеми провайдера й перевіряє, що вихідна деталь з’являється в журналах Gateway. -- Міст channel MCP (seeded Gateway + stdio bridge + сирий димовий тест notification-frame Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) -- Інструменти MCP для комплекту Pi (реальний stdio MCP-сервер + димовий тест дозволу/заборони вбудованого профілю 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 (димовий тест інсталяції + псевдонім `/plugin` + семантика перезапуску комплекту Claude): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) -- Димовий тест незмінного оновлення Plugin: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`) -- Димовий тест метаданих перезавантаження config: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) -- Runtime-залежності вбудованих plugin: `pnpm test:docker:bundled-channel-deps` за замовчуванням збирає невеликий Docker-образ раннера, один раз збирає й пакує OpenClaw на хості, а потім монтує цей tarball у кожен сценарій інсталяції Linux. Повторно використовуйте образ через `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропустіть перебудову на хості після свіжої локальної збірки через `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` або вкажіть наявний tarball через `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. -- Звужуйте runtime-залежності вбудованих plugin під час ітерацій, вимикаючи непов’язані сценарії, наприклад: +- Мінімальна регресія 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`, потім примусово викликає відхилення схеми провайдера і перевіряє, що необроблені деталі з’являються в журналах Gateway. +- Міст каналу MCP (ініціалізований Gateway + stdio bridge + необроблений smoke фрейма сповіщення Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- Інструменти MCP у 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 + завершення дочірнього stdio MCP після ізольованих запусків cron і одноразового subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) +- Plugins (smoke встановлення + alias `/plugin` + семантика перезапуску Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) +- Smoke незмінного оновлення Plugin: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`) +- Smoke метаданих reload config: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) +- Runtime deps вбудованих Plugins: `pnpm test:docker:bundled-channel-deps` за замовчуванням збирає невеликий образ Docker runner, один раз збирає й пакує OpenClaw на хості, а потім монтує цей tarball у кожен сценарій встановлення Linux. Повторно використовуйте образ через `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропустіть перебудову на хості після свіжої локальної збірки через `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` або вкажіть наявний tarball через `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. +- Звужуйте runtime deps вбудованих Plugins під час ітерації, вимикаючи непов’язані сценарії, наприклад: `OPENCLAW_BUNDLED_CHANNEL_SCENARIOS=0 OPENCLAW_BUNDLED_CHANNEL_UPDATE_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_ROOT_OWNED_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_SETUP_ENTRY_SCENARIO=0 pnpm test:docker:bundled-channel-deps`. -Щоб вручну попередньо зібрати й повторно використати спільний образ built-app: +Щоб вручну попередньо зібрати й повторно використовувати спільний образ built-app: ```bash OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e:local pnpm test:docker:e2e-build OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels ``` -Перевизначення образів для конкретних наборів, такі як `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, як і раніше мають пріоритет, якщо вони встановлені. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на віддалений спільний образ, скрипти завантажують його, якщо його ще немає локально. Docker-тести QR та інсталятора зберігають власні Dockerfile, оскільки вони перевіряють поведінку пакування/інсталяції, а не спільний runtime зібраної програми. +Специфічні для набору перевизначення образів, такі як `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, усе ще мають пріоритет, якщо їх задано. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на віддалений спільний образ, скрипти завантажують його, якщо його ще немає локально. Docker-тести QR та installer зберігають власні Dockerfile, оскільки вони перевіряють поведінку пакета/встановлення, а не спільний runtime зібраного застосунку. -Docker-ранери live-моделей також монтують поточний checkout у режимі лише читання і -переносять його до тимчасового workdir усередині контейнера. Це зберігає runtime-образ -компактним, але водночас дає змогу запускати Vitest точно проти вашого локального source/config. -Під час перенесення пропускаються великі локальні кеші та результати збірки програм, такі як -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для програм каталоги `.build` або -результати Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання -машинно-специфічних артефактів. -Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-перевірки Gateway не запускали -реальні worker-процеси channel Telegram/Discord тощо всередині контейнера. +Docker-ранери live-моделей також bind-mount поточний checkout у режимі лише для читання та +розміщують його в тимчасовому workdir усередині контейнера. Це зберігає runtime-образ +легким, але водночас дозволяє запускати Vitest точно проти ваших локальних source/config. +Крок staging пропускає великі локальні кеші та вихідні дані збірки застосунку, такі як +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для застосунку каталоги +`.build` або вивід Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання +артефактів, специфічних для машини. +Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-перевірки gateway не запускали +реальні channel workers Telegram/Discord тощо всередині контейнера. `test:docker:live-models` усе ще запускає `pnpm test:live`, тому також передавайте -`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити live-покриття Gateway у цій Docker-лінії. -`test:docker:openwebui` — це димовий тест сумісності вищого рівня: він запускає -контейнер Gateway OpenClaw з увімкненими HTTP-endpoint, сумісними з OpenAI, -запускає закріплений контейнер Open WebUI проти цього Gateway, виконує вхід через -Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає -реальний запит чату через проксі `/api/chat/completions` Open WebUI. +`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити live-покриття gateway із цієї Docker-ланки. +`test:docker:openwebui` — це smoke-перевірка сумісності вищого рівня: вона запускає +контейнер gateway OpenClaw з увімкненими HTTP-endpoint, сумісними з OpenAI, +запускає закріплений контейнер Open WebUI проти цього gateway, входить через +Open WebUI, перевіряє, що `/api/models` надає `openclaw/default`, а потім надсилає +реальний запит чату через proxy Open WebUI `/api/chat/completions`. Перший запуск може бути помітно повільнішим, оскільки Docker може знадобитися завантажити -образ Open WebUI, а самому Open WebUI — завершити власне холодне початкове налаштування. -Ця лінія очікує придатний ключ live-моделі, а `OPENCLAW_PROFILE_FILE` -(типово `~/.profile`) є основним способом передати його в Docker-запусках. -Успішні запуски друкують невеликий JSON payload на кшталт `{ "ok": true, "model": +образ Open WebUI, а самому Open WebUI — завершити власне cold-start налаштування. +Ця ланка очікує придатний ключ live-моделі, і `OPENCLAW_PROFILE_FILE` +(типово `~/.profile`) — основний спосіб надати його в Dockerized-запусках. +Успішні запуски виводять невеликий JSON payload на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. -`test:docker:mcp-channels` є навмисно детермінованим і не потребує -реального облікового запису Telegram, Discord або iMessage. Він запускає seeded Gateway -у контейнері, запускає другий контейнер, який створює `openclaw mcp serve`, а потім +`test:docker:mcp-channels` навмисно детермінований і не потребує +реального облікового запису Telegram, Discord або iMessage. Він запускає ініціалізований контейнер Gateway, +запускає другий контейнер, який створює `openclaw mcp serve`, а потім перевіряє виявлення маршрутизованих розмов, читання транскриптів, метадані вкладень, -поведінку черги live-подій, маршрутизацію вихідних надсилань і сповіщення у стилі Claude про channel + +поведінку черги live-подій, маршрутизацію вихідного надсилання та сповіщення у стилі Claude про channel + дозволи через реальний stdio MCP bridge. Перевірка сповіщень -безпосередньо аналізує сирі stdio MCP frame, тож цей димовий тест перевіряє те, що -міст реально передає, а не лише те, що випадково показує конкретний SDK клієнта. -`test:docker:pi-bundle-mcp-tools` є детермінованим і не потребує ключа -live-моделі. Він збирає Docker-образ репозиторію, запускає реальний stdio MCP probe server -всередині контейнера, матеріалізує цей сервер через вбудований runtime MCP комплекту Pi, -виконує інструмент, а потім перевіряє, що `coding` і `messaging` зберігають +безпосередньо аналізує необроблені stdio MCP frame, тож smoke-перевірка валідовує те, що +міст фактично випромінює, а не лише те, що випадково показує конкретний client SDK. +`test:docker:pi-bundle-mcp-tools` є детермінованим і не потребує +ключа live-моделі. Він збирає Docker-образ репозиторію, запускає реальний stdio MCP probe server +усередині контейнера, матеріалізує цей сервер через вбудований runtime Pi bundle +MCP, виконує інструмент, а потім перевіряє, що `coding` і `messaging` зберігають інструменти `bundle-mcp`, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` їх відфільтровують. `test:docker:cron-mcp-cleanup` є детермінованим і не потребує ключа live-моделі. -Він запускає seeded Gateway з реальним stdio MCP probe server, виконує +Він запускає ініціалізований Gateway з реальним stdio MCP probe server, виконує ізольований хід cron і одноразовий дочірній хід `/subagents spawn`, а потім перевіряє, що дочірній процес MCP завершується після кожного запуску. -Ручний димовий тест ACP plain-language для тредів (не для CI): +Ручна smoke-перевірка ACP plain-language thread (не для CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для регресійних сценаріїв і налагодження. Він може знову знадобитися для перевірки маршрутизації тредів ACP, тому не видаляйте його. +- Зберігайте цей скрипт для сценаріїв регресії/налагодження. Він може знову знадобитися для валідації маршрутизації ACP thread, тому не видаляйте його. -Корисні змінні середовища: +Корисні 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` для перевірки лише env-змінних, отриманих із `OPENCLAW_PROFILE_FILE`, з використанням тимчасових каталогів config/workspace і без зовнішніх монтувань CLI auth -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих установлень CLI всередині Docker -- Зовнішні каталоги/файли CLI auth у `$HOME` монтуються в режимі лише читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед стартом тестів +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевіряти лише env vars, отримані з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові каталоги config/workspace і без зовнішніх mount для CLI auth +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих встановлень CLI усередині Docker +- Зовнішні каталоги/файли CLI auth у `$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_REQUIRE_PROFILE_KEYS=1` щоб переконатися, що облікові дані надходять зі сховища профілю (а не з env) -- `OPENCLAW_OPENWEBUI_MODEL=...` для вибору моделі, яку Gateway показує для димового тесту Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...` для перевизначення prompt перевірки nonce, який використовує димовий тест Open WebUI -- `OPENWEBUI_IMAGE=...` для перевизначення закріпленого тега образу Open WebUI +- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...`, щоб звузити запуск +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб відфільтрувати провайдерів усередині контейнера +- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використовувати наявний образ `openclaw:local-live` для повторних запусків, яким не потрібна перебудова +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб переконатися, що облікові дані походять зі сховища profile (а не з env) +- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку gateway надає для smoke Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити nonce-check prompt, який використовує smoke Open WebUI +- `OPENWEBUI_IMAGE=...`, щоб перевизначити закріплений тег образу Open WebUI -## Перевірка коректності документації +## Перевірка документації -Після редагування документації запускайте перевірки: `pnpm check:docs`. -Запускайте повну перевірку якорів Mintlify, коли потрібна також перевірка заголовків усередині сторінки: `pnpm docs:check-links:anchors`. +Після редагування документації запускайте перевірки docs: `pnpm check:docs`. +Запускайте повну перевірку anchor у Mintlify, коли вам також потрібна перевірка заголовків усередині сторінки: `pnpm docs:check-links:anchors`. -## Офлайн-регресії (безпечно для CI) +## Офлайнова регресія (безпечна для 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`, примусовий запис config + auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") +- Виклик інструментів Gateway (змоканий OpenAI, реальний цикл gateway + agent): `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 + примусово застосовує auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") -## Оцінювання надійності агентів (Skills) +## Evals надійності агентів (Skills) -У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агентів»: +У нас уже є кілька безпечних для CI тестів, які поводяться як «evals надійності агентів»: -- Mock-виклик інструментів через реальний Gateway + цикл агента (`src/gateway/gateway.test.ts`). -- Наскрізні потоки майстра, які перевіряють wiring сесій та ефекти config (`src/gateway/gateway.test.ts`). +- Моканий виклик інструментів через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). +- Наскрізні потоки майстра, які перевіряють wiring сесії та ефекти config (`src/gateway/gateway.test.ts`). -Що ще бракує для Skills (див. [Skills](/uk/tools/skills)): +Чого ще бракує для Skills (див. [Skills](/uk/tools/skills)): -- **Прийняття рішень:** коли Skills наведено в prompt, чи вибирає агент правильний Skill (або уникає нерелевантних)? -- **Відповідність вимогам:** чи читає агент `SKILL.md` перед використанням і чи виконує потрібні кроки/аргументи? +- **Прийняття рішень:** коли Skills перелічені в prompt, чи вибирає агент правильний Skills (або уникає нерелевантних)? +- **Дотримання вимог:** чи читає агент `SKILL.md` перед використанням і чи виконує потрібні кроки/аргументи? - **Контракти workflow:** багатокрокові сценарії, що перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. -Майбутні оцінювання мають насамперед залишатися детермінованими: +Майбутні evals насамперед мають залишатися детермінованими: -- Runner сценаріїв, що використовує mock-провайдери для перевірки викликів інструментів + їх порядку, читання файлів Skill і wiring сесій. -- Невеликий набір сценаріїв, зосереджених на Skills (використовувати чи уникати, gating, prompt injection). -- Необов’язкові live-оцінювання (opt-in, керовані env) лише після того, як буде готовий безпечний для CI набір. +- Ранер сценаріїв із mock-провайдерами для перевірки викликів інструментів + їхнього порядку, читання skill-файлів і wiring сесії. +- Невеликий набір сценаріїв, зосереджених на Skills (використати чи уникнути, gating, prompt injection). +- Необов’язкові live-evals (opt-in, із gating через env) лише після того, як безпечний для CI набір буде реалізовано. -## Контрактні тести (форма plugin і channel) +## Контрактні тести (форма Plugin і channel) -Контрактні тести перевіряють, що кожен зареєстрований plugin і channel відповідає своєму -контракту інтерфейсу. Вони проходять по всіх знайдених plugin і запускають набір -перевірок форми та поведінки. Типова unit-лінія `pnpm test` навмисно -пропускає ці файли спільних меж і димових тестів; запускайте контрактні команди явно, -коли змінюєте спільні поверхні channel або провайдера. +Контрактні тести перевіряють, що кожен зареєстрований Plugin і channel відповідає своєму +інтерфейсному контракту. Вони проходять по всіх виявлених Plugins і запускають набір +перевірок форми та поведінки. Типова unit-ланка `pnpm test` навмисно +пропускає ці спільні seam- та smoke-файли; запускайте контрактні команди явно, +коли торкаєтеся спільних поверхонь channel або provider. ### Команди - Усі контракти: `pnpm test:contracts` - Лише контракти channel: `pnpm test:contracts:channels` -- Лише контракти провайдерів: `pnpm test:contracts:plugins` +- Лише контракти provider: `pnpm test:contracts:plugins` ### Контракти channel Розташовані в `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - Базова форма plugin (id, name, capabilities) +- **plugin** - Базова форма Plugin (id, name, capabilities) - **setup** - Контракт майстра налаштування - **session-binding** - Поведінка прив’язки сесії - **outbound-payload** - Структура payload повідомлення - **inbound** - Обробка вхідних повідомлень - **actions** - Обробники дій channel -- **threading** - Обробка thread ID -- **directory** - API каталогу/реєстру +- **threading** - Обробка Thread ID +- **directory** - API каталогу/списку учасників - **group-policy** - Застосування групової політики -### Контракти статусу провайдера +### Контракти status провайдера Розташовані в `src/plugins/contracts/*.contract.test.ts`. -- **status** - Перевірки статусу channel -- **registry** - Форма реєстру plugin +- **status** - Перевірки status channel +- **registry** - Форма registry Plugin -### Контракти провайдерів +### Контракти provider Розташовані в `src/plugins/contracts/*.contract.test.ts`: - **auth** - Контракт потоку auth -- **auth-choice** - Вибір/селектор auth +- **auth-choice** - Вибір/підбір auth - **catalog** - API каталогу моделей -- **discovery** - Виявлення plugin -- **loader** - Завантаження plugin +- **discovery** - Виявлення Plugin +- **loader** - Завантаження Plugin - **runtime** - Runtime провайдера -- **shape** - Форма/інтерфейс plugin +- **shape** - Форма/інтерфейс Plugin - **wizard** - Майстер налаштування ### Коли запускати -- Після зміни експортів або subpath у plugin-sdk -- Після додавання або зміни plugin channel чи провайдера -- Після рефакторингу реєстрації plugin або виявлення +- Після зміни експортів або підшляхів plugin-sdk +- Після додавання або зміни channel чи provider Plugin +- Після рефакторингу реєстрації або виявлення Plugin -Контрактні тести запускаються в CI і не потребують реальних API-ключів. +Контрактні тести запускаються в CI і не потребують реальних API key. ## Додавання регресій (рекомендації) -Коли ви виправляєте проблему провайдера/моделі, виявлену в live: +Коли ви виправляєте проблему provider/model, виявлену в live: -- Якщо можливо, додайте безпечну для CI регресію (mock/stub провайдера або захоплення точного перетворення форми запиту) -- Якщо проблема за своєю природою лише live (rate limit, політики auth), залишайте live-тест вузьким і opt-in через env-змінні -- Надавайте перевагу найменшому рівню, який виявляє помилку: - - помилка перетворення/відтворення запиту провайдера → тест прямих моделей - - помилка конвеєра сесії/історії/інструментів Gateway → live-дімовий тест Gateway або безпечний для CI mock-тест Gateway +- Якщо можливо, додайте безпечну для CI регресію (mock/stub провайдер або захопіть точну трансформацію форми запиту) +- Якщо це властиво лише live-середовищу (rate limit, політики auth), залишайте live-тест вузьким і opt-in через env vars +- Віддавайте перевагу найменшому шару, який виявляє баг: + - баг конвертації/повторення запиту провайдера → direct models test + - баг сесії/history/tool pipeline у gateway → smoke для gateway live або безпечний для CI gateway mock test - Захист обходу SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить по одній вибраній цілі на клас SecretRef із метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id сегментів обходу відхиляються. - - Якщо ви додаєте нову сім’ю цілей SecretRef з `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно завершується помилкою для некласифікованих target id, щоб нові класи не можна було непомітно пропустити. + - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль на клас SecretRef з метаданих registry (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id сегментів обходу відхиляються. + - Якщо ви додаєте нову сім’ю цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно завершується з помилкою для некласифікованих target id, щоб нові класи не можна було пропустити непомітно. ## Пов’язане -- [Тестування live](/uk/help/testing-live) +- [Testing live](/uk/help/testing-live) - [CI](/uk/ci)