diff --git a/docs/uk/concepts/qa-e2e-automation.md b/docs/uk/concepts/qa-e2e-automation.md index c34f0ccb5..e06fddf7c 100644 --- a/docs/uk/concepts/qa-e2e-automation.md +++ b/docs/uk/concepts/qa-e2e-automation.md @@ -1,49 +1,49 @@ --- read_when: - Розширення qa-lab або qa-channel - - Додавання QA-сценаріїв із підтримкою репозиторію - - Побудова реалістичнішої автоматизації QA навколо панелі керування Gateway -summary: Приватна форма автоматизації QA для qa-lab, qa-channel, початково заповнених сценаріїв і звітів протоколу + - Додавання QA-сценаріїв, що спираються на репозиторій + - Створення реалістичнішої автоматизації QA навколо панелі керування Gateway +summary: Приватна форма автоматизації QA для qa-lab, qa-channel, сценаріїв із початковими даними та звітів протоколу title: Автоматизація QA E2E x-i18n: - generated_at: "2026-04-26T23:47:39Z" + generated_at: "2026-04-26T23:53:03Z" model: gpt-5.4 provider: openai - source_hash: 654d8333149d98a85373652ce483ab29f3e524df298493d2d3101564f3e01799 + source_hash: 107c0af2635ffa272c6d559ac77cc4b3846a664c92cb1054d37fa73ded119559 source_path: concepts/qa-e2e-automation.md workflow: 15 --- -Приватний стек QA призначений для перевірки OpenClaw у більш реалістичний, +Приватний стек QA призначений для тестування OpenClaw у більш реалістичний, каналоподібний спосіб, ніж це може один модульний тест. Поточні складові: -- `extensions/qa-channel`: синтетичний канал повідомлень із поверхнями для DM, каналів, гілок, +- `extensions/qa-channel`: синтетичний канал повідомлень із поверхнями DM, каналу, треду, реакцій, редагування та видалення. -- `extensions/qa-lab`: UI налагодження та шина QA для спостереження за транскриптом, - інʼєкції вхідних повідомлень і експорту звіту у форматі Markdown. -- `qa/`: assets початкового заповнення з підтримкою репозиторію для стартового завдання та базових QA- - сценаріїв. +- `extensions/qa-lab`: інтерфейс налагодження та шина QA для спостереження за транскриптом, + введення вхідних повідомлень і експорту звіту в Markdown. +- `qa/`: seed-ресурси на основі репозиторію для стартового завдання та базових + QA-сценаріїв. -Поточний потік роботи оператора QA — це двопанельний сайт QA: +Поточний робочий процес оператора QA — це двопанельний сайт QA: - Ліворуч: панель керування Gateway (Control UI) з агентом. -- Праворуч: QA Lab, що показує транскрипт у стилі Slack і план сценарію. +- Праворуч: QA Lab, де показано транскрипт у стилі Slack і план сценарію. -Запустіть це так: +Запустіть це за допомогою: ```bash pnpm qa:lab:up ``` -Це збирає сайт QA, запускає лінію Gateway на базі Docker і відкриває -сторінку QA Lab, де оператор або цикл автоматизації може дати агенту QA- -місію, спостерігати реальну поведінку каналу та фіксувати, що спрацювало, що -не спрацювало або що залишилося заблокованим. +Це збирає сайт QA, запускає доріжку gateway на базі Docker і відкриває +сторінку QA Lab, де оператор або цикл автоматизації може дати агенту QA-місію, +спостерігати реальну поведінку каналу та фіксувати, що спрацювало, що не +спрацювало або що залишилося заблокованим. -Для швидшої ітерації UI QA Lab без повторного збирання образу Docker щоразу, -запустіть стек із QA Lab bundle, змонтованим через bind mount: +Щоб швидше ітерувати UI QA Lab без перебудови Docker-образу щоразу, +запускайте стек зі змонтованим через bind bundle QA Lab: ```bash pnpm openclaw qa docker-build-image @@ -52,136 +52,144 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -`qa:lab:up:fast` утримує сервіси Docker на попередньо зібраному образі та монтує -`extensions/qa-lab/web/dist` у контейнер `qa-lab` через bind mount. `qa:lab:watch` -перезбирає цей bundle при змінах, а браузер автоматично перезавантажується, коли -змінюється хеш asset QA Lab. +`qa:lab:up:fast` залишає сервіси Docker на попередньо зібраному образі та +монтує `extensions/qa-lab/web/dist` у контейнер `qa-lab` через bind-mount. `qa:lab:watch` +перезбирає цей bundle при змінах, а браузер автоматично перезавантажується, +коли змінюється хеш ресурсів QA Lab. -Для локального smoke-тесту трасування OpenTelemetry виконайте: +Для локальної smoke-перевірки трасування OpenTelemetry виконайте: ```bash pnpm qa:otel:smoke ``` Цей скрипт запускає локальний приймач трас OTLP/HTTP, виконує -QA-сценарій `otel-trace-smoke` з увімкненим Plugin `diagnostics-otel`, потім -декодує експортовані protobuf spans і перевіряє критично важливу для релізу форму: +QA-сценарій `otel-trace-smoke` з увімкненим Plugin `diagnostics-otel`, а потім +декодує експортовані protobuf span-и та перевіряє критично важливу для релізу форму: мають бути присутні `openclaw.run`, `openclaw.harness.run`, `openclaw.model.call`, `openclaw.context.assembled` і `openclaw.message.delivery`; -виклики моделі не повинні експортувати `StreamAbandoned` у разі успішних ходів; сирі ID діагностики та -атрибути `openclaw.content.*` не повинні потрапляти в трасу. Він записує -`otel-smoke-summary.json` поруч з artifacts QA suite. +виклики моделі не повинні експортувати `StreamAbandoned` у разі успішних ходів; сирі діагностичні ID і +атрибути `openclaw.content.*` не повинні потрапляти до траси. Він записує +`otel-smoke-summary.json` поруч з артефактами набору QA. -Звичайний агрегат Docker також виконує лінію спостережуваності. Він збирає або -повторно використовує Docker-образ спостережуваності на основі вихідного коду, запускає smoke-тест трасування OTEL -всередині контейнера, а потім виконує QA-сценарій `docker-prometheus-smoke` з -увімкненим Plugin `diagnostics-prometheus`. Установіть +Звичайний агрегований Docker-запуск і базовий chunk для релізного шляху також +виконують доріжку спостережуваності. Вона повторно використовує спільний +функціональний Docker-образ, встановлений як пакет, монтує файли harness QA лише для читання, +виконує smoke-перевірку трасування OTEL усередині контейнера, а потім запускає +QA-сценарій `docker-prometheus-smoke` з увімкненим Plugin `diagnostics-prometheus`. Установіть `OPENCLAW_DOCKER_OBSERVABILITY_LOOPS=`, щоб повторити обидві перевірки в межах одного -запуску Docker зі збереженням artifacts кожного циклу в +Docker-запуску, зберігаючи артефакти кожного циклу в `.artifacts/docker-observability/...`. -Для smoke-лінії Matrix з реальним транспортом виконайте: +Для транспортно-реальної smoke-доріжки Matrix виконайте: ```bash pnpm openclaw qa matrix ``` -Ця лінія розгортає в Docker тимчасовий homeserver Tuwunel, реєструє -тимчасових користувачів driver, SUT і observer, створює одну приватну кімнату, а потім запускає -справжній Plugin Matrix у дочірньому Gateway QA. Лінія живого транспорту тримає -конфігурацію дочірнього процесу обмеженою транспортом, що тестується, тож Matrix запускається без -`qa-channel` у дочірній конфігурації. Вона записує структуровані artifacts звіту та -обʼєднаний журнал stdout/stderr у вибраний вихідний каталог Matrix QA. Щоб -також захопити зовнішній вивід збирання/запуску `scripts/run-node.mjs`, установіть -`OPENCLAW_RUN_NODE_OUTPUT_LOG=` на локальний щодо репозиторію файл журналу. -Поступ Matrix за замовчуванням виводиться в консоль. `OPENCLAW_QA_MATRIX_TIMEOUT_MS` обмежує -повний запуск, а `OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS` обмежує очищення, щоб -зависле завершення Docker повідомляло точну команду відновлення замість зависання. +Ця доріжка розгортає одноразовий homeserver Tuwunel у Docker, реєструє +тимчасових користувачів driver, SUT і observer, створює одну приватну кімнату, +а потім запускає справжній Plugin Matrix усередині дочірнього QA gateway. Доріжка +живого транспорту тримає конфігурацію дочірнього процесу обмеженою тестованим +транспортом, тому Matrix працює без `qa-channel` у конфігурації дочірнього процесу. Вона записує +артефакти структурованого звіту та об’єднаний журнал stdout/stderr у вибраний +вихідний каталог Matrix QA. Щоб також захопити зовнішній вивід побудови/запуску +`scripts/run-node.mjs`, установіть `OPENCLAW_RUN_NODE_OUTPUT_LOG=` на +локальний для репозиторію файл журналу. +Хід Matrix виводиться за замовчуванням. `OPENCLAW_QA_MATRIX_TIMEOUT_MS` +обмежує весь запуск, а `OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS` обмежує очищення, щоб +зависле завершення Docker повідомляло точну команду відновлення замість +зависання. -Для smoke-лінії Telegram з реальним транспортом виконайте: +Для транспортно-реальної smoke-доріжки Telegram виконайте: ```bash pnpm openclaw qa telegram ``` -Ця лінія націлюється на одну реальну приватну групу Telegram замість розгортання -тимчасового сервера. Вона потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, +Ця доріжка націлена на одну реальну приватну групу Telegram замість розгортання +одноразового сервера. Вона вимагає `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, а також двох різних ботів в одній -приватній групі. Бот SUT повинен мати імʼя користувача Telegram, а спостереження бот-до-бота -працює найкраще, коли для обох ботів увімкнено режим Bot-to-Bot Communication Mode -у `@BotFather`. -Команда завершується з ненульовим кодом, якщо будь-який сценарій завершується невдачею. Використовуйте `--allow-failures`, коли -потрібні artifacts без коду завершення з помилкою. -Звіт і підсумок Telegram включають RTT для кожної відповіді — від запиту на +приватній групі. Бот SUT повинен мати ім’я користувача Telegram, а спостереження +бота за ботом працює найкраще, коли для обох ботів увімкнено режим +Bot-to-Bot Communication Mode у `@BotFather`. +Команда завершується з ненульовим кодом, якщо будь-який сценарій завершується +невдачею. Використовуйте `--allow-failures`, якщо вам потрібні артефакти без +коду завершення з помилкою. +Звіт і підсумок Telegram містять RTT для кожної відповіді від запиту на надсилання повідомлення driver до спостережуваної відповіді SUT, починаючи з canary. -Перш ніж використовувати спільні живі облікові дані, виконайте: +Перш ніж використовувати об’єднані живі облікові дані, виконайте: ```bash pnpm openclaw qa credentials doctor ``` -Doctor перевіряє env брокера Convex, валідовує налаштування endpoint і перевіряє -досяжність admin/list, коли присутній секрет супровідника. Він повідомляє лише -статус set/missing для секретів. +Doctor перевіряє env брокера Convex, валідує налаштування endpoint і перевіряє +досяжність admin/list, коли присутній секрет супроводжувача. Він повідомляє лише +про статус set/missing для секретів. -Для smoke-лінії Discord з реальним транспортом виконайте: +Для транспортно-реальної smoke-доріжки Discord виконайте: ```bash pnpm openclaw qa discord ``` -Ця лінія націлюється на один реальний приватний канал guild у Discord із двома ботами: +Ця доріжка націлена на один реальний приватний канал guild у Discord із двома ботами: ботом driver, яким керує harness, і ботом SUT, запущеним дочірнім -Gateway OpenClaw через вбудований Plugin Discord. Вона потребує +OpenClaw gateway через вбудований Plugin Discord. Вона вимагає `OPENCLAW_QA_DISCORD_GUILD_ID`, `OPENCLAW_QA_DISCORD_CHANNEL_ID`, `OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN`, `OPENCLAW_QA_DISCORD_SUT_BOT_TOKEN` -і `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` під час використання облікових даних через env. -Лінія перевіряє обробку згадок каналу та перевіряє, що бот SUT +і `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` під час використання облікових даних з env. +Доріжка перевіряє обробку згадок у каналі та перевіряє, що бот SUT зареєстрував нативну команду `/help` у Discord. -Команда завершується з ненульовим кодом, якщо будь-який сценарій завершується невдачею. Використовуйте `--allow-failures`, коли -потрібні artifacts без коду завершення з помилкою. +Команда завершується з ненульовим кодом, якщо будь-який сценарій завершується +невдачею. Використовуйте `--allow-failures`, якщо вам потрібні артефакти без +коду завершення з помилкою. -Тепер лінії живого транспорту спільно використовують один менший контракт замість того, щоб -кожна вигадувала власну форму списку сценаріїв: +Доріжки живого транспорту тепер спільно використовують один менший контракт, +замість того щоб кожна вигадувала власну форму списку сценаріїв: -`qa-channel` залишається широким синтетичним набором поведінки продукту й не входить -до матриці покриття живого транспорту. +`qa-channel` залишається широким синтетичним набором перевірок поведінки продукту й не є частиною +матриці покриття живого транспорту. -| Лінія | Canary | Контроль згадок | Блокування списком дозволених | Відповідь верхнього рівня | Відновлення після перезапуску | Подальша дія в гілці | Ізоляція гілки | Спостереження реакцій | Команда help | Реєстрація нативної команді | -| -------- | ------ | --------------- | ----------------------------- | ------------------------- | ----------------------------- | -------------------- | -------------- | --------------------- | ------------ | --------------------------- | -| Matrix | x | x | x | x | x | x | x | x | | | -| Telegram | x | x | | | | | | | x | | -| Discord | x | x | | | | | | | | x | +| Доріжка | Canary | Блокування за згадками | Блокування allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальше повідомлення в треді | Ізоляція треду | Спостереження за реакціями | Команда help | Реєстрація нативної команд | +| -------- | ------ | ---------------------- | -------------------- | ------------------------- | ----------------------------- | ----------------------------- | -------------- | -------------------------- | ------------- | -------------------------- | +| Matrix | x | x | x | x | x | x | x | x | | | +| Telegram | x | x | | | | | | | x | | +| Discord | x | x | | | | | | | | x | -Це зберігає `qa-channel` як широкий набір поведінки продукту, тоді як Matrix, -Telegram і майбутні живі транспорти спільно використовують один явний контрольний список транспортного контракту. +Це зберігає `qa-channel` як широкий набір перевірок поведінки продукту, тоді як Matrix, +Telegram і майбутні живі транспорти спільно використовують один явний чекліст +транспортного контракту. -Для лінії з тимчасовою Linux VM без залучення Docker у шлях QA виконайте: +Для доріжки з одноразовою Linux VM без включення Docker у шлях QA виконайте: ```bash pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline ``` -Це завантажує свіжу гостьову систему Multipass, встановлює залежності, збирає OpenClaw -всередині гостьової системи, запускає `qa suite`, а потім копіює звичайний звіт і +Це завантажує нову гостьову VM Multipass, установлює залежності, збирає OpenClaw +усередині гостя, запускає `qa suite`, а потім копіює звичайний звіт і підсумок QA назад у `.artifacts/qa-e2e/...` на хості. -Вона повторно використовує ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. -Запуски suite на хості та в Multipass за замовчуванням виконують кілька вибраних сценаріїв паралельно -з ізольованими Gateway workers. `qa-channel` за замовчуванням використовує concurrency 4, -обмежену кількістю вибраних сценаріїв. Використовуйте `--concurrency `, щоб налаштувати -кількість workers, або `--concurrency 1` для послідовного виконання. -Команда завершується з ненульовим кодом, якщо будь-який сценарій завершується невдачею. Використовуйте `--allow-failures`, коли -потрібні artifacts без коду завершення з помилкою. -Живі запуски передають підтримувані вхідні дані автентифікації QA, які практичні для -гостьової системи: ключі провайдерів через env, шлях до конфігурації живого провайдера QA та -`CODEX_HOME`, якщо присутній. Тримайте `--output-dir` у межах кореня репозиторію, щоб гостьова система -могла записувати назад через змонтований workspace. +Воно повторно використовує ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. +Запуски набору на хості та в Multipass за замовчуванням виконують кілька вибраних +сценаріїв паралельно з ізольованими worker-ами gateway. `qa-channel` за замовчуванням +використовує concurrency 4, обмежену кількістю вибраних сценаріїв. Використовуйте `--concurrency `, щоб налаштувати +кількість worker-ів, або `--concurrency 1` для послідовного виконання. +Команда завершується з ненульовим кодом, якщо будь-який сценарій завершується +невдачею. Використовуйте `--allow-failures`, якщо вам потрібні артефакти без +коду завершення з помилкою. +Живі запуски пересилають підтримувані вхідні дані автентифікації QA, які +практичні для гостя: ключі провайдера на основі env, шлях до конфігурації +живого провайдера QA і `CODEX_HOME`, якщо він присутній. Тримайте `--output-dir` +у межах кореня репозиторію, щоб гість міг записувати назад через змонтований +робочий простір. -## Початкове заповнення з підтримкою репозиторію +## Seed-ресурси на основі репозиторію -Assets початкового заповнення розміщені в `qa/`: +Seed-ресурси розміщені в `qa/`: - `qa/scenarios/index.md` - `qa/scenarios//*.md` @@ -189,81 +197,83 @@ Assets початкового заповнення розміщені в `qa/`: Вони навмисно зберігаються в git, щоб план QA був видимий і людям, і агенту. -`qa-lab` має залишатися загальним виконавцем markdown. Кожен файл сценарію markdown є -джерелом істини для одного тестового запуску та має визначати: +`qa-lab` має залишатися універсальним runner-ом Markdown. Кожен файл сценарію в Markdown — +це джерело істини для одного тестового запуску й повинен визначати: - метадані сценарію -- необовʼязкові метадані категорії, можливостей, лінії та ризику -- посилання на docs і код -- необовʼязкові вимоги до Plugin -- необовʼязковий patch конфігурації Gateway +- необов’язкові метадані категорії, можливостей, доріжки та ризику +- посилання на документацію та код +- необов’язкові вимоги до Plugin +- необов’язковий patch конфігурації gateway - виконуваний `qa-flow` -Багаторазова runtime-поверхня, що підтримує `qa-flow`, може залишатися загальною -і наскрізною. Наприклад, markdown-сценарії можуть поєднувати helper-и на боці транспорту -з helper-ами на боці браузера, які керують вбудованим Control UI через -seam `browser.request` Gateway, без додавання спеціального виконавця. +Багаторазово використовувана поверхня runtime, що стоїть за `qa-flow`, може +залишатися універсальною та наскрізною. Наприклад, Markdown-сценарії можуть +поєднувати допоміжні засоби на боці транспорту з допоміжними засобами на боці браузера, які керують +вбудованим Control UI через seam `browser.request` у Gateway, не додаючи runner +зі спеціальною обробкою. -Файли сценаріїв слід групувати за можливостями продукту, а не за папками дерева -вихідного коду. Зберігайте стабільність ID сценаріїв, коли файли переміщуються; використовуйте `docsRefs` і `codeRefs` -для простежуваності реалізації. +Файли сценаріїв слід групувати за можливостями продукту, а не за папкою +дерева вихідного коду. Зберігайте стабільність ID сценаріїв під час переміщення файлів; використовуйте `docsRefs` і `codeRefs` +для відстежуваності реалізації. Базовий список має залишатися достатньо широким, щоб охоплювати: -- чати в DM і каналах -- поведінку гілок +- чат у DM і каналі +- поведінку тредів - життєвий цикл дій із повідомленнями -- Cron callbacks -- відновлення з памʼяті +- зворотні виклики cron +- відтворення пам’яті - перемикання моделей -- передачу підлеглому агенту -- читання репозиторію та docs -- одне невелике завдання зі збирання, наприклад Lobster Invaders +- передачу підзадач субагенту +- читання репозиторію та документації +- одне невелике завдання збірки, наприклад Lobster Invaders -## Лінії mock провайдерів +## Доріжки mock-провайдерів -`qa suite` має дві локальні лінії mock провайдерів: +`qa suite` має дві локальні доріжки mock-провайдерів: -- `mock-openai` — це сценарійно-орієнтований mock OpenClaw. Він залишається - типовою детермінованою mock-лінією для QA з підтримкою репозиторію та parity gates. -- `aimock` запускає сервер провайдера на базі AIMock для експериментального покриття протоколів, - fixtures, запису/відтворення та chaos. Він є додатковим і не замінює - диспетчер сценаріїв `mock-openai`. +- `mock-openai` — це сценарно-орієнтований mock OpenClaw. Він залишається + типовою детермінованою mock-доріжкою для QA на основі репозиторію та перевірок паритету. +- `aimock` запускає сервер провайдера на базі AIMock для експериментального + покриття протоколів, фікстур, record/replay і chaos. Він є додатковим і не + замінює dispatcher сценаріїв `mock-openai`. -Реалізація лінії провайдера розташована в `extensions/qa-lab/src/providers/`. -Кожен провайдер володіє своїми значеннями за замовчуванням, запуском локального сервера, -конфігурацією моделі Gateway, потребами staging auth-profile та прапорцями можливостей -live/mock. Спільний код suite і Gateway має маршрутизуватися через реєстр провайдерів, -а не розгалужуватися за назвами провайдерів. +Реалізація доріжок провайдерів розміщена в `extensions/qa-lab/src/providers/`. +Кожен провайдер володіє своїми типовими значеннями, запуском локального сервера, +конфігурацією моделі gateway, потребами staging для auth-profile і прапорцями +можливостей live/mock. Спільний код suite і gateway має маршрутизуватися через +реєстр провайдерів, а не розгалужуватися за назвами провайдерів. ## Адаптери транспорту -`qa-lab` володіє загальним seam транспорту для markdown QA-сценаріїв. -`qa-channel` — перший адаптер на цьому seam, але цільовий дизайн ширший: -майбутні реальні або синтетичні канали мають підключатися до того самого виконавця suite -замість додавання специфічного для транспорту виконавця QA. +`qa-lab` володіє універсальним seam транспорту для Markdown-сценаріїв QA. +`qa-channel` — перший адаптер на цьому seam, але ціль дизайну ширша: +майбутні реальні або синтетичні канали мають підключатися до того самого runner-а suite +замість додавання спеціального runner-а QA для конкретного транспорту. На рівні архітектури поділ такий: -- `qa-lab` володіє загальним виконанням сценаріїв, concurrency workers, записом artifacts і звітністю. -- адаптер транспорту володіє конфігурацією Gateway, готовністю, спостереженням за вхідними й вихідними подіями, транспортними діями та нормалізованим станом транспорту. -- markdown-файли сценаріїв у `qa/scenarios/` визначають тестовий запуск; `qa-lab` надає багаторазову runtime-поверхню, яка їх виконує. +- `qa-lab` володіє універсальним виконанням сценаріїв, concurrency worker-ів, записом артефактів і звітністю. +- адаптер транспорту володіє конфігурацією gateway, готовністю, спостереженням за вхідним і вихідним трафіком, діями транспорту та нормалізованим станом транспорту. +- файли сценаріїв Markdown у `qa/scenarios/` визначають тестовий запуск; `qa-lab` надає багаторазово використовувану поверхню runtime, що їх виконує. -Керівництво з упровадження для супровідників нових адаптерів каналів розміщене в -[Тестування](/uk/help/testing#adding-a-channel-to-qa). +Рекомендації для супроводжувачів щодо впровадження нових адаптерів каналів +розміщені в +[Testing](/uk/help/testing#adding-a-channel-to-qa). ## Звітність -`qa-lab` експортує Markdown-звіт протоколу зі спостережуваної часової шкали шини. -Звіт має відповідати на такі запитання: +`qa-lab` експортує звіт протоколу в Markdown зі спостережуваної часової шкали шини. +Звіт має відповідати на такі питання: - Що спрацювало - Що не спрацювало - Що залишилося заблокованим - Які подальші сценарії варто додати -Для перевірок характеру та стилю виконайте той самий сценарій на кількох refs живих моделей -і запишіть оцінений Markdown-звіт: +Для перевірок характеру та стилю запустіть той самий сценарій на кількох live model +refs і запишіть оцінений звіт у Markdown: ```bash pnpm openclaw qa character-eval \ @@ -282,41 +292,42 @@ pnpm openclaw qa character-eval \ --judge-concurrency 16 ``` -Команда запускає локальні дочірні процеси Gateway QA, а не Docker. Сценарії character eval +Команда запускає локальні дочірні процеси QA gateway, а не Docker. Сценарії character eval мають задавати persona через `SOUL.md`, а потім виконувати звичайні ходи користувача, -такі як чат, допомога з workspace і невеликі файлові завдання. Кандидатній моделі +такі як чат, допомога з робочим простором і невеликі файлові завдання. Моделі-кандидату не слід повідомляти, що її оцінюють. Команда зберігає кожен повний транскрипт, записує базову статистику запуску, а потім просить моделі-судді в швидкому режимі з міркуванням `xhigh`, де це підтримується, ранжувати запуски за природністю, вайбом і гумором. -Використовуйте `--blind-judge-models` під час порівняння провайдерів: prompt судді все одно отримує -кожен транскрипт і статус запуску, але refs кандидатів замінюються нейтральними -мітками, такими як `candidate-01`; після парсингу звіт зіставляє ранжування з реальними refs. +Використовуйте `--blind-judge-models` під час порівняння провайдерів: промпт судді все одно отримує +кожен транскрипт і статус запуску, але посилання на кандидатів замінюються нейтральними +мітками, такими як `candidate-01`; звіт зіставляє ранжування з реальними посиланнями після +розбору. -Для запусків кандидатів за замовчуванням використовується thinking `high`, `medium` для GPT-5.5 і `xhigh` -для старіших eval refs OpenAI, які це підтримують. Перевизначайте конкретного кандидата безпосередньо через -`--model provider/model,thinking=`. `--thinking ` як і раніше задає -глобальне резервне значення, а старіша форма `--model-thinking ` збережена +Для запусків кандидатів за замовчуванням використовується мислення `high`, для GPT-5.5 — `medium`, а `xhigh` +— для старіших eval-посилань OpenAI, які це підтримують. Перевизначте конкретного кандидата прямо в рядку через +`--model provider/model,thinking=`. `--thinking ` як і раніше встановлює +глобальне резервне значення, а старіша форма `--model-thinking ` зберігається для сумісності. -Refs кандидатів OpenAI за замовчуванням використовують швидкий режим, щоб застосовувалась пріоритетна обробка там, -де провайдер це підтримує. Додайте `,fast`, `,no-fast` або `,fast=false` безпосередньо, коли -для одного кандидата або судді потрібне перевизначення. Передавайте `--fast` лише тоді, коли -хочете примусово ввімкнути швидкий режим для кожної моделі-кандидата. Тривалість запусків кандидатів і суддів -записується у звіт для аналізу benchmark, але prompts суддів явно вказують +Для посилань кандидатів OpenAI за замовчуванням увімкнено швидкий режим, щоб використовувалася +пріоритетна обробка там, де це підтримується провайдером. Додайте `,fast`, `,no-fast` або `,fast=false` прямо в рядку, коли +окремому кандидату або судді потрібно перевизначення. Передавайте `--fast`, лише якщо хочете +примусово ввімкнути швидкий режим для кожної моделі-кандидата. Тривалість запусків кандидатів і суддів +записується у звіт для аналізу бенчмарків, але в промптах суддів прямо сказано не ранжувати за швидкістю. -І запуски моделей-кандидатів, і запуски моделей-суддів за замовчуванням мають concurrency 16. Зменшуйте -`--concurrency` або `--judge-concurrency`, коли обмеження провайдера або локальне навантаження на Gateway +І для запусків моделей-кандидатів, і для запусків моделей-суддів за замовчуванням використовується concurrency 16. Зменшуйте +`--concurrency` або `--judge-concurrency`, коли ліміти провайдера або навантаження на локальний gateway роблять запуск надто шумним. -Коли не передано жодного кандидата `--model`, character eval за замовчуванням використовує +Якщо не передано жодного `--model` кандидата, для character eval за замовчуванням використовуються `openai/gpt-5.5`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`, `anthropic/claude-sonnet-4-6`, `zai/glm-5.1`, `moonshot/kimi-k2.5` і `google/gemini-3.1-pro-preview`, якщо не передано `--model`. -Коли не передано `--judge-model`, за замовчуванням використовуються судді +Якщо не передано `--judge-model`, за замовчуванням використовуються судді `openai/gpt-5.5,thinking=xhigh,fast` і `anthropic/claude-opus-4-6,thinking=high`. -## Пов’язана документація +## Пов’язані документи -- [Тестування](/uk/help/testing) +- [Testing](/uk/help/testing) - [QA Channel](/uk/channels/qa-channel) -- [Панель керування](/uk/web/dashboard) +- [Dashboard](/uk/web/dashboard) diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index c152ded42..5b68823ba 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -2,14 +2,14 @@ read_when: - Запуск тестів локально або в CI - Додавання регресійних тестів для багів моделей/провайдерів - - Налагодження поведінки Gateway + agent + - Налагодження поведінки Gateway + агента summary: 'Набір для тестування: набори unit/e2e/live, ранери Docker і що охоплює кожен тест' title: Тестування x-i18n: - generated_at: "2026-04-26T23:47:38Z" + generated_at: "2026-04-26T23:53:02Z" model: gpt-5.4 provider: openai - source_hash: 9c423c19712f405d6264f65a42b9b9d270d702b0617bbf79c5ce798cb1e22a93 + source_hash: d6f0046762a11dc771dd39e2a71b32f6b80600edcf3d22d607c72602cdbcd3d6 source_path: help/testing.md workflow: 15 --- @@ -18,7 +18,7 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не ранерів Docker. Цей документ — це посібник «як ми тестуємо»: - Що охоплює кожен набір (і що він навмисно _не_ охоплює). -- Які команди запускати для типових сценаріїв (локально, перед push, налагодження). +- Які команди запускати для типових робочих процесів (локально, перед push, налагодження). - Як live-тести знаходять облікові дані та вибирають моделі/провайдерів. - Як додавати регресійні тести для реальних проблем моделей/провайдерів. @@ -30,9 +30,9 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не - Швидший локальний запуск повного набору на потужній машині: `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 lane на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` Коли ви змінюєте тести або хочете більше впевненості: @@ -43,202 +43,203 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не - Live-набір (моделі + перевірки інструментів/зображень Gateway): `pnpm test:live` - Тихо націлитися на один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -- Docker-прогін live-моделей: `pnpm test:docker:live-models` - - Кожна вибрана модель тепер виконує текстовий хід плюс невелику перевірку у стилі читання файла. - Моделі, чиї метадані оголошують вхід `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 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` і його - викликів за розкладом/релізом. -- Нативний smoke-тест прив’язаного чату Codex: `pnpm test:docker:live-codex-bind` - - Запускає Docker live-лінію проти шляху app-server Codex, прив’язує синтетичний +- Docker live-перевірка моделей: `pnpm test:docker:live-models` + - Кожна вибрана модель тепер запускає текстовий хід, а також невелику перевірку в стилі читання файлу. + Моделі, у чиїх метаданих заявлено вхід `image`, також запускають невеликий хід із зображенням. + Вимкніть додаткові перевірки через `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` або + `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0`, коли ізолюєте збої провайдерів. + - Покриття в CI: щоденний `OpenClaw Scheduled Live And E2E Checks` і ручний + `OpenClaw Release Checks` обидва викликають повторно використовуваний live/E2E workflow з + `include_live_suites: true`, що включає окремі matrix jobs Docker live models, + поділені за провайдером. + - Для цільових повторних запусків у 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` і його + виклики за розкладом/для релізів. +- Native Codex bound-chat smoke: `pnpm test:docker:live-codex-bind` + - Запускає Docker live lane проти шляху app-server Codex, прив’язує синтетичний Slack DM через `/codex bind`, виконує `/codex fast` і - `/codex permissions`, потім перевіряє, що звичайна відповідь і вкладення-зображення - маршрутизуються через нативну прив’язку plugin, а не через ACP. -- Smoke-тест harness app-server Codex: `pnpm test:docker:live-codex-harness` - - Пропускає ходи агента Gateway через harness app-server Codex, що належить plugin, + `/codex permissions`, а потім перевіряє, що звичайна відповідь і вкладення зображення + проходять через native Plugin binding замість ACP. +- Codex app-server harness smoke: `pnpm test:docker:live-codex-harness` + - Запускає ходи агента Gateway через harness app-server Codex, що належить Plugin, перевіряє `/codex status` і `/codex models`, а за замовчуванням також виконує перевірки image, - Cron MCP, sub-agent і Guardian. Вимкніть перевірку sub-agent за допомогою - `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0`, коли ізолюєте інші збої app-server Codex. - Для цільової перевірки sub-agent вимкніть інші перевірки: + cron MCP, sub-agent і Guardian. Вимкніть перевірку sub-agent через + `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0`, коли ізолюєте інші збої + app-server Codex. Для цільової перевірки sub-agent вимкніть інші перевірки: `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, якщо не встановлено + Це завершиться після перевірки sub-agent, якщо не встановлено `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0`. -- Smoke-тест rescue-команди Crestodian: `pnpm test:live:crestodian-rescue-channel` - - Додаткова опційна belt-and-suspenders перевірка поверхні rescue-команд каналу повідомлень. - Вона виконує `/crestodian status`, ставить у чергу постійну - зміну моделі, відповідає `/crestodian yes` і перевіряє шлях запису audit/config. -- Docker smoke-тест планувальника Crestodian: `pnpm test:docker:crestodian-planner` - - Запускає Crestodian у контейнері без конфігурації з підробним Claude CLI у `PATH` - і перевіряє, що нечіткий резервний шлях планувальника перетворюється на - протоколований запис типізованої конфігурації. -- Docker smoke-тест першого запуску Crestodian: `pnpm test:docker:crestodian-first-run` - - Стартує з порожнього каталогу стану OpenClaw, маршрутизує звичайний `openclaw` до - Crestodian, застосовує записи setup/model/agent/Discord plugin + SecretRef, - перевіряє конфігурацію та записи аудиту. Той самий шлях налаштування Ring 0 - також покрито в QA Lab через +- Smoke-тест команди порятунку Crestodian: `pnpm test:live:crestodian-rescue-channel` + - Додаткова перевірка message-channel rescue command, яка вмикається за бажанням. + Вона виконує `/crestodian status`, ставить у чергу постійну зміну + моделі, відповідає `/crestodian yes` і перевіряє шлях запису audit/config. +- Docker smoke тестувальника Crestodian: `pnpm test:docker:crestodian-planner` + - Запускає Crestodian у контейнері без конфігурації з фальшивим Claude CLI у `PATH` + і перевіряє, що нечіткий fallback тестувальника транслюється в audited typed + запис конфігурації. +- Docker smoke першого запуску Crestodian: `pnpm test:docker:crestodian-first-run` + - Починає з порожнього каталогу стану OpenClaw, маршрутизує базовий `openclaw` до + Crestodian, застосовує setup/model/agent/Discord Plugin + записи SecretRef, + валідує конфігурацію та перевіряє записи аудиту. Той самий шлях налаштування Ring 0 + також покривається в QA Lab через `pnpm openclaw qa suite --scenario crestodian-ring-zero-setup`. -- Smoke-тест вартості Moonshot/Kimi: якщо встановлено `MOONSHOT_API_KEY`, виконайте - `openclaw models list --provider moonshot --json`, потім виконайте ізольований +- Smoke перевірка вартості 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`. + проти `moonshot/kimi-k2.6`. Переконайтеся, що JSON показує Moonshot/K2.6, а + transcript асистента зберігає нормалізоване `usage.cost`. -Порада: коли вам потрібен лише один збійний випадок, надавайте перевагу звуженню live-тестів через змінні середовища allowlist, описані нижче. +Порада: коли вам потрібен лише один збійний випадок, віддавайте перевагу звуженню live-тестів через змінні середовища allowlist, описані нижче. -## QA-специфічні ранери +## Спеціалізовані ранери для 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` +запускає ті самі lanes перед схваленням релізу. - `pnpm openclaw qa suite` - - Запускає сценарії QA на базі репозиторію безпосередньо на хості. - - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими - воркерами Gateway. `qa-channel` за замовчуванням має concurrency 4 (обмежено + - Запускає QA-сценарії на основі репозиторію безпосередньо на хості. + - За замовчуванням паралельно запускає кілька вибраних сценаріїв з ізольованими + воркерами Gateway. `qa-channel` за замовчуванням має concurrency 4 (обмежене кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати - кількість воркерів, або `--concurrency 1` для старої послідовної лінії. - - Завершується з ненульовим кодом, якщо будь-який сценарій завершився невдачею. Використовуйте `--allow-failures`, коли - хочете отримати артефакти без коду завершення з помилкою. - - Підтримує режими провайдерів `live-frontier`, `mock-openai` і `aimock`. + кількість воркерів, або `--concurrency 1` для старішого послідовного lane. + - Завершується з ненульовим кодом, якщо будь-який сценарій завершується помилкою. Використовуйте `--allow-failures`, коли + вам потрібні артефакти без коду завершення з помилкою. + - Підтримує режими провайдера `live-frontier`, `mock-openai` і `aimock`. `aimock` запускає локальний сервер провайдера на базі AIMock для експериментального - покриття фікстур і mock-протоколів без заміни сценарно-орієнтованої - лінії `mock-openai`. + покриття fixture і protocol-mock без заміни lane `mock-openai`, + який розуміє сценарії. - `pnpm openclaw qa suite --runner multipass` - - Запускає той самий QA-набір усередині тимчасової Linux VM Multipass. + - Запускає той самий QA-набір усередині одноразової Linux VM Multipass. - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. - Повторно використовує ті самі прапорці вибору провайдера/моделі, що й `qa suite`. - - Live-запуски передають підтримувані вхідні дані авторизації QA, практичні для гостьової системи: - ключі провайдерів через env, шлях до конфігурації live-провайдера QA і `CODEX_HOME`, якщо він присутній. - - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб гостьова система могла записувати назад через - змонтований робочий простір. - - Записує звичайний QA-звіт і підсумок, а також логи Multipass у + - Live-запуски передають у гістьові підтримувані входи автентифікації QA, практичні для такого середовища: + ключі провайдерів через env, шлях до конфігурації live-провайдера QA і `CODEX_HOME`, + якщо він присутній. + - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб гість міг записувати назад через + змонтований workspace. + - Записує звичайний 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, запускає неінтерактивне onboarding з API-ключем OpenAI, за замовчуванням налаштовує Telegram, - перевіряє, що ввімкнення plugin встановлює runtime-залежності на вимогу, - запускає doctor і виконує один локальний хід агента проти mock-endpoint OpenAI. - - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити ту саму лінію - встановлення упакованої версії з Discord. + Docker, запускає неінтерактивне onboarding з OpenAI API key, за замовчуванням налаштовує Telegram, + перевіряє, що ввімкнення Plugin встановлює runtime dependencies на вимогу, + запускає doctor і виконує один локальний хід агента проти змоканого endpoint OpenAI. + - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити той самий lane + встановлення з пакетованого дистрибутива з Discord. - `pnpm test:docker:session-runtime-context` - - Запускає детермінований Docker smoke-тест зібраного застосунку для транскриптів - вбудованого runtime-контексту. Він перевіряє, що прихований runtime-контекст OpenClaw - зберігається як недисплейне кастомне повідомлення замість витоку у видимий хід користувача, - потім створює проблемний зламаний JSONL сеансу та перевіряє, що - `openclaw doctor --fix` переписує його на активну гілку з резервною копією. + - Запускає детермінований smoke-тест built-app у Docker для transcript із вбудованим runtime context. + Він перевіряє, що прихований runtime context OpenClaw зберігається як + недемонстроване custom message, а не протікає у видимий user turn, + потім створює затравку зламаного JSONL сесії та перевіряє, що + `openclaw doctor --fix` переписує його в активну гілку з резервною копією. - `pnpm test:docker:npm-telegram-live` - Встановлює опублікований пакет OpenClaw у Docker, запускає onboarding встановленого пакета, налаштовує Telegram через встановлений CLI, а потім повторно використовує - QA-лінію live Telegram з цим встановленим пакетом як SUT Gateway. + live Telegram QA lane з цим встановленим пакетом як SUT Gateway. - За замовчуванням використовується `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`. - - Використовує ті самі облікові дані Telegram через env або джерело облікових даних Convex, що й - `pnpm openclaw qa telegram`. Для автоматизації CI/release встановіть - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex` разом із - `OPENCLAW_QA_CONVEX_SITE_URL` і секретом ролі. Якщо + - Використовує ті самі env-облікові дані Telegram або джерело облікових даних Convex, що й + `pnpm openclaw qa telegram`. Для автоматизації CI/релізів встановіть + `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`. Вона не запускається при merge. Workflow використовує + `OPENCLAW_QA_CREDENTIAL_ROLE` лише для цього lane. + - GitHub Actions надає цей lane як ручний workflow для супроводжувачів + `NPM Telegram Beta E2E`. Він не запускається під час merge. Workflow використовує середовище `qa-live-shared` і оренду облікових даних Convex CI. - `pnpm test:docker:bundled-channel-deps` - - Пакує та встановлює поточну збірку OpenClaw у Docker, запускає Gateway з налаштованим OpenAI, - потім вмикає вбудовані channel/plugin через редагування конфігурації. - - Перевіряє, що виявлення налаштування залишає runtime-залежності - не налаштованих plugin відсутніми, що перший налаштований запуск Gateway або doctor встановлює - runtime-залежності кожного вбудованого plugin на вимогу, і що другий перезапуск не перевстановлює - залежності, які вже були активовані. + - Пакує та встановлює поточну збірку OpenClaw у Docker, запускає Gateway + з налаштованим OpenAI, а потім вмикає bundled channel/plugins через редагування конфігурації. + - Перевіряє, що виявлення setup залишає runtime dependencies + неконфігурованого Plugin відсутніми, що перший налаштований запуск Gateway або doctor + встановлює runtime dependencies кожного bundled Plugin на вимогу, і що другий restart + не перевстановлює залежності, які вже були активовані. - Також встановлює відомий старіший npm baseline, вмикає Telegram перед запуском - `openclaw update --tag `, і перевіряє, що post-update doctor кандидатної версії - відновлює runtime-залежності вбудованого каналу без відновлення postinstall - з боку harness. + `openclaw update --tag ` і перевіряє, що doctor після оновлення + у кандидата відновлює runtime dependencies bundled channel без + postinstall-відновлення з боку harness. - `pnpm test:parallels:npm-update` - - Запускає нативний smoke-тест оновлення встановленого пакета на гостьових системах Parallels. Кожна - вибрана платформа спочатку встановлює запитаний базовий пакет, потім запускає + - Запускає native smoke оновлення пакетованої інсталяції в гостьових системах Parallels. Кожна + вибрана платформа спочатку встановлює потрібний baseline package, потім виконує встановлену команду `openclaw update` у тій самій гостьовій системі й перевіряє встановлену версію, статус оновлення, готовність gateway і один локальний хід агента. - Використовуйте `--platform macos`, `--platform windows` або `--platform linux` під час - ітерацій над однією гостьовою системою. Використовуйте `--json` для шляху до підсумкового артефакту - і статусу кожної лінії. - - За замовчуванням лінія OpenAI використовує `openai/gpt-5.5` для підтвердження live-ходу агента. + ітерації лише над однією гостьовою системою. Використовуйте `--json` для шляху до артефакту підсумку та + статусу кожного lane. + - За замовчуванням lane OpenAI використовує `openai/gpt-5.5` для доказу живого ходу агента. Передайте `--model ` або встановіть `OPENCLAW_PARALLELS_OPENAI_MODEL`, якщо навмисно перевіряєте іншу модель OpenAI. - - Обгортайте довгі локальні запуски в host timeout, щоб зависання транспорту Parallels - не з’їдало решту вікна тестування: + - Обгортайте тривалі локальні запуски в timeout на хості, щоб збої транспорту Parallels + не забрали решту вікна тестування: ```bash timeout --foreground 150m pnpm test:parallels:npm-update -- --json timeout --foreground 90m pnpm test:parallels:npm-update -- --platform windows --json ``` - - Скрипт записує вкладені логи ліній у `/tmp/openclaw-parallels-npm-update.*`. - Перевіряйте `windows-update.log`, `macos-update.log` або `linux-update.log`, + - Скрипт записує вкладені журнали lane до `/tmp/openclaw-parallels-npm-update.*`. + Перегляньте `windows-update.log`, `macos-update.log` або `linux-update.log`, перш ніж вважати, що зовнішня обгортка зависла. - - Оновлення Windows може витрачати від 10 до 15 хвилин на post-update doctor/відновлення - runtime-залежностей на холодній гостьовій системі; це все ще нормально, якщо вкладений - лог налагодження npm продовжує оновлюватися. - - Не запускайте цю агреговану обгортку паралельно з окремими smoke-лініями Parallels + - Оновлення Windows може витрачати 10–15 хвилин на відновлення post-update doctor/runtime + dependencies на холодній гостьовій системі; це все ще є нормальним станом, якщо вкладений + журнал налагодження npm продовжує оновлюватися. + - Не запускайте цю агреговану обгортку паралельно з окремими smoke lanes Parallels для macOS, Windows або Linux. Вони спільно використовують стан VM і можуть конфліктувати під час - відновлення snapshot, роздачі пакета або стану gateway у гостьовій системі. - - Підтвердження після оновлення виконує звичайну поверхню вбудованих plugin, оскільки - фасади можливостей, такі як мовлення, генерація зображень і - розуміння медіа, завантажуються через вбудовані runtime API, навіть якщо сам + відновлення snapshot, роздачі пакетів або стану guest gateway. + - Доказ після оновлення запускає звичайну поверхню bundled Plugin, оскільки + capability facades, як-от speech, image generation і media + understanding, завантажуються через bundled runtime APIs, навіть якщо сам хід агента перевіряє лише просту текстову відповідь. - `pnpm openclaw qa aimock` - Запускає лише локальний сервер провайдера AIMock для прямого smoke-тестування протоколу. - `pnpm openclaw qa matrix` - - Запускає live-лінію QA Matrix проти тимчасового homeserver Tuwunel на базі Docker. - - Цей QA-хост наразі призначений лише для репозиторію/розробки. Упаковані встановлення OpenClaw не постачають + - Запускає live QA lane Matrix проти одноразового homeserver Tuwunel на базі Docker. + - Цей QA host наразі призначений лише для репозиторію/розробки. Пакетовані інсталяції OpenClaw не постачають `qa-lab`, тож вони не надають `openclaw qa`. - - Checkout репозиторію завантажують вбудований ранер напряму; окремий крок встановлення plugin не потрібен. - - Створює трьох тимчасових користувачів Matrix (`driver`, `sut`, `observer`) і одну приватну кімнату, після чого запускає дочірній QA gateway з реальним plugin Matrix як транспортом SUT. + - Checkout репозиторію завантажують bundled runner безпосередньо; окремий крок встановлення 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/...`. - - За замовчуванням виводить прогрес і застосовує жорсткий timeout запуску через `OPENCLAW_QA_MATRIX_TIMEOUT_MS` (типово 30 хвилин). Очищення обмежується через `OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS`, а в разі збоїв включається команда відновлення `docker compose ... down --remove-orphans`. + - Matrix не надає спільних прапорців джерела облікових даних, оскільки lane локально створює одноразових користувачів. + - Записує QA-звіт Matrix, підсумок, артефакт observed-events і комбінований журнал stdout/stderr у `.artifacts/qa-e2e/...`. + - За замовчуванням виводить прогрес і застосовує жорсткий timeout запуску через `OPENCLAW_QA_MATRIX_TIMEOUT_MS` (за замовчуванням 30 хвилин). Очищення обмежується `OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS`, а в разі збоїв виводиться команда відновлення `docker compose ... down --remove-orphans`. - `pnpm openclaw qa telegram` - - Запускає live-лінію QA Telegram проти реальної приватної групи, використовуючи токени ботів driver і SUT з env. + - Запускає live QA lane Telegram проти реальної приватної групи, використовуючи токени ботів 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`, коли - хочете отримати артефакти без коду завершення з помилкою. + - Підтримує `--credential-source convex` для спільних пулінгових облікових даних. За замовчуванням використовуйте режим env або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути пулінгові lease. + - Завершується з ненульовим кодом, якщо будь-який сценарій завершується помилкою. Використовуйте `--allow-failures`, коли + вам потрібні артефакти без коду завершення з помилкою. - Потребує двох різних ботів в одній приватній групі, причому бот SUT має мати Telegram username. - - Для стабільного спостереження bot-to-bot увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що бот driver може спостерігати трафік ботів у групі. - - Записує звіт QA Telegram, підсумок і артефакт observed-messages у `.artifacts/qa-e2e/...`. Сценарії з відповідями включають RTT від запиту на відправлення driver до спостереженої відповіді SUT. + - Для стабільного спостереження bot-to-bot увімкніть Bot-to-Bot Communication Mode в `@BotFather` для обох ботів і переконайтеся, що бот driver може спостерігати трафік ботів у групі. + - Записує QA-звіт Telegram, підсумок і артефакт observed-messages у `.artifacts/qa-e2e/...`. Сценарії з відповідями включають RTT від запиту на надсилання driver до спостережуваної відповіді SUT. -Live-лінії транспорту мають спільний стандартний контракт, щоб нові транспорти не розходилися в поведінці: +Live transport lanes використовують один стандартний контракт, щоб нові транспорти не відхилялися від нього: -`qa-channel` залишається широким синтетичним QA-набором і не входить до матриці покриття live-транспорту. +`qa-channel` залишається широким синтетичним QA-набором і не є частиною матриці покриття live transport. -| Лінія | Canary | Контроль згадок | Блок allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальша дія в потоці | Ізоляція потоку | Спостереження реакцій | Команда help | -| -------- | ------ | --------------- | -------------- | ------------------------- | ----------------------------- | --------------------- | --------------- | --------------------- | ------------ | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Lane | Canary | Mention gating | Allowlist block | Top-level reply | Restart resume | Thread follow-up | Thread isolation | Reaction observation | Help command | +| -------- | ------ | -------------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ | +| 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 отримує ексклюзивну оренду з пулу на базі Convex, надсилає Heartbeat -цієї оренди під час виконання лінії та звільняє оренду під час завершення роботи. +QA lab отримує ексклюзивну lease із пулу на базі Convex, надсилає Heartbeat +для цієї lease, поки lane працює, і звільняє lease під час завершення роботи. -Еталонний каркас проєкту Convex: +Еталонний scaffold проєкту Convex: - `qa/convex-credential-broker/` @@ -250,24 +251,24 @@ QA lab отримує ексклюзивну оренду з пулу на ба - `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`) Необов’язкові змінні середовища: -- `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 URL Convex через `http://` лише для локальної розробки. +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback `http://` URL Convex лише для локальної розробки. `OPENCLAW_QA_CONVEX_SITE_URL` у звичайному режимі роботи має використовувати `https://`. -Адміністративні команди для мейнтейнерів (додавання/видалення/перелік пулу) потребують +Адміністративні команди супроводжувача (додавання/видалення/список пулу) потребують саме `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. -Допоміжні команди CLI для мейнтейнерів: +Допоміжні CLI-команди для супроводжувачів: ```bash pnpm openclaw qa credentials doctor @@ -277,10 +278,10 @@ pnpm openclaw qa credentials remove --credential-id ``` Використовуйте `doctor` перед live-запусками, щоб перевірити URL сайту Convex, секрети broker, -префікс endpoint, HTTP timeout і доступність admin/list без виведення +prefix endpoint, timeout HTTP і доступність admin/list без виведення секретних значень. Використовуйте `--json` для машиночитаного виводу в скриптах і утилітах 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 }` @@ -298,7 +299,7 @@ pnpm openclaw qa credentials remove --credential-id - `POST /admin/remove` (лише секрет maintainer) - Запит: `{ credentialId, actorId }` - Успіх: `{ status: "ok", changed, credential }` - - Захист активної оренди: `{ status: "error", code: "LEASE_ACTIVE", ... }` + - Захист активної lease: `{ status: "error", code: "LEASE_ACTIVE", ... }` - `POST /admin/list` (лише секрет maintainer) - Запит: `{ kind?, status?, includePayload?, limit? }` - Успіх: `{ status: "ok", credentials, count }` @@ -307,59 +308,59 @@ pnpm openclaw qa credentials remove --credential-id - `{ groupId: string, driverToken: string, sutToken: string }` - `groupId` має бути рядком із числовим Telegram chat id. -- `admin/add` перевіряє цю форму для `kind: "telegram"` і відхиляє некоректний payload. +- `admin/add` перевіряє цю форму для `kind: "telegram"` і відхиляє некоректні payload. ### Додавання каналу до QA Додавання каналу до markdown-системи QA потребує рівно двох речей: -1. Адаптер транспорту для каналу. -2. Пакет сценаріїв, який перевіряє контракт каналу. +1. Transport adapter для каналу. +2. Набір сценаріїв, що перевіряє контракт каналу. -Не додавайте новий кореневий QA-командний простір верхнього рівня, якщо спільний хост `qa-lab` може -керувати цим потоком. +Не додавайте новий кореневий QA-командний простір верхнього рівня, якщо спільний хост `qa-lab` +може керувати цим потоком. `qa-lab` володіє спільною механікою хоста: -- кореневою командою `openclaw qa` +- коренем команди `openclaw qa` - запуском і завершенням набору - concurrency воркерів - записом артефактів - генерацією звітів - виконанням сценаріїв -- сумісними псевдонімами для старіших сценаріїв `qa-channel` +- alias сумісності для старіших сценаріїв `qa-channel` Runner plugins володіють транспортним контрактом: -- як `openclaw qa ` монтується під спільним коренем `qa` -- як налаштовується gateway для цього транспорту -- як перевіряється готовність -- як інжектуються вхідні події -- як спостерігаються вихідні повідомлення -- як відкриваються транскрипти й нормалізований стан транспорту -- як виконуються дії на базі транспорту -- як обробляються специфічні для транспорту скидання чи очищення +- тим, як `openclaw qa ` монтується під спільним коренем `qa` +- тим, як gateway налаштовується для цього транспорту +- тим, як перевіряється готовність +- тим, як інжектуються вхідні події +- тим, як спостерігаються вихідні повідомлення +- тим, як надаються transcript і нормалізований стан транспорту +- тим, як виконуються дії на базі транспорту +- тим, як обробляються transport-specific reset або cleanup Мінімальний поріг впровадження для нового каналу: -1. Залишайте `qa-lab` власником спільного кореня `qa`. -2. Реалізуйте transport runner на спільному хостовому seam `qa-lab`. -3. Тримайте специфічну для транспорту механіку всередині runner plugin або harness каналу. -4. Монтуйте runner як `openclaw qa `, а не реєструйте конкуруючу кореневу команду. +1. Залишити `qa-lab` власником спільного кореня `qa`. +2. Реалізувати transport runner на спільному шві хоста `qa-lab`. +3. Залишити transport-specific mechanics усередині runner Plugin або harness каналу. +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. Використовуйте узагальнені helper для нових сценаріїв. -7. Зберігайте наявні compatibility aliases працездатними, якщо тільки репозиторій не виконує навмисну міграцію. + Тримайте `runtime-api.ts` легким; лінивий CLI і виконання runner мають залишатися за окремими entrypoint. +5. Створювати або адаптувати markdown-сценарії в тематичних каталогах `qa/scenarios/`. +6. Використовувати generic scenario helpers для нових сценаріїв. +7. Зберігати роботу наявних alias сумісності, якщо репозиторій не виконує навмисну міграцію. Правило ухвалення рішення суворе: -- Якщо поведінку можна один раз виразити в `qa-lab`, розміщуйте її в `qa-lab`. -- Якщо поведінка залежить від одного канального транспорту, тримайте її в runner plugin або harness цього plugin. -- Якщо сценарію потрібна нова можливість, яку можуть використовувати більше ніж один канал, додайте узагальнений helper замість специфічної для каналу гілки в `suite.ts`. -- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій специфічним для цього транспорту й явно вказуйте це в контракті сценарію. +- Якщо поведінку можна один раз виразити в `qa-lab`, поміщайте її в `qa-lab`. +- Якщо поведінка залежить від одного транспорту каналу, залишайте її в runner Plugin або harness цього Plugin. +- Якщо сценарію потрібна нова можливість, яку може використати більш ніж один канал, додайте generic helper замість channel-specific branch у `suite.ts`. +- Якщо поведінка має сенс лише для одного транспорту, робіть сценарій transport-specific і явно зазначайте це в контракті сценарію. -Бажані назви узагальнених helper для нових сценаріїв: +Бажані назви generic helper для нових сценаріїв: - `waitForTransportReady` - `waitForChannelReady` @@ -374,7 +375,7 @@ Runner plugins володіють транспортним контрактом: - `formatTransportTranscript` - `resetTransport` -Compatibility aliases залишаються доступними для наявних сценаріїв, зокрема: +Alias сумісності залишаються доступними для наявних сценаріїв, зокрема: - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -382,22 +383,22 @@ Compatibility aliases залишаються доступними для ная - `formatConversationTranscript` - `resetBus` -Нова робота над каналами має використовувати узагальнені назви helper. -Compatibility aliases існують, щоб уникнути міграції одним днем, а не як модель для -авторингу нових сценаріїв. +Нова робота над каналами має використовувати generic helper names. +Alias сумісності існують, щоб уникнути міграції типу flag day, а не як модель для +створення нових сценаріїв. -## Набори тестів (що де запускається) +## Набори тестів (що і де запускається) -Думайте про набори як про «зростаючий реалізм» (і зростаючу нестабільність/вартість): +Сприймайте набори як «зростаючу реалістичність» (і зростаючу нестабільність/вартість): -### Unit / integration (типовий) +### Unit / integration (за замовчуванням) - Команда: `pnpm test` -- Конфігурація: нецільові запуски використовують набір шардів `vitest.full-*.config.ts` і можуть розгортати багатопроєктні шарди в конфігурації окремих проєктів для паралельного планування -- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і whitelist-нуті node-тести `ui`, які покриває `vitest.unit.config.ts` +- Конфігурація: неналаштовані цільово запуски використовують набір шардів `vitest.full-*.config.ts` і можуть розгортати multi-project shards у per-project config для паралельного планування +- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і дозволені node-тести `ui`, що покриваються `vitest.unit.config.ts` - Обсяг: - Чисті unit-тести - - Інтеграційні тести в межах процесу (auth gateway, маршрутизація, tooling, парсинг, конфігурація) + - In-process integration-тести (автентифікація gateway, routing, tooling, parsing, config) - Детерміновані регресії для відомих багів - Очікування: - Запускається в CI @@ -405,192 +406,190 @@ Compatibility aliases існують, щоб уникнути міграції - Має бути швидким і стабільним - + - - Нецільовий `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` як і раніше використовує нативний граф проєктів кореневого `vitest.config.ts`, оскільки цикл спостереження з кількома шардами непрактичний. - - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файлів/каталогів через scoped-лінії, тому `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску кореневого проєкту. - - `pnpm test:changed` за замовчуванням розгортає змінені шляхи git у дешеві scoped-лінії: прямі редагування тестів, сусідні файли `*.test.ts`, явні зіставлення вихідного коду та локальні залежні елементи графа імпорту. Редагування config/setup/package не запускають тести широко, якщо ви явно не використовуєте `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`. - - `pnpm check:changed` — це звичайний розумний локальний контрольний gate для вузьких змін. Він класифікує diff на core, тести core, extensions, тести extension, apps, docs, метадані релізу, live Docker tooling і tooling, а потім запускає відповідні команди typecheck, lint і guard. Він не запускає тести Vitest; для підтвердження тестами викликайте `pnpm test:changed` або явний `pnpm test `. Підняття версій лише в метаданих релізу запускає цільові перевірки version/config/root-dependency з guard, який відхиляє зміни package поза полем версії верхнього рівня. - - Редагування live Docker ACP harness запускають сфокусовані перевірки: синтаксис shell для скриптів авторизації live Docker і dry-run планувальника live Docker. Зміни `package.json` включаються лише тоді, коли diff обмежено `scripts["test:docker:live-*"]`; зміни залежностей, export, версії та інших поверхонь package, як і раніше, використовують ширші guard. - - Легкі щодо імпорту 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/**`. CI додатково розбиває піддерево reply на шарди agent-runner, dispatch і commands/state-routing, щоб один кошик з важким імпортом не контролював увесь довгий хвіст Node. + - Неналаштований цільово `pnpm test` запускає дванадцять менших shard config (`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 graph проєкту `vitest.config.ts`, тому що multi-shard watch loop непрактичний. + - `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: прямі зміни тестів, сусідні файли `*.test.ts`, явні відображення джерел і локальні залежні елементи з import graph. Редагування config/setup/package не запускають широкі тести, якщо ви явно не використовуєте `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`. + - `pnpm check:changed` — це звичайний розумний локальний gate перевірки для вузької роботи. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, metadata релізу, live Docker tooling і tooling, а потім запускає відповідні команди typecheck, lint і guard. Він не запускає тести Vitest; для доказу тестами викликайте `pnpm test:changed` або явний `pnpm test `. Підвищення версії лише в metadata релізу запускають цільові перевірки version/config/root-dependency з guard, який відхиляє зміни package поза полем версії верхнього рівня. + - Редагування live Docker ACP harness запускають цільові перевірки: shell syntax для live Docker auth scripts і dry-run планувальника live Docker. Зміни `package.json` включаються лише коли diff обмежений `scripts["test:docker:live-*"]`; зміни dependencies, export, version та інших поверхонь package і далі використовують ширші guard. + - Unit-тести з легкими import із agents, commands, plugins, helper auto-reply, `plugin-sdk` і подібних чистих utility areas маршрутизуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних lanes. + - Вибрані вихідні helper-файли `plugin-sdk` і `commands` також відображають запуск у режимі changed на явні sibling tests у цих легких lanes, тож редагування helper уникають повторного запуску повного важкого набору для цього каталогу. + - `auto-reply` має виділені buckets для core helper верхнього рівня, integration tests верхнього рівня `reply.*` і піддерева `src/auto-reply/reply/**`. CI додатково розділяє піддерево reply на шарди agent-runner, dispatch і commands/state-routing, щоб один bucket із важкими import не володів усім хвостом Node. - + - - Коли ви змінюєте вхідні дані виявлення message-tool або runtime-контекст Compaction, + - Коли ви змінюєте входи виявлення message-tool або runtime context Compaction, зберігайте обидва рівні покриття. - - Додавайте сфокусовані регресії helper для чистих меж - маршрутизації та нормалізації. - - Підтримуйте інтеграційні набори вбудованого runner у здоровому стані: + - Додавайте цільові helper-regression для чистих меж routing і normalization. + - Підтримуйте integration suites 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-тести + не є достатньою заміною для цих integration paths. - + - - Базова конфігурація Vitest типово використовує `threads`. + - Базова конфігурація Vitest за замовчуванням використовує `threads`. - Спільна конфігурація Vitest фіксує `isolate: false` і використовує - неізольований runner у кореневих проєктах, конфігураціях e2e і live. - - Коренева лінія UI зберігає свій setup і optimizer для `jsdom`, але також працює на + неізольований runner у root project, e2e і live config. + - Root lane UI зберігає свій `jsdom` setup і optimizer, але також працює на спільному неізольованому runner. - - Кожен шард `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` + - Кожен shard `pnpm test` успадковує ті самі значення за замовчуванням `threads` + `isolate: false` зі спільної конфігурації Vitest. - - `scripts/run-vitest.mjs` типово додає `--no-maglev` для дочірніх Node-процесів Vitest, + - `scripts/run-vitest.mjs` за замовчуванням додає `--no-maglev` для дочірніх Node-process Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. - Встановіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти зі стандартною + Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти зі стандартною поведінкою V8. - - `pnpm changed:lanes` показує, які архітектурні лінії запускає diff. - - Pre-commit hook відповідає лише за форматування. Він повторно додає відформатовані файли до staged і + - `pnpm changed:lanes` показує, які архітектурні lanes запускає diff. + - Хук pre-commit виконує лише форматування. Він повторно додає відформатовані файли до staging і не запускає lint, typecheck або тести. - - Явно запускайте `pnpm check:changed` перед передачею або push, коли вам - потрібен розумний локальний контрольний gate. - - `pnpm test:changed` за замовчуванням маршрутизує через дешеві scoped-лінії. Використовуйте + - Явно запускайте `pnpm check:changed` перед передачею роботи або push, коли + вам потрібен розумний локальний gate перевірки. + - `pnpm test:changed` за замовчуванням маршрутизує через дешеві scoped lanes. Використовуйте `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` лише тоді, коли агент вирішує, що редагування harness, config, package або contract справді потребує ширшого покриття Vitest. - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, - лише з вищим лімітом воркерів. - - Автоматичне локальне масштабування воркерів навмисно консервативне й зменшується, + лише з вищою межею кількості воркерів. + - Автомасштабування локальних воркерів навмисно консервативне й зменшує навантаження, коли середнє навантаження хоста вже високе, тож кілька одночасних запусків Vitest за замовчуванням завдають менше шкоди. - - Базова конфігурація Vitest позначає файли проєктів/конфігурацій як - `forceRerunTriggers`, щоб повторні запуски в режимі changed залишалися коректними, коли - змінюється зв’язування тестів. - - Конфігурація зберігає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних - хостах; встановіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете - одне явне розташування кешу для прямого профілювання. + - Базова конфігурація Vitest позначає файли projects/config як + `forceRerunTriggers`, щоб повторні запуски в режимі changed залишалися коректними, коли змінюється wiring тестів. + - Конфігурація тримає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних + хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете + одну явну локацію кешу для прямого профілювання. - - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість імпорту плюс - вивід деталізації імпорту. - - `pnpm test:perf:imports:changed` обмежує той самий вигляд профілювання - файлами, зміненими відносно `origin/main`. - - Дані таймінгів шардів записуються в `.artifacts/vitest-shard-timings.json`. - Запуски цілих конфігурацій використовують шлях конфігурації як ключ; шарди CI за include-pattern - додають ім’я шарда, щоб відфільтровані шарди можна було відстежувати + - `pnpm test:perf:imports` вмикає звітність Vitest про тривалість import плюс + вивід розбивки import. + - `pnpm test:perf:imports:changed` обмежує той самий вигляд профілювання файлами, + зміненими з часу `origin/main`. + - Дані таймінгу shard записуються в `.artifacts/vitest-shard-timings.json`. + Запуски цілої config використовують шлях config як ключ; шарди CI з include-pattern + додають назву shard, щоб відфільтровані shard можна було відстежувати окремо. - - Коли один гарячий тест усе ще витрачає більшість часу на імпорти під час запуску, - тримайте важкі залежності за вузьким локальним seam `*.runtime.ts` і - робіть mock цього seam напряму замість глибокого імпорту helper runtime - лише для того, щоб передати їх через `vi.mock(...)`. + - Коли один гарячий тест усе ще витрачає більшість часу на startup import, + тримайте важкі dependencies за вузьким локальним швом `*.runtime.ts` і + напряму мокайте цей шов замість глибокого import runtime helper лише + для того, щоб передати їх через `vi.mock(...)`. - `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований - `test:changed` з нативним шляхом root-project для цього зафіксованого + `test:changed` із native root-project path для цього закоміченого diff і виводить wall time плюс macOS max RSS. - - `pnpm test:perf:changed:bench -- --worktree` вимірює поточне - брудне дерево, маршрутизуючи список змінених файлів через - `scripts/test-projects.mjs` і кореневу конфігурацію Vitest. - - `pnpm test:perf:profile:main` записує профіль CPU головного потоку для - накладних витрат запуску та трансформації Vitest/Vite. - - `pnpm test:perf:profile:runner` записує профілі CPU+heap runner для + - `pnpm test:perf:changed:bench -- --worktree` вимірює поточне брудне дерево, + маршрутизуючи список змінених файлів через + `scripts/test-projects.mjs` і root config Vitest. + - `pnpm test:perf:profile:main` записує CPU profile головного потоку для + накладних витрат запуску й transform у Vitest/Vite. + - `pnpm test:perf:profile:runner` записує CPU+heap profile runner для unit-набору з вимкненим паралелізмом файлів. -### Стабільність (Gateway) +### Стабільність (gateway) - Команда: `pnpm test:stability:gateway` - Конфігурація: `vitest.gateway.config.ts`, примусово один воркер - Обсяг: - Запускає реальний loopback Gateway з увімкненою діагностикою за замовчуванням - - Пропускає синтетичне навантаження повідомленнями gateway, пам’яттю та великими payload через шлях діагностичних подій + - Проганяє синтетичне навантаження повідомлень gateway, пам’яті та великих payload через шлях діагностичних подій - Запитує `diagnostics.stability` через Gateway WS RPC - - Покриває helper збереження діагностичного пакета стабільності - - Перевіряє, що recorder залишається обмеженим, синтетичні вибірки RSS залишаються нижче бюджету тиску, а глибина черг на сеанс знову зменшується до нуля + - Покриває helper persistence для diagnostic stability bundle + - Перевіряє, що recorder залишається обмеженим, синтетичні зразки RSS залишаються в межах бюджету тиску, а глибини черг на сесію повертаються до нуля - Очікування: - Безпечно для CI і без ключів - - Вузька лінія для подальшої роботи над регресіями стабільності, а не заміна повного набору Gateway + - Вузький lane для подальшого відстеження регресій стабільності, а не заміна повного набору Gateway ### E2E (gateway smoke) - Команда: `pnpm test:e2e` - Конфігурація: `vitest.e2e.config.ts` -- Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і E2E-тести вбудованих plugin у `extensions/` -- Типові параметри runtime: - - Використовує Vitest `threads` з `isolate: false`, як і решта репозиторію. - - Використовує адаптивних воркерів (CI: до 2, локально: типово 1). - - За замовчуванням запускається в silent-режимі, щоб зменшити накладні витрати на консольний I/O. +- Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і bundled-plugin E2E-тести в `extensions/` +- Значення runtime за замовчуванням: + - Використовує `threads` Vitest з `isolate: false`, як і решта репозиторію. + - Використовує адаптивну кількість воркерів (CI: до 2, локально: 1 за замовчуванням). + - За замовчуванням працює в тихому режимі, щоб зменшити накладні витрати на консольний I/O. - Корисні перевизначення: - `OPENCLAW_E2E_WORKERS=`, щоб примусово задати кількість воркерів (обмежено 16). - - `OPENCLAW_E2E_VERBOSE=1`, щоб знову ввімкнути докладний консольний вивід. + - `OPENCLAW_E2E_VERBOSE=1`, щоб знову ввімкнути докладний вивід у консоль. - Обсяг: - - Наскрізна поведінка gateway з кількома інстансами - - Поверхні WebSocket/HTTP, pairing вузлів і важчі мережеві сценарії + - End-to-end-поведінка gateway з кількома інстансами + - Поверхні WebSocket/HTTP, спаровування Node і важче мережеве навантаження - Очікування: - Запускається в CI (коли увімкнено в pipeline) - Реальні ключі не потрібні - - Має більше рухомих частин, ніж unit-тести (може бути повільніше) + - Більше рухомих частин, ніж у unit-тестах (може бути повільніше) ### E2E: smoke OpenShell backend - Команда: `pnpm test:e2e:openshell` - Файл: `extensions/openshell/src/backend.e2e.test.ts` - Обсяг: - - Запускає ізольований Gateway OpenShell на хості через Docker + - Запускає ізольований gateway OpenShell на хості через Docker - Створює sandbox із тимчасового локального Dockerfile - Перевіряє OpenShell backend OpenClaw через реальні `sandbox ssh-config` + виконання SSH - - Перевіряє віддалено-канонічну поведінку файлової системи через fs bridge sandbox + - Перевіряє remote-canonical поведінку файлової системи через sandbox fs bridge - Очікування: - - Лише за запитом; не входить до типового запуску `pnpm test:e2e` - - Потребує локального CLI `openshell` і робочого демона Docker - - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує тестові gateway і sandbox + - Лише за бажанням; не входить до стандартного запуску `pnpm test:e2e` + - Потребує локальний CLI `openshell` і робочий демон Docker + - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує тестовий gateway і sandbox - Корисні перевизначення: - - `OPENCLAW_E2E_OPENSHELL=1`, щоб увімкнути тест під час ручного запуску ширшого набору e2e - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`, щоб вказати нестандартний CLI binary або wrapper script + - `OPENCLAW_E2E_OPENSHELL=1`, щоб увімкнути тест під час ручного запуску ширшого e2e-набору + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`, щоб указати нестандартний бінарний файл CLI або wrapper script ### Live (реальні провайдери + реальні моделі) - Команда: `pnpm test:live` - Конфігурація: `vitest.live.config.ts` -- Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і live-тести вбудованих plugin у `extensions/` -- Типово: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) +- Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і bundled-plugin live-тести в `extensions/` +- За замовчуванням: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) - Обсяг: - «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?» - - Виявлення змін формату провайдера, особливостей виклику інструментів, проблем авторизації та поведінки обмеження швидкості + - Виявлення змін формату провайдера, особливостей виклику інструментів, проблем автентифікації та поведінки rate limit - Очікування: - - Навмисно нестабільні для CI (реальні мережі, реальні політики провайдерів, квоти, збої) - - Коштують грошей / використовують обмеження швидкості - - Краще запускати звужені підмножини замість «усього» -- Live-запуски підвантажують `~/.profile`, щоб отримати відсутні API-ключі. -- За замовчуванням live-запуски все одно ізолюють `HOME` і копіюють матеріали config/auth у тимчасовий тестовий home, щоб 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`; тести повторюють спробу при відповідях з обмеженням швидкості. + - За задумом нестабільно для CI (реальні мережі, реальні політики провайдерів, квоти, відмови) + - Коштує грошей / використовує rate limit + - Краще запускати звужені підмножини, а не «все» +- Live-запуски підключають `~/.profile`, щоб підхопити відсутні API keys. +- За замовчуванням live-запуски все одно ізолюють `HOME` і копіюють config/auth material у тимчасовий test home, щоб unit fixtures не могли змінити ваш реальний `~/.openclaw`. +- Установлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли навмисно хочете, щоб live-тести використовували ваш реальний домашній каталог. +- `pnpm test:live` тепер за замовчуванням використовує тихіший режим: він зберігає вивід прогресу `[live] ...`, але прибирає додаткове повідомлення про `~/.profile` і приглушує журнали bootstrap gateway/шум Bonjour. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні startup-логи. +- Ротація API keys (специфічна для провайдера): установлюйте `*_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-запусків. + - Live-набори тепер виводять рядки прогресу в stderr, тому довгі виклики провайдерів видно як активні навіть тоді, коли захоплення консолі Vitest тихе. + - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, щоб рядки прогресу провайдера/gateway негайно транслювалися під час live-запусків. - Налаштовуйте Heartbeat для direct-model через `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Налаштовуйте Heartbeat для gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Налаштовуйте Heartbeat gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Який набір мені запускати? -Використовуйте цю таблицю рішень: +Скористайтеся цією таблицею рішень: -- Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змінили багато) -- Торкаєтеся мережевої частини gateway / протоколу WS / pairing: додайте `pnpm test:e2e` -- Налагоджуєте «мій бот не працює» / збої, специфічні для провайдера / виклик інструментів: запускайте звужений `pnpm test:live` +- Редагування логіки/тестів: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змінили багато) +- Зміни в мережевій частині gateway / WS protocol / pairing: додайте `pnpm test:e2e` +- Налагодження «мій бот не працює» / збоїв конкретного провайдера / виклику інструментів: запускайте звужений `pnpm test:live` ## Live-тести (що торкаються мережі) -Для live-матриці моделей, smoke-тестів CLI backend, smoke-тестів ACP, harness app-server Codex -і всіх live-тестів медіапровайдерів (Deepgram, BytePlus, ComfyUI, image, +Для live matrix моделей, smoke-тестів backend CLI, smoke-тестів ACP, harness app-server Codex +і всіх live-тестів media-provider (Deepgram, BytePlus, ComfyUI, image, music, video, media harness) — а також обробки облікових даних для live-запусків — див. [Тестування — live-набори](/uk/help/testing-live). @@ -598,224 +597,224 @@ music, video, media harness) — а також обробки облікових Ці ранери 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 і робочий простір (і підвантажуючи `~/.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`, +- Ранери live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл profile-key усередині Docker image репозиторію (`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 vars, коли явно хочете більший вичерпний прогін. -- `test:docker:all` один раз збирає live Docker image через `test:docker:live-build`, один раз пакує OpenClaw як npm tarball через `scripts/package-openclaw-for-docker.mjs`, а потім збирає/повторно використовує два образи `scripts/e2e/Dockerfile`. Базовий образ — це лише Node/Git runner для ліній install/update/plugin-dependency; ці лінії монтують попередньо зібраний tarball. Функціональний образ встановлює той самий tarball у `/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/image та облікових даних. -- Контейнерні smoke-ранери: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:update-channel-switch`, `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` запускають один або більше реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. +- `test:docker:all` один раз збирає live Docker image через `test:docker:live-build`, один раз пакує OpenClaw як npm tarball через `scripts/package-openclaw-for-docker.mjs`, а потім збирає/повторно використовує два image `scripts/e2e/Dockerfile`. Базовий image — це лише раннер Node/Git для lane install/update/plugin-dependency; ці lane монтують попередньо зібраний tarball. Функціональний image встановлює той самий tarball у `/app` для lane функціональності built-app. Визначення Docker lane розташовані в `scripts/lib/docker-e2e-scenarios.mjs`; логіка planner — у `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` виконує вибраний план. Агрегат використовує зважений локальний scheduler: `OPENCLAW_DOCKER_ALL_PARALLELISM` керує слотами process, тоді як ліміти ресурсів не дають усім важким live, npm-install і multi-service lane стартувати одночасно. Значення за замовчуванням — 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 host має більший запас ресурсів. За замовчуванням раннер виконує Docker preflight, видаляє застарілі контейнери OpenClaw E2E, друкує статус кожні 30 секунд, зберігає таймінги успішних lane у `.artifacts/docker-tests/lane-timings.json` і використовує ці таймінги, щоб у наступних запусках стартувати довші lane раніше. Використовуйте `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, щоб вивести зважений маніфест lane без збірки чи запуску Docker, або `node scripts/test-docker-all.mjs --plan-json`, щоб вивести план CI для вибраних lane, потреб package/image і облікових даних. +- Контейнерні smoke-ранери: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:update-channel-switch`, `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` запускають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. -Live-модельні Docker-ранери також bind-mount лише потрібні каталоги авторизації CLI (або всі підтримувані, якщо запуск не звужений), а потім копіюють їх у домашній каталог контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени без змін у сховищі авторизації хоста: +Docker-ранери live-моделей також bind-mount лише потрібні домівки автентифікації CLI (або всі підтримувані, коли запуск не звужений), а потім копіюють їх у домашній каталог контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени без змін у host auth store: -- Прямі моделі: `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`; за замовчуванням охоплює Claude, Codex і Gemini, зі строгим покриттям Droid/OpenCode через `pnpm test:docker:live-acp-bind:droid` і `pnpm test:docker:live-acp-bind:opencode`) -- Smoke-тест CLI backend: `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`) +- Direct models: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) +- ACP bind smoke: `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`) +- CLI backend smoke: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) +- Codex app-server harness smoke: `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`) -- Smoke-тест спостережуваності Docker: включено до `pnpm test:docker:all` і `pnpm test:docker:local:all` (скрипт: `scripts/e2e/docker-observability-smoke.sh`). Він запускає перевірки діагностики OTEL і Prometheus QA-lab усередині Docker-образу на базі вихідного коду. Встановіть `OPENCLAW_DOCKER_OBSERVABILITY_LOOPS=`, щоб повторити обидві перевірки в межах одного запуску контейнера. -- Live smoke-тест Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) -- Майстер onboarding (TTY, повне scaffold): `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 відновлює runtime-залежності активованих plugin, і виконує один mock-хід агента OpenAI. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропускайте host rebuild через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` або перемикайте канал через `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. -- Smoke-тест перемикання каналу оновлення: `pnpm test:docker:update-channel-switch` встановлює запакований tarball OpenClaw глобально в Docker, перемикається з package `stable` на git `dev`, перевіряє, що збережений канал і plugin після оновлення працюють, потім повертається до package `stable` і перевіряє статус оновлення. -- Smoke-тест runtime-контексту сеансу: `pnpm test:docker:session-runtime-context` перевіряє збереження транскрипту прихованого runtime-контексту плюс відновлення doctor для уражених дубльованих гілок prompt-rewrite. -- 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`, пропускайте host build через `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` як стабільний baseline перед оновленням до кандидатного tarball. Локально перевизначайте через `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22` або через вхід `update_baseline_version` workflow Install Smoke на GitHub. Нерутові перевірки installer зберігають ізольований npm cache, щоб записи кешу, що належать root, не маскували поведінку локального встановлення користувача. Встановіть `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати cache root/update/direct-npm між локальними перезапусками. +- Docker observability smoke: входить до `pnpm test:docker:all`, `pnpm test:docker:local:all` і `core`-частини шляху релізу (скрипт: `scripts/e2e/docker-observability-smoke.sh`). Він запускає перевірки діагностики QA-lab OTEL і Prometheus усередині спільного функціонального Docker image зі встановленим package, при цьому лише файли harness QA змонтовані в режимі лише для читання. Установіть `OPENCLAW_DOCKER_OBSERVABILITY_LOOPS=`, щоб повторити обидві перевірки в одному запуску контейнера. +- Open WebUI live smoke: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) +- Wizard onboarding (TTY, повне scaffold): `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 відновлює runtime dependencies активованого Plugin, і запускає один змоканий хід агента OpenAI. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть host rebuild через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` або змініть канал через `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. +- Smoke перемикання каналу оновлення: `pnpm test:docker:update-channel-switch` глобально встановлює запакований tarball OpenClaw у Docker, перемикається з package `stable` на git `dev`, перевіряє, що збережений канал і Plugin після оновлення працюють, потім перемикається назад на package `stable` і перевіряє статус оновлення. +- Smoke session runtime context: `pnpm test:docker:session-runtime-context` перевіряє збереження transcript прихованого runtime context плюс відновлення через 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`, пропустіть host build через `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` або скопіюйте `dist/` із зібраного Docker image через `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` як стабільний baseline перед оновленням до candidate tarball. Перевизначайте локально через `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22` або через вхід `update_baseline_version` workflow Install Smoke на GitHub. Перевірки installer без root зберігають ізольований npm cache, щоб записи 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`. -- CLI smoke-тест видалення спільного робочого простору агентів: `pnpm test:docker:agents-delete-shared-workspace` (скрипт: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) за замовчуванням збирає image кореневого Dockerfile, створює два агенти з одним робочим простором в ізольованому home контейнера, запускає `agents delete --json` і перевіряє коректний JSON та поведінку зі збереженим робочим простором. Повторно використовуйте image install-smoke через `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-тест знімка Browser CDP: `pnpm test:docker:browser-cdp-snapshot` (скрипт: `scripts/e2e/browser-cdp-snapshot-docker.sh`) збирає source E2E image плюс шар Chromium, запускає Chromium із сирим CDP, виконує `browser doctor --deep` і перевіряє, що знімки ролей CDP охоплюють URL посилань, clickables, підняті курсором, посилання iframe і метадані frame. -- Регресія мінімального reasoning для OpenAI Responses `web_search`: `pnpm test:docker:openai-web-search-minimal` (скрипт: `scripts/e2e/openai-web-search-minimal-docker.sh`) запускає mock-сервер OpenAI через Gateway, перевіряє, що `web_search` підвищує `reasoning.effort` з `minimal` до `low`, потім примусово викликає відхилення схеми провайдера і перевіряє, що сирі деталі з’являються в логах Gateway. -- Міст каналу MCP (попередньо ініціалізований Gateway + stdio-міст + raw smoke-тест notification-frame Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) -- Інструменти MCP пакета Pi (реальний stdio MCP server + smoke-тест allow/deny вбудованого профілю Pi): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) -- Очищення Cron/subagent MCP (реальний Gateway + teardown дочірнього stdio MCP після ізольованих запусків cron і одноразового subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) -- Plugins (smoke-тест встановлення, встановлення/видалення ClawHub, оновлення marketplace і увімкнення/перевірка пакета Claude): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) - Встановіть `OPENCLAW_PLUGINS_E2E_CLAWHUB=0`, щоб пропустити live-блок ClawHub, або перевизначайте типовий package через `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` і `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID`. -- Smoke-тест незмінного оновлення Plugin: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`) -- Smoke-тест метаданих перезавантаження config: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) -- Runtime-залежності вбудованих plugin: `pnpm test:docker:bundled-channel-deps` за замовчуванням збирає малий Docker runner image, один раз збирає й пакує OpenClaw на хості, а потім монтує цей tarball у кожен сценарій встановлення Linux. Повторно використовуйте image через `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропускайте host rebuild після свіжого локального build через `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` або вказуйте на наявний tarball через `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. Повний Docker-агрегатор один раз попередньо пакує цей tarball, а потім розбиває перевірки bundled channel на незалежні лінії, зокрема окремі лінії оновлення для Telegram, Discord, Slack, Feishu, memory-lancedb і ACPX. Використовуйте `OPENCLAW_BUNDLED_CHANNELS=telegram,slack`, щоб звузити матрицю каналів під час прямого запуску bundled-лінії, або `OPENCLAW_BUNDLED_CHANNEL_UPDATE_TARGETS=telegram,acpx`, щоб звузити сценарій оновлення. Лінія також перевіряє, що `channels..enabled=false` і `plugins.entries..enabled=false` пригнічують відновлення runtime-залежностей doctor. -- Звужуйте runtime-залежності вбудованих plugin під час ітерацій, вимикаючи не пов’язані сценарії, наприклад: +- CLI smoke видалення agents зі спільним workspace: `pnpm test:docker:agents-delete-shared-workspace` (скрипт: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) за замовчуванням збирає image root Dockerfile, створює два агенти з одним workspace в ізольованому home контейнера, запускає `agents delete --json` і перевіряє коректний JSON та поведінку збереження workspace. Повторно використовуйте image install-smoke через `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 image плюс шар Chromium, запускає Chromium із сирим CDP, виконує `browser doctor --deep` і перевіряє, що snapshot ролей CDP покривають URL посилань, клікабельні елементи, підняті курсором, посилання 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`, потім примусово викликає відхилення схеми провайдера і перевіряє, що сирі деталі з’являються в журналах Gateway. +- MCP channel bridge (ініціалізований Gateway + міст stdio + raw smoke notification-frame Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- Інструменти MCP у bundle Pi (реальний сервер stdio MCP + embedded 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, оновлення marketplace і ввімкнення/перевірка bundle Claude): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) + Установіть `OPENCLAW_PLUGINS_E2E_CLAWHUB=0`, щоб пропустити live-блок ClawHub, або перевизначте package за замовчуванням через `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` і `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID`. +- Smoke незмінного оновлення Plugin: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`) +- Smoke metadata перезавантаження config: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) +- Runtime dependencies bundled Plugin: `pnpm test:docker:bundled-channel-deps` за замовчуванням збирає невеликий Docker runner image, один раз збирає й пакує OpenClaw на host, а потім монтує цей tarball у кожен сценарій Linux install. Повторно використовуйте image через `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропустіть host rebuild після свіжої локальної збірки через `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` або вкажіть наявний tarball через `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. Повний агрегат Docker попередньо пакує цей tarball один раз, а потім розбиває перевірки bundled channel на незалежні lane, включно з окремими lane оновлення для Telegram, Discord, Slack, Feishu, memory-lancedb і ACPX. Використовуйте `OPENCLAW_BUNDLED_CHANNELS=telegram,slack`, щоб звузити матрицю каналів під час прямого запуску bundled lane, або `OPENCLAW_BUNDLED_CHANNEL_UPDATE_TARGETS=telegram,acpx`, щоб звузити сценарій оновлення. Lane також перевіряє, що `channels..enabled=false` і `plugins.entries..enabled=false` пригнічують відновлення doctor/runtime-dependency. +- Звужуйте runtime dependencies bundled Plugin під час ітерації, вимикаючи не пов’язані сценарії, наприклад: `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`. -Щоб вручну попередньо зібрати і повторно використовувати спільний функціональний image: +Щоб вручну попередньо зібрати й повторно використовувати спільний функціональний image: ```bash OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local pnpm test:docker:e2e-build OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels ``` -Перевизначення image, специфічні для набору, як-от `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, усе ще мають пріоритет, якщо встановлені. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на віддалений спільний image, скрипти завантажують його, якщо його ще немає локально. Docker-тести QR та installer зберігають власні Dockerfile, оскільки вони перевіряють поведінку package/install, а не спільний runtime зібраного застосунку. +Перевизначення image для конкретного набору, як-от `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, і далі мають пріоритет, якщо їх установлено. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на віддалений спільний image, скрипти завантажують його, якщо його ще немає локально. Docker-тести QR і installer зберігають власні Dockerfile, тому що вони перевіряють поведінку package/install, а не спільний runtime built-app. -Live-модельні Docker-ранери також bind-mount поточний checkout лише для читання і -розгортають його в тимчасовий workdir усередині контейнера. Це зберігає runtime +Docker-ранери live-моделей також bind-mount поточний checkout у режимі лише читання і +переміщують його в тимчасовий workdir усередині контейнера. Це зберігає runtime image компактним, водночас дозволяючи запускати Vitest точно проти вашого локального source/config. -Крок staging пропускає великі локальні кеші та результати збірки застосунку, такі як -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для застосунку каталоги `.build` або -Gradle output, щоб live-запуски Docker не витрачали хвилини на копіювання -машинно-специфічних артефактів. -Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-перевірки gateway не запускали +Крок підготовки пропускає великі локальні кеші та результати збірки застосунків, як-от +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для застосунків каталоги `.build` або +виводу Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання +артефактів, специфічних для машини. +Вони також установлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probe gateway не запускали реальні воркери каналів Telegram/Discord тощо всередині контейнера. `test:docker:live-models` усе ще запускає `pnpm test:live`, тож також передавайте -`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити gateway -live-покриття з цієї Docker-лінії. -`test:docker:openwebui` — це smoke-тест сумісності вищого рівня: він запускає -контейнер gateway OpenClaw з увімкненими OpenAI-сумісними HTTP endpoint, -запускає зафіксований контейнер Open WebUI проти цього gateway, входить через -Open WebUI, перевіряє, що `/api/models` надає `openclaw/default`, а потім надсилає -реальний чат-запит через проксі `/api/chat/completions` Open WebUI. -Перший запуск може бути помітно повільнішим, оскільки Docker може знадобитися завантажити -image Open WebUI, а самому Open WebUI може знадобитися завершити власне налаштування холодного старту. -Ця лінія очікує придатний ключ live-моделі, а `OPENCLAW_PROFILE_FILE` -(типово `~/.profile`) — це основний спосіб надати його в Docker-запусках. +`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити покриття gateway +live з цього Docker lane. +`test:docker:openwebui` — це smoke сумісності вищого рівня: він запускає +контейнер gateway OpenClaw з увімкненими HTTP endpoint, сумісними з OpenAI, +запускає закріплений контейнер Open WebUI проти цього gateway, виконує вхід через +Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає +реальний chat-запит через proxy `/api/chat/completions` Open WebUI. +Перший запуск може бути помітно повільнішим, тому що Docker може знадобитися завантажити +image Open WebUI, а самому Open WebUI може знадобитися завершити власне cold-start налаштування. +Цей lane очікує придатний ключ live-моделі, а `OPENCLAW_PROFILE_FILE` +(`~/.profile` за замовчуванням) — основний спосіб надати його в Dockerized-запусках. Успішні запуски друкують невеликий JSON payload на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. `test:docker:mcp-channels` навмисно детермінований і не потребує -реального облікового запису Telegram, Discord чи iMessage. Він запускає заздалегідь ініціалізований контейнер -Gateway, запускає другий контейнер, який породжує `openclaw mcp serve`, а потім -перевіряє виявлення маршрутизованих розмов, читання транскриптів, метадані вкладень, -поведінку черги live-подій, маршрутизацію надсилання назовні та сповіщення у стилі Claude про канал + -дозволи через реальний stdio MCP bridge. Перевірка сповіщень -безпосередньо аналізує сирі stdio MCP frame, тож smoke-тест підтверджує, що міст -справді надсилає, а не лише те, що випадково показує конкретний SDK клієнта. -`test:docker:pi-bundle-mcp-tools` детермінований і не потребує -ключа live-моделі. Він збирає Docker image репозиторію, запускає реальний stdio MCP probe server -всередині контейнера, матеріалізує цей server через вбудований runtime -MCP пакета Pi, виконує інструмент, а потім перевіряє, що `coding` і `messaging` зберігають +реального облікового запису Telegram, Discord чи iMessage. Він запускає підготовлений контейнер +Gateway, запускає другий контейнер, який стартує `openclaw mcp serve`, а потім +перевіряє виявлення маршрутизованих розмов, читання transcript, метадані вкладень, +поведінку черги live-подій, маршрутизацію вихідного надсилання, а також channel + +permission notifications у стилі Claude через реальний міст stdio MCP. Перевірка notification +безпосередньо аналізує сирі кадри stdio MCP, тож smoke перевіряє те, що +міст реально надсилає, а не лише те, що випадково показує конкретний SDK клієнта. +`test:docker:pi-bundle-mcp-tools` є детермінованим і не потребує ключа live-моделі. +Він збирає Docker image репозиторію, запускає реальний probe server stdio MCP +усередині контейнера, матеріалізує цей сервер через embedded runtime MCP bundle Pi, +виконує інструмент, а потім перевіряє, що `coding` і `messaging` зберігають інструменти `bundle-mcp`, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` їх відфільтровують. -`test:docker:cron-mcp-cleanup` детермінований і не потребує ключа live-моделі. -Він запускає заздалегідь ініціалізований Gateway з реальним stdio MCP probe server, виконує +`test:docker:cron-mcp-cleanup` є детермінованим і не потребує ключа live-моделі. +Він запускає підготовлений Gateway із реальним probe server stdio MCP, виконує ізольований хід cron і одноразовий дочірній хід `/subagents spawn`, а потім перевіряє, що дочірній процес MCP завершується після кожного запуску. -Ручний smoke-тест ACP plain-language для потоку (не CI): +Ручний smoke plain-language thread для ACP (не CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для workflow регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації потоків ACP, тож не видаляйте його. +- Зберігайте цей скрипт для workflow регресій/налагодження. Він може знову знадобитися для перевірки маршрутизації 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`, щоб перевіряти лише env vars, підвантажені з `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_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому на кшталт `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` +- `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 vars, підключені з `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_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`, щоб повторно використовувати наявний image `openclaw:local-live` для повторних запусків, яким не потрібне нове збирання -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб гарантувати, що облікові дані походять зі сховища профілю (а не з env) -- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку gateway надає для smoke Open WebUI +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб фільтрувати провайдерів усередині контейнера +- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використовувати наявний image `openclaw:local-live` для повторних запусків, яким не потрібна повторна збірка +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб переконатися, що облікові дані беруться зі сховища profile (а не з env) +- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку gateway показує для smoke Open WebUI - `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити prompt перевірки nonce, який використовує smoke Open WebUI -- `OPENWEBUI_IMAGE=...`, щоб перевизначити тег зафіксованого image Open WebUI +- `OPENWEBUI_IMAGE=...`, щоб перевизначити закріплений тег image Open WebUI ## Перевірка документації Після редагування документації запускайте перевірки docs: `pnpm check:docs`. -Запускайте повну перевірку anchor у Mintlify, коли вам також потрібні перевірки заголовків у межах сторінки: `pnpm docs:check-links:anchors`. +Запускайте повну перевірку якорів Mintlify, коли вам також потрібні перевірки заголовків у межах сторінки: `pnpm docs:check-links:anchors`. ## Офлайн-регресія (безпечно для CI) Це регресії «реального pipeline» без реальних провайдерів: -- Виклик інструментів Gateway (mock 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 enforced): `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") +- Wizard Gateway (WS `wizard.start`/`wizard.next`, записує config + примусово застосовує auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") -## Оцінювання надійності agent (Skills) +## Evals надійності агента (Skills) -У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності agent»: +У нас уже є кілька безпечних для CI тестів, що поводяться як «evals надійності агента»: -- Mock-виклик інструментів через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). -- Наскрізні потоки майстра, які перевіряють session wiring і ефекти config (`src/gateway/gateway.test.ts`). +- Змоканий виклик інструментів через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). +- End-to-end-потоки wizard, які перевіряють session wiring і ефекти config (`src/gateway/gateway.test.ts`). -Чого ще бракує для Skills (див. [Skills](/uk/tools/skills)): +Чого все ще бракує для Skills (див. [Skills](/uk/tools/skills)): -- **Ухвалення рішень:** коли Skills перелічено в prompt, чи вибирає agent правильний Skill (або уникає нерелевантних)? -- **Дотримання:** чи читає agent `SKILL.md` перед використанням і чи виконує обов’язкові кроки/аргументи? -- **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. +- **Decisioning:** коли Skills перелічено в prompt, чи вибирає агент правильний Skill (або уникає нерелевантних)? +- **Compliance:** чи читає агент `SKILL.md` перед використанням і чи дотримується потрібних кроків/args? +- **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок інструментів, перенесення історії session і межі sandbox. -Майбутні evals мають спочатку залишатися детермінованими: +Майбутні evals мають передусім залишатися детермінованими: -- Runner сценаріїв з mock-провайдерами для перевірки викликів інструментів + їх порядку, читання файлів skill і wiring сесії. -- Невеликий набір сценаріїв, зосереджених на Skills (використати чи уникнути, gating, prompt injection). -- Необов’язкові live-eval (opt-in, з керуванням через env) лише після того, як буде готовий безпечний для CI набір. +- Сценарний раннер із mock-провайдерами для перевірки викликів інструментів + їх порядку, читання файлів Skill і wiring session. +- Невеликий набір сценаріїв, орієнтованих на Skills (використати чи уникнути, gating, prompt injection). +- Необов’язкові live evals (opt-in, із gating через env) лише після того, як буде готовий безпечний для CI набір. -## Контрактні тести (форма plugin і channel) +## Контрактні тести (форма Plugin і каналу) -Контрактні тести перевіряють, що кожен зареєстрований plugin і channel відповідає своєму -контракту інтерфейсу. Вони ітерують усі виявлені plugins і запускають набір -перевірок форми та поведінки. Типова unit-лінія `pnpm test` навмисно -пропускає ці спільні seam- і smoke-файли; явно запускайте -контрактні команди, коли змінюєте спільні поверхні channel або provider. +Контрактні тести перевіряють, що кожен зареєстрований Plugin і канал відповідає своєму +контракту інтерфейсу. Вони проходять по всіх виявлених Plugin і запускають набір +перевірок форми та поведінки. Unit lane за замовчуванням у `pnpm test` навмисно +пропускає ці спільні seam- і smoke-файли; запускайте команди контрактів явно, +коли змінюєте спільні поверхні каналу або провайдера. ### Команди - Усі контракти: `pnpm test:contracts` -- Лише контракти channel: `pnpm test:contracts:channels` -- Лише контракти provider: `pnpm test:contracts:plugins` +- Лише контракти каналів: `pnpm test:contracts:channels` +- Лише контракти провайдерів: `pnpm test:contracts:plugins` -### Контракти channel +### Контракти каналів Розташовані в `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - Базова форма plugin (id, name, capabilities) -- **setup** - Контракт майстра налаштування -- **session-binding** - Поведінка прив’язки сесії +- **plugin** - Базова форма Plugin (id, name, capabilities) +- **setup** - Контракт wizard налаштування +- **session-binding** - Поведінка прив’язки session - **outbound-payload** - Структура payload повідомлення - **inbound** - Обробка вхідних повідомлень -- **actions** - Обробники дій channel -- **threading** - Обробка ID потоку -- **directory** - API каталогу/реєстру -- **group-policy** - Застосування групової політики +- **actions** - Обробники дій каналу +- **threading** - Обробка ID thread +- **directory** - API directory/roster +- **group-policy** - Застосування group policy -### Контракти статусу provider +### Контракти статусу провайдера Розташовані в `src/plugins/contracts/*.contract.test.ts`. -- **status** - Перевірки статусу channel -- **registry** - Форма реєстру plugin +- **status** - Перевірки статусу каналу +- **registry** - Форма реєстру Plugin -### Контракти provider +### Контракти провайдерів Розташовані в `src/plugins/contracts/*.contract.test.ts`: - **auth** - Контракт потоку auth - **auth-choice** - Вибір/селекція auth - **catalog** - API каталогу моделей -- **discovery** - Виявлення plugin -- **loader** - Завантаження plugin -- **runtime** - Runtime provider -- **shape** - Форма/інтерфейс plugin -- **wizard** - Майстер налаштування +- **discovery** - Виявлення Plugin +- **loader** - Завантаження Plugin +- **runtime** - Runtime провайдера +- **shape** - Форма/інтерфейс Plugin +- **wizard** - Wizard налаштування ### Коли запускати - Після зміни export або subpath у plugin-sdk -- Після додавання або зміни channel чи provider plugin -- Після рефакторингу реєстрації або виявлення plugin +- Після додавання або зміни Plugin каналу чи провайдера +- Після рефакторингу реєстрації або виявлення Plugin -Контрактні тести запускаються в CI й не потребують реальних API-ключів. +Контрактні тести запускаються в CI і не потребують реальних API keys. ## Додавання регресій (рекомендації) -Коли ви виправляєте проблему provider/model, виявлену в live: +Коли ви виправляєте проблему провайдера/моделі, виявлену в live: -- Додавайте безпечну для CI регресію, якщо це можливо (mock/stub provider або фіксація точного перетворення форми запиту) -- Якщо це за своєю природою лише live-випадок (обмеження швидкості, політики auth), залишайте live-тест вузьким і opt-in через env vars -- Надавайте перевагу найменшому шару, який виявляє баг: - - баг перетворення/повторення запиту provider → тест прямих моделей - - баг сесії/історії/пайплайна інструментів gateway → live-smoke gateway або безпечний для CI mock-тест gateway -- Захист від traversal для SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль для кожного класу SecretRef з метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id сегментів traversal відхиляються. - - Якщо ви додаєте нову родину цілей SecretRef з `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно завершується невдачею для некласифікованих target id, щоб нові класи не можна було тихо пропустити. +- Додайте безпечну для CI регресію, якщо це можливо (mock/stub-провайдер або захоплення точного перетворення форми запиту) +- Якщо це за своєю природою лише live-проблема (rate limit, політики auth), залишайте live-тест вузьким і opt-in через env vars +- Віддавайте перевагу найменшому рівню, який виявляє баг: + - баг перетворення/відтворення запиту провайдера → direct models test + - баг у pipeline session/history/tool gateway → live smoke gateway або безпечний для CI mock-тест gateway +- Захисний бар’єр обходу 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, щоб нові класи не можна було тихо пропустити. -## Пов’язане +## Пов’язані матеріали -- [Testing live](/uk/help/testing-live) +- [Тестування live](/uk/help/testing-live) - [CI](/uk/ci)