--- read_when: - Запуск или исправление тестов summary: Как запускать тесты локально (vitest) и когда использовать режимы force/coverage title: Тесты x-i18n: generated_at: "2026-07-13T20:17:31Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 24 provider: openai source_hash: 63806ea72da1579f4aa0b92c14a6d2d3e67990d6c10cb6d9b1b2bb4a63c8e140 source_path: reference/test.md workflow: 16 --- - Полный набор средств тестирования (наборы тестов, тестирование в реальной среде, Docker): [Тестирование](/ru/help/testing) - Проверка обновлений и пакетов плагинов: [Тестирование обновлений и плагинов](/ru/help/testing-updates-plugins) ## Настройки агента по умолчанию В сеансах агента тесты и ресурсоёмкие проверки выполняются удалённо через Crabbox. Для доверенного кода сопровождающих по умолчанию используется Blacksmith Testbox. Настроенный рабочий процесс Testbox загружает учётные данные, поэтому для недоверенного кода участников или форков необходимо вместо него использовать CI форка без секретов либо защищённый прямой AWS Crabbox. Если для задачи с доверенным кодом, вероятно, потребуются тесты или ресурсоёмкая проверка, немедленно запустите предварительный прогрев в фоновом сеансе командной строки, продолжайте работу во время его выполнения, повторно используйте возвращённый идентификатор `tbx_...`, синхронизируйте текущую рабочую копию при каждом запуске и остановите его перед передачей работы: ```bash 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 ` для одного файла, каталога или явно указанной цели. 3. `pnpm test` только когда вам намеренно требуется полный локальный набор тестов Vitest. В рабочем дереве Codex или связанном/разреженном рабочем дереве агенты избегают прямого локального запуска `pnpm test*` / `pnpm check*` / `pnpm crabbox:run`: - Явно запрошенный пользователем локальный резервный вариант для небольшого файла: `node scripts/run-vitest.mjs `. - Проверки изменений или широкое подтверждение: `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 `: сохраняет сериализацию ресурсоёмких проверок в текущем рабочем дереве, а не в общем каталоге Git, для таких команд, как `pnpm check:changed` и целевой `pnpm test ...`. Используйте это только на высокопроизводительных локальных хостах, когда намеренно запускаете независимые проверки в связанных рабочих деревьях. ## Основные команды Запуски оболочки тестов завершаются краткой сводкой `[test] passed|failed|skipped ... in ...`; собственная строка длительности Vitest остаётся детализацией по сегментам. | Команда | Что она делает | | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pnpm test` | Явные цели в виде файлов или каталогов направляются через ограниченные областию дорожки Vitest. Запуски без указания цели служат подтверждением полного набора: фиксированные группы сегментов разворачиваются в конечные конфигурации для локального параллельного выполнения, а ожидаемое количество сегментов выводится перед запуском. Группа расширений всегда разворачивается в отдельные конфигурации сегментов для каждого расширения вместо одного огромного процесса корневого проекта. | | `pnpm test:changed` | Быстрый интеллектуальный запуск изменённых тестов: точные цели определяются по непосредственным изменениям тестов, соседним файлам `*.test.ts`, явным сопоставлениям исходного кода и локальному графу импортов. Широкие изменения конфигурации или пакетов пропускаются, если они не сопоставляются с конкретными тестами. | | `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` | Явный широкий запуск изменённых тестов; используйте, когда изменение тестовой инфраструктуры, конфигурации или пакета должно задействовать более широкое поведение Vitest для изменённых тестов. | | `pnpm test:force` | Освобождает настроенный порт Gateway OpenClaw (по умолчанию `18789`), затем запускает полный набор с изолированным портом Gateway, чтобы серверные тесты не конфликтовали с работающим экземпляром. | | `pnpm test:coverage` | Формирует информационный отчёт V8 о покрытии для стандартной дорожки модульных тестов (`vitest.unit.config.ts`); пороговые значения покрытия не применяются. | | `pnpm test:coverage:changed` | Покрытие модульными тестами только файлов, изменённых с момента `origin/main`. | | `pnpm changed:lanes` | Показывает архитектурные дорожки, активированные различиями относительно `origin/main`. | | `pnpm check:changed` | По умолчанию вне CI делегирует выполнение Crabbox/Testbox, затем запускает интеллектуальный шлюз проверок изменений внутри удалённого дочернего процесса: форматирование, а также проверку типов, линтинг и защитные команды для затронутых дорожек. Vitest не запускается; для подтверждения тестами используйте `pnpm test:changed` или `pnpm test `. | ## Общее состояние тестов и вспомогательные средства процессов - `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