docs/docs/uk/help/testing.md

read_when	summary	title	x-i18n
Запуск тестів локально або в CI Додавання регресійних тестів для помилок моделей/провайдерів Налагодження поведінки Gateway і агента	Набір для тестування: модульні/e2e/живі набори тестів, ранери Docker і що охоплює кожен тест	Тестування	generated_at model provider source_hash source_path workflow 2026-05-01T19:38:53Z gpt-5.5 openai 22a2899810a395fa4417be250ab1abacc18375758ca8389dd950fa2ca46404b6 help/testing.md 16

OpenClaw має три набори Vitest (модульні/інтеграційні, e2e, живі) і невеликий набір Docker-запускачів. Цей документ є посібником «як ми тестуємо»:

• Що охоплює кожен набір (і що він навмисно не охоплює).
• Які команди запускати для типових робочих процесів (локально, перед push, налагодження).
• Як живі тести знаходять облікові дані та вибирають моделі/провайдерів.
• Як додавати регресійні тести для реальних проблем із моделями/провайдерами.

**Стек QA (qa-lab, qa-channel, живі транспортні лінії)** задокументовано окремо:

• Огляд QA — архітектура, командна поверхня, створення сценаріїв.
• Матричний QA — довідник для pnpm openclaw qa matrix.
• Канал QA — синтетичний транспортний Plugin, який використовується сценаріями на основі репозиторію.

Ця сторінка описує запуск звичайних тестових наборів і Docker/Parallels-запускачів. Розділ нижче про спеціальні QA-запускачі (спеціальні QA-запускачі) перелічує конкретні виклики qa і відсилає до наведених вище довідників.

Швидкий старт

У більшості випадків:

• Повний gate (очікується перед push): pnpm build && pnpm check && pnpm check:test-types && pnpm test
• Швидший локальний запуск повного набору на потужній машині: pnpm test:max
• Прямий цикл спостереження Vitest: pnpm test:watch
• Пряме націлювання на файл тепер також маршрутизує шляхи розширень/каналів: pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts
• Спершу віддавайте перевагу таргетованим запускам, коли ітеруєте над однією помилкою.
• Docker-підтримуваний QA-сайт: pnpm qa:lab:up
• QA-лінія на основі Linux VM: pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline

Коли ви змінюєте тести або хочете додаткової впевненості:

• Gate покриття: pnpm test:coverage
• Набір E2E: pnpm test:e2e

Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані):

• Живий набір (моделі + проби інструментів/зображень Gateway): pnpm test:live
• Тихо націлити один живий файл: pnpm test:live -- src/agents/models.profiles.live.test.ts
• Docker-живий sweep моделей: 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, що включає окремі Docker-живі матричні jobs моделей, розшардовані за провайдером.
  • Для сфокусованих повторних запусків CI запустіть OpenClaw Live And E2E Checks (Reusable) з include_live_suites: true і live_models_only: true.
  • Додайте нові високосигнальні секрети провайдера до scripts/ci-hydrate-live-auth.sh плюс .github/workflows/openclaw-live-and-e2e-checks-reusable.yml та його scheduled/release викликачів.
• Нативний smoke bound-chat для Codex: pnpm test:docker:live-codex-bind
  • Запускає Docker-живу лінію проти шляху сервера застосунку Codex, прив’язує синтетичний Slack DM через /codex bind, виконує /codex fast і /codex permissions, потім перевіряє, що проста відповідь і вкладення зображення проходять через нативне прив’язування Plugin замість ACP.
• Smoke harness сервера застосунку Codex: pnpm test:docker:live-codex-harness
  • Запускає ходи агента Gateway через harness сервера застосунку Codex, який належить Plugin, перевіряє /codex status і /codex models та за замовчуванням виконує проби зображення, cron MCP, sub-agent і Guardian. Вимкніть пробу sub-agent за допомогою OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0, коли ізолюєте інші збої сервера застосунку 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, якщо не встановлено OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0.
• Smoke команди порятунку Crestodian: pnpm test:live:crestodian-rescue-channel
  • Додаткова перевірка «ремінь і підтяжки» для поверхні команди порятунку message-channel. Вона виконує /crestodian status, ставить у чергу постійну зміну моделі, відповідає /crestodian yes і перевіряє шлях запису аудиту/конфігу.
• Docker smoke планувальника Crestodian: pnpm test:docker:crestodian-planner
  • Запускає Crestodian у контейнері без конфігу з фальшивим Claude CLI у PATH і перевіряє, що fuzzy fallback планувальника перетворюється на аудитований типізований запис конфігу.
• 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, потім запустіть ізольований 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 і transcript асистента зберігає нормалізований usage.cost.

Коли вам потрібен лише один випадок збою, віддавайте перевагу звуженню живих тестів через env-змінні allowlist, описані нижче.

Спеціальні QA-запускачі

Ці команди розташовані поруч з основними тестовими наборами, коли потрібен реалізм QA-lab:

CI запускає QA Lab у спеціальних workflow. Parity gate запускається на відповідних PR і з ручного dispatch з mock-провайдерами. QA-Lab - All Lanes запускається щоночі на main і з ручного dispatch з mock parity gate, живою Matrix-лінією, керованою Convex живою Telegram-лінією та керованою Convex живою Discord-лінією як паралельними jobs. Заплановані QA та release-перевірки явно передають Matrix --profile fast, тоді як CLI Matrix і вхід ручного workflow за замовчуванням залишаються all; ручний dispatch може шардити all у jobs transport, media, e2ee-smoke, e2ee-deep і e2ee-cli. OpenClaw Release Checks запускає parity плюс швидкі Matrix і Telegram-лінії перед схваленням release, використовуючи mock-openai/gpt-5.5 для release-перевірок транспорту, щоб вони залишалися детермінованими та уникали звичайного запуску provider-Plugin. Ці живі транспортні Gateway вимикають пошук у пам’яті; поведінка пам’яті залишається покритою parity-наборами QA.

Повні release-живі media shards використовують ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04, який уже має ffmpeg і ffprobe. Docker-живі shards моделей/backend використовують спільний образ ghcr.io/openclaw/openclaw-live-test:<sha>, зібраний один раз для вибраного коміту, а потім витягують його з OPENCLAW_SKIP_DOCKER_BUILD=1 замість повторної збірки всередині кожного shard.

• pnpm openclaw qa suite
  • Запускає QA-сценарії на основі репозиторію безпосередньо на host.
  • За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими gateway workers. qa-channel за замовчуванням має concurrency 4 (обмежено кількістю вибраних сценаріїв). Використовуйте --concurrency <count> для налаштування кількості workers або --concurrency 1 для старішої serial-лінії.
  • Завершується з ненульовим кодом, коли будь-який сценарій падає. Використовуйте --allow-failures, коли хочете отримати artifacts без коду завершення з помилкою.
  • Підтримує режими провайдера live-frontier, mock-openai і aimock. aimock запускає локальний AIMock-backed сервер провайдера для експериментального покриття fixture і protocol-mock без заміни scenario-aware лінії mock-openai.
• pnpm test:gateway:cpu-scenarios
  • Запускає bench старту Gateway плюс невеликий пакет mock QA Lab сценаріїв (channel-chat-baseline, memory-failure-fallback, gateway-restart-inflight-run) і записує об’єднаний підсумок спостережень CPU у .artifacts/gateway-cpu-scenarios/.
  • За замовчуванням позначає лише сталі спостереження гарячого CPU (--cpu-core-warn плюс --hot-wall-warn-ms), тож короткі сплески старту записуються як метрики без вигляду регресії gateway peg тривалістю в хвилини.
  • Використовує зібрані artifacts dist; спершу запустіть build, коли checkout ще не має свіжого runtime-виводу.
• pnpm openclaw qa suite --runner multipass
  • Запускає той самий QA-набір усередині одноразової Multipass Linux VM.
  • Зберігає ту саму поведінку вибору сценаріїв, що й qa suite на host.
  • Повторно використовує ті самі прапорці вибору провайдера/моделі, що й qa suite.
  • Живі запуски передають підтримувані QA auth inputs, практичні для guest: env-based ключі провайдера, шлях конфігу QA live provider і CODEX_HOME, коли він присутній.
  • Output dirs мають залишатися під коренем репозиторію, щоб guest міг записувати назад через змонтований workspace.
  • Записує звичайний QA-звіт + підсумок плюс логи Multipass у .artifacts/qa-e2e/....
• pnpm qa:lab:up
  • Запускає Docker-backed QA-сайт для operator-style QA-роботи.
• pnpm test:docker:npm-onboard-channel-agent
  • Збирає npm tarball з поточного checkout, глобально встановлює його в Docker, запускає неінтерактивний onboarding OpenAI API-key, за замовчуванням налаштовує Telegram, перевіряє, що ввімкнення Plugin встановлює runtime-залежності на вимогу, запускає doctor і виконує один локальний хід агента проти mocked endpoint OpenAI.
  • Використовуйте OPENCLAW_NPM_ONBOARD_CHANNEL=discord, щоб запустити ту саму packaged-install лінію з Discord.
• pnpm test:docker:session-runtime-context
  • Запускає детермінований built-app Docker smoke для transcripts embedded runtime context. Він перевіряє, що прихований runtime context OpenClaw зберігається як non-display custom message замість витоку у видимий user turn, потім seed-ить уражений зламаний session JSONL і перевіряє, що openclaw doctor --fix переписує його на активну гілку з backup.
• pnpm test:docker:npm-telegram-live
  • Встановлює кандидат пакета OpenClaw у Docker, запускає installed-package onboarding, налаштовує Telegram через встановлений CLI, потім повторно використовує живу Telegram QA-лінію з цим встановленим пакетом як SUT Gateway.
  • За замовчуванням використовує OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta; встановіть OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz або OPENCLAW_CURRENT_PACKAGE_TGZ, щоб тестувати resolved локальний tarball замість встановлення з registry.
  • Використовує ті самі Telegram env credentials або Convex credential source, що й pnpm openclaw qa telegram. Для CI/release automation встановіть OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex плюс OPENCLAW_QA_CONVEX_SITE_URL і role secret. Якщо OPENCLAW_QA_CONVEX_SITE_URL і Convex role secret присутні в CI, Docker-wrapper автоматично вибирає Convex.
  • OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer перевизначає спільний OPENCLAW_QA_CREDENTIAL_ROLE лише для цієї лінії.
  • GitHub Actions відкриває цю лінію як ручний maintainer workflow NPM Telegram Beta E2E. Він не запускається під час merge. Workflow використовує середовище qa-live-shared і leases Convex CI credential.
• GitHub Actions також відкриває Package Acceptance для side-run product proof проти одного кандидатного пакета. Він приймає trusted ref, опубліковану npm spec, HTTPS tarball URL плюс SHA-256 або tarball artifact з іншого run, завантажує нормалізований openclaw-current.tgz як package-under-test, потім запускає наявний Docker E2E scheduler зі smoke, package, product, full або custom profiles ліній. Встановіть telegram_mode=mock-openai або live-frontier, щоб запустити Telegram QA workflow проти того самого artifact package-under-test.
  • Останній beta product proof:

gh workflow run package-acceptance.yml --ref main \
  -f source=npm \
  -f package_spec=openclaw@beta \
  -f suite_profile=product \
  -f telegram_mode=mock-openai

• Proof точного tarball URL потребує digest:

gh workflow run package-acceptance.yml --ref main \
  -f source=url \
  -f package_url=https://registry.npmjs.org/openclaw/-/openclaw-VERSION.tgz \
  -f package_sha256=<sha256> \
  -f suite_profile=package

• Доказ артефакта завантажує tarball-артефакт з іншого запуску Actions:

gh workflow run package-acceptance.yml --ref main \
  -f source=artifact \
  -f artifact_run_id=<run-id> \
  -f artifact_name=<artifact-name> \
  -f suite_profile=smoke

• pnpm test:docker:bundled-channel-deps

  • Пакує та встановлює поточну збірку OpenClaw у Docker, запускає Gateway з налаштованим OpenAI, а потім вмикає вбудовані канали/plugins через редагування конфігурації.
  • Перевіряє, що виявлення налаштування залишає відсутніми runtime-залежності неналаштованих plugins, що перший налаштований запуск Gateway або doctor встановлює runtime-залежності кожного вбудованого Plugin на вимогу, і що другий перезапуск не перевстановлює залежності, які вже були активовані.
  • Також встановлює відому старішу базову версію npm, вмикає Telegram перед запуском openclaw update --tag <candidate> і перевіряє, що post-update doctor кандидата відновлює runtime-залежності вбудованих каналів без postinstall-відновлення з боку harness.

• pnpm test:parallels:npm-update

  • Запускає smoke-перевірку оновлення нативного пакетного встановлення серед гостей Parallels. Кожна вибрана платформа спочатку встановлює запитаний базовий пакет, потім запускає встановлену команду openclaw update у тому самому гості та перевіряє встановлену версію, стан оновлення, готовність gateway і один хід локального агента.

  • Використовуйте --platform macos, --platform windows або --platform linux під час ітерацій на одному гості. Використовуйте --json для шляху до підсумкового артефакта та статусу кожної lane.

  • Lane OpenAI типово використовує openai/gpt-5.4 для живого доказу ходу агента. Передайте --model <provider/model> або задайте OPENCLAW_PARALLELS_OPENAI_MODEL, коли навмисно перевіряєте іншу модель OpenAI.

  • Обгортайте довгі локальні запуски в timeout хоста, щоб зависання транспорту Parallels не могли використати решту вікна тестування:

    timeout --foreground 150m pnpm test:parallels:npm-update -- --json
    timeout --foreground 90m pnpm test:parallels:npm-update -- --platform windows --json
    

  • Скрипт записує вкладені журнали lane у /tmp/openclaw-parallels-npm-update.*. Перегляньте windows-update.log, macos-update.log або linux-update.log, перш ніж припускати, що зовнішня обгортка зависла.

  • Оновлення Windows може витратити від 10 до 15 хвилин на post-update doctor/runtime-відновлення залежностей на холодному гості; це все ще нормальний стан, якщо вкладений журнал npm debug просувається.

  • Не запускайте цю агреговану обгортку паралельно з окремими smoke-lanes Parallels для macOS, Windows або Linux. Вони спільно використовують стан VM і можуть конфліктувати під час відновлення snapshot, подавання пакета або стану guest gateway.

  • Post-update доказ запускає звичайну поверхню вбудованого Plugin, оскільки capability-фасади, як-от мовлення, генерація зображень і розуміння медіа, завантажуються через вбудовані runtime API, навіть коли сам хід агента перевіряє лише просту текстову відповідь.

• pnpm openclaw qa aimock

  • Запускає лише локальний сервер провайдера AIMock для прямого smoke-тестування протоколу.

• pnpm openclaw qa matrix

  • Запускає live QA lane Matrix проти одноразового homeserver Tuwunel на базі Docker. Лише source-checkout — пакетні встановлення не постачають qa-lab.
  • Повний CLI, каталог profile/scenario, env vars і структура артефактів: QA Matrix.

• pnpm openclaw qa telegram

  • Запускає live QA lane Telegram проти справжньої приватної групи з використанням токенів driver і SUT bot з env.
  • Потребує OPENCLAW_QA_TELEGRAM_GROUP_ID, OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN і OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN. Ідентифікатор групи має бути числовим chat id Telegram.
  • Підтримує --credential-source convex для спільних pooled credentials. Типово використовуйте режим env або задайте OPENCLAW_QA_CREDENTIAL_SOURCE=convex, щоб увімкнути pooled leases.
  • Завершується з ненульовим кодом, коли будь-який сценарій завершується невдало. Використовуйте --allow-failures, коли потрібні артефакти без коду виходу помилки.
  • Потребує двох різних bot в одній приватній групі, причому SUT bot має відкривати username Telegram.
  • Для стабільного спостереження bot-to-bot увімкніть Bot-to-Bot Communication Mode в @BotFather для обох bot і переконайтеся, що driver bot може спостерігати трафік bot у групі.
  • Записує звіт QA Telegram, підсумок і артефакт observed-messages у .artifacts/qa-e2e/.... Сценарії з відповіддю включають RTT від запиту driver send до спостереженої відповіді SUT.

Live transport lanes мають один стандартний контракт, щоб нові транспорти не розходилися; матриця покриття для кожної lane розміщена в огляд QA → Покриття live transport. qa-channel — це широкий синтетичний набір і не є частиною цієї матриці.

Спільні облікові дані Telegram через Convex (v1)

Коли --credential-source convex (або OPENCLAW_QA_CREDENTIAL_SOURCE=convex) увімкнено для openclaw qa telegram, QA lab отримує ексклюзивну lease зі backed Convex pool, надсилає Heartbeat для цієї lease, поки lane виконується, і звільняє lease під час завершення.

Еталонний scaffold проєкту Convex:

• qa/convex-credential-broker/

Обов’язкові env vars:

• OPENCLAW_QA_CONVEX_SITE_URL (наприклад, https://your-deployment.convex.site)
• Один secret для вибраної ролі:
  • OPENCLAW_QA_CONVEX_SECRET_MAINTAINER для maintainer
  • OPENCLAW_QA_CONVEX_SECRET_CI для ci
• Вибір credential role:
  • CLI: --credential-role maintainer|ci
  • Типове значення env: OPENCLAW_QA_CREDENTIAL_ROLE (типово ci у CI, інакше maintainer)

Необов’язкові env vars:

• OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS (типово 1200000)
• OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS (типово 30000)
• OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS (типово 90000)
• OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS (типово 15000)
• OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX (типово /qa-credentials/v1)
• OPENCLAW_QA_CREDENTIAL_OWNER_ID (необов’язковий trace id)
• OPENCLAW_QA_ALLOW_INSECURE_HTTP=1 дозволяє local loopback URL Convex http:// лише для локальної розробки.

OPENCLAW_QA_CONVEX_SITE_URL має використовувати https:// у звичайній роботі.

Admin-команди maintainer (pool add/remove/list) потребують саме OPENCLAW_QA_CONVEX_SECRET_MAINTAINER.

CLI helpers для maintainers:

pnpm openclaw qa credentials doctor
pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json
pnpm openclaw qa credentials list --kind telegram
pnpm openclaw qa credentials remove --credential-id <credential-id>

Використовуйте doctor перед live runs, щоб перевірити URL сайту Convex, broker secrets, endpoint prefix, HTTP timeout і доступність admin/list без виведення значень secret. Використовуйте --json для machine-readable виводу в scripts і CI utilities.

Типовий endpoint contract (OPENCLAW_QA_CONVEX_SITE_URL + /qa-credentials/v1):

• POST /acquire
  • Запит: { kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }
  • Успіх: { status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }
  • Вичерпано/retryable: { status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }
• POST /heartbeat
  • Запит: { kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }
  • Успіх: { status: "ok" } (або порожній 2xx)
• POST /release
  • Запит: { kind, ownerId, actorRole, credentialId, leaseToken }
  • Успіх: { status: "ok" } (або порожній 2xx)
• POST /admin/add (лише maintainer secret)
  • Запит: { kind, actorId, payload, note?, status? }
  • Успіх: { status: "ok", credential }
• POST /admin/remove (лише maintainer secret)
  • Запит: { credentialId, actorId }
  • Успіх: { status: "ok", changed, credential }
  • Захист active lease: { status: "error", code: "LEASE_ACTIVE", ... }
• POST /admin/list (лише maintainer secret)
  • Запит: { kind?, status?, includePayload?, limit? }
  • Успіх: { status: "ok", credentials, count }

Форма payload для kind Telegram:

• { groupId: string, driverToken: string, sutToken: string }
• groupId має бути числовим рядком chat id Telegram.
• admin/add перевіряє цю форму для kind: "telegram" і відхиляє malformed payloads.

Додавання каналу до QA

Архітектура та назви scenario-helper для нових channel adapters описані в огляд QA → Додавання каналу. Мінімальна планка: реалізувати transport runner на спільному host seam qa-lab, оголосити qaRunners у manifest Plugin, змонтувати як openclaw qa <runner> і створити сценарії в qa/scenarios/.

Набори тестів (що де запускається)

Думайте про набори як про “зростання реалістичності” (і зростання нестабільності/вартості):

Unit / integration (типово)

• Команда: pnpm test
• Конфігурація: нецільові запуски використовують shard-набір vitest.full-*.config.ts і можуть розгортати multi-project shards у per-project configs для паралельного планування
• Файли: інвентарі core/unit у src/**/*.test.ts, packages/**/*.test.ts і test/**/*.test.ts; UI unit tests запускаються у виділеному shard unit-ui
• Область:
  • Чисті unit tests
  • In-process integration tests (gateway auth, routing, tooling, parsing, config)
  • Детерміновані регресії для відомих багів
• Очікування:
  • Запускається в CI
  • Не потребує справжніх ключів
  • Має бути швидким і стабільним
  • Тести resolver і public-surface loader мають доводити широку fallback-поведінку api.js і runtime-api.js з генерованими крихітними fixtures Plugin, а не справжніми API джерела вбудованого Plugin. Справжні завантаження API Plugin належать до contract/integration suites, власником яких є Plugin.

- Ненацілений `pnpm test` запускає дванадцять менших конфігурацій шардів (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського нативного процесу кореневого проєкту. Це зменшує пікове RSS на навантажених машинах і не дає auto-reply/extension-роботі позбавляти ресурсів непов’язані набори тестів.
- `pnpm test --watch` і далі використовує нативний граф проєктів кореневого `vitest.config.ts`, тому що багатошардовий цикл watch непрактичний.
- `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файлів/каталогів через scoped lanes, тому `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску кореневого проєкту.
- `pnpm test:changed` за замовчуванням розгортає змінені git-шляхи в дешеві scoped lanes: прямі зміни тестів, сусідні файли `*.test.ts`, явні зіставлення джерел і локальні залежні елементи import-графа. Зміни конфігурації/налаштування/пакетів не запускають широкі тести, якщо ви явно не використаєте `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`.
- `pnpm check:changed` — звичайний розумний локальний check gate для вузької роботи. Він класифікує diff на core, core-тести, extensions, extension-тести, apps, docs, release metadata, live Docker tooling і tooling, а потім запускає відповідні команди typecheck, lint і guard. Він не запускає Vitest-тести; для тестового підтвердження викликайте `pnpm test:changed` або явний `pnpm test <target>`. Підняття версії лише в release metadata запускає цільові перевірки версії/конфігурації/root-dependency з guard, який відхиляє зміни package поза верхньорівневим полем version.
- Зміни live Docker ACP harness запускають сфокусовані перевірки: синтаксис shell для live Docker auth-скриптів і dry-run live Docker scheduler. Зміни `package.json` включаються лише тоді, коли diff обмежений `scripts["test:docker:live-*"]`; зміни dependency, export, version та інших package-surface і далі використовують ширші guards.
- Import-light unit-тести з agents, commands, plugins, auto-reply helpers, `plugin-sdk` і подібних областей чистих утиліт маршрутизуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних lanes.
- Вибрані допоміжні source-файли `plugin-sdk` і `commands` також зіставляють changed-mode запуски з явними сусідніми тестами в цих легких lanes, тому зміни helpers не перезапускають увесь важкий набір для цього каталогу.
- `auto-reply` має окремі buckets для верхньорівневих core helpers, верхньорівневих integration-тестів `reply.*` і піддерева `src/auto-reply/reply/**`. CI додатково ділить reply-піддерево на шарди agent-runner, dispatch і commands/state-routing, щоб один import-heavy bucket не володів повним Node-хвостом.
- Звичайний PR/main CI навмисно пропускає batch sweep extensions і release-only шард `agentic-plugins`. Full Release Validation запускає окремий дочірній workflow `Plugin Prerelease` для цих plugin/extension-heavy наборів на release candidates.

- Коли ви змінюєте вхідні дані виявлення message-tool або runtime-контекст compaction, зберігайте обидва рівні покриття.
- Додавайте сфокусовані helper-регресії для меж чистої маршрутизації та нормалізації.
- Підтримуйте справність integration-наборів embedded runner:
  `src/agents/pi-embedded-runner/compact.hooks.test.ts`,
  `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` і
  `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`.
- Ці набори перевіряють, що scoped ids і поведінка compaction і далі проходять через реальні шляхи `run.ts` / `compact.ts`; helper-only тести не є достатньою заміною для цих integration-шляхів.

- Базова конфігурація Vitest за замовчуванням використовує `threads`.
- Спільна конфігурація Vitest фіксує `isolate: false` і використовує неізольований runner у кореневих проєктах, e2e та live-конфігураціях.
- Кореневий UI lane зберігає своє налаштування `jsdom` і optimizer, але теж працює на спільному неізольованому runner.
- Кожен шард `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` зі спільної конфігурації Vitest.
- `scripts/run-vitest.mjs` за замовчуванням додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків.
  Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти зі стандартною поведінкою V8.

- `pnpm changed:lanes` показує, які архітектурні lanes запускає diff.
- Pre-commit hook виконує лише форматування. Він повторно додає відформатовані файли до stage і не запускає lint, typecheck або тести.
- Запускайте `pnpm check:changed` явно перед handoff або push, коли потрібен розумний локальний check 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` зберігають ту саму поведінку маршрутизації, лише з вищим лімітом workers.
- Локальне автоматичне масштабування workers навмисно консервативне і зменшує навантаження, коли load average хоста вже високий, тому кілька одночасних запусків Vitest за замовчуванням завдають менше шкоди.
- Базова конфігурація Vitest позначає projects/config files як `forceRerunTriggers`, щоб changed-mode перезапуски залишалися коректними, коли змінюється test wiring.
- Конфігурація тримає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете одну явну локацію кешу для прямого профілювання.

- `pnpm test:perf:imports` вмикає звітування Vitest про import-duration плюс вивід import-breakdown.
- `pnpm test:perf:imports:changed` обмежує той самий profiling view файлами, зміненими з `origin/main`.
- Дані timing шардів записуються в `.artifacts/vitest-shard-timings.json`.
  Whole-config запуски використовують шлях config як key; include-pattern CI shards додають назву шарда, щоб filtered shards можна було відстежувати окремо.
- Коли один hot test і далі витрачає більшість часу на startup imports, тримайте важкі dependencies за вузьким локальним seam `*.runtime.ts` і mock-айте цей seam напряму замість deep-importing runtime helpers лише для передавання їх через `vi.mock(...)`.
- `pnpm test:perf:changed:bench -- --ref <git-ref>` порівнює routed `test:changed` із нативним шляхом root-project для цього committed diff і друкує wall time плюс macOS max RSS.
- `pnpm test:perf:changed:bench -- --worktree` benchmark-ить поточне dirty tree, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і кореневу конфігурацію Vitest.
- `pnpm test:perf:profile:main` записує CPU profile головного потоку для startup Vitest/Vite і transform overhead.
- `pnpm test:perf:profile:runner` записує CPU+heap profiles runner для unit suite з вимкненим file parallelism.

Стабільність (gateway)

• Команда: pnpm test:stability:gateway
• Конфігурація: vitest.gateway.config.ts, примусово один worker
• Обсяг:
  • Запускає реальний loopback Gateway з diagnostics, увімкненою за замовчуванням
  • Проганяє synthetic gateway message, memory і large-payload churn через diagnostic event path
  • Запитує diagnostics.stability через Gateway WS RPC
  • Покриває helpers збереження diagnostic stability bundle
  • Перевіряє, що recorder залишається bounded, synthetic RSS samples не перевищують pressure budget, а per-session queue depths повертаються до нуля
• Очікування:
  • Безпечно для CI і не потребує ключів
  • Вузький lane для stability-regression follow-up, а не заміна повного Gateway suite

E2E (gateway smoke)

• Команда: pnpm test:e2e
• Конфігурація: vitest.e2e.config.ts
• Файли: src/**/*.e2e.test.ts, test/**/*.e2e.test.ts і E2E-тести bundled-plugin під extensions/
• Типові значення runtime:
  • Використовує Vitest threads з isolate: false, як і решта repo.
  • Використовує adaptive workers (CI: до 2, локально: 1 за замовчуванням).
  • За замовчуванням працює в silent mode, щоб зменшити overhead console I/O.
• Корисні overrides:
  • OPENCLAW_E2E_WORKERS=<n> для примусового worker count (обмежено 16).
  • OPENCLAW_E2E_VERBOSE=1 для повторного ввімкнення verbose console output.
• Обсяг:
  • End-to-end поведінка multi-instance gateway
  • WebSocket/HTTP surfaces, node pairing і важча networking
• Очікування:
  • Запускається в CI (коли ввімкнено в pipeline)
  • Реальні ключі не потрібні
  • Більше рухомих частин, ніж у unit tests (може бути повільніше)

E2E: OpenShell backend smoke

• Команда: pnpm test:e2e:openshell
• Файл: extensions/openshell/src/backend.e2e.test.ts
• Обсяг:
  • Запускає ізольований OpenShell gateway на хості через Docker
  • Створює sandbox із тимчасового локального Dockerfile
  • Перевіряє OpenShell backend OpenClaw через реальні sandbox ssh-config + SSH exec
  • Перевіряє remote-canonical filesystem behavior через sandbox fs bridge
• Очікування:
  • Лише opt-in; не є частиною типового запуску pnpm test:e2e
  • Потребує локального openshell CLI і робочого Docker daemon
  • Використовує ізольовані HOME / XDG_CONFIG_HOME, а потім знищує test gateway і sandbox
• Корисні overrides:
  • OPENCLAW_E2E_OPENSHELL=1 для ввімкнення тесту під час ручного запуску ширшого e2e suite
  • OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell для вказування нестандартного CLI binary або wrapper script

Live (реальні providers + реальні models)

• Команда: pnpm test:live
• Конфігурація: vitest.live.config.ts
• Файли: src/**/*.live.test.ts, test/**/*.live.test.ts і bundled-plugin live tests під extensions/
• Типове значення: увімкнено через pnpm test:live (установлює OPENCLAW_LIVE_TEST=1)
• Обсяг:
  • “Чи цей provider/model справді працює сьогодні з реальними creds?”
  • Виявляє зміни format providers, нюанси tool-calling, проблеми auth і поведінку rate limit
• Очікування:
  • За задумом не є CI-stable (реальні мережі, реальні policies providers, quotas, outages)
  • Коштує грошей / використовує rate limits
  • Краще запускати звужені subsets замість “усього”
• Live runs source ~/.profile, щоб підхопити відсутні API keys.
• За замовчуванням live runs і далі ізолюють HOME і копіюють config/auth material у тимчасовий test home, щоб unit fixtures не могли змінити ваш реальний ~/.openclaw.
• Установлюйте OPENCLAW_LIVE_USE_REAL_HOME=1 лише тоді, коли навмисно потрібно, щоб live tests використовували ваш реальний home directory.
• pnpm test:live тепер за замовчуванням працює в тихішому mode: зберігає progress output [live] ..., але приглушує додаткове повідомлення ~/.profile і вимикає gateway bootstrap logs/Bonjour chatter. Установіть OPENCLAW_LIVE_TEST_QUIET=0, якщо хочете повернути повні startup logs.
• API key rotation (provider-specific): установіть *_API_KEYS у форматі з комами/крапками з комою або *_API_KEY_1, *_API_KEY_2 (наприклад OPENAI_API_KEYS, ANTHROPIC_API_KEYS, GEMINI_API_KEYS) або per-live override через OPENCLAW_LIVE_*_KEY; tests повторюють спробу на rate limit responses.
• Progress/heartbeat output:
  • Live suites тепер виводять progress lines у stderr, щоб довгі provider calls були видимо активними, навіть коли Vitest console capture тихий.
  • vitest.live.config.ts вимикає Vitest console interception, щоб provider/gateway progress lines стрімилися одразу під час live runs.
  • Налаштовуйте direct-model heartbeats через OPENCLAW_LIVE_HEARTBEAT_MS.
  • Налаштовуйте gateway/probe heartbeats через OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS.

Який suite слід запустити?

Використовуйте цю таблицю рішень:

• Редагування логіки/тестів: запустіть pnpm test (і pnpm test:coverage, якщо ви змінили багато)
• Зміни в мережевій частині gateway / WS-протоколі / pairing: додайте pnpm test:e2e
• Налагодження “my bot is down” / збоїв, специфічних для провайдера / виклику інструментів: запустіть звужений pnpm test:live

Live-тести (із мережевим доступом)

Для live-матриці моделей, smoke-тестів CLI backend, smoke-тестів ACP, harness Codex app-server та всіх live-тестів медіапровайдерів (Deepgram, BytePlus, ComfyUI, image, music, video, media harness), а також обробки облікових даних для live-запусків, див. Тестування — live-набори.

Docker-запускачі (необов’язкові перевірки "працює в Linux")

Ці Docker-запускачі поділяються на дві групи:

• Запускачі live-моделей: test:docker:live-models і test:docker:live-gateway запускають лише відповідний live-файл із profile-key всередині Docker-образу репозиторію (src/agents/models.profiles.live.test.ts і src/gateway/gateway-models.profiles.live.test.ts), монтують ваш локальний каталог конфігурації та workspace (і завантажують ~/.profile, якщо його змонтовано). Відповідні локальні точки входу: test:live:models-profiles і test:live:gateway-profiles.
• Docker live-запускачі типово мають менший ліміт smoke-тестів, щоб повний Docker-прогін залишався практичним: test:docker:live-models типово використовує OPENCLAW_LIVE_MAX_MODELS=12, а test:docker:live-gateway типово використовує OPENCLAW_LIVE_GATEWAY_SMOKE=1, OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8, OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000 і OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000. Перевизначайте ці змінні середовища, коли явно потрібне ширше вичерпне сканування.
• test:docker:all один раз збирає live Docker-образ через test:docker:live-build, один раз пакує OpenClaw як npm tarball через scripts/package-openclaw-for-docker.mjs, а потім збирає/повторно використовує два образи scripts/e2e/Dockerfile. Bare-образ — це лише Node/Git-запускач для install/update/plugin-dependency lane; ці lane монтують попередньо зібраний tarball. Функціональний образ встановлює той самий tarball у /app для lane функціональності зібраного застосунку. Визначення Docker lane містяться в 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 lane стартувати всі разом. Якщо одна 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-хост має більший запас ресурсів. Запускач типово виконує 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 та облікових даних.
• Package Acceptance — це GitHub-native package gate для перевірки "чи працює цей установлюваний tarball як продукт?" Він визначає один кандидатний package із source=npm, source=ref, source=url або source=artifact, завантажує його як package-under-test, а потім запускає reusable Docker E2E lane проти саме цього tarball замість повторного пакування вибраного ref. workflow_ref вибирає довірені сценарії workflow/harness, а package_ref вибирає source commit/branch/tag для пакування, коли source=ref; це дає змогу поточній логіці acceptance перевіряти старіші довірені коміти. Профілі впорядковано за шириною охоплення: smoke — це швидкі install/channel/agent плюс gateway/config, package — це package/update/plugin contract плюс keyless upgrade-survivor fixture, published-baseline upgrade survivor lane і типова native-заміна для більшості покриття Parallels package/update, product додає MCP channels, cron/subagent cleanup, OpenAI web search і OpenWebUI, а full запускає release-path Docker chunks з OpenWebUI. Для published-upgrade-survivor Package Acceptance завжди використовує package-under-test як кандидата і published_upgrade_survivor_baseline як fallback published baseline, типово openclaw@latest; задайте published_upgrade_survivor_baselines=release-history, щоб розбити lane на deduped-матрицю з останніх шести стабільних релізів, 2026.4.23 і останнього стабільного релізу до 2026-03-15. Published lane налаштовує свій baseline за допомогою вбудованого рецепта команди openclaw config set, а потім записує кроки рецепта в підсумок lane. Валідація релізу запускає custom package delta (bundled-channel-deps-compat plugins-offline) плюс Telegram package QA, оскільки release-path Docker chunks уже покривають lane package/update/plugin, що перекриваються. Цільові команди повторного GitHub Docker-запуску, згенеровані з артефактів, включають попередній package artifact, підготовлені image inputs і список baseline для published upgrade-survivor, коли він доступний, щоб невдалі lane могли уникнути повторного збирання package та image.
• Перевірки збирання й релізу запускають scripts/check-cli-bootstrap-imports.mjs після tsdown. Guard обходить статичний зібраний граф із dist/entry.js і dist/cli/run-main.js та завершується помилкою, якщо переддиспетчерський startup імпортує залежності package, як-от Commander, prompt UI, undici або logging, до dispatch команди; він також тримає bundled gateway run chunk у межах бюджету та відхиляє статичні імпорти відомих cold gateway paths. Packaged CLI smoke також покриває root help, onboard help, doctor help, status, config schema і команду model-list.
• Legacy-сумісність Package Acceptance обмежена 2026.4.25 (включно з 2026.4.25-beta.*). До цієї межі harness допускає лише прогалини shipped-package metadata: пропущені private QA inventory entries, відсутній gateway install --wrapper, відсутні patch files у tarball-derived git fixture, відсутній збережений update.channel, legacy plugin install-record locations, відсутня marketplace install-record persistence і міграція config metadata під час plugins update. Для package після 2026.4.25 ці шляхи є строгими помилками.
• Container smoke runners: test:docker:openwebui, test:docker:onboard, test:docker:npm-onboard-channel-agent, test:docker:update-channel-switch, test:docker:upgrade-survivor, test:docker:published-upgrade-survivor, test:docker:session-runtime-context, test:docker:agents-delete-shared-workspace, test:docker:gateway-network, test:docker:browser-cdp-snapshot, test:docker:mcp-channels, test:docker:pi-bundle-mcp-tools, test:docker:cron-mcp-cleanup, test:docker:plugins, test:docker:plugin-update і test:docker:config-reload завантажують один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня.

Docker-запускачі live-моделей також bind-mount лише потрібні auth homes CLI (або всі підтримувані, коли запуск не звужено), а потім копіюють їх у home контейнера перед запуском, щоб external-CLI OAuth міг оновлювати токени без зміни host auth store:

• Прямі моделі: pnpm test:docker:live-models (скрипт: scripts/test-live-models-docker.sh)
• Димовий тест прив’язки ACP: pnpm test:docker:live-acp-bind (скрипт: scripts/test-live-acp-bind-docker.sh; за замовчуванням охоплює Claude, Codex і Gemini, зі строгим покриттям Droid/OpenCode через pnpm test:docker:live-acp-bind:droid і pnpm test:docker:live-acp-bind:opencode)
• Димовий тест бекенду CLI: pnpm test:docker:live-cli-backend (скрипт: scripts/test-live-cli-backend-docker.sh)
• Димовий тест обв’язки сервера застосунку Codex: pnpm test:docker:live-codex-harness (скрипт: scripts/test-live-codex-harness-docker.sh)
• Gateway + dev-агент: pnpm test:docker:live-gateway (скрипт: scripts/test-live-gateway-models-docker.sh)
• Димовий тест спостережуваності: pnpm qa:otel:smoke — це приватна лінія QA для checkout вихідного коду. Вона навмисно не входить до ліній Docker-релізу пакета, бо npm tarball не містить QA Lab.
• Живий димовий тест Open WebUI: pnpm test:docker:openwebui (скрипт: scripts/e2e/openwebui-docker.sh)
• Майстер онбордингу (TTY, повне створення каркаса): pnpm test:docker:onboard (скрипт: scripts/e2e/onboard-docker.sh)
• Димовий тест онбордингу/channel/агента з npm tarball: pnpm test:docker:npm-onboard-channel-agent глобально встановлює запакований tarball OpenClaw у Docker, налаштовує OpenAI через онбординг з посиланням на env і Telegram за замовчуванням, перевіряє, що doctor відремонтував активовані runtime-залежності Plugin, і запускає один змодельований хід агента OpenAI. Повторно використайте попередньо зібраний tarball через OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz, пропустіть перебудову на host через OPENCLAW_NPM_ONBOARD_HOST_BUILD=0 або перемкніть channel через OPENCLAW_NPM_ONBOARD_CHANNEL=discord.
• Димовий тест перемикання update channel: pnpm test:docker:update-channel-switch глобально встановлює запакований tarball OpenClaw у Docker, перемикається з пакета stable на git dev, перевіряє збережений channel і роботу Plugin після оновлення, потім перемикається назад на пакет stable і перевіряє статус оновлення.
• Димовий тест виживання після upgrade: pnpm test:docker:upgrade-survivor встановлює запакований tarball OpenClaw поверх брудної фікстури старого користувача з агентами, конфігурацією channel, allowlist Plugin, застарілим станом runtime-deps Plugin і наявними файлами workspace/session. Він запускає оновлення пакета плюс неінтерактивний doctor без ключів live provider або channel, потім запускає loopback Gateway і перевіряє збереження config/state, а також бюджети startup/status.
• Димовий тест виживання після опублікованого upgrade: pnpm test:docker:published-upgrade-survivor за замовчуванням встановлює openclaw@latest, засіває реалістичні файли наявного користувача, налаштовує цей baseline за допомогою вбудованого рецепта команд, перевіряє отриману конфігурацію, оновлює це опубліковане встановлення до кандидатного tarball, запускає неінтерактивний doctor, записує .artifacts/upgrade-survivor/summary.json, потім запускає loopback Gateway і перевіряє налаштовані intents, збереження state, startup, /healthz, /readyz і бюджети статусу RPC. Перевизначте один baseline через OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC, попросіть aggregate scheduler розгорнути точні baselines через OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS і розгорніть фікстури у формі issue через OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS, наприклад reported-issues; Package Acceptance надає їх як published_upgrade_survivor_baseline, published_upgrade_survivor_baselines і published_upgrade_survivor_scenarios.
• Димовий тест runtime context сесії: pnpm test:docker:session-runtime-context перевіряє збереження прихованого runtime context transcript, а також ремонт doctor для зачеплених дубльованих гілок prompt-rewrite.
• Димовий тест глобального встановлення Bun: bash scripts/e2e/bun-global-install-smoke.sh пакує поточне дерево, встановлює його через bun install -g в ізольованому home і перевіряє, що openclaw infer image providers --json повертає вбудованих 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: bash scripts/test-install-sh-docker.sh спільно використовує один npm cache для своїх root, update і direct-npm containers. Димовий тест update за замовчуванням використовує npm latest як stable baseline перед upgrade до кандидатного tarball. Перевизначте локально через OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22 або через input 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 між локальними повторними запусками.
• Install Smoke CI пропускає дубльоване пряме глобальне update npm через OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1; запускайте скрипт локально без цього env, коли потрібне покриття прямого npm install -g.
• Димовий тест CLI видалення агентів зі спільним workspace: pnpm test:docker:agents-delete-shared-workspace (скрипт: scripts/e2e/agents-delete-shared-workspace-docker.sh) за замовчуванням збирає root Dockerfile image, засіває двох агентів з одним workspace в ізольованому container home, запускає agents delete --json і перевіряє валідний JSON плюс поведінку збереженого workspace. Повторно використайте install-smoke image через OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1.
• Мережа Gateway (два containers, WS auth + health): pnpm test:docker:gateway-network (скрипт: scripts/e2e/gateway-network-docker.sh)
• Димовий тест Browser CDP snapshot: pnpm test:docker:browser-cdp-snapshot (скрипт: scripts/e2e/browser-cdp-snapshot-docker.sh) збирає source E2E image плюс шар Chromium, запускає Chromium із raw CDP, виконує browser doctor --deep і перевіряє, що role snapshots CDP охоплюють URL посилань, clickables, підвищені курсором, iframe refs і frame metadata.
• Регресія мінімального reasoning для OpenAI Responses web_search: pnpm test:docker:openai-web-search-minimal (скрипт: scripts/e2e/openai-web-search-minimal-docker.sh) запускає змодельований сервер OpenAI через Gateway, перевіряє, що web_search підвищує reasoning.effort з minimal до low, потім примусово викликає відхилення provider schema і перевіряє, що raw detail з’являється в логах Gateway.
• Міст MCP channel (засіяний Gateway + stdio bridge + димовий тест raw Claude notification-frame): pnpm test:docker:mcp-channels (скрипт: scripts/e2e/mcp-channels-docker.sh)
• MCP tools у bundle Pi (реальний stdio MCP server + димовий тест вбудованого Pi profile allow/deny): pnpm test:docker:pi-bundle-mcp-tools (скрипт: scripts/e2e/pi-bundle-mcp-tools-docker.sh)
• Очищення Cron/subagent MCP (реальний Gateway + teardown дочірнього stdio MCP після ізольованих запусків cron і one-shot subagent): pnpm test:docker:cron-mcp-cleanup (скрипт: scripts/e2e/cron-mcp-cleanup-docker.sh)
• Plugins (димовий тест встановлення, встановлення/видалення kitchen-sink ClawHub, marketplace updates і enable/inspect Claude-bundle): pnpm test:docker:plugins (скрипт: scripts/e2e/plugins-docker.sh) Встановіть OPENCLAW_PLUGINS_E2E_CLAWHUB=0, щоб пропустити блок ClawHub, або перевизначте стандартну пару kitchen-sink package/runtime через OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC і OPENCLAW_PLUGINS_E2E_CLAWHUB_ID. Без OPENCLAW_CLAWHUB_URL/CLAWHUB_URL тест використовує герметичний локальний сервер фікстури ClawHub.
• Димовий тест Plugin update без змін: pnpm test:docker:plugin-update (скрипт: scripts/e2e/plugin-update-unchanged-docker.sh)
• Димовий тест config reload metadata: pnpm test:docker:config-reload (скрипт: scripts/e2e/config-reload-source-docker.sh)
• Runtime deps вбудованого Plugin: pnpm test:docker:bundled-channel-deps за замовчуванням збирає невеликий Docker runner image, один раз збирає й пакує OpenClaw на host, а потім монтує цей tarball у кожен сценарій встановлення Linux. Повторно використайте image через OPENCLAW_SKIP_DOCKER_BUILD=1, пропустіть host rebuild після свіжої локальної збірки через OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0 або вкажіть на наявний tarball через OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz. Повний Docker aggregate і release-path bundled-channel chunks попередньо пакують цей tarball один раз, а потім shard-ять перевірки bundled channel на незалежні лінії, включно з окремими update lanes для Telegram, Discord, Slack, Feishu, memory-lancedb і ACPX. Release chunks розділяють channel smokes, update targets і setup/runtime contracts на bundled-channels-core, bundled-channels-update-a, bundled-channels-update-b і bundled-channels-contracts; aggregate chunk bundled-channels лишається доступним для ручних повторних запусків. Release workflow також розділяє provider installer chunks і bundled Plugin install/uninstall chunks; застарілі chunks package-update, plugins-runtime і plugins-integrations лишаються aggregate aliases для ручних повторних запусків. Використовуйте OPENCLAW_BUNDLED_CHANNELS=telegram,slack, щоб звузити channel matrix під час прямого запуску bundled lane, або OPENCLAW_BUNDLED_CHANNEL_UPDATE_TARGETS=telegram,acpx, щоб звузити update scenario. Docker runs для кожного scenario за замовчуванням мають OPENCLAW_BUNDLED_CHANNEL_DOCKER_RUN_TIMEOUT=900s; multi-target update scenario за замовчуванням має OPENCLAW_BUNDLED_CHANNEL_UPDATE_DOCKER_RUN_TIMEOUT=2400s. Лінія також перевіряє, що channels.<id>.enabled=false і plugins.entries.<id>.enabled=false пригнічують repair runtime-dependency у doctor.
• Звужуйте runtime deps вбудованого 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.

Щоб вручну попередньо зібрати й повторно використовувати спільний functional image:

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

Suite-specific image overrides, такі як OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE, усе одно мають пріоритет, коли задані. Коли OPENCLAW_SKIP_DOCKER_BUILD=1 вказує на віддалений спільний image, скрипти pull-ять його, якщо його ще немає локально. Docker-тести QR і installer зберігають власні Dockerfiles, бо вони перевіряють поведінку package/install, а не спільний runtime зібраного застосунку.

Docker-запускачі для live-моделей також монтують поточний checkout лише для читання і розгортають його у тимчасову робочу директорію всередині контейнера. Це зберігає образ середовища виконання компактним, водночас запускаючи Vitest проти саме вашого локального source/config. Крок розгортання пропускає великі локальні кеші та результати складання застосунків, як-от .pnpm-store, .worktrees, __openclaw_vitest__, а також локальні для застосунків .build або каталоги результатів Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання машинно-специфічних артефактів. Вони також задають OPENCLAW_SKIP_CHANNELS=1, щоб live-перевірки Gateway не запускали реальні Telegram/Discord тощо channel workers усередині контейнера. test:docker:live-models усе ще запускає pnpm test:live, тому також передавайте OPENCLAW_LIVE_GATEWAY_*, коли потрібно звузити або виключити live-покриття Gateway з цієї Docker-ланки. test:docker:openwebui — це суміснісний smoke вищого рівня: він запускає контейнер OpenClaw gateway з увімкненими OpenAI-сумісними HTTP endpoint’ами, запускає закріплений контейнер Open WebUI проти цього Gateway, входить через Open WebUI, перевіряє, що /api/models відкриває openclaw/default, а потім надсилає реальний chat-запит через proxy /api/chat/completions Open WebUI. Перший запуск може бути помітно повільнішим, бо Docker може знадобитися підтягнути образ Open WebUI, а Open WebUI — завершити власне cold-start налаштування. Ця ланка очікує придатний ключ live-моделі, а OPENCLAW_PROFILE_FILE (~/.profile за замовчуванням) є основним способом надати його в Dockerized-запусках. Успішні запуски друкують невеликий JSON payload на кшталт { "ok": true, "model": "openclaw/default", ... }. test:docker:mcp-channels навмисно детермінований і не потребує реального облікового запису Telegram, Discord чи iMessage. Він завантажує засіяний контейнер Gateway, запускає другий контейнер, який породжує openclaw mcp serve, а потім перевіряє routed conversation discovery, читання transcript, attachment metadata, поведінку live event queue, маршрутизацію outbound send, а також Claude-style channel + permission notifications через реальний stdio MCP bridge. Перевірка notification інспектує сирі stdio MCP frames напряму, тож smoke валідує те, що bridge фактично випромінює, а не лише те, що випадково показує конкретний client SDK. test:docker:pi-bundle-mcp-tools детермінований і не потребує ключа live-моделі. Він збирає Docker-образ репозиторію, запускає реальний stdio MCP probe server усередині контейнера, матеріалізує цей server через вбудований Pi bundle MCP runtime, виконує tool, а потім перевіряє, що coding і messaging зберігають bundle-mcp tools, тоді як minimal і tools.deny: ["bundle-mcp"] їх фільтрують. test:docker:cron-mcp-cleanup детермінований і не потребує ключа live-моделі. Він запускає засіяний Gateway з реальним stdio MCP probe server, виконує ізольований cron turn і одноразовий child turn /subagents spawn, а потім перевіряє, що дочірній MCP-процес завершується після кожного запуску.

Ручний ACP plain-language thread smoke (не CI):

• bun scripts/dev/discord-acp-plain-language-smoke.ts --channel <discord-channel-id> ...
• Зберігайте цей script для regression/debug workflow. Він може знову знадобитися для валідації ACP thread routing, тому не видаляйте його.

Корисні 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 і source’иться перед запуском тестів
• OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1 для перевірки лише env vars, source’нутих із OPENCLAW_PROFILE_FILE, з використанням тимчасових config/workspace dirs і без зовнішніх CLI auth mounts
• OPENCLAW_DOCKER_CLI_TOOLS_DIR=... (за замовчуванням: ~/.cache/openclaw/docker-cli-tools) монтується до /home/node/.npm-global для кешованих CLI installs усередині Docker
• Зовнішні CLI auth dirs/files під $HOME монтуються лише для читання під /host-auth..., а потім копіюються до /home/node/... перед початком тестів
  • Типові dirs: .minimax
  • Типові files: ~/.codex/auth.json, ~/.codex/config.toml, .claude.json, ~/.claude/.credentials.json, ~/.claude/settings.json, ~/.claude/settings.local.json
  • Звужені provider runs монтують лише потрібні dirs/files, виведені з OPENCLAW_LIVE_PROVIDERS / OPENCLAW_LIVE_GATEWAY_PROVIDERS
  • Перевизначайте вручну через OPENCLAW_DOCKER_AUTH_DIRS=all, OPENCLAW_DOCKER_AUTH_DIRS=none або comma list на кшталт OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex
• OPENCLAW_LIVE_GATEWAY_MODELS=... / OPENCLAW_LIVE_MODELS=... для звуження запуску
• OPENCLAW_LIVE_GATEWAY_PROVIDERS=... / OPENCLAW_LIVE_PROVIDERS=... для фільтрації providers у контейнері
• OPENCLAW_SKIP_DOCKER_BUILD=1 для повторного використання наявного образу openclaw:local-live у повторних запусках, яким не потрібна перебудова
• OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 щоб гарантувати, що creds надходять із profile store (не env)
• OPENCLAW_OPENWEBUI_MODEL=... для вибору model, яку Gateway відкриває для smoke Open WebUI
• OPENCLAW_OPENWEBUI_PROMPT=... для перевизначення nonce-check prompt, який використовує smoke Open WebUI
• OPENWEBUI_IMAGE=... для перевизначення закріпленого tag образу Open WebUI

Перевірка документації

Запускайте перевірки документації після редагування docs: pnpm check:docs. Запускайте повну Mintlify anchor validation, коли також потрібні перевірки in-page headings: pnpm docs:check-links:anchors.

Offline regression (CI-safe)

Це “real pipeline” regression без реальних providers:

• Gateway tool calling (mock OpenAI, реальний Gateway + agent loop): src/gateway/gateway.test.ts (case: "runs a mock OpenAI tool call end-to-end via gateway agent loop")
• Gateway wizard (WS wizard.start/wizard.next, writes config + auth enforced): src/gateway/gateway.test.ts (case: "runs wizard over ws and writes auth token config")

Agent reliability evals (skills)

У нас уже є кілька CI-safe тестів, які поводяться як “agent reliability evals”:

• Mock tool-calling через реальний Gateway + agent loop (src/gateway/gateway.test.ts).
• End-to-end wizard flows, які валідують session wiring і config effects (src/gateway/gateway.test.ts).

Чого все ще бракує для Skills (див. Skills):

• Decisioning: коли skills перелічені у prompt, чи вибирає agent правильний skill (або уникає нерелевантних)?
• Compliance: чи читає agent SKILL.md перед використанням і чи дотримується required steps/args?
• Workflow contracts: multi-turn scenarios, які assert tool order, session history carryover і sandbox boundaries.

Майбутні evals мають спершу залишатися детермінованими:

• Scenario runner із mock providers для assert tool calls + order, skill file reads і session wiring.
• Невеликий suite skill-focused scenarios (use vs avoid, gating, prompt injection).
• Необов’язкові live evals (opt-in, env-gated) лише після появи CI-safe suite.

Contract tests (plugin and channel shape)

Contract tests перевіряють, що кожен зареєстрований Plugin і channel відповідає своєму interface contract. Вони проходять усі знайдені plugins і запускають suite shape and behavior assertions. Типова unit lane pnpm test навмисно пропускає ці shared seam and smoke files; запускайте contract commands явно, коли торкаєтеся shared channel або provider surfaces.

Команди

• Усі contracts: pnpm test:contracts
• Лише channel contracts: pnpm test:contracts:channels
• Лише provider contracts: pnpm test:contracts:plugins

Channel contracts

Розташовані в src/channels/plugins/contracts/*.contract.test.ts:

• plugin - Базова форма plugin (id, name, capabilities)
• setup - Contract setup wizard
• session-binding - Поведінка session binding
• outbound-payload - Структура message payload
• inbound - Обробка inbound message
• actions - Channel action handlers
• threading - Обробка thread ID
• directory - Directory/roster API
• group-policy - Застосування group policy

Provider status contracts

Розташовані в src/plugins/contracts/*.contract.test.ts.

• status - Channel status probes
• registry - Форма Plugin registry

Provider contracts

Розташовані в src/plugins/contracts/*.contract.test.ts:

• auth - Contract auth flow
• auth-choice - Auth choice/selection
• catalog - Model catalog API
• discovery - Plugin discovery
• loader - Plugin loading
• runtime - Provider runtime
• shape - Форма/інтерфейс Plugin
• wizard - Setup wizard

Коли запускати

• Після зміни plugin-sdk exports або subpaths
• Після додавання або зміни channel чи provider Plugin
• Після рефакторингу Plugin registration або discovery

Contract tests запускаються в CI і не потребують реальних API keys.

Додавання regressions (guidance)

Коли ви виправляєте provider/model issue, виявлену live:

• Додайте CI-safe regression, якщо можливо (mock/stub provider або capture exact request-shape transformation)
• Якщо це inherently live-only (rate limits, auth policies), залиште live test вузьким і opt-in через env vars
• Надавайте перевагу таргетуванню найменшого шару, який ловить bug:
  • provider request conversion/replay bug → direct models test
  • gateway session/history/tool pipeline bug → gateway live smoke або CI-safe gateway mock test
• SecretRef traversal guardrail:
  • src/secrets/exec-secret-ref-id-parity.test.ts derives one sampled target per SecretRef class from registry metadata (listSecretTargetRegistryEntries()), then asserts traversal-segment exec ids are rejected.
  • Якщо ви додаєте нову includeInPlan SecretRef target family у src/secrets/target-registry-data.ts, оновіть classifyTargetClass у цьому тесті. Тест навмисно падає на unclassified target ids, щоб нові classes не можна було тихо пропустити.

Пов’язане

• Testing live
• CI