--- read_when: - Uruchamianie lub naprawianie testów summary: Jak uruchamiać testy lokalnie (vitest) i kiedy używać trybów wymuszania/pokrycia title: Testy x-i18n: generated_at: "2026-07-12T15:35:47Z" model: gpt-5.6 postprocess_version: locale-links-v1 provider: openai source_hash: 63806ea72da1579f4aa0b92c14a6d2d3e67990d6c10cb6d9b1b2bb4a63c8e140 source_path: reference/test.md workflow: 16 --- - Kompletny zestaw testowy (zestawy, testy na żywo, Docker): [Testowanie](/pl/help/testing) - Walidacja aktualizacji i pakietów Pluginów: [Testowanie aktualizacji i Pluginów](/pl/help/testing-updates-plugins) ## 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: ```bash 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 ` 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 `. - 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 `: 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. | Polecenie | Działanie | | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pnpm test` | Jawne cele w postaci plików lub katalogów są kierowane do ograniczonych zakresowo ścieżek Vitest. Uruchomienia bez celu stanowią walidację pełnego zestawu: stałe grupy fragmentów są rozwijane do konfiguracji końcowych w celu lokalnego wykonywania równoległego, a oczekiwany podział na fragmenty jest wyświetlany przed rozpoczęciem. Grupa rozszerzeń jest zawsze rozwijana do konfiguracji fragmentów dla poszczególnych rozszerzeń zamiast jednego ogromnego procesu projektu głównego. | | `pnpm test:changed` | Tanie, inteligentne uruchomienie testów zmian: precyzyjne cele wynikające z bezpośrednich zmian w testach, sąsiednich plików `*.test.ts`, jawnych mapowań źródeł i lokalnego grafu importów. Szerokie zmiany konfiguracji lub pakietów są pomijane, chyba że można je odwzorować na konkretne testy. | | `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` | Jawne szerokie uruchomienie testów zmian; użyj, gdy zmiana infrastruktury testowej, konfiguracji lub pakietu powinna powodować użycie szerszego mechanizmu testowania zmian Vitest. | | `pnpm test:force` | Zwalnia skonfigurowany port Gateway OpenClaw (domyślnie `18789`), a następnie uruchamia pełny zestaw z odizolowanym portem Gateway, aby testy serwera nie kolidowały z działającą instancją. | | `pnpm test:coverage` | Generuje informacyjny raport pokrycia V8 dla domyślnej ścieżki testów jednostkowych (`vitest.unit.config.ts`); nie są egzekwowane żadne progi pokrycia. | | `pnpm test:coverage:changed` | Pokrycie testami jednostkowymi wyłącznie dla plików zmienionych od `origin/main`. | | `pnpm changed:lanes` | Wyświetla ścieżki architektoniczne aktywowane przez różnice względem `origin/main`. | | `pnpm check:changed` | Poza CI domyślnie deleguje do Crabbox/Testbox, a następnie uruchamia inteligentną bramkę kontroli zmian w zdalnym procesie podrzędnym: formatowanie oraz polecenia sprawdzania typów, lintowania i zabezpieczeń dla objętych zmianami ścieżek. Nie uruchamia Vitest; do walidacji testowej użyj `pnpm test:changed` lub `pnpm test `. | ## 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