--- read_when: - Запуск або виправлення тестів summary: Як запускати тести локально (vitest) і коли використовувати режими примусового запуску та покриття коду title: Тести x-i18n: generated_at: "2026-07-12T13:47:53Z" model: gpt-5.6 postprocess_version: locale-links-v1 provider: openai source_hash: 63806ea72da1579f4aa0b92c14a6d2d3e67990d6c10cb6d9b1b2bb4a63c8e140 source_path: reference/test.md workflow: 16 --- - Повний набір засобів тестування (набори тестів, перевірки наживо, Docker): [Тестування](/uk/help/testing) - Перевірка оновлень і пакетів плагінів: [Тестування оновлень і плагінів](/uk/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