Testy

• Kompletny zestaw testowy (zestawy, testy na żywo, Docker): Testowanie
• Walidacja aktualizacji i pakietów Pluginów: Testowanie aktualizacji i Pluginów

Domyślne ustawienia agenta

Sesje agentów uruchamiają testy i walidację wymagającą dużej mocy obliczeniowej zdalnie za pośrednictwem Crabbox. Dla zaufanego kodu opiekunów domyślnie używany jest Blacksmith Testbox. Skonfigurowany przepływ pracy Testbox wczytuje dane uwierzytelniające, dlatego niezaufany kod współtwórców lub forków musi zamiast niego korzystać z CI forka bez sekretów albo oczyszczonego, bezpośredniego środowiska AWS Crabbox.

Jeśli zadanie dotyczące zaufanego kodu prawdopodobnie będzie wymagać testów lub rozbudowanych dowodów, natychmiast rozpocznij wstępne rozgrzewanie w sesji poleceń działającej w tle, kontynuuj pracę podczas przygotowywania środowiska, ponownie wykorzystuj zwrócony identyfikator tbx_..., synchronizuj bieżącą kopię roboczą przy każdym uruchomieniu i zatrzymaj środowisko przed przekazaniem pracy:

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

Po pierwszym udanym ponownym użyciu wrapper zapisuje bazę dzierżawy, zależności i odcisk palca przepływu pracy Testbox w katalogu .crabbox/testbox-leases/. Zmiany wyłącznie w kodzie źródłowym nadal korzystają z rozgrzanego środowiska. Zmieniona baza scalania, plik blokady, dane wejściowe menedżera pakietów, wrapper lub przepływ pracy Testbox powodują bezpieczne przerwanie i wymagają nowej dzierżawy. Każde uruchomienie nadal synchronizuje bieżącą kopię roboczą. OPENCLAW_TESTBOX_ALLOW_STALE=1 służy wyłącznie do celowej diagnostyki, a nie jako dowód wydania.

Poniższe lokalne polecenia testowe są przeznaczone dla przepływów pracy wykonywanych przez ludzi lub jako jawnie zażądany przez użytkownika mechanizm zastępczy dla agenta. Niedostępność zdalnego dostawcy musi zostać zgłoszona; nie stanowi ona pozwolenia na ciche uruchomienie szerokiej lokalnej bramki.

W przypadku niezaufanego kodu wykonaj wstępne rozgrzewanie z użyciem --provider aws. Każde uruchomienie musi ustawiać CRABBOX_ENV_ALLOW=CI, przekazywać --provider aws --no-hydrate i używać nowego tymczasowego zdalnego katalogu HOME przed instalacją zależności lub uruchomieniem testów. Użyj nowo rozgrzanej dzierżawy przeznaczonej wyłącznie dla tego niezaufanego źródła; nigdy nie używaj ponownie zaufanej ani wcześniej przygotowanej dzierżawy. Uruchom zainstalowany, zaufany plik wykonywalny Crabbox z czystej, zaufanej kopii roboczej gałęzi main i pobierz wyłącznie zdalny PR za pomocą --fresh-pr; nigdy nie wykonuj lokalnie wrappera ani konfiguracji z niezaufanej kopii roboczej. Usuń ustawienie CRABBOX_AWS_INSTANCE_PROFILE i przerwij bezpiecznie, jeśli rozpoznana wartość aws.instanceProfile nie jest pusta. Przed każdą instalacją lub testem użyj zaufanych narzędzi wskazanych ścieżkami bezwzględnymi, aby wymagać tokenu IMDSv2, udowodnić, że punkt końcowy danych uwierzytelniających IAM zwraca kod 404, oraz sprawdzić, czy zdalne git rev-parse HEAD jest równe pełnemu, sprawdzonemu SHA rewizji głównej PR-a. Powiąż dzierżawę z tym SHA oraz zatrzymaj i ponownie rozgrzej środowisko, gdy rewizja główna się zmieni. Prześlij zaufany skrypt scripts/crabbox-untrusted-bootstrap.sh z czystej gałęzi main wraz z --fresh-pr; instaluje on przypięte wersje Node/pnpm, weryfikuje SHA i przypięcie menedżera pakietów, izoluje HOME, instaluje zależności, a następnie wykonuje żądany test. Jeśli broker nie może potwierdzić braku roli lub nie istnieje zdalny PR, użyj CI forka bez sekretów. Nie używaj hydrate-github, --no-sync ani przepływu pracy Testbox z wczytanymi danymi uwierzytelniającymi. Usuń wszystkie nadpisania CRABBOX_TAILSCALE*, wymuś --network public --tailscale=false, wyczyść flagi węzła wyjściowego i sieci LAN oraz przed przesłaniem jakiegokolwiek skryptu wymagaj, aby crabbox inspect raportował sieć publiczną bez stanu Tailscale.

Rutynowa kolejność lokalna

1. pnpm test:changed do walidacji zmienionego zakresu za pomocą Vitest.
2. pnpm test <path-or-filter> dla jednego pliku, katalogu lub jawnie określonego celu.
3. pnpm test tylko wtedy, gdy celowo potrzebujesz pełnego lokalnego zestawu Vitest.

W drzewie roboczym Codex albo połączonej lub częściowej kopii roboczej agenci unikają bezpośredniego lokalnego uruchamiania pnpm test* / pnpm check* / pnpm crabbox:run:

• Jawnie zażądany przez użytkownika lokalny mechanizm zastępczy dla małego pliku: node scripts/run-vitest.mjs <path-or-filter>.
• Bramki zmian lub szeroka walidacja: 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, dzięki czemu pnpm działa wewnątrz Testbox.
• Końcowy exitCode wrappera oraz dane czasowe JSON stanowią wynik polecenia. Delegowane uruchomienie Blacksmith GitHub Actions może po pomyślnym poleceniu SSH wyświetlić stan cancelled, ponieważ Testbox jest zatrzymywany spoza akcji podtrzymującej działanie; zanim uznasz to za błąd, sprawdź podsumowanie wrappera i dane wyjściowe polecenia.
• OPENCLAW_HEAVY_CHECK_LOCK_SCOPE=worktree <local-heavy-check command>: utrzymuje serializację intensywnych kontroli w bieżącym drzewie roboczym zamiast we wspólnym katalogu Git dla poleceń takich jak pnpm check:changed i ukierunkowane pnpm test .... Używaj tego wyłącznie na lokalnych hostach o dużej wydajności, gdy celowo uruchamiasz niezależne kontrole w wielu połączonych drzewach roboczych.

Podstawowe polecenia

Uruchomienia wrappera testów kończą się krótkim podsumowaniem [test] passed|failed|skipped ... in ...; własny wiersz czasu trwania Vitest pozostaje szczegółem poszczególnego fragmentu.

Współdzielony stan testów i pomocnicze funkcje procesów

• src/test-utils/openclaw-test-state.ts: używaj w Vitest, gdy test wymaga odizolowanego HOME, OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, przykładowej konfiguracji, przestrzeni roboczej, katalogu agenta lub magazynu profili uwierzytelniania.
• pnpm test:env-mutations:report: nieblokujący raport testów i infrastruktur testowych, które bezpośrednio modyfikują HOME, OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, OPENCLAW_WORKSPACE_DIR lub powiązane klucze środowiskowe. Użyj go do znajdowania kandydatów do migracji na współdzieloną funkcję pomocniczą stanu testów.
• test/helpers/openclaw-test-instance.ts: testy E2E na poziomie procesu, które wymagają działającego Gateway, środowiska CLI, przechwytywania dzienników i sprzątania w jednym miejscu.
• Ścieżki E2E Docker/Bash, które wczytują scripts/lib/docker-e2e-image.sh, mogą przekazać docker_e2e_test_state_shell_b64 <label> <scenario> do kontenera i zdekodować go za pomocą scripts/lib/openclaw-e2e-instance.sh; skrypty korzystające z wielu katalogów domowych mogą przekazać docker_e2e_test_state_function_b64 i wywołać openclaw_test_state_create <label> <scenario> w każdym przepływie. node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json zapisuje plik środowiskowy hosta, który można wczytać jako źródło (-- przed create zapobiega interpretowaniu --env-file jako flagi Node przez nowsze środowiska uruchomieniowe Node). Ścieżki uruchamiające Gateway mogą wczytać scripts/lib/openclaw-e2e-instance.sh, aby uzyskać rozpoznawanie punktu wejścia, uruchamianie makiety OpenAI, uruchamianie na pierwszym planie lub w tle, sondy gotowości, eksport środowiska stanu, zrzuty dzienników i sprzątanie procesów.

Ścieżki Control UI, TUI i rozszerzeń

• Testy E2E interfejsu Control UI z atrapami: pnpm test:ui:e2e uruchamia ścieżkę Vitest + Playwright, która uruchamia Control UI w Vite i steruje rzeczywistą stroną Chromium komunikującą się z atrapą WebSocketu Gateway. Testy znajdują się w ui/src/**/*.e2e.test.ts, a współdzielone atrapy i elementy sterujące w ui/src/test-helpers/control-ui-e2e.ts. pnpm test:e2e obejmuje tę ścieżkę. Uruchomienia przez agenta domyślnie odbywają się w Testbox/Crabbox, w tym ukierunkowane testy potwierdzające; polecenia 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 używaj tylko jako jawnie wybranego lokalnego rozwiązania awaryjnego.
• Testy PTY interfejsu TUI: node scripts/run-vitest.mjs run --config test/vitest/vitest.tui-pty.config.ts uruchamia szybką ścieżkę PTY z atrapą zaplecza. OPENCLAW_TUI_PTY_INCLUDE_LOCAL=1 lub pnpm tui:pty:test:watch --mode local uruchamia wolniejszy test dymny tui --local, który zastępuje atrapą wyłącznie zewnętrzny punkt końcowy modelu. Sprawdzaj stabilny widoczny tekst lub wywołania fikstur, a nie surowe migawki ANSI.
• pnpm test:extensions i pnpm test extensions uruchamiają wszystkie fragmenty rozszerzeń/pluginów. Zasobożerne pluginy kanałów, plugin przeglądarki i OpenAI działają jako osobne fragmenty; pozostałe grupy pluginów pozostają zgrupowane. pnpm test extensions/<id> uruchamia ścieżkę jednego wbudowanego pluginu.
• Pliki źródłowe z sąsiednimi testami są najpierw mapowane na te testy, a dopiero potem używane są szersze wzorce katalogów. Zmiany pomocnicze w src/channels/plugins/contracts/test-helpers, src/plugin-sdk/test-helpers i src/plugins/contracts wykorzystują lokalny graf importów, aby uruchamiać testy importujące te pliki zamiast szeroko uruchamiać każdy fragment, gdy ścieżka zależności jest jednoznaczna.
• Cele katalogów kontraktów są rozdzielane na odpowiadające im ścieżki kontraktów: pnpm test src/channels/plugins/contracts uruchamia cztery konfiguracje kontraktów kanałów, a pnpm test src/plugins/contracts uruchamia konfigurację kontraktów pluginów, ponieważ ogólne projekty channels/plugins wykluczają contracts/**.
• auto-reply jest podzielone na trzy dedykowane konfiguracje (core, top-level, reply), aby infrastruktura testowa odpowiedzi nie dominowała nad lżejszymi testami stanu, tokenów i funkcji pomocniczych najwyższego poziomu.
• Wybrane pliki testowe plugin-sdk i commands są kierowane przez dedykowane lekkie ścieżki, które zachowują tylko test/setup.ts, pozostawiając przypadki mocno zależne od środowiska uruchomieniowego w ich dotychczasowych ścieżkach.
• Podstawowa konfiguracja Vitest używa domyślnie pool: "threads" i isolate: false, a współdzielony nieizolowany mechanizm uruchamiający jest włączony we wszystkich konfiguracjach repozytorium.
• pnpm test:channels uruchamia vitest.channels.config.ts.

Gateway i E2E

• Integracja z Gateway jest opcjonalna: OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test lub pnpm test:gateway.
• pnpm test:e2e: zbiorczy zestaw E2E repozytorium = pnpm test:e2e:gateway && pnpm test:ui:e2e.
• pnpm test:e2e:gateway: kompleksowe testy dymne Gateway (parowanie wielu instancji przez WS/HTTP/Node). Domyślnie używa threads + isolate: false z adaptacyjną liczbą procesów roboczych w vitest.e2e.config.ts; dostosuj ją za pomocą OPENCLAW_E2E_WORKERS=<n>, a szczegółowe dzienniki włącz przez OPENCLAW_E2E_VERBOSE=1.
• pnpm test:live: testy dostawców na żywo (Claude/Minimax/DeepSeek/z.ai/itd., kontrolowane przez *.live.test.ts). Wymagają kluczy API oraz LIVE=1 (lub OPENCLAW_LIVE_TEST=1), aby nie zostały pominięte; szczegółowe dane wyjściowe włącza OPENCLAW_LIVE_TEST_QUIET=0.

Pełny zestaw Docker (pnpm test:docker:all)

Buduje współdzielony obraz testów na żywo, jednokrotnie pakuje OpenClaw jako archiwum tar npm, buduje lub ponownie wykorzystuje bazowy obraz wykonawczy Node/Git oraz obraz funkcjonalny, który instaluje to archiwum tar w /app, a następnie uruchamia ścieżki testów dymnych Docker za pomocą harmonogramu z wagami. scripts/package-openclaw-for-docker.mjs jest jedynym lokalnym i używanym w CI narzędziem pakującym oraz weryfikuje archiwum tar i plik dist/postinstall-inventory.json, zanim Docker ich użyje.

• Obraz bazowy (OPENCLAW_DOCKER_E2E_BARE_IMAGE): ścieżki instalatora, aktualizacji i zależności pluginów; montuje wcześniej zbudowane archiwum tar zamiast skopiowanych źródeł repozytorium.
• Obraz funkcjonalny (OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE): ścieżki zwykłej funkcjonalności zbudowanej aplikacji.
• Definicje ścieżek: scripts/lib/docker-e2e-scenarios.mjs. Planista: scripts/lib/docker-e2e-plan.mjs. Wykonawca: scripts/test-docker-all.mjs.
• node scripts/test-docker-all.mjs --plan-json generuje należący do harmonogramu plan CI (ścieżki, rodzaje obrazów, wymagania dotyczące pakietów i obrazów testów na żywo, scenariusze stanu, kontrole danych uwierzytelniających) bez budowania ani uruchamiania Docker.

Parametry harmonogramu (zmienne środowiskowe, wartości domyślne w nawiasach):

Wzorzec nazw zmiennych środowiskowych dla limitów zasobów to OPENCLAW_DOCKER_ALL_<RESOURCE>_LIMIT (nazwa zasobu wielkimi literami, znaki niealfanumeryczne zastąpione przez _).

Inne zachowania: runner domyślnie wykonuje kontrolę wstępną Dockera, usuwa nieaktualne kontenery E2E OpenClaw, współdzieli pamięci podręczne narzędzi CLI dostawców między zgodnymi ścieżkami i po pierwszej awarii przestaje planować nowe ścieżki z puli, chyba że ustawiono OPENCLAW_DOCKER_ALL_FAIL_FAST=0. Jeśli jedna ścieżka przekracza efektywny limit wagi/zasobów na hoście o niskim poziomie równoległości, nadal może wystartować z pustej puli i działać samodzielnie do czasu zwolnienia zasobów. Dzienniki poszczególnych ścieżek, pliki summary.json i failures.json oraz pomiary czasu faz są zapisywane w .artifacts/docker-tests/<run-id>/; użyj pnpm test:docker:timings <summary.json>, aby sprawdzić wolne ścieżki, oraz pnpm test:docker:rerun <run-id|summary.json|failures.json>, aby wyświetlić niedrogie polecenia ukierunkowanego ponownego uruchomienia.

Istotne ścieżki Dockera

Lokalna bramka PR

Aby lokalnie sprawdzić możliwość scalenia/bramkę PR, uruchom:

• pnpm check:changed
• pnpm check
• pnpm check:test-types
• pnpm build
• pnpm test
• pnpm check:docs

Jeśli pnpm test sporadycznie zawiedzie na obciążonym hoście, uruchom go ponownie raz, zanim uznasz to za regresję, a następnie wyizoluj problem za pomocą pnpm test <path/to/test>. W przypadku hostów z ograniczoną pamięcią:

• OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test
• OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed

Narzędzia do analizy wydajności testów

• pnpm test:perf:imports: włącza raportowanie czasu trwania importów i ich szczegółowego podziału w Vitest, nadal używając trasowania w ramach odpowiednich ścieżek dla jawnie wskazanych plików lub katalogów. pnpm test:perf:imports:changed ogranicza to samo profilowanie do plików zmienionych względem origin/main.
• pnpm test:perf:changed:bench -- --ref <git-ref> porównuje wydajność trasowanej ścieżki trybu zmian z natywnym uruchomieniem projektu głównego dla tej samej zatwierdzonej różnicy Git; pnpm test:perf:changed:bench -- --worktree mierzy wydajność bieżącego zestawu zmian w drzewie roboczym bez ich wcześniejszego zatwierdzania.
• pnpm test:perf:profile:main zapisuje profil CPU dla głównego wątku Vitest (.artifacts/vitest-main-profile); pnpm test:perf:profile:runner zapisuje profile CPU i sterty dla procesu uruchamiającego testy jednostkowe (.artifacts/vitest-runner-profile).
• pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json: uruchamia kolejno każdą końcową konfigurację pełnego zestawu Vitest oraz zapisuje pogrupowane dane o czasie trwania wraz z artefaktami JSON i dziennikami dla poszczególnych konfiguracji. Raporty pełnego zestawu domyślnie izolują pliki, aby zachowane grafy modułów i wstrzymania spowodowane przez GC z wcześniejszych plików nie obciążały późniejszych asercji; przekaż -- --no-isolate tylko podczas celowego profilowania kumulacji we współdzielonym procesie roboczym. Agent wydajności testów używa tych danych jako punktu odniesienia przed próbą usprawnienia powolnych testów. pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json porównuje pogrupowane raporty po zmianie ukierunkowanej na wydajność.
• Uruchomienia pełne, rozszerzeń i fragmentów zgodnych ze wzorcem dołączania aktualizują lokalne dane czasowe w .artifacts/vitest-shard-timings.json; późniejsze uruchomienia całych konfiguracji używają tych czasów do równoważenia wolnych i szybkich fragmentów. Fragmenty CI zgodne ze wzorcem dołączania dodają nazwę fragmentu do klucza czasu, dzięki czemu czasy filtrowanych fragmentów pozostają widoczne bez zastępowania danych czasowych całej konfiguracji. Ustaw OPENCLAW_TEST_PROJECTS_TIMINGS=0, aby ignorować lokalny artefakt z danymi czasowymi.

Testy wydajnościowe

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

Kompleksowy test wdrażania (Docker)

Opcjonalny; potrzebny tylko do uproszczonych testów wdrażania w kontenerze. Pełny przebieg zimnego startu w czystym kontenerze Linux:

scripts/e2e/onboard-docker.sh

Steruje interaktywnym kreatorem przez pseudoterminal, weryfikuje pliki konfiguracji, obszaru roboczego i sesji, a następnie uruchamia Gateway i wykonuje openclaw health.

Uproszczony test importowania QR (Docker)

Zapewnia, że utrzymywana funkcja pomocnicza środowiska wykonawczego QR ładuje się w obsługiwanych środowiskach Docker Node (domyślnie Node 24, zgodność z Node 22):

pnpm test:docker:qr

Powiązane

• Testowanie
• Testowanie na żywo
• Testowanie aktualizacji i Pluginów