---
read_when:
    - Запуск або виправлення тестів
summary: Як запускати тести локально (vitest) і коли використовувати режими force/coverage
title: Тести
x-i18n:
    generated_at: "2026-07-16T18:35:42Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 391185703e853bb523e1396eb22da4693d10d47b1644d3b2a51707d329f67dae
    source_path: reference/test.md
    workflow: 16
---

- Повний набір для тестування (набори тестів, перевірка наживо, Docker): [Тестування](/uk/help/testing)
- Перевірка оновлень і пакетів плагінів: [Тестування оновлень і плагінів](/uk/help/testing-updates-plugins)

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

Сеанси агента запускають локально один або кілька цільових тестів і швидкі статичні перевірки лише
для довіреного вихідного коду та за наявності готових установлених залежностей. Ніколи не
виконуйте локально інструменти з недовіреного репозиторію. Більші набори тестів, перевірки змін із
розпаралелюванням перевірки типів/лінтингу, збірки, 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 залишається деталізацією для кожного сегмента.

| Команда                                           | Що вона робить                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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`                              | Класифікує змінені конвеєри перед вибором способу виконання. Плани лише з документацією, без змін і з невеликими змінами метаданих залишаються локальними, коли залежності готові; плани з розпаралелюванням перевірки типів/лінтингу, іншими ресурсомісткими конвеєрами або відсутніми локальними залежностями передаються до Crabbox/Testbox поза CI. Не запускає Vitest; для перевірки тестами використовуйте `pnpm test:changed` або `pnpm test <target>`. |

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

- `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_PARALLELISM`                                                                               | 10                  | Слоти процесів.                                                                                                                                                                                                                                                                             |
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM`                                                                          | 10                  | Чутливий до провайдера кінцевий пул.                                                                                                                                                                                                                                                        |
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT`                                                                                | 9                   | Обмеження ресурсомістких наборів інтерактивних тестів провайдерів.                                                                                                                                                                                                                          |
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT`                                                                                 | 5                   | Обмеження наборів, що використовують ресурси npm.                                                                                                                                                                                                                                           |
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT`                                                                             | 7                   | Обмеження наборів, що використовують ресурси сервісів.                                                                                                                                                                                                                                      |
| `OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT` / `_CODEX_LIMIT` / `_GEMINI_LIMIT` / `_DROID_LIMIT` / `_OPENCODE_LIMIT` | 4                   | Обмеження ресурсомістких наборів для кожного провайдера.                                                                                                                                                                                                                                    |
| `OPENCLAW_DOCKER_ALL_LIVE_OPENAI_LIMIT` / `_TELEGRAM_LIMIT`                                                     | 1                   | Вужчі обмеження для кожного провайдера.                                                                                                                                                                                                                                                     |
| `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` / `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT`                                         | -                   | Перевизначення для потужніших хостів.                                                                                                                                                                                                                                                       |
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS`                                                                          | 2000                | Затримка між запусками наборів, що запобігає локальним сплескам створення в демоні Docker.                                                                                                                                                                                                  |
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`                                                                           | 7,200,000 (120 min) | Резервний час очікування для кожного набору; для вибраних інтерактивних/кінцевих наборів застосовуються жорсткіші обмеження.                                                                                                                                                                 |
| `OPENCLAW_DOCKER_ALL_LIVE_RETRIES`                                                                              | 1                   | Повторні спроби в разі тимчасових збоїв інтерактивних тестів провайдерів.                                                                                                                                                                                                                    |
| `OPENCLAW_DOCKER_ALL_DRY_RUN`                                                                                   | off                 | Вивести маніфест наборів без запуску Docker.                                                                                                                                                                                                                                                |
| `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS`                                                                        | 30000               | Інтервал виведення стану активних наборів.                                                                                                                                                                                                                                                  |
| `OPENCLAW_DOCKER_ALL_TIMINGS`                                                                                   | on                  | Повторно використовувати `.artifacts/docker-tests/lane-timings.json` для впорядкування від найдовшого; установіть `0`, щоб вимкнути.                                                                                                                                                     |
| `OPENCLAW_DOCKER_ALL_LIVE_MODE`                                                                                 | -                   | `skip` лише для детермінованих/локальних наборів, `only` лише для інтерактивних наборів провайдерів. Псевдоніми: `pnpm test:docker:local:all`, `pnpm test:docker:live:all`. Режим лише інтерактивних тестів об’єднує основні й кінцеві інтерактивні набори в один пул із найдовшими завданнями першими, щоб групи провайдерів разом компонували завдання Claude/Codex/Gemini. |
| `OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS`                                                               | 180                 | Час очікування налаштування Docker для бекенду CLI.                                                                                                                                                                                                                                         |

Шаблон змінної середовища для обмежень ресурсів — `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

| Команда                                                                     | Що перевіряє                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| --------------------------------------------------------------------------- |   |
| `pnpm test:docker:browser-cdp-snapshot`                                     | E2E-контейнер вихідного коду на базі Chromium із необробленим CDP та ізольованим Gateway; знімки ролей CDP `browser doctor --deep` містять URL-адреси посилань, клікабельні елементи, підвищені до цього статусу курсором, посилання на iframe та метадані фреймів.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `pnpm test:docker:skill-install`                                            | Установлює запакований tarball у чистому засобі запуску Docker з `skills.install.allowUploadedArchives: false`, визначає поточний ідентифікатор навички за результатами пошуку в реальному ClawHub, установлює її через `openclaw skills install` і перевіряє `SKILL.md`, `.clawhub/origin.json`, `.clawhub/lock.json` та `skills info --json`.                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `pnpm test:docker:live-cli-backend:claude`, `:claude:resume`, `:claude:mcp` | Цільові перевірки активних серверних частин CLI; Gemini має відповідні псевдоніми `:resume` і `:mcp`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `pnpm test:docker:openwebui`                                                | Контейнеризовані OpenClaw + Open WebUI: вхід у систему, перевірка `/api/models`, запуск реального чату через проксі за допомогою `/api/chat/completions`. Потребує придатного ключа активної моделі та завантажує зовнішній образ; на відміну від наборів модульних/E2E-тестів, стабільність у CI не очікується.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `pnpm test:docker:mcp-channels`                                             | Контейнер Gateway із початковими даними та клієнтський контейнер, що запускає `openclaw mcp serve`: маршрутизоване виявлення розмов, читання транскриптів, метадані вкладень, поведінка черги подій у реальному часі, маршрутизація вихідного надсилання та сповіщення в стилі Claude про канал і дозволи через справжній міст stdio (перевірка безпосередньо читає необроблені MCP-фрейми stdio).                                                                                                                                                                                                                                                                                                                                                                                                               |
| `pnpm test:docker:upgrade-survivor`                                         | Установлює запакований tarball поверх забрудненої фікстури старого користувача, виконує оновлення пакета та неінтерактивну діагностику без активних ключів провайдерів/каналів, запускає Gateway на loopback-інтерфейсі й перевіряє збереження агентів, конфігурації каналів, списків дозволених плагінів, файлів робочого простору/сеансів, стану застарілих залежностей плагінів, запуску та стану RPC.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `pnpm test:docker:published-upgrade-survivor`                               | За замовчуванням установлює `openclaw@latest`, створює реалістичні файли наявного користувача, налаштовує систему за допомогою вбудованого рецепта `openclaw config set`, оновлює її до запакованого tarball, запускає неінтерактивну діагностику, записує `.artifacts/upgrade-survivor/summary.json`, перевіряє `/healthz`, `/readyz` і стан RPC. Перевизначте за допомогою `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, розширте матрицю за допомогою `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` або додайте фікстури сценаріїв за допомогою `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues` (містить `configured-plugin-installs` і `stale-source-plugin-shadow`). Package Acceptance надає їх як `published_upgrade_survivor_baseline(s)` / `_scenarios` і визначає метатокени на кшталт `last-stable-4` або `all-since-2026.4.23`. |
| `pnpm test:docker:update-migration`                                         | Стенд перевірки збереження стану після оновлення опублікованої версії у сценарії `plugin-deps-cleanup`, який за замовчуванням починається з `openclaw@2026.4.23`. Робочий процес `Update Migration` розширює його за допомогою `baselines=all-since-2026.4.23`, щоб підтвердити очищення залежностей налаштованих плагінів поза межами Full Release CI.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `pnpm test:docker:plugins`                                                  | Димова перевірка встановлення/оновлення для локального шляху, `file:`, пакетів реєстру npm із піднятими залежностями, рухомих посилань git, фікстур ClawHub, оновлень маркетплейсу та ввімкнення/перевірки пакета Claude.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

## Локальний шлюз 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`, щоб ігнорувати локальний часовий артефакт.

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

<Accordion title="Затримка моделі (scripts/bench-model.ts)">

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

Необов’язкові змінні середовища: `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY`. Запит за замовчуванням: "Відповідай одним словом: ok. Без розділових знаків або додаткового тексту."

</Accordion>

<Accordion title="Запуск CLI (scripts/bench-cli-startup.ts)">

```bash
pnpm test:startup:bench
pnpm test:startup:bench:smoke
pnpm test:startup:bench:save
pnpm test:startup:bench:update
pnpm test:startup:bench:check
pnpm tsx scripts/bench-cli-startup.ts --runs 12
pnpm tsx scripts/bench-cli-startup.ts --preset real --case status --case gatewayStatus --runs 3
pnpm tsx scripts/bench-cli-startup.ts --entry openclaw.mjs --entry-secondary dist/entry.js --preset all
```

Попередньо задані набори:

- `startup`: `--version`, `--help`, `health`, `health --json`, `status --json`, `status`
- `real`: `health`, `status`, `status --json`, `sessions`, `sessions --json`, `tasks --json`, `tasks list --json`, `tasks audit --json`, `agents list --json`, `gateway status`, `gateway status --json`, `gateway health --json`, `config get gateway.port`
- `all`: обидва попередньо задані набори разом

Вивід містить `sampleCount`, середнє значення, p50, p95, мінімум/максимум, розподіл кодів виходу/сигналів і максимальний RSS для кожної команди. `--cpu-prof-dir` / `--heap-prof-dir` записують профілі V8 для кожного запуску.

Збережений вивід: `pnpm test:startup:bench:smoke` записує `.artifacts/cli-startup-bench-smoke.json`; `pnpm test:startup:bench:save` записує `.artifacts/cli-startup-bench-all.json` (`runs=5 warmup=1`). Зафіксований у репозиторії тестовий зразок: `test/fixtures/cli-startup-bench.json`, оновлюється командою `pnpm test:startup:bench:update`, порівнюється командою `pnpm test:startup:bench:check`.

</Accordion>

<Accordion title="Запуск Gateway (scripts/bench-gateway-startup.ts)">

Типово використовується зібрана точка входу CLI за адресою `dist/entry.js`; спочатку виконайте `pnpm build`. Передайте `--entry scripts/run-node.mjs`, щоб натомість вимірювати засіб запуску з вихідного коду, і зберігайте ці результати окремо від базових показників зібраної точки входу.

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

Ідентифікатори випадків: `default`, `skipChannels` (запуск каналів пропущено), `oneInternalHook`, `allInternalHooks`, `fiftyPlugins` (50 плагінів із маніфестами), `fiftyStartupLazyPlugins` (50 плагінів із маніфестами, що ліниво запускаються).

Вивід містить перший вивід процесу, `/healthz`, `/readyz`, час запису журналу про початок прослуховування HTTP, час запису журналу про готовність Gateway, процесорний час, коефіцієнт використання ядер процесора, максимальний RSS, купу, метрики трасування запуску, затримку циклу подій і докладні метрики таблиці пошуку плагінів. Скрипт установлює `OPENCLAW_GATEWAY_STARTUP_TRACE=1` у середовищі дочірнього Gateway.

`/healthz` означає життєздатність (HTTP-сервер може відповідати). `/readyz` означає готовність до використання (супровідні процеси плагінів запуску, канали та критично важливі для готовності завдання після приєднання завершили роботу). Обробники запуску виконуються асинхронно й не входять до гарантії готовності. Час запису журналу про готовність — це внутрішня часова позначка Gateway, корисна для атрибуції на боці процесу, але вона не замінює зовнішню перевірку `/readyz`.

Під час порівняння змін використовуйте вивід JSON або `--output`. Використовуйте `--cpu-prof-dir` лише тоді, коли вивід трасування вказує на імпорт, компіляцію або роботу, обмежену ресурсами процесора, яку неможливо пояснити лише часовими показниками фаз.

</Accordion>

<Accordion title="Перезапуск Gateway (scripts/bench-gateway-restart.ts)">

Лише для macOS і Linux (використовує SIGUSR1 для перезапусків усередині процесу; у Windows негайно завершується з помилкою). Ті самі типові налаштування зібраної точки входу та перевизначення `--entry scripts/run-node.mjs`, що й для запуску Gateway вище.

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

Ідентифікатори випадків: `skipChannels`, `skipChannelsAcpxProbe` (перевірку запуску ACPX увімкнено), `skipChannelsNoAcpxProbe` (перевірку вимкнено), `default`, `fiftyPlugins`.

Вивід містить наступні `/healthz`, наступні `/readyz`, час простою, час готовності після перезапуску, показники процесора, RSS, метрики трасування запуску для процесу-замінника та метрики трасування перезапуску для оброблення сигналу, очікування завершення активної роботи, фаз закриття, наступного запуску, часу готовності й знімків пам’яті. Скрипт установлює `OPENCLAW_GATEWAY_STARTUP_TRACE=1` і `OPENCLAW_GATEWAY_RESTART_TRACE=1`.

Використовуйте цей еталонний тест, коли зміна стосується сигналів перезапуску, обробників закриття, запуску після перезапуску, завершення роботи супровідних процесів, передавання керування службою або готовності після перезапуску. Почніть із `skipChannels`, щоб відокремити механіку Gateway від запуску каналів; використовуйте `default` або випадки з великою кількістю плагінів лише після того, як вузький випадок пояснить шлях перезапуску. Метрики трасування — це підказки для атрибуції, а не остаточні висновки: оцінюйте зміну перезапуску за кількома зразками, відповідним проміжком власника, поведінкою `/healthz`/`/readyz` і видимим для користувача контрактом перезапуску.

</Accordion>

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

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

```bash
scripts/e2e/onboard-docker.sh
```

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

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

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

```bash
pnpm test:docker:qr
```

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

- [Тестування](/uk/help/testing)
- [Тестування наживо](/uk/help/testing-live)
- [Тестування оновлень і плагінів](/uk/help/testing-updates-plugins)
