Тести

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

Типова поведінка агента

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

Якщо завдання з довіреним кодом, імовірно, потребуватиме тестів або ретельного підтвердження, негайно виконайте попередній прогрів у фоновому командному сеансі, продовжуйте працювати, поки він готується, повторно використовуйте повернений ідентифікатор tbx_..., синхронізуйте поточну робочу копію під час кожного запуску та зупиніть його перед передаванням роботи:

node scripts/crabbox-wrapper.mjs warmup --provider blacksmith-testbox --keep --timing-json

Після першого успішного повторного використання обгортка записує базу оренди, залежності та відбиток робочого процесу 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/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: для процесних наскрізних тестів, яким потрібні запущений Gateway, середовище CLI, збирання журналів і очищення в одному місці.
• Смуги наскрізного тестування 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> запускає контур одного вбудованого плагіна.
• Файли вихідного коду із сусідніми тестами зіставляються спочатку з цими тестами, а вже потім — із ширшими шаблонами каталогів. Зміни допоміжного коду в 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/вузлів). Типово використовує 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 як tar-архів npm, збирає або повторно використовує базовий образ виконавця Node/Git і функціональний образ, який установлює цей tar-архів у /app, а потім запускає контури димових Docker-тестів через зважений планувальник. scripts/package-openclaw-for-docker.mjs — єдиний локальний і CI-пакувальник; він перевіряє tar-архів і dist/postinstall-inventory.json, перш ніж Docker їх використає.

• Базовий образ (OPENCLAW_DOCKER_E2E_BARE_IMAGE): контури інсталятора, оновлення та залежностей плагінів; монтує попередньо зібраний tar-архів замість скопійованого вихідного коду репозиторію.
• Функціональний образ (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

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

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