Тести

• Повний набір для тестування (набори тестів, перевірка наживо, Docker): Тестування
• Перевірка оновлень і пакетів плагінів: Тестування оновлень і плагінів

Типові налаштування агента

Сеанси агента запускають локально один або кілька цільових тестів і швидкі статичні перевірки лише для довіреного вихідного коду та за наявності готових установлених залежностей. Ніколи не виконуйте локально інструменти з недовіреного репозиторію. Більші набори тестів, перевірки змін із розпаралелюванням перевірки типів/лінтингу, збірки, Docker, конвеєри пакетів, E2E, перевірка наживо та кросплатформна перевірка виконуються віддалено через Crabbox. Для ресурсомістких перевірок від довірених супровідників типовим є Blacksmith Testbox. Налаштований робочий процес Testbox завантажує облікові дані, тому недовірений код учасника або форка натомість повинен використовувати CI форка без секретів або санітизований прямий AWS Crabbox.

Не виконуйте попередній прогрів для запланованої роботи. Отримуйте середовище ліниво, коли перша ресурсомістка команда готова, повторно використовуйте повернений ідентифікатор tbx_... для наступних ресурсомістких команд, синхронізуйте поточний робочий каталог під час кожного запуску та зупиняйте його перед передаванням роботи.

Після першого успішного повторного використання обгортка записує базовий відбиток оренди, відбиток залежностей і відбиток робочого процесу Testbox у .crabbox/testbox-leases/. Зміни лише у вихідному коді дають змогу й надалі використовувати прогріте середовище. Зміна бази злиття, файла блокування, вхідних даних менеджера пакетів, обгортки або робочого процесу Testbox спричиняє безпечну відмову та вимагає нової оренди. Під час кожного запуску поточний робочий каталог усе одно синхронізується. OPENCLAW_TESTBOX_ALLOW_STALE=1 призначено лише для навмисної діагностики, а не для перевірки релізу.

Наведені нижче команди локального тестування призначені для робочих процесів людей і обмеженої перевірки агентом. Про недоступність віддаленого постачальника слід повідомити; вона не дає дозволу непомітно запускати широку локальну перевірку.

Для ресурсомісткої перевірки недовіреного коду ліниво прогрівайте середовище за допомогою --provider aws. Кожен запуск має задавати CRABBOX_ENV_ALLOW=CI, передавати --provider aws --no-hydrate і використовувати новий тимчасовий віддалений HOME перед установленням залежностей або запуском тестів. Використовуйте нову прогріту оренду, виділену для цього недовіреного вихідного коду; ніколи не використовуйте повторно довірену або раніше заповнену обліковими даними оренду. Запускайте встановлений довірений двійковий файл Crabbox із чистого довіреного робочого каталогу main і отримуйте лише віддалений PR за допомогою --fresh-pr; ніколи не виконуйте локально обгортку або конфігурацію з недовіреного робочого каталогу. Скасуйте значення CRABBOX_AWS_INSTANCE_PROFILE і виконайте безпечну відмову, якщо визначене значення aws.instanceProfile не порожнє. Перед будь-яким установленням або тестуванням використовуйте довірені інструменти з абсолютними шляхами, щоб вимагати токен IMDSv2, довести, що кінцева точка облікових даних IAM повертає 404, і перевірити, що віддалене значення git rev-parse HEAD дорівнює повному перевіреному SHA головної версії PR. Прив’яжіть оренду до цього SHA та зупиняйте й повторно прогрівайте її, коли головна версія змінюється. Завантажте довірений scripts/crabbox-untrusted-bootstrap.sh із чистого main разом з --fresh-pr; він установлює закріплені версії Node/pnpm, перевіряє SHA і закріплену версію менеджера пакетів, ізолює HOME, установлює залежності, а потім виконує запитаний тест. Якщо брокер не може довести відсутність ролі або віддаленого PR, використовуйте CI форка без секретів. Не використовуйте hydrate-github, --no-sync або робочий процес Testbox, заповнений обліковими даними. Скасуйте всі перевизначення CRABBOX_TAILSCALE*, примусово задайте --network public --tailscale=false, очистьте прапорці вузла виходу/LAN і вимагайте, щоб crabbox inspect повідомляв про загальнодоступну мережу без стану Tailscale перед завантаженням будь-якого сценарію.

Звичайний порядок локальних дій

1. pnpm test:changed для перевірки Vitest у межах зміненої області.
2. pnpm test <path-or-filter> для одного файла, каталогу або явно заданої цілі.
3. pnpm test лише коли навмисно потрібен повний локальний набір Vitest.

У робочому дереві Codex або пов’язаному/розрідженому робочому каталозі агенти уникають прямого локального запуску pnpm test* / pnpm check* / pnpm crabbox:run:

• Обмежена цільова перевірка з готовими залежностями: node scripts/run-vitest.mjs <path-or-filter>.
• Перевірка змін із попередньою класифікацією: node scripts/check-changed.mjs; плани лише з документацією, без змін і з невеликими змінами метаданих залишаються локальними, коли залежності готові, а ресурсомісткі плани або плани з відсутніми залежностями передаються до Testbox.
• Явна широка перевірка зі збереженою орендою: node scripts/crabbox-wrapper.mjs run --provider blacksmith-testbox ... -- env OPENCLAW_CHECK_CHANGED_REMOTE_CHILD=1 OPENCLAW_CHANGED_LANES_RAW_SYNC=1 corepack pnpm check:changed, щоб pnpm виконувався всередині Testbox.
• Остаточні exitCode обгортки та JSON із часовими показниками є результатом команди. Делегований запуск Blacksmith GitHub Actions може показувати cancelled після успішної команди SSH, оскільки Testbox зупиняється ззовні дії підтримання активності; перевірте підсумок обгортки та вивід команди, перш ніж вважати це помилкою.
• OPENCLAW_HEAVY_CHECK_LOCK_SCOPE=worktree <local-heavy-check command>: зберігає серіалізацію ресурсомістких перевірок у поточному робочому дереві, а не в спільному каталозі Git, для таких команд, як pnpm check:changed і цільовий pnpm test .... Використовуйте це лише на потужних локальних хостах, коли навмисно запускаєте незалежні перевірки в пов’язаних робочих деревах.

Основні команди

Запуски обгортки тестів завершуються коротким підсумком [test] passed|failed|skipped ... in ...; власний рядок тривалості Vitest залишається деталізацією для кожного сегмента.

Спільний стан тестів і допоміжні засоби процесів

• src/test-utils/openclaw-test-state.ts: використовуйте з Vitest, коли тест потребує ізольованого HOME, OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, фікстури конфігурації, робочого простору, каталогу агента або сховища профілів автентифікації.
• pnpm test:env-mutations:report: неблокувальний звіт про тести/тестові інфраструктури, які безпосередньо змінюють HOME, OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, OPENCLAW_WORKSPACE_DIR або пов’язані ключі середовища. Використовуйте його, щоб знаходити кандидатів на міграцію до спільного допоміжного засобу стану тестів.
• test/helpers/openclaw-test-instance.ts: E2E-тести на рівні процесів, яким потрібні запущений Gateway, середовище CLI, захоплення журналів і очищення в одному місці.
• Конвеєри E2E для Docker/Bash, які підключають scripts/lib/docker-e2e-image.sh, можуть передавати docker_e2e_test_state_shell_b64 <label> <scenario> у контейнер і декодувати його за допомогою scripts/lib/openclaw-e2e-instance.sh; сценарії з кількома домашніми каталогами можуть передавати docker_e2e_test_state_function_b64 і викликати openclaw_test_state_create <label> <scenario> у кожному потоці. node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json записує придатний для підключення файл середовища хоста (-- перед create не дає новішим середовищам виконання Node трактувати --env-file як прапорець Node). Конвеєри, які запускають Gateway, можуть підключати scripts/lib/openclaw-e2e-instance.sh для визначення точки входу, запуску імітації OpenAI, запуску на передньому/задньому плані, перевірок готовності, експорту змінних середовища стану, дампів журналів і очищення процесів.

Конвеєри Control UI, TUI та розширень

• Імітовані E2E-тести Control UI: pnpm test:ui:e2e запускає набір Vitest + Playwright, який запускає Vite Control UI та керує реальною сторінкою Chromium, підключеною до імітованого WebSocket Gateway. Тести розміщено в ui/src/**/*.e2e.test.ts; спільні імітації та елементи керування — у ui/src/test-helpers/control-ui-e2e.ts. pnpm test:e2e охоплює цей набір. Запуски агентів за замовчуванням виконуються в Testbox/Crabbox, зокрема для цільової перевірки; використовуйте node scripts/run-vitest.mjs run --config test/vitest/vitest.ui-e2e.config.ts --configLoader runner ui/src/ui/e2e/chat-flow.e2e.test.ts лише як явно вказаний локальний резервний варіант.
• PTY-тести TUI: node scripts/run-vitest.mjs run --config test/vitest/vitest.tui-pty.config.ts запускає швидкий PTY-набір із фіктивним бекендом. OPENCLAW_TUI_PTY_INCLUDE_LOCAL=1 або pnpm tui:pty:test:watch --mode local запускає повільнішу димову перевірку tui --local, яка імітує лише зовнішню кінцеву точку моделі. Перевіряйте стабільний видимий текст або виклики фікстур, а не необроблені знімки ANSI.
• pnpm test:extensions і pnpm test extensions запускають усі шарди розширень/плагінів. Ресурсомісткі плагіни каналів, браузерний плагін і OpenAI запускаються як окремі шарди; інші групи плагінів залишаються згрупованими. pnpm test extensions/<id> запускає набір для одного вбудованого плагіна.
• Файли вихідного коду, що мають сусідні тести, зіставляються з цими тестами перед переходом до ширших glob-шаблонів каталогів. Для змін допоміжних засобів у src/channels/plugins/contracts/test-helpers, src/plugin-sdk/test-helpers і src/plugins/contracts використовується локальний граф імпортів, щоб запускати тести, які їх імпортують, замість широкого запуску кожного шарда, коли шлях залежності визначено точно.
• Цільові каталоги контрактів розгалужуються на відповідні набори контрактів: pnpm test src/channels/plugins/contracts запускає чотири конфігурації контрактів каналів, а pnpm test src/plugins/contracts — конфігурацію контрактів плагінів, оскільки загальні проєкти channels/plugins виключають contracts/**.
• auto-reply розділено на три окремі конфігурації (core, top-level, reply), щоб засіб тестування відповідей не переважав над легшими тестами стану, токенів і допоміжних засобів верхнього рівня.
• Вибрані тестові файли plugin-sdk і commands спрямовуються через окремі легкі набори, які зберігають лише test/setup.ts, залишаючи ресурсомісткі для середовища виконання випадки в наявних наборах.
• Базова конфігурація Vitest за замовчуванням використовує pool: "threads" і isolate: false, а спільний неізольований засіб запуску ввімкнено в усіх конфігураціях репозиторію.
• pnpm test:channels запускає vitest.channels.config.ts.

Gateway та E2E

• Інтеграція Gateway вмикається явно: OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test або pnpm test:gateway.
• pnpm test:e2e: сукупний E2E-набір репозиторію = pnpm test:e2e:gateway && pnpm test:ui:e2e.
• pnpm test:e2e:gateway: наскрізні димові тести Gateway (сполучення кількох екземплярів через WS/HTTP/Node). За замовчуванням використовує threads + isolate: false з адаптивними воркерами в vitest.e2e.config.ts; налаштовуйте за допомогою OPENCLAW_E2E_WORKERS=<n>, докладні журнали — за допомогою OPENCLAW_E2E_VERBOSE=1.
• pnpm test:live: інтерактивні тести провайдерів (Claude/Minimax/DeepSeek/z.ai/тощо, обмежені умовою *.live.test.ts). Потрібні ключі API та LIVE=1 (або OPENCLAW_LIVE_TEST=1), щоб не пропускати тести; докладний вивід — за допомогою OPENCLAW_LIVE_TEST_QUIET=0.

Повний набір Docker (pnpm test:docker:all)

Створює спільний образ для інтерактивних тестів, один раз пакує OpenClaw як tarball npm, створює/повторно використовує базовий образ засобу запуску Node/Git і функціональний образ, який установлює цей tarball у /app, а потім запускає набори димових перевірок Docker через зважений планувальник. scripts/package-openclaw-for-docker.mjs — єдиний локальний/CI-засіб пакування, який перевіряє tarball і dist/postinstall-inventory.json перед їх використанням у Docker.

• Базовий образ (OPENCLAW_DOCKER_E2E_BARE_IMAGE): набори встановлення/оновлення/залежностей плагінів; монтує попередньо створений tarball замість скопійованих вихідних файлів репозиторію.
• Функціональний образ (OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE): набори перевірки звичайної функціональності зібраного застосунку.
• Визначення наборів: scripts/lib/docker-e2e-scenarios.mjs. Планувальник: scripts/lib/docker-e2e-plan.mjs. Виконавець: scripts/test-docker-all.mjs.
• node scripts/test-docker-all.mjs --plan-json виводить керований планувальником план CI (набори, типи образів, потреби в пакетах/образах для інтерактивних тестів, сценарії стану, перевірки облікових даних), не створюючи й не запускаючи Docker.

Параметри планування (змінні середовища, значення за замовчуванням у дужках):

Шаблон змінної середовища для обмежень ресурсів — OPENCLAW_DOCKER_ALL_<RESOURCE>_LIMIT (назва ресурсу у верхньому регістрі, неалфавітно-цифрові символи згорнуто до _).

Інша поведінка: засіб запуску за замовчуванням виконує попередню перевірку Docker, очищає застарілі E2E-контейнери OpenClaw, спільно використовує кеші CLI-інструментів провайдерів між сумісними смугами та припиняє планувати нові смуги зі спільного пулу після першого збою, якщо не задано OPENCLAW_DOCKER_ALL_FAIL_FAST=0. Якщо одна смуга перевищує ефективне обмеження ваги/ресурсів на хості з низьким рівнем паралелізму, вона все одно може запуститися з порожнього пулу й виконуватися окремо, доки не звільнить ресурси. Журнали окремих смуг, summary.json, failures.json і часові показники фаз записуються в .artifacts/docker-tests/<run-id>/; використовуйте pnpm test:docker:timings <summary.json> для перевірки повільних смуг і pnpm test:docker:rerun <run-id|summary.json|failures.json> для виведення недорогих цільових команд повторного запуску.

Важливі смуги Docker

Локальний шлюз PR

Для локальних перевірок перед злиттям/на шлюзі PR виконайте:

• pnpm check:changed
• pnpm check
• pnpm check:test-types
• pnpm build
• pnpm test
• pnpm check:docs

Якщо pnpm test нестабільно завершується на навантаженому хості, повторіть запуск один раз, перш ніж вважати це регресією, а потім ізолюйте проблему за допомогою pnpm test <path/to/test>. Для хостів з обмеженим обсягом пам’яті:

• OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test
• OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed

Інструменти продуктивності тестів

• pnpm test:perf:imports: вмикає звітування Vitest про тривалість імпорту та її деталізацію, водночас і надалі використовуючи маршрутизацію за цільовими смугами для явно заданих файлів/каталогів. pnpm test:perf:imports:changed обмежує таке саме профілювання файлами, зміненими після origin/main.
• pnpm test:perf:changed:bench -- --ref <git-ref> порівнює продуктивність маршрутизованого режиму змін із власним запуском кореневого проєкту для тієї самої зафіксованої різниці git; pnpm test:perf:changed:bench -- --worktree вимірює продуктивність поточного набору змін робочого дерева без попередньої фіксації.
• pnpm test:perf:profile:main записує профіль CPU для головного потоку Vitest (.artifacts/vitest-main-profile); pnpm test:perf:profile:runner записує профілі CPU й купи для засобу запуску модульних тестів (.artifacts/vitest-runner-profile).
• pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json: послідовно запускає кожну кінцеву конфігурацію Vitest повного набору та записує згруповані дані про тривалість, а також JSON-артефакти/журнали для кожної конфігурації. Звіти повного набору за замовчуванням ізолюють файли, щоб збережені графи модулів і паузи збирання сміття від попередніх файлів не зараховувалися до наступних перевірок; передавайте -- --no-isolate лише для навмисного профілювання накопичення у спільному робочому процесі. Агент продуктивності тестів використовує це як базовий рівень перед спробами виправити повільні тести. pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json порівнює згруповані звіти після зміни, спрямованої на підвищення продуктивності.
• Запуски повного набору, розширень і шард із шаблонами включення оновлюють локальні часові дані в .artifacts/vitest-shard-timings.json; наступні запуски цілих конфігурацій використовують ці дані для збалансування повільних і швидких шард. Шарди CI з шаблонами включення додають назву шарда до часового ключа, завдяки чому часові показники відфільтрованих шард залишаються видимими без заміни часових даних цілої конфігурації. Задайте OPENCLAW_TEST_PROJECTS_TIMINGS=0, щоб ігнорувати локальний часовий артефакт.

Тести продуктивності

pnpm tsx scripts/bench-model.ts --runs 10

pnpm test:startup:benchpnpm test:startup:bench:smokepnpm test:startup:bench:savepnpm test:startup:bench:updatepnpm test:startup:bench:checkpnpm tsx scripts/bench-cli-startup.ts --runs 12pnpm tsx scripts/bench-cli-startup.ts --preset real --case status --case gatewayStatus --runs 3pnpm tsx scripts/bench-cli-startup.ts --entry openclaw.mjs --entry-secondary dist/entry.js --preset all

pnpm test:startup:gateway -- --runs 5 --warmup 1pnpm test:startup:gateway -- --case skipChannels --case fiftyPlugins --runs 5node --import tsx scripts/bench-gateway-startup.ts --case default --runs 5 --output .artifacts/gateway-startup.json

pnpm test:restart:gateway -- --case skipChannels --runs 1 --restarts 5pnpm test:restart:gateway -- --case default --runs 3 --restarts 3 --warmup 1

Наскрізне тестування початкового налаштування (Docker)

Необов’язково; потрібне лише для димових тестів початкового налаштування в контейнері. Повний процес холодного запуску в чистому контейнері Linux:

scripts/e2e/onboard-docker.sh

Керує інтерактивним майстром через псевдотермінал, перевіряє файли конфігурації, робочого простору й сеансу, потім запускає Gateway і виконує openclaw health.

Димова перевірка імпорту QR-коду (Docker)

Перевіряє, що підтримуваний допоміжний засіб середовища виконання QR завантажується в підтримуваних середовищах виконання Docker Node (типово Node 24, сумісність із Node 22):

pnpm test:docker:qr

Пов’язані матеріали

• Тестування
• Тестування наживо
• Тестування оновлень і плагінів