Тестування

OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір Docker-ранерів. Цей документ є посібником «як ми тестуємо»:

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

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

У більшість днів:

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

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

• Coverage gate: pnpm test:coverage
• Набір E2E: pnpm test:e2e

Тимчасові каталоги тестів

Віддавайте перевагу спільним helper-функціям у test/helpers/temp-dir.ts для тимчасових каталогів, що належать тестам. Вони роблять власність явною й утримують очищення в тому самому життєвому циклі тесту:

  const tempDirs = useAutoCleanupTempDirTracker(afterEach); it("uses a temp workspace", () => {  const workspace = tempDirs.make("openclaw-example-");  // use workspace});

useAutoCleanupTempDirTracker(afterEach) навмисно не відкриває ручний метод очищення; Vitest володіє очищенням після кожного тесту. Наявні нижчорівневі helper-функції залишаються для тестів, які ще не перенесено, але нові та мігровані тести мають використовувати tracker з автоматичним очищенням. Уникайте нового використання ручних makeTempDir, cleanupTempDirs або createTempDirTracker і уникайте нових голих викликів fs.mkdtemp* у тестах, якщо кейс явно не перевіряє сире поводження temp-dir. Додайте придатний до аудиту дозвільний коментар із конкретною причиною, коли тест навмисно потребує голого тимчасового каталогу:

// openclaw-temp-dir: allow verifies raw fs cleanup behaviorconst workspace = fs.mkdtempSync(prefix);

Для видимості міграції node scripts/report-test-temp-creations.mjs повідомляє про нове створення голих temp-dir і нове ручне використання спільних helper-функцій у доданих рядках diff без блокування наявних стилів очищення. Його область дії на рівні файлів навмисно дотримується тієї самої класифікації test-path, яку використовує scripts/changed-lanes.mjs, замість підтримання окремої евристики імен файлів test-helper, водночас пропускаючи саму реалізацію спільного helper. check:changed запускає цей звіт для змінених тестових шляхів як warning-only CI-сигнал; знахідки є warning-анотаціями GitHub, а не збоями.

Коли налагоджуєте реальних провайдерів/моделі (потрібні реальні облікові дані):

• Live-набір (моделі + gateway tool/image probes): pnpm test:live
• Тихо націлити один live-файл: pnpm test:live -- src/agents/models.profiles.live.test.ts
• Звіти продуктивності runtime: dispatch OpenClaw Performance з live_openai_candidate=true для реального agent turn openai/gpt-5.5 або deep_profile=true для артефактів CPU/heap/trace Kova. Щоденні заплановані запуски публікують артефакти mock-provider, deep-profile і GPT 5.5 lane до openclaw/clawgrit-reports, коли CLAWGRIT_REPORTS_TOKEN налаштовано. Звіт mock-provider також включає source-level gateway boot, memory, plugin-pressure, repeated fake-model hello-loop і CLI startup numbers.
• Docker live model sweep: pnpm test:docker:live-models
  • Кожна вибрана модель тепер запускає текстовий turn плюс невеликий file-read-style probe. Моделі, чиї метадані оголошують вхід image, також запускають крихітний image turn. Вимкніть додаткові probes через 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 live model matrix jobs, розшардовані за провайдером.
  • Для сфокусованих повторних запусків CI dispatch OpenClaw Live And E2E Checks (Reusable) з include_live_suites: true і live_models_only: true.
  • Додавайте нові high-signal секрети провайдерів до scripts/ci-hydrate-live-auth.sh плюс .github/workflows/openclaw-live-and-e2e-checks-reusable.yml і його scheduled/release викликачів.
• Native Codex bound-chat smoke: pnpm test:docker:live-codex-bind
  • Запускає Docker live lane проти шляху Codex app-server, прив’язує синтетичний Slack DM через /codex bind, виконує /codex fast і /codex permissions, потім перевіряє, що звичайна відповідь і image attachment проходять через нативну plugin binding замість ACP.
• Codex app-server harness smoke: pnpm test:docker:live-codex-harness
  • Запускає gateway agent turns через plugin-owned Codex app-server harness, перевіряє /codex status і /codex models, а за замовчуванням виконує image, cron MCP, sub-agent і Guardian probes. Вимкніть sub-agent probe через OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0, коли ізолюєте інші збої Codex app-server. Для сфокусованої перевірки sub-agent вимкніть інші probes: OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=1 pnpm test:docker:live-codex-harness. Це завершується після sub-agent probe, якщо не встановлено OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0.
• Codex on-demand install smoke: pnpm test:docker:codex-on-demand
  • Встановлює запакований OpenClaw tarball у Docker, запускає onboarding з OpenAI API-key і перевіряє, що Codex plugin плюс залежність @openai/codex були завантажені до керованого кореня npm-проєкту на вимогу.
• Live plugin tool dependency smoke: pnpm test:docker:live-plugin-tool
  • Пакує fixture plugin з реальною залежністю slugify, встановлює його через npm-pack:, перевіряє залежність під керованим коренем npm-проєкту, потім просить live OpenAI model викликати plugin tool і повернути прихований slug.
• Crestodian rescue command smoke: pnpm test:live:crestodian-rescue-channel
  • Opt-in belt-and-suspenders перевірка поверхні message-channel rescue command. Вона виконує /crestodian status, ставить у чергу persistent model change, відповідає /crestodian yes і перевіряє audit/config write path.
• Crestodian planner Docker smoke: pnpm test:docker:crestodian-planner
  • Запускає Crestodian у контейнері без конфігурації з фейковим Claude CLI у PATH і перевіряє, що fuzzy planner fallback транслюється в audited typed config write.
• Crestodian first-run Docker smoke: pnpm test:docker:crestodian-first-run
  • Починає з порожнього OpenClaw state dir, перевіряє сучасний onboard Crestodian entrypoint, застосовує setup/model/agent/Discord plugin + SecretRef writes, валідує конфігурацію й перевіряє audit entries. Той самий шлях налаштування Ring 0 також покрито в QA Lab через pnpm openclaw qa suite --scenario crestodian-ring-zero-setup.
• Moonshot/Kimi cost smoke: з установленим MOONSHOT_API_KEY запустіть openclaw models list --provider moonshot --json, потім запустіть ізольований openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json проти moonshot/kimi-k2.6. Перевірте, що JSON повідомляє Moonshot/K2.6 і assistant transcript зберігає нормалізований usage.cost.

QA-специфічні ранери

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

CI запускає QA Lab у виділених workflow. Agentic parity вкладено під QA-Lab - All Lanes і release validation, а не в окремий PR workflow. Широка валідація має використовувати Full Release Validation з rerun_group=qa-parity або QA-групу release-checks. Стабільні/default release checks тримають exhaustive live/Docker soak за run_release_soak=true; профіль full примусово вмикає soak. QA-Lab - All Lanes запускається щоночі на main і з manual dispatch з mock parity lane, live Matrix lane, Convex-managed live Telegram lane і Convex-managed live Discord lane як паралельними jobs. Scheduled QA і release checks явно передають Matrix --profile fast, тоді як Matrix CLI і manual workflow input за замовчуванням залишаються all; manual dispatch може шардити all у transport, media, e2ee-smoke, e2ee-deep і e2ee-cli jobs. OpenClaw Release Checks запускає parity плюс fast Matrix і Telegram lanes перед release approval, використовуючи mock-openai/gpt-5.5 для release transport checks, щоб вони залишалися детермінованими й уникали звичайного startup provider-plugin. Ці live transport gateways вимикають memory search; поведінка memory залишається покритою QA parity suites.

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

• pnpm openclaw qa suite
  • Запускає QA-сценарії з репозиторію безпосередньо на хості.
  • Записує артефакти верхнього рівня qa-evidence.json, qa-suite-summary.json і qa-suite-report.md для вибраного набору сценаріїв, зокрема вибірки змішаних потоків, Vitest і Playwright-сценаріїв.
  • Коли запускається через pnpm openclaw qa run --qa-profile <profile>, вбудовує scorecard вибраного профілю таксономії в той самий qa-evidence.json. smoke-ci записує скорочені докази, що встановлює evidenceMode: "slim" і пропускає execution для кожного запису. release охоплює підібрану частину готовності до релізу; all вибирає кожну активну категорію зрілості та призначений для явних запусків workflow QA Profile Evidence, коли потрібен повний артефакт scorecard.
  • За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими Gateway workers. qa-channel за замовчуванням має паралельність 4 (обмежену кількістю вибраних сценаріїв). Використовуйте --concurrency <count>, щоб налаштувати кількість workers, або --concurrency 1 для старішого послідовного lane.
  • Завершується з ненульовим кодом, якщо будь-який сценарій не вдається. Використовуйте --allow-failures, коли потрібні артефакти без коду завершення з помилкою.
  • Підтримує режими провайдера live-frontier, mock-openai і aimock. aimock запускає локальний сервер провайдера на основі AIMock для експериментального покриття fixture і protocol-mock без заміни lane mock-openai, що враховує сценарії.
• pnpm openclaw qa coverage --match <query>
  • Шукає ID сценаріїв, заголовки, surfaces, coverage IDs, docs refs, code refs, плагіни й вимоги до провайдера, а потім виводить відповідні suite targets.
  • Використовуйте це перед запуском QA Lab, коли ви знаєте змінювану поведінку або шлях до файлу, але не найменший сценарій. Це лише рекомендація; все одно вибирайте mock, live, Multipass, Matrix або transport proof на основі поведінки, яку змінюють.
• pnpm test:plugins:kitchen-sink-live
  • Запускає live-ланцюжок OpenAI Kitchen Sink plugin через QA Lab. Він встановлює зовнішній пакет Kitchen Sink, перевіряє інвентар surface plugin SDK, зондує /healthz і /readyz, записує докази CPU/RSS Gateway, запускає live-хід OpenAI і перевіряє adversarial diagnostics. Потребує live-автентифікації OpenAI, наприклад OPENAI_API_KEY. У hydrated Testbox sessions він автоматично підключає Testbox live-auth profile, коли наявний helper openclaw-testbox-env.
• pnpm test:gateway:cpu-scenarios
  • Запускає startup 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.
  • Використовує зібрані артефакти dist; спочатку запустіть build, якщо checkout ще не має свіжого runtime-виводу.
• pnpm openclaw qa suite --runner multipass
  • Запускає той самий QA suite всередині одноразової Linux VM Multipass.
  • Зберігає ту саму поведінку вибору сценаріїв, що й qa suite на хості.
  • Повторно використовує ті самі прапорці вибору провайдера/моделі, що й qa suite.
  • Live-запуски передають підтримувані вхідні дані QA auth, практичні для guest: provider keys на основі env, шлях до QA live provider config і CODEX_HOME, коли він наявний.
  • Output dirs мають залишатися під коренем репозиторію, щоб guest міг записувати назад через змонтований workspace.
  • Записує звичайний QA report + summary, а також журнали Multipass у .artifacts/qa-e2e/....
• pnpm qa:lab:up
  • Запускає Docker-backed QA site для QA-роботи в операторському стилі.
• pnpm test:docker:npm-onboard-channel-agent
  • Збирає npm tarball з поточного checkout, встановлює його глобально в Docker, запускає неінтерактивний onboarding з OpenAI API-key, налаштовує Telegram за замовчуванням, перевіряє, що packaged plugin runtime завантажується без startup dependency repair, запускає doctor і запускає один локальний хід агента проти mocked OpenAI endpoint.
  • Використовуйте OPENCLAW_NPM_ONBOARD_CHANNEL=discord, щоб запустити той самий packaged-install lane з Discord.
• pnpm test:docker:session-runtime-context
  • Запускає детермінований built-app Docker smoke для transcripts вбудованого runtime context. Він перевіряє, що прихований runtime context OpenClaw зберігається як non-display custom message, а не витікає у видимий user turn, потім seed-ить уражений broken session JSONL і перевіряє, що openclaw doctor --fix переписує його на активну гілку з резервною копією.
• pnpm test:docker:npm-telegram-live
  • Встановлює candidate-пакет OpenClaw у Docker, запускає installed-package onboarding, налаштовує Telegram через встановлений CLI, потім повторно використовує live Telegram QA lane з цим installed package як SUT Gateway.
  • Wrapper монтує лише harness source qa-lab з checkout; встановлений пакет володіє dist, openclaw/plugin-sdk і bundled plugin runtime, щоб lane не змішував plugins поточного checkout із пакетом під тестом.
  • За замовчуванням використовує OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta; встановіть OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz або OPENCLAW_CURRENT_PACKAGE_TGZ, щоб тестувати resolved local tarball замість встановлення з registry.
  • За замовчуванням виводить повторні RTT timing у qa-evidence.json з OPENCLAW_NPM_TELEGRAM_RTT_SAMPLES=20. Перевизначте OPENCLAW_NPM_TELEGRAM_RTT_SAMPLES, OPENCLAW_NPM_TELEGRAM_RTT_TIMEOUT_MS або OPENCLAW_NPM_TELEGRAM_RTT_MAX_FAILURES, щоб налаштувати RTT run. OPENCLAW_NPM_TELEGRAM_RTT_CHECKS приймає comma-separated list ID перевірок Telegram QA для вибірки; коли не встановлено, стандартною RTT-capable check є telegram-mentioned-message-reply.
  • Використовує ті самі 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.
  • Wrapper перевіряє env для Telegram або Convex credentials на хості перед Docker build/install роботою. Встановлюйте OPENCLAW_NPM_TELEGRAM_SKIP_CREDENTIAL_PREFLIGHT=1 лише коли навмисно налагоджуєте pre-credential setup.
  • OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer перевизначає спільну OPENCLAW_QA_CREDENTIAL_ROLE лише для цього lane. Коли вибрано Convex credentials і role не встановлено, wrapper використовує ci в CI та maintainer поза CI.
  • GitHub Actions надає цей lane як manual maintainer workflow NPM Telegram Beta E2E. Він не запускається під час merge. Workflow використовує environment qa-live-shared і Convex CI credential leases.
• GitHub Actions також надає Package Acceptance для side-run product proof проти одного candidate package. Він приймає trusted ref, published npm spec, HTTPS tarball URL плюс SHA-256 або tarball artifact з іншого run, завантажує нормалізований openclaw-current.tgz як package-under-test, а потім запускає наявний Docker E2E scheduler зі smoke, package, product, full або custom lane profiles. Встановіть telegram_mode=mock-openai або live-frontier, щоб запустити Telegram QA workflow проти того самого artifact package-under-test.
  • Latest 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

• Exact tarball URL proof потребує digest і використовує public URL safety policy:

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

• Enterprise/private tarball mirrors використовують явну trusted-source policy:

gh workflow run package-acceptance.yml --ref main \  -f source=trusted-url \  -f trusted_source_id=enterprise-artifactory \  -f package_url=https://packages.example.internal:8443/artifactory/openclaw/openclaw-VERSION.tgz \  -f package_sha256=<sha256> \  -f suite_profile=package

source=trusted-url читає .github/package-trusted-sources.json з trusted workflow ref і не приймає URL credentials або workflow-input private-network bypass. Якщо названа policy оголошує bearer auth, налаштуйте фіксований secret OPENCLAW_TRUSTED_PACKAGE_TOKEN.

• Artifact proof завантажує tarball artifact з іншого Actions run:

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:plugins

  • Пакує та встановлює поточний build OpenClaw у Docker, запускає Gateway з налаштованим OpenAI, а потім вмикає bundled channel/plugins через редагування config.
  • Перевіряє, що setup discovery залишає неналаштовані downloadable plugins відсутніми, перший налаштований doctor repair явно встановлює кожен відсутній downloadable plugin, а другий restart не запускає прихований dependency repair.
  • Також встановлює відому старішу npm baseline, вмикає Telegram перед запуском openclaw update --tag <candidate> і перевіряє, що post-update doctor candidate очищує legacy plugin dependency debris без harness-side postinstall repair.

• pnpm test:parallels:npm-update

  • Запускає native packaged-install update smoke across Parallels guests. Кожна вибрана платформа спочатку встановлює запитаний baseline package, потім запускає встановлену команду openclaw update у тому самому guest і перевіряє installed version, update status, gateway readiness і один локальний хід агента.

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

  • OpenAI lane за замовчуванням використовує openai/gpt-5.5 для live agent-turn proof. Передайте --model <provider/model> або встановіть OPENCLAW_PARALLELS_OPENAI_MODEL, коли навмисно перевіряєте іншу OpenAI model.

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

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

  • Script записує nested lane logs у /tmp/openclaw-parallels-npm-update.*. Перегляньте windows-update.log, macos-update.log або linux-update.log перед тим як припускати, що outer wrapper завис.

  • Windows update може витрачати 10-15 хвилин на post-update doctor і package update work на cold guest; це все ще штатно, коли nested npm debug log просувається.

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

  • Post-update proof запускає звичайний bundled plugin surface, тому що capability facades, як-от speech, image generation і media understanding, завантажуються через bundled runtime APIs, навіть коли сам agent turn перевіряє лише просту text response.

• pnpm openclaw qa aimock

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

• pnpm openclaw qa matrix

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

• pnpm openclaw qa telegram

  • Запускає 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, щоб увімкнути пулові leases.
  • Значення за замовчуванням охоплюють canary, mention gating, command addressing, /status, згадані bot-to-bot replies і core native command replies. Значення за замовчуванням mock-openai також охоплюють детерміновані регресії reply-chain і Telegram final-message streaming. Використовуйте --list-scenarios для необов’язкових probes, як-от session_status.
  • Завершується з ненульовим кодом, коли будь-який сценарій завершується невдало. Використовуйте --allow-failures, коли вам потрібні artifacts без коду виходу, що сигналізує про помилку.
  • Потребує двох окремих ботів в одній приватній групі, причому SUT bot має надавати Telegram username.
  • Для стабільного bot-to-bot observation увімкніть Bot-to-Bot Communication Mode у @BotFather для обох ботів і переконайтеся, що driver bot може спостерігати group bot traffic.
  • Записує Telegram QA report, summary і qa-evidence.json у .artifacts/qa-e2e/.... Сценарії з replies включають RTT від запиту надсилання driver до спостереженої SUT reply.

Mantis Telegram Live — це PR-evidence wrapper навколо цієї lane. Він запускає candidate ref із Telegram обліковими даними, орендованими через Convex, рендерить редагований QA report/evidence bundle у браузері desktop Crabbox, записує MP4 evidence, генерує motion-trimmed GIF, завантажує artifact bundle і публікує inline PR evidence через Mantis GitHub App, коли задано pr_number. Maintainers можуть запустити його з Actions UI через Mantis Scenario (scenario_id: telegram-live) або напряму з коментаря до pull request:

@openclaw-mantis telegram@openclaw-mantis telegram scenario=telegram-status-command@openclaw-mantis telegram scenarios=telegram-status-command,telegram-mentioned-message-reply

Mantis Telegram Desktop Proof — це agentic native Telegram Desktop before/after wrapper для візуального доказу PR. Запустіть його з Actions UI з довільними instructions, через Mantis Scenario (scenario_id: telegram-desktop-proof) або з коментаря PR:

@openclaw-mantis telegram desktop proof

Агент Mantis читає PR, вирішує, яка Telegram-visible behavior доводить зміну, запускає real-user Crabbox Telegram Desktop proof lane на baseline і candidate refs, ітерує, доки native GIFs не стануть корисними, записує paired motionPreview manifest і публікує ту саму 2-column GIF table через Mantis GitHub App, коли задано pr_number.

• pnpm openclaw qa mantis telegram-desktop-builder
  • Орендує або повторно використовує desktop Crabbox Linux, встановлює native Telegram Desktop, налаштовує OpenClaw з орендованим Telegram SUT bot token, запускає Gateway і записує screenshot/MP4 evidence з видимого VNC desktop.
  • За замовчуванням використовує --credential-source convex, щоб workflows потребували лише Convex broker secret. Використовуйте --credential-source env з тими самими змінними OPENCLAW_QA_TELEGRAM_*, що й pnpm openclaw qa telegram.
  • Telegram Desktop усе ще потребує user login/profile. Bot token налаштовує лише OpenClaw. Використовуйте --telegram-profile-archive-env <name> для base64 .tgz profile archive або --keep-lease і один раз увійдіть вручну через VNC.
  • Записує mantis-telegram-desktop-builder-report.md, mantis-telegram-desktop-builder-summary.json, telegram-desktop-builder.png і telegram-desktop-builder.mp4 у output directory.

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

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

Коли для live transport QA увімкнено --credential-source convex (або OPENCLAW_QA_CREDENTIAL_SOURCE=convex), QA lab отримує ексклюзивну lease з пулу на базі Convex, надсилає Heartbeat для цієї lease, доки lane виконується, і звільняє lease під час shutdown. Назва розділу з’явилася до підтримки Discord, Slack і WhatsApp; контракт lease спільний для всіх kinds.

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

• qa/convex-credential-broker/

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

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

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

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

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

Maintainer admin commands (pool add/remove/list) потребують саме OPENCLAW_QA_CONVEX_SECRET_MAINTAINER.

CLI helpers для maintainers:

pnpm openclaw qa credentials doctorpnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.jsonpnpm openclaw qa credentials list --kind telegrampnpm openclaw qa credentials remove --credential-id <credential-id>

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

Контракт endpoint за замовчуванням (OPENCLAW_QA_CONVEX_SITE_URL + /qa-credentials/v1):

• POST /acquire
  • Request: { kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }
  • Success: { status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }
  • Exhausted/retryable: { status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }
• POST /payload-chunk
  • Request: { kind, ownerId, actorRole, credentialId, leaseToken, index }
  • Success: { status: "ok", index, data }
• POST /heartbeat
  • Request: { kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }
  • Success: { status: "ok" } (або порожній 2xx)
• POST /release
  • Request: { kind, ownerId, actorRole, credentialId, leaseToken }
  • Success: { status: "ok" } (або порожній 2xx)
• POST /admin/add (лише maintainer secret)
  • Request: { kind, actorId, payload, note?, status? }
  • Success: { status: "ok", credential }
• POST /admin/remove (лише maintainer secret)
  • Request: { credentialId, actorId }
  • Success: { status: "ok", changed, credential }
  • Active lease guard: { status: "error", code: "LEASE_ACTIVE", ... }
• POST /admin/list (лише maintainer secret)
  • Request: { kind?, status?, includePayload?, limit? }
  • Success: { status: "ok", credentials, count }

Payload shape для Telegram kind:

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

Payload shape для Telegram real-user kind:

• { groupId: string, sutToken: string, testerUserId: string, testerUsername: string, telegramApiId: string, telegramApiHash: string, tdlibDatabaseEncryptionKey: string, tdlibArchiveBase64: string, tdlibArchiveSha256: string, desktopTdataArchiveBase64: string, desktopTdataArchiveSha256: string }
• groupId, testerUserId і telegramApiId мають бути numeric strings.
• tdlibArchiveSha256 і desktopTdataArchiveSha256 мають бути SHA-256 hex strings.
• kind: "telegram-user" зарезервовано для workflow Mantis Telegram Desktop proof. Generic QA Lab lanes не повинні отримувати його.

Broker-validated multi-channel payloads:

• Discord: { guildId: string, channelId: string, driverBotToken: string, sutBotToken: string, sutApplicationId: string, voiceChannelId?: string }
• WhatsApp: { driverPhoneE164: string, sutPhoneE164: string, driverAuthArchiveBase64: string, sutAuthArchiveBase64: string, groupJid?: string }

Slack lanes також можуть орендувати з пулу, але валідація Slack payload наразі живе у Slack QA runner, а не в broker. Використовуйте { channelId: string, driverBotToken: string, sutBotToken: string, sutAppToken: string } для Slack rows.

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

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

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

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

Unit / integration (default)

• Command: pnpm test
• Config: untargeted runs використовують набір shards vitest.full-*.config.ts і можуть розгортати multi-project shards у per-project configs для parallel scheduling
• Files: core/unit inventories у src/**/*.test.ts, packages/**/*.test.ts і test/**/*.test.ts; UI unit tests запускаються у dedicated shard unit-ui
• Scope:
  • Pure unit tests
  • In-process integration tests (Gateway auth, routing, tooling, parsing, config)
  • Детерміновані regressions для відомих bugs
• Expectations:
  • Запускається в CI
  • Не потребує real keys
  • Має бути fast і stable
  • Resolver і public-surface loader tests мають доводити широке fallback behavior api.js і runtime-api.js з generated tiny plugin fixtures, а не real bundled plugin source APIs. Real plugin API loads належать до plugin-owned contract/integration suites.

Політика native dependencies:

• Default test installs пропускають optional native Discord opus builds. Discord voice використовує bundled libopus-wasm, а @discordjs/opus залишається disabled в allowBuilds, щоб local tests і Testbox lanes не компілювали native addon.
• Порівнюйте performance native opus у benchmark repo libopus-wasm, а не в default OpenClaw install/test loops. Не задавайте @discordjs/opus як true у default allowBuilds; це змушує unrelated install/test loops компілювати native code.

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

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

E2E (repo aggregate)

• Команда: pnpm test:e2e
• Scope:
  • Запускає gateway smoke E2E lane
  • Запускає mocked Control UI browser E2E lane
• Очікування:
  • Безпечно для CI і не потребує keys
  • Потребує встановленого Playwright Chromium

E2E (gateway smoke)

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

E2E (Control UI mocked browser)

• Команда: pnpm test:ui:e2e
• Config: test/vitest/vitest.ui-e2e.config.ts
• Файли: ui/src/**/*.e2e.test.ts
• Scope:
  • Запускає Vite Control UI
  • Проганяє реальну сторінку Chromium через Playwright
  • Замінює Gateway WebSocket детермінованими in-browser mocks
• Очікування:
  • Запускається в CI як частина pnpm test:e2e
  • Реальні Gateway, agents або provider keys не потрібні
  • Browser dependency має бути присутня (pnpm --dir ui exec playwright install chromium)

E2E: OpenShell backend smoke

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

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

• Команда: pnpm test:live
• Конфігурація: vitest.live.config.ts
• Файли: src/**/*.live.test.ts, test/**/*.live.test.ts і реальні тести вбудованих Plugin під extensions/
• За замовчуванням: увімкнено через pnpm test:live (встановлює OPENCLAW_LIVE_TEST=1)
• Область:
  • "Чи цей провайдер/модель справді працює сьогодні з реальними обліковими даними?"
  • Виявляти зміни форматів провайдерів, особливості виклику інструментів, проблеми автентифікації та поведінку лімітів частоти
• Очікування:
  • Навмисно не стабільні для CI (реальні мережі, реальні політики провайдерів, квоти, збої)
  • Коштують грошей / використовують ліміти частоти
  • Надавайте перевагу запуску звужених піднаборів замість "усього"
• Реальні запуски використовують уже експортовані ключі API та підготовлені профілі автентифікації.
• За замовчуванням реальні запуски все одно ізолюють HOME і копіюють конфігурацію/матеріали автентифікації в тимчасовий тестовий домашній каталог, щоб модульні фікстури не могли змінити ваш реальний ~/.openclaw.
• Встановлюйте OPENCLAW_LIVE_USE_REAL_HOME=1 лише тоді, коли ви свідомо хочете, щоб реальні тести використовували ваш реальний домашній каталог.
• pnpm test:live за замовчуванням працює в тихішому режимі: він зберігає вивід прогресу [live] ... і приглушує журнали запуску 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) чи перевизначення для окремого реального запуску через OPENCLAW_LIVE_*_KEY; тести повторюють спроби у відповідь на ліміти частоти.
• Вивід прогресу/Heartbeat:
  • Реальні набори тепер виводять рядки прогресу в stderr, щоб довгі виклики провайдерів були помітно активними навіть тоді, коли захоплення консолі Vitest тихе.
  • vitest.live.config.ts вимикає перехоплення консолі Vitest, щоб рядки прогресу провайдера/Gateway одразу транслювалися під час реальних запусків.
  • Налаштовуйте Heartbeat прямих моделей через OPENCLAW_LIVE_HEARTBEAT_MS.
  • Налаштовуйте Heartbeat Gateway/проб через OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS.

Який набір слід запускати?

Скористайтеся цією таблицею рішень:

• Редагування логіки/тестів: запустіть pnpm test (і pnpm test:coverage, якщо змінили багато)
• Зміни мережевої взаємодії Gateway / протоколу WS / спарювання: додайте pnpm test:e2e
• Налагодження "мій бот не працює" / збоїв, специфічних для провайдера / виклику інструментів: запустіть звужений pnpm test:live

Реальні (мережеві) тести

Для матриці реальних моделей, димових перевірок бекенда CLI, димових перевірок ACP, стенда сервера застосунку Codex і всіх реальних тестів медіапровайдерів (Deepgram, BytePlus, ComfyUI, зображення, музика, відео, медіастенд) - а також обробки облікових даних для реальних запусків - дивіться Тестування реальних наборів. Для спеціального контрольного списку оновлень і перевірки Plugin дивіться Тестування оновлень і Plugin.

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

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

• Ранери реальних моделей: test:docker:live-models і test:docker:live-gateway запускають лише відповідний реальний файл профілю-ключа всередині Docker-образу репозиторію (src/agents/models.profiles.live.test.ts і src/gateway/gateway-models.profiles.live.test.ts), монтувавши ваш локальний каталог конфігурації, робочий простір і необов'язковий файл env профілю. Відповідні локальні точки входу: test:live:models-profiles і test:live:gateway-profiles.
• Реальні Docker-ранери за потреби зберігають власні практичні обмеження: test:docker:live-models за замовчуванням використовує кураторський підтримуваний набір із високим сигналом, а 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. Встановіть OPENCLAW_LIVE_MAX_MODELS або env-змінні Gateway, коли явно хочете менше обмеження або ширше сканування.
• test:docker:all один раз збирає реальний Docker-образ через test:docker:live-build, один раз пакує OpenClaw як npm tarball через scripts/package-openclaw-for-docker.mjs, а потім збирає/повторно використовує два образи scripts/e2e/Dockerfile. Базовий образ є лише Node/Git-ранером для шляхів встановлення/оновлення/залежностей Plugin; ці шляхи монтують попередньо зібраний 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 керує слотами процесів, тоді як ресурсні обмеження не дають важким реальним, npm-install і багатосервісним шляхам стартувати всім одночасно. Якщо один шлях важчий за активні обмеження, планувальник усе ще може запустити його, коли пул порожній, а потім тримає його єдиним активним, доки знову не стане доступна місткість. Значення за замовчуванням: 10 слотів, OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9, OPENCLAW_DOCKER_ALL_NPM_LIMIT=5 і OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7; налаштовуйте OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT або OPENCLAW_DOCKER_ALL_DOCKER_LIMIT лише тоді, коли Docker-хост має більше запасу ресурсів. Ранер за замовчуванням виконує Docker-передперевірку, видаляє застарілі 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-план для вибраних шляхів, потреб у пакеті/образі та облікових даних.
• Приймання пакета - це GitHub-нативний пакетний шлюз для "чи цей встановлюваний tarball працює як продукт?" Він визначає один пакет-кандидат із source=npm, source=ref, source=url або source=artifact, завантажує його як package-under-test, а потім запускає повторно використовувані Docker E2E-шляхи проти саме цього tarball замість повторного пакування вибраного ref. Профілі впорядковані за широтою: smoke, package, product і full. Дивіться Тестування оновлень і Plugin щодо контракту пакета/оновлення/Plugin, матриці витривалості для опублікованого оновлення, типових значень релізу та тріажу збоїв.
• Перевірки збирання та релізу запускають scripts/check-cli-bootstrap-imports.mjs після tsdown. Захист обходить статичний зібраний граф від dist/entry.js і dist/cli/run-main.js і завершується з помилкою, якщо запуск до диспетчеризації команди імпортує залежності пакета, як-от Commander, інтерфейс запитів, undici або логування, до диспетчеризації команди; він також утримує вбудований фрагмент запуску Gateway в межах бюджету й відхиляє статичні імпорти відомих холодних шляхів Gateway. Димова перевірка упакованого CLI також охоплює кореневу довідку, довідку onboard, довідку doctor, status, схему config і команду списку моделей.
• Застаріла сумісність Приймання пакета обмежена 2026.4.25 (включно з 2026.4.25-beta.*). До цієї межі стенд допускає лише прогалини метаданих у відвантажених пакетах: пропущені приватні записи інвентаря QA, відсутній gateway install --wrapper, відсутні patch-файли у git-фікстурі, отриманій із tarball, відсутній збережений update.channel, застарілі розташування install-record Plugin, відсутнє збереження install-record маркетплейсу та міграцію метаданих конфігурації під час plugins update. Для пакетів після 2026.4.25 ці шляхи є суворими збоями.
• Контейнерні димові ранери: test:docker:openwebui, test:docker:onboard, test:docker:npm-onboard-channel-agent, test:docker:release-user-journey, test:docker:release-typed-onboarding, test:docker:release-media-memory, test:docker:release-upgrade-user-journey, test:docker:release-plugin-marketplace, test:docker:skill-install, 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:agent-bundle-mcp-tools, test:docker:cron-mcp-cleanup, test:docker:plugins, test:docker:plugin-update, test:docker:plugin-lifecycle-matrix і test:docker:config-reload завантажують один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня.
• Docker/Bash E2E-шляхи, які встановлюють упакований tarball OpenClaw через scripts/lib/openclaw-e2e-instance.sh, обмежують npm install через OPENCLAW_E2E_NPM_INSTALL_TIMEOUT (за замовчуванням 600s; встановіть 0, щоб вимкнути обгортку для налагодження).

Docker-ранери реальних моделей також bind-монтують лише потрібні домашні каталоги автентифікації CLI (або всі підтримувані, коли запуск не звужено), а потім копіюють їх у домашній каталог контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени без зміни сховища автентифікації хоста:

• Прямі моделі: pnpm test:docker:live-models (скрипт: scripts/test-live-models-docker.sh)

• Димова перевірка ACP bind: pnpm test:docker:live-acp-bind (скрипт: scripts/test-live-acp-bind-docker.sh; за замовчуванням охоплює 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 + агент розробки: pnpm test:docker:live-gateway (скрипт: scripts/test-live-gateway-models-docker.sh)

• Димові перевірки спостережуваності: pnpm qa:otel:smoke, pnpm qa:prometheus:smoke і pnpm qa:observability: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)

• Димова перевірка онбордингу/каналу/агента з npm tarball: pnpm test:docker:npm-onboard-channel-agent встановлює упакований tarball OpenClaw глобально в Docker, конфігурує OpenAI через онбординг із посиланням на env і за замовчуванням Telegram, запускає doctor і виконує один імітований хід агента OpenAI. Повторно використовуйте попередньо зібраний tarball через OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz, пропускайте перебудову на хості через OPENCLAW_NPM_ONBOARD_HOST_BUILD=0 або перемикайте канал через OPENCLAW_NPM_ONBOARD_CHANNEL=discord чи OPENCLAW_NPM_ONBOARD_CHANNEL=slack.

• Смоук-тест користувацького шляху релізу: pnpm test:docker:release-user-journey глобально встановлює запакований tarball OpenClaw у чистому домашньому каталозі Docker, запускає onboarding, налаштовує імітований провайдер OpenAI, виконує хід агента, встановлює/видаляє зовнішні plugins, налаштовує ClickClack на локальну фікстуру, перевіряє вихідні/вхідні повідомлення, перезапускає Gateway і запускає doctor.

• Смоук-тест типізованого onboarding релізу: pnpm test:docker:release-typed-onboarding встановлює запакований tarball, проводить openclaw onboard через справжній TTY, налаштовує OpenAI як провайдера з посиланням на env, перевіряє, що сирий ключ не зберігається, і запускає імітований хід агента.

• Смоук-тест медіа/пам’яті релізу: pnpm test:docker:release-media-memory встановлює запакований tarball, перевіряє розуміння зображення з PNG-вкладення, вихід генерації зображення, сумісний з OpenAI, пригадування з пошуку пам’яті та збереження пригадування після перезапуску Gateway.

• Смоук-тест користувацького шляху оновлення релізу: pnpm test:docker:release-upgrade-user-journey за замовчуванням встановлює найновіший опублікований baseline, старіший за tarball кандидата, налаштовує стан provider/plugin/ClickClack на опублікованому пакеті, оновлює до tarball кандидата, а потім повторно запускає основний шлях agent/plugin/channel. Якщо старішого опублікованого baseline немає, він повторно використовує версію кандидата. Перевизначте baseline за допомогою OPENCLAW_RELEASE_UPGRADE_BASELINE_SPEC=openclaw@<version>.

• Смоук-тест marketplace Plugin релізу: pnpm test:docker:release-plugin-marketplace встановлює з локальної fixture marketplace, оновлює встановлений plugin, видаляє його та перевіряє, що CLI plugin зникає разом з очищеними метаданими встановлення.

• Смоук-тест встановлення Skill: pnpm test:docker:skill-install глобально встановлює запакований tarball OpenClaw у Docker, вимикає встановлення завантажених архівів у конфігурації, визначає поточний live slug skill ClawHub із пошуку, встановлює його через openclaw skills install і перевіряє встановлений skill разом із метаданими походження/lock .clawhub.

• Смоук-тест перемикання каналу оновлень: pnpm test:docker:update-channel-switch глобально встановлює запакований tarball OpenClaw у Docker, перемикається з package stable на git dev, перевіряє збережений канал і роботу Plugin після оновлення, потім перемикається назад на package stable і перевіряє статус оновлення.

• Смоук-тест виживання після оновлення: pnpm test:docker:upgrade-survivor встановлює запакований tarball OpenClaw поверх брудної fixture старого користувача з агентами, конфігурацією каналу, allowlists Plugin, застарілим станом залежностей Plugin і наявними файлами workspace/session. Він запускає package update плюс неінтерактивний doctor без live provider або ключів каналу, потім запускає loopback Gateway і перевіряє збереження config/state, а також бюджети startup/status.

• Смоук-тест виживання після опублікованого оновлення: pnpm test:docker:published-upgrade-survivor за замовчуванням встановлює openclaw@latest, засіває реалістичні файли наявного користувача, налаштовує цей baseline за допомогою вбудованого рецепта команд, валідовує отриману конфігурацію, оновлює це опубліковане встановлення до tarball кандидата, запускає неінтерактивний doctor, записує .artifacts/upgrade-survivor/summary.json, потім запускає loopback Gateway і перевіряє налаштовані intents, збереження стану, startup, /healthz, /readyz і бюджети статусу RPC. Перевизначте один baseline за допомогою OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC, попросіть агрегований scheduler розгорнути точні локальні baselines за допомогою OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS, наприклад openclaw@2026.5.2 openclaw@2026.4.23 openclaw@2026.4.15, і розгорніть fixtures у формі issues за допомогою OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS, наприклад reported-issues; набір reported-issues містить configured-plugin-installs для автоматичного відновлення встановлення зовнішнього Plugin OpenClaw. Package Acceptance надає їх як published_upgrade_survivor_baseline, published_upgrade_survivor_baselines і published_upgrade_survivor_scenarios, розв’язує meta baseline tokens, наприклад last-stable-4 або all-since-2026.4.23, а Full Release Validation розгортає package gate release-soak до last-stable-4 2026.4.23 2026.5.2 2026.4.15 плюс reported-issues.

• Смоук-тест runtime context сесії: pnpm test:docker:session-runtime-context перевіряє збереження прихованого transcript runtime context, а також відновлення doctor для зачеплених дубльованих гілок prompt-rewrite.

• Смоук-тест глобального встановлення Bun: bash scripts/e2e/bun-global-install-smoke.sh пакує поточне дерево, встановлює його через bun install -g в ізольованому домашньому каталозі та перевіряє, що 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.

• Смоук-тест Docker installer: bash scripts/test-install-sh-docker.sh спільно використовує один npm cache для своїх root, update і direct-npm containers. Смоук-тест update за замовчуванням використовує npm latest як stable baseline перед оновленням до 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, щоб повторно використовувати cache root/update/direct-npm під час локальних повторних запусків.

• Install Smoke CI пропускає дубльоване глобальне оновлення direct-npm за допомогою OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1; запускайте script локально без цього env, коли потрібне покриття прямого npm install -g.

• Смоук-тест CLI видалення агентами спільного workspace: pnpm test:docker:agents-delete-shared-workspace (script: scripts/e2e/agents-delete-shared-workspace-docker.sh) за замовчуванням збирає root Dockerfile image, засіває двох агентів з одним workspace в ізольованому домашньому каталозі container, запускає 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 (script: scripts/e2e/gateway-network-docker.sh)

• Смоук-тест snapshot Browser CDP: pnpm test:docker:browser-cdp-snapshot (script: scripts/e2e/browser-cdp-snapshot-docker.sh) збирає source E2E image плюс Chromium layer, запускає Chromium із raw CDP, запускає browser doctor --deep і перевіряє, що CDP role snapshots охоплюють URLs links, cursor-promoted clickables, iframe refs і frame metadata.

• Регресійний тест мінімального reasoning OpenAI Responses web_search: pnpm test:docker:openai-web-search-minimal (script: scripts/e2e/openai-web-search-minimal-docker.sh) запускає імітований сервер OpenAI через Gateway, перевіряє, що web_search підвищує reasoning.effort з minimal до low, потім примусово відхиляє provider schema і перевіряє, що raw detail з’являється в logs Gateway.

• Міст MCP channel (засіяний Gateway + stdio bridge + raw Claude notification-frame smoke): pnpm test:docker:mcp-channels (script: scripts/e2e/mcp-channels-docker.sh)

• MCP tools bundle OpenClaw (справжній stdio MCP server + вбудований smoke allow/deny профілю OpenClaw): pnpm test:docker:agent-bundle-mcp-tools (script: scripts/e2e/agent-bundle-mcp-tools-docker.sh)

• Очищення Cron/subagent MCP (справжній Gateway + teardown stdio MCP child після ізольованих запусків cron і одноразового subagent): pnpm test:docker:cron-mcp-cleanup (script: scripts/e2e/cron-mcp-cleanup-docker.sh)

• Plugins (смоук-тест install/update для local path, file:, npm registry з hoisted dependencies, malformed npm package metadata, git moving refs, ClawHub kitchen-sink, marketplace updates і Claude-bundle enable/inspect): pnpm test:docker:plugins (script: scripts/e2e/plugins-docker.sh) Задайте OPENCLAW_PLUGINS_E2E_CLAWHUB=0, щоб пропустити блок ClawHub, або перевизначте стандартну пару package/runtime kitchen-sink за допомогою OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC і OPENCLAW_PLUGINS_E2E_CLAWHUB_ID. Без OPENCLAW_CLAWHUB_URL/CLAWHUB_URL тест використовує герметичний локальний fixture server ClawHub.

• Смоук-тест незмінного оновлення Plugin: pnpm test:docker:plugin-update (script: scripts/e2e/plugin-update-unchanged-docker.sh)

• Смоук-тест матриці життєвого циклу Plugin: pnpm test:docker:plugin-lifecycle-matrix встановлює запакований tarball OpenClaw у порожній container, встановлює npm plugin, перемикає enable/disable, upgrade і downgrade через локальний npm registry, видаляє встановлений code, потім перевіряє, що uninstall все ще видаляє stale state, записуючи RSS/CPU metrics для кожної фази lifecycle.

• Смоук-тест metadata reload config: pnpm test:docker:config-reload (script: scripts/e2e/config-reload-source-docker.sh)

• Plugins: pnpm test:docker:plugins охоплює смоук-тест install/update для local path, file:, npm registry з hoisted dependencies, git moving refs, fixtures ClawHub, marketplace updates і Claude-bundle enable/inspect. pnpm test:docker:plugin-update охоплює поведінку unchanged update для встановлених plugins. pnpm test:docker:plugin-lifecycle-matrix охоплює відстежувані за ресурсами install, enable, disable, upgrade, downgrade і missing-code uninstall npm plugin.

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

OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local pnpm test:docker:e2e-buildOPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels

Перевизначення image, специфічні для suite, як-от OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE, усе ще мають пріоритет, коли задані. Коли OPENCLAW_SKIP_DOCKER_BUILD=1 вказує на віддалений shared image, scripts завантажують його, якщо він ще не є локальним. QR і installer Docker tests зберігають власні Dockerfiles, бо вони валідовують поведінку package/install, а не спільний runtime зібраної app.

Запускачі Docker для live-моделей також монтують поточний checkout у режимі лише для читання та розгортають його в тимчасовий робочий каталог усередині контейнера. Це зберігає runtime-образ компактним, водночас запускаючи Vitest саме на ваших локальних source/config. Етап розгортання пропускає великі локальні кеші та вихідні файли збірки застосунків, як-от .pnpm-store, .worktrees, __openclaw_vitest__, а також локальні для застосунку каталоги .build або вихідні каталоги Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання артефактів, специфічних для машини. Вони також задають OPENCLAW_SKIP_CHANNELS=1, щоб live-перевірки Gateway не запускали реальних працівників каналів Telegram/Discord/тощо всередині контейнера. test:docker:live-models все ще запускає pnpm test:live, тому також передавайте OPENCLAW_LIVE_GATEWAY_*, коли потрібно звузити або виключити live-покриття Gateway з цієї Docker-смуги. test:docker:openwebui — це суміснісний smoke-тест вищого рівня: він запускає контейнер OpenClaw Gateway з увімкненими HTTP-ендпоїнтами, сумісними з OpenAI, запускає закріплений контейнер Open WebUI проти цього Gateway, входить через Open WebUI, перевіряє, що /api/models показує openclaw/default, а потім надсилає реальний chat-запит через проксі Open WebUI /api/chat/completions. Задайте OPENWEBUI_SMOKE_MODE=models для CI-перевірок release-шляху, які мають зупинятися після входу в Open WebUI та виявлення моделі, не очікуючи завершення live-моделі. Перший запуск може бути помітно повільнішим, оскільки Docker може потребувати завантажити образ Open WebUI, а Open WebUI може потребувати завершити власне налаштування cold-start. Ця смуга очікує придатний ключ live-моделі. Надайте його через середовище процесу, підготовлені auth-профілі або явний OPENCLAW_PROFILE_FILE. Успішні запуски друкують невелике JSON-навантаження на кшталт { "ok": true, "model": "openclaw/default", ... }. test:docker:mcp-channels навмисно детермінований і не потребує реального облікового запису Telegram, Discord або iMessage. Він завантажує засіяний контейнер Gateway, запускає другий контейнер, який породжує openclaw mcp serve, а потім перевіряє маршрутизоване виявлення розмов, читання transcript, метадані attachment, поведінку live-черги подій, маршрутизацію outbound send, а також channel + permission notifications у стилі Claude через реальний stdio MCP bridge. Перевірка notifications безпосередньо інспектує сирі stdio MCP frames, тож smoke перевіряє те, що bridge фактично випромінює, а не лише те, що випадково показує конкретний client SDK. test:docker:agent-bundle-mcp-tools детермінований і не потребує live ключа моделі. Він збирає Docker-образ репозиторію, запускає реальний stdio MCP probe server усередині контейнера, матеріалізує цей сервер через вбудований OpenClaw bundle MCP runtime, виконує tool, а потім перевіряє, що coding і messaging зберігають tools bundle-mcp, тоді як minimal і tools.deny: ["bundle-mcp"] їх фільтрують. test:docker:cron-mcp-cleanup детермінований і не потребує live model key. Він запускає засіяний Gateway із реальним stdio MCP probe server, виконує ізольований cron turn і одноразовий дочірній turn sessions_spawn, а потім перевіряє, що дочірній MCP-процес завершується після кожного запуску.

Ручний ACP smoke-тест thread простою мовою (не CI):

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

Корисні env vars:

• OPENCLAW_CONFIG_DIR=... (за замовчуванням: ~/.openclaw) монтується до /home/node/.openclaw
• OPENCLAW_WORKSPACE_DIR=... (за замовчуванням: ~/.openclaw/workspace) монтується до /home/node/.openclaw/workspace
• OPENCLAW_PROFILE_FILE=... монтується й підвантажується перед запуском tests
• OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1 для перевірки лише env vars, підвантажених із 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/... перед початком tests
  • Default dirs: .minimax
  • Default 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 у повторних запусках, які не потребують rebuild
• OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 для гарантії, що creds надходять зі сховища profiles (а не з env)
• OPENCLAW_OPENWEBUI_MODEL=... для вибору моделі, яку Gateway показує для Open WebUI smoke
• OPENCLAW_OPENWEBUI_PROMPT=... для перевизначення nonce-check prompt, який використовує Open WebUI smoke
• OPENWEBUI_IMAGE=... для перевизначення закріпленого Open WebUI image tag

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

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

Offline regression (CI-safe)

Це регресії "real pipeline" без реальних 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, пише config + auth enforced): src/gateway/gateway.test.ts (case: "runs wizard over ws and writes auth token config")

Agent reliability evals (skills)

У нас уже є кілька CI-safe tests, які поводяться як "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):

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

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

• Scenario runner з mock providers для перевірки tool calls + order, читання skill files і session wiring.
• Невеликий suite сценаріїв, сфокусованих на skills (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-смуга pnpm test навмисно пропускає ці спільні 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 - базова shape 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 - shape 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 shape/interface
• wizard - Setup wizard

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

• Після зміни plugin-sdk exports або subpaths
• Після додавання або модифікації channel чи provider plugin
• Після refactoring plugin registration або discovery

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

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

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

• Додайте CI-safe regression, якщо можливо (mock/stub provider або зафіксуйте точне 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 виводить один sampled target на клас SecretRef із registry metadata (listSecretTargetRegistryEntries()), а потім перевіряє, що traversal-segment exec ids відхиляються.
  • Якщо ви додаєте нову includeInPlan SecretRef target family у src/secrets/target-registry-data.ts, оновіть classifyTargetClass у цьому test. Test навмисно падає на unclassified target ids, щоб нові classes не могли бути мовчки пропущені.

Пов’язане

• Testing live
• Testing updates and plugins
• CI