Тесты

• Полный набор средств тестирования (наборы тестов, тестирование в реальной среде, 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/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 записывает профиль ЦП для основного потока Vitest (.artifacts/vitest-main-profile); pnpm test:perf:profile:runner записывает профили ЦП и кучи для средства запуска модульных тестов (.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

См. также

• Тестирование
• Тестирование в реальной среде
• Тестирование обновлений и плагинов