Testowanie

OpenClaw ma trzy zestawy testów Vitest (jednostkowe/integracyjne, e2e i live) oraz mechanizmy uruchamiające Docker. Ta strona opisuje zakres każdego zestawu, polecenia odpowiednie dla poszczególnych przepływów pracy, sposób wykrywania danych uwierzytelniających przez testy live oraz dodawanie testów regresji dla rzeczywistych błędów dostawców i modeli.

Szybki start

W większości przypadków:

• Pełna bramka (oczekiwana przed wysłaniem zmian): pnpm build && pnpm check && pnpm check:test-types && pnpm test
• Szybsze lokalne uruchomienie pełnego zestawu na maszynie z dużą ilością zasobów: pnpm test:max
• Bezpośrednia pętla obserwowania zmian Vitest: pnpm test:watch
• Bezpośrednie wskazanie pliku obsługuje również ścieżki pluginów/kanałów: pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts
• Podczas pracy nad pojedynczym błędem najpierw wybieraj ukierunkowane uruchomienia.
• Środowisko QA oparte na Dockerze: pnpm qa:lab:up
• Ścieżka QA oparta na maszynie wirtualnej z systemem Linux: pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline

Gdy modyfikujesz testy lub potrzebujesz większej pewności:

• Informacyjny raport pokrycia V8: pnpm test:coverage
• Zestaw E2E: pnpm test:e2e

Katalogi tymczasowe testów

Używaj współdzielonych funkcji pomocniczych z test/helpers/temp-dir.ts dla należących do testów katalogów tymczasowych, aby własność była jednoznaczna, a sprzątanie pozostawało częścią cyklu życia testu:

  const tempDirs = useAutoCleanupTempDirTracker(afterEach); it("uses a temp workspace", () => {  const workspace = tempDirs.make("openclaw-example-");  // use workspace});

useAutoCleanupTempDirTracker(afterEach) celowo nie udostępnia ręcznej metody sprzątania — Vitest odpowiada za sprzątanie po każdym teście. Starsze funkcje pomocnicze niższego poziomu (makeTempDir, cleanupTempDirs, createTempDirTracker) nadal istnieją dla testów, które nie zostały jeszcze zmigrowane; unikaj ich w nowym kodzie oraz nowych bezpośrednich wywołań fs.mkdtemp*, chyba że test jawnie sprawdza podstawowe zachowanie katalogu tymczasowego. Gdy bezpośrednio utworzony katalog tymczasowy jest rzeczywiście potrzebny, dodaj możliwy do skontrolowania komentarz zezwalający wraz z uzasadnieniem:

// openclaw-temp-dir: allow verifies raw fs cleanup behaviorconst workspace = fs.mkdtempSync(prefix);

node scripts/report-test-temp-creations.mjs raportuje nowe bezpośrednie tworzenie katalogów tymczasowych oraz nowe przypadki ręcznego użycia współdzielonych funkcji pomocniczych w dodanych wierszach różnic, bez blokowania istniejących sposobów sprzątania. Stosuje tę samą klasyfikację ścieżek testów co scripts/changed-lanes.mjs i pomija samą implementację współdzielonej funkcji pomocniczej. check:changed uruchamia ten raport dla zmienionych ścieżek testów jako sygnał CI zawierający wyłącznie ostrzeżenia (adnotacje ostrzegawcze GitHub, a nie błędy).

Przepływy pracy live i Docker/Parallels

Podczas debugowania rzeczywistych dostawców/modeli (wymaga prawdziwych danych uwierzytelniających):

• Zestaw live (modele oraz sondy narzędzi/obrazów Gateway): pnpm test:live
• Ciche uruchomienie jednego pliku live: pnpm test:live -- src/agents/models.profiles.live.test.ts
• Raporty wydajności środowiska uruchomieniowego: uruchom OpenClaw Performance z live_openai_candidate=true, aby wykonać rzeczywistą turę agenta openai/gpt-5.6-luna, albo z deep_profile=true, aby uzyskać artefakty procesora, sterty i śledzenia Kova. Codzienne zaplanowane uruchomienia publikują raporty ścieżek fikcyjnego dostawcy, profilowania szczegółowego oraz GPT-5.6 Luna w openclaw/clawgrit-reports za pomocą oddzielnego zadania publikującego, które przetwarza artefakty; brakujące lub nieprawidłowe uwierzytelnienie publikatora powoduje niepowodzenie uruchomień zaplanowanych oraz uruchomień z profile=release. Ręczne uruchomienia niebędące wydaniami zachowują artefakty GitHub i traktują publikację raportu jako opcjonalną. Raport fikcyjnego dostawcy zawiera również pomiary uruchamiania Gateway na poziomie kodu źródłowego, pamięci, obciążenia pluginami, powtarzanej pętli powitalnej fikcyjnego modelu oraz uruchamiania CLI.
• Przegląd modeli live w Dockerze: pnpm test:docker:live-models
  • Każdy wybrany model wykonuje turę tekstową oraz niewielką sondę przypominającą odczyt pliku. Modele, których metadane deklarują wejście image, wykonują również niewielką turę z obrazem. Podczas izolowania awarii dostawcy wyłącz dodatkowe sondy za pomocą OPENCLAW_LIVE_MODEL_FILE_PROBE=0 lub OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0.
  • Pokrycie CI: codzienny przepływ OpenClaw Scheduled Live And E2E Checks oraz ręczny OpenClaw Release Checks wywołują wielokrotnego użytku przepływ live/E2E z include_live_suites: true, który obejmuje zadania macierzy modeli live w Dockerze podzielone na fragmenty według dostawcy.
  • Aby wykonać ukierunkowane ponowne uruchomienie CI, uruchom OpenClaw Live And E2E Checks (Reusable) z include_live_suites: true i live_models_only: true.
  • Dodawaj nowe sekrety dostawców o wysokiej wartości diagnostycznej do scripts/ci-hydrate-live-auth.sh, .github/workflows/openclaw-live-and-e2e-checks-reusable.yml oraz wywołujących go przepływów zaplanowanych i wydaniowych.
• Test dymny natywnego powiązanego czatu Codex: pnpm test:docker:live-codex-bind
  • Uruchamia ścieżkę live w Dockerze względem ścieżki serwera aplikacji Codex, wiąże syntetyczną wiadomość prywatną Slack poleceniem /codex bind, sprawdza /codex fast i /codex permissions, a następnie weryfikuje, że zwykła odpowiedź oraz załącznik graficzny są kierowane przez natywne powiązanie pluginu zamiast przez ACP.
• Test dymny środowiska testowego serwera aplikacji Codex: pnpm test:docker:live-codex-harness
  • Uruchamia tury agenta Gateway przez należące do pluginu środowisko testowe serwera aplikacji Codex, weryfikuje /codex status i /codex models, a domyślnie sprawdza sondy obrazu, MCP Cron, podagenta oraz Guardian. Podczas izolowania innych awarii wyłącz sondę podagenta za pomocą OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0. Aby wykonać ukierunkowaną kontrolę podagenta, wyłącz pozostałe sondy: OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=1 pnpm test:docker:live-codex-harness. Proces kończy się po sondzie podagenta, chyba że ustawiono OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0.
• Test dymny instalacji Codex na żądanie: pnpm test:docker:codex-on-demand
  • Instaluje spakowane archiwum OpenClaw w Dockerze, przeprowadza konfigurację początkową z kluczem API OpenAI i sprawdza, czy plugin Codex oraz zależność @openai/codex zostały na żądanie pobrane do katalogu głównego zarządzanego projektu npm.
• Test dymny zależności narzędzia pluginu live: pnpm test:docker:live-plugin-tool
  • Pakuje plugin testowy z rzeczywistą zależnością slugify, instaluje go przez npm-pack:, weryfikuje zależność w katalogu głównym zarządzanego projektu npm, a następnie prosi model OpenAI live o wywołanie narzędzia pluginu i zwrócenie ukrytego uproszczonego identyfikatora.
• Test dymny polecenia ratunkowego Crestodian: pnpm test:live:crestodian-rescue-channel
  • Opcjonalna, redundantna kontrola zestawu poleceń ratunkowych kanału wiadomości. Sprawdza /crestodian status, umieszcza trwałą zmianę modelu w kolejce, odpowiada /crestodian yes i weryfikuje ścieżkę zapisu audytu/konfiguracji.
• Test dymny pierwszego uruchomienia Crestodian w Dockerze: pnpm test:docker:crestodian-first-run
  • Rozpoczyna od pustego katalogu stanu OpenClaw i najpierw potwierdza, że spakowane polecenie CLI openclaw crestodian bezpiecznie odmawia działania bez inferencji. Następnie testuje i aktywuje fikcyjny model Claude za pomocą spakowanego modułu aktywacji. Dopiero później nieprecyzyjne żądanie spakowanego CLI dociera do planera i zostaje przekształcone w typowaną konfigurację, po której następują jednorazowe operacje na modelu, agencie, pluginie Discord i SecretRef. Test weryfikuje konfigurację oraz wpisy audytu. Jest to pomocniczy dowód działania bramki i operacji, a nie dowód interaktywnej konfiguracji początkowej ani działania agenta, narzędzia lub zatwierdzania Crestodian. Ta sama ścieżka jest dostępna w QA Lab przez pnpm openclaw qa suite --scenario crestodian-ring-zero-setup.
• Test dymny kosztów Moonshot/Kimi: po ustawieniu MOONSHOT_API_KEY uruchom openclaw models list --provider moonshot --json, a następnie wykonaj izolowane polecenie openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json względem moonshot/kimi-k2.6. Sprawdź, czy dane JSON wskazują Moonshot/K2.6, a transkrypcja asystenta przechowuje znormalizowane usage.cost.

Mechanizmy uruchamiające przeznaczone dla QA

Te polecenia uzupełniają główne zestawy testów, gdy potrzebujesz realizmu środowiska QA Lab.

CI uruchamia QA Lab w dedykowanych przepływach pracy. Zgodność agentowa jest częścią QA-Lab - All Lanes oraz walidacji wydania, a nie osobnego przepływu pracy PR. Szeroka walidacja powinna używać Full Release Validation z rerun_group=qa-parity albo grupy QA kontroli wydania. Kontrole wydania stabilnego/domyślnego pozostawiają wyczerpujące długotrwałe testy live/Docker za opcją run_release_soak=true; profil full wymusza ich włączenie. QA-Lab - All Lanes uruchamia się każdej nocy na main oraz ręcznie, wykonując równolegle ścieżkę zgodności z fikcyjnym dostawcą, ścieżkę Matrix live, zarządzaną przez Convex ścieżkę Telegram live oraz zarządzaną przez Convex ścieżkę Discord live. Zaplanowane QA i kontrole wydania jawnie przekazują do Matrix opcję --profile fast, natomiast domyślną wartością CLI Matrix i ręcznego wejścia przepływu pracy pozostaje all; ręczne uruchomienie może podzielić all na zadania transport, media, e2ee-smoke, e2ee-deep i e2ee-cli. OpenClaw Release Checks uruchamia sprawdzenie zgodności oraz szybkie ścieżki Matrix i Telegram przed zatwierdzeniem wydania, używając mock-openai/gpt-5.6-luna do wydaniowych kontroli transportu, dzięki czemu pozostają deterministyczne i unikają standardowego uruchamiania pluginu dostawcy. Te bramy transportowe live wyłączają wyszukiwanie w pamięci; zachowanie pamięci pozostaje objęte zestawami zgodności QA.

Fragmenty multimediów live pełnego wydania używają ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04, który zawiera już ffmpeg i ffprobe. Fragmenty modeli/zaplecza live w Dockerze używają współdzielonego obrazu ghcr.io/openclaw/openclaw-live-test:<sha>, budowanego raz dla każdego wybranego commitu, a następnie pobierają go z OPENCLAW_SKIP_DOCKER_BUILD=1 zamiast przebudowywać go wewnątrz każdego fragmentu.

• pnpm openclaw qa suite
  • Uruchamia scenariusze kontroli jakości oparte na repozytorium bezpośrednio na hoście.
  • Zapisuje artefakty najwyższego poziomu qa-evidence.json, qa-suite-summary.json oraz qa-suite-report.md dla wybranego zestawu scenariuszy, w tym wybrane scenariusze przepływów mieszanych, Vitest i Playwright.
  • Po uruchomieniu przez pnpm openclaw qa run --qa-profile <profile> osadza kartę wyników wybranego profilu taksonomii w tym samym pliku qa-evidence.json. smoke-ci zapisuje uproszczone dowody (evidenceMode: "slim", bez execution dla poszczególnych wpisów). release obejmuje wyselekcjonowany zakres gotowości do wydania; all wybiera wszystkie aktywne kategorie dojrzałości i jest przeznaczony do jawnego uruchamiania przepływu pracy QA Profile Evidence, gdy potrzebny jest pełny artefakt karty wyników.
  • Domyślnie uruchamia wiele wybranych scenariuszy równolegle przy użyciu izolowanych procesów roboczych Gateway. Dla qa-channel domyślna współbieżność wynosi 4 (ograniczona liczbą wybranych scenariuszy). Użyj --concurrency <count>, aby dostosować liczbę procesów roboczych, albo --concurrency 1, aby użyć starszej ścieżki szeregowej.
  • Kończy działanie kodem różnym od zera, jeśli którykolwiek scenariusz zakończy się niepowodzeniem. Użyj --allow-failures, aby uzyskać artefakty bez kodu zakończenia oznaczającego błąd.
  • Obsługuje tryby dostawcy live-frontier, mock-openai oraz aimock. aimock uruchamia lokalny serwer dostawcy oparty na AIMock w celu eksperymentalnego testowania fikstur i atrap protokołu bez zastępowania ścieżki mock-openai uwzględniającej scenariusze.
• pnpm openclaw qa coverage --match <query>
  • Przeszukuje identyfikatory i tytuły scenariuszy, powierzchnie, identyfikatory pokrycia, odwołania do dokumentacji i kodu, pluginy oraz wymagania dostawców, a następnie wyświetla pasujące cele zestawów testów.
  • Użyj tego przed uruchomieniem QA Lab, gdy znasz zmieniane zachowanie lub ścieżkę pliku, ale nie znasz najmniejszego odpowiedniego scenariusza. Wynik ma wyłącznie charakter doradczy — nadal wybierz dowód oparty na atrapach, środowisku rzeczywistym, Multipass, Matrix lub transporcie zgodnie ze zmienianym zachowaniem.
• pnpm test:plugins:kitchen-sink-live
  • Uruchamia pełny zestaw rzeczywistych testów pluginu OpenAI Kitchen Sink za pośrednictwem QA Lab. Instaluje zewnętrzny pakiet Kitchen Sink, weryfikuje spis powierzchni SDK pluginu, sonduje /healthz i /readyz, rejestruje dowody dotyczące CPU/RSS Gateway, wykonuje rzeczywistą turę OpenAI i sprawdza diagnostykę w warunkach wrogich. Wymaga rzeczywistych danych uwierzytelniających OpenAI, takich jak OPENAI_API_KEY. W przygotowanych sesjach Testbox automatycznie wczytuje profil rzeczywistego uwierzytelniania Testbox, gdy dostępny jest pomocnik openclaw-testbox-env.
• pnpm test:gateway:cpu-scenarios
  • Uruchamia test wydajności uruchamiania Gateway wraz z małym zestawem scenariuszy QA Lab opartych na atrapach (channel-chat-baseline, memory-failure-fallback, gateway-restart-inflight-run) i zapisuje połączone podsumowanie obserwacji CPU w katalogu .artifacts/gateway-cpu-scenarios/.
  • Domyślnie oznacza tylko utrzymujące się wysokie użycie CPU (--cpu-core-warn, domyślnie 0.9; --hot-wall-warn-ms, domyślnie 30000), dzięki czemu krótkie skoki podczas uruchamiania są rejestrowane jako metryki, ale nie wyglądają jak regresja powodująca wielominutowe maksymalne obciążenie Gateway.
  • Działa na zbudowanych artefaktach dist; najpierw uruchom kompilację, jeśli kopia robocza nie zawiera jeszcze aktualnych wyników środowiska uruchomieniowego.
• pnpm openclaw qa suite --runner multipass
  • Uruchamia ten sam zestaw testów kontroli jakości wewnątrz jednorazowej maszyny wirtualnej Multipass z systemem Linux, zachowując te same flagi wyboru scenariuszy oraz dostawcy/modelu co qa suite.
  • Rzeczywiste uruchomienia przekazują dane uwierzytelniające QA, które mogą być użyte w systemie gościa: klucze dostawców oparte na zmiennych środowiskowych, ścieżkę konfiguracji rzeczywistego dostawcy QA oraz CODEX_HOME, jeśli jest dostępna.
  • Katalogi wyjściowe muszą znajdować się w katalogu głównym repozytorium, aby system gościa mógł zapisywać wyniki przez zamontowaną przestrzeń roboczą.
  • Zapisuje standardowy raport i podsumowanie QA oraz dzienniki Multipass w .artifacts/qa-e2e/....
• pnpm qa:lab:up
  • Uruchamia witrynę QA opartą na Dockerze do pracy kontrolnej w stylu operatorskim.
• pnpm test:docker:npm-onboard-channel-agent
  • Buduje archiwum npm z bieżącej kopii roboczej, instaluje je globalnie w Dockerze, wykonuje nieinteraktywną konfigurację początkową z kluczem API OpenAI, domyślnie konfiguruje Telegram, sprawdza, czy środowisko uruchomieniowe spakowanego pluginu ładuje się bez naprawiania zależności podczas uruchamiania, uruchamia doctor i wykonuje jedną lokalną turę agenta z atrapą punktu końcowego OpenAI.
  • Użyj OPENCLAW_NPM_ONBOARD_CHANNEL=discord, aby uruchomić tę samą ścieżkę instalacji pakietu z Discord.
• pnpm test:docker:session-runtime-context
  • Uruchamia deterministyczny test dymny zbudowanej aplikacji w Dockerze dla transkrypcji osadzonego kontekstu środowiska uruchomieniowego. Sprawdza, czy ukryty kontekst środowiska uruchomieniowego OpenClaw jest zachowywany jako niewyświetlana wiadomość niestandardowa, zamiast przedostawać się do widocznej tury użytkownika, a następnie umieszcza uszkodzony plik JSONL sesji dotkniętej problemem i sprawdza, czy openclaw doctor --fix przepisuje go do aktywnej gałęzi oraz tworzy kopię zapasową.
• pnpm test:docker:npm-telegram-live
  • Instaluje kandydujący pakiet OpenClaw w Dockerze, wykonuje konfigurację początkową zainstalowanego pakietu, konfiguruje Telegram za pomocą zainstalowanego CLI, a następnie ponownie wykorzystuje rzeczywistą ścieżkę QA Telegram z tym zainstalowanym pakietem jako testowanym Gateway.
  • Skrypt opakowujący montuje z kopii roboczej wyłącznie kod zestawu testowego qa-lab; zainstalowany pakiet jest właścicielem dist, openclaw/plugin-sdk oraz środowiska uruchomieniowego dołączonych pluginów, dzięki czemu ścieżka nie miesza pluginów z bieżącej kopii roboczej z testowanym pakietem.
  • Domyślnie używa OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta; ustaw OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz lub OPENCLAW_CURRENT_PACKAGE_TGZ, aby zamiast instalacji z rejestru przetestować rozpoznane lokalne archiwum.
  • Domyślnie zapisuje wielokrotne pomiary RTT w qa-evidence.json z OPENCLAW_NPM_TELEGRAM_RTT_SAMPLES=20. Zmień OPENCLAW_NPM_TELEGRAM_RTT_SAMPLES, OPENCLAW_NPM_TELEGRAM_RTT_TIMEOUT_MS lub OPENCLAW_NPM_TELEGRAM_RTT_MAX_FAILURES, aby dostosować uruchomienie. OPENCLAW_NPM_TELEGRAM_RTT_CHECKS przyjmuje rozdzielaną przecinkami listę identyfikatorów kontroli QA Telegram do próbkowania; jeśli nie jest ustawiona, domyślną kontrolą obsługującą RTT jest telegram-mentioned-message-reply.
  • Używa tych samych danych uwierzytelniających Telegram ze zmiennych środowiskowych lub źródła danych uwierzytelniających Convex co pnpm openclaw qa telegram. Na potrzeby automatyzacji CI/wydania ustaw OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex wraz z OPENCLAW_QA_CONVEX_SITE_URL i sekretem roli. Jeśli OPENCLAW_QA_CONVEX_SITE_URL i sekret roli Convex są dostępne w CI, skrypt opakowujący Dockera automatycznie wybiera Convex.
  • Skrypt opakowujący sprawdza na hoście zmienne środowiskowe danych uwierzytelniających Telegram lub Convex przed rozpoczęciem budowania i instalacji w Dockerze. Ustaw OPENCLAW_NPM_TELEGRAM_SKIP_CREDENTIAL_PREFLIGHT=1 tylko podczas świadomego debugowania konfiguracji poprzedzającej udostępnienie danych uwierzytelniających.
  • OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer zastępuje współdzielone OPENCLAW_QA_CREDENTIAL_ROLE wyłącznie dla tej ścieżki. Gdy wybrano dane uwierzytelniające Convex i nie ustawiono roli, skrypt opakowujący używa ci w CI, a maintainer poza CI.
  • GitHub Actions udostępnia tę ścieżkę jako ręczny przepływ pracy opiekuna NPM Telegram Beta E2E. Nie jest ona uruchamiana podczas scalania. Przepływ pracy używa środowiska qa-live-shared oraz dzierżaw danych uwierzytelniających Convex CI.
• GitHub Actions udostępnia również Package Acceptance do dodatkowej weryfikacji produktu względem jednego kandydującego pakietu. Przyjmuje odwołanie Git, opublikowaną specyfikację npm, adres URL HTTPS archiwum wraz z SHA-256, zasady zaufanych adresów URL lub artefakt archiwum z innego uruchomienia (source=ref|npm|url|trusted-url|artifact), przesyła znormalizowany plik openclaw-current.tgz jako package-under-test, a następnie uruchamia istniejący harmonogram kompleksowych testów Dockera z profilami ścieżek smoke, package, product, full lub custom. Ustaw telegram_mode=mock-openai albo live-frontier, aby uruchomić przepływ pracy QA Telegram względem tego samego artefaktu package-under-test.
  • Weryfikacja produktu dla najnowszej wersji beta:

gh workflow run package-acceptance.yml --ref main \  -f source=npm \  -f package_spec=openclaw@beta \  -f suite_profile=product \  -f telegram_mode=mock-openai

• Weryfikacja dokładnego adresu URL archiwum wymaga skrótu i korzysta z publicznych zasad bezpieczeństwa adresów URL:

gh workflow run package-acceptance.yml --ref main \  -f source=url \  -f package_url=https://registry.npmjs.org/openclaw/-/openclaw-VERSION.tgz \  -f package_sha256=<sha256> \  -f suite_profile=package

• Firmowe/prywatne serwery lustrzane archiwów używają jawnych zasad zaufanego źródła:

gh workflow run package-acceptance.yml --ref main \  -f source=trusted-url \  -f trusted_source_id=enterprise-artifactory \  -f package_url=https://packages.example.internal:8443/artifactory/openclaw/openclaw-VERSION.tgz \  -f package_sha256=<sha256> \  -f suite_profile=package

source=trusted-url odczytuje .github/package-trusted-sources.json z zaufanego odwołania przepływu pracy i nie akceptuje danych uwierzytelniających w adresie URL ani obejścia sieci prywatnej przekazanego jako parametr wejściowy przepływu pracy. Jeśli wskazane zasady deklarują uwierzytelnianie za pomocą tokenu Bearer, skonfiguruj stały sekret OPENCLAW_TRUSTED_PACKAGE_TOKEN.

• Weryfikacja artefaktu pobiera artefakt archiwum z innego uruchomienia Actions:

gh workflow run package-acceptance.yml --ref main \  -f source=artifact \  -f artifact_run_id=<run-id> \  -f artifact_name=<artifact-name> \  -f suite_profile=smoke

• pnpm test:docker:plugins

  • Pakuje i instaluje bieżącą kompilację OpenClaw w Dockerze, uruchamia Gateway ze skonfigurowanym OpenAI, a następnie włącza dołączone kanały/pluginy przez modyfikacje konfiguracji.
  • Sprawdza, czy wykrywanie podczas konfiguracji nie instaluje nieskonfigurowanych pluginów dostępnych do pobrania, czy pierwsza skonfigurowana naprawa przez doctor jawnie instaluje każdy brakujący plugin dostępny do pobrania oraz czy drugie ponowne uruchomienie nie wykonuje ukrytej naprawy zależności.
  • Instaluje również znaną starszą wersję bazową npm, włącza Telegram przed uruchomieniem openclaw update --tag <candidate> i sprawdza, czy doctor kandydata po aktualizacji usuwa pozostałości starszych zależności pluginów bez naprawy wykonywanej po instalacji przez zestaw testowy.

• pnpm test:parallels:npm-update

  • Uruchamia natywny test dymny aktualizacji instalacji pakietu na systemach gościa Parallels. Każda wybrana platforma najpierw instaluje żądany pakiet bazowy, następnie uruchamia zainstalowane polecenie openclaw update w tym samym systemie gościa i sprawdza zainstalowaną wersję, stan aktualizacji, gotowość Gateway oraz jedną lokalną turę agenta.

  • Podczas pracy nad jednym systemem gościa użyj --platform macos, --platform windows lub --platform linux. Użyj --json, aby uzyskać ścieżkę artefaktu podsumowania i stan poszczególnych ścieżek.

  • Ścieżka OpenAI domyślnie używa openai/gpt-5.6-luna do rzeczywistej weryfikacji tury agenta. Przekaż --model <provider/model> lub ustaw OPENCLAW_PARALLELS_OPENAI_MODEL, aby zweryfikować inny model OpenAI.

  • Obejmuj długie lokalne uruchomienia limitem czasu hosta, aby zawieszenia transportu Parallels nie zużyły pozostałego czasu przeznaczonego na testy:

    timeout --foreground 150m pnpm test:parallels:npm-update -- --jsontimeout --foreground 90m pnpm test:parallels:npm-update -- --platform windows --json

  • Skrypt zapisuje zagnieżdżone dzienniki ścieżek w /tmp/openclaw-parallels-npm-update.*. Sprawdź windows-update.log, macos-update.log lub linux-update.log, zanim uznasz, że zewnętrzny skrypt opakowujący się zawiesił.

  • Aktualizacja systemu Windows może spędzić od 10 do 15 minut na działaniu doctor po aktualizacji i aktualizowaniu pakietu w zimnym systemie gościa; działanie nadal przebiega prawidłowo, jeśli zagnieżdżony dziennik debugowania npm jest aktualizowany.

  • Nie uruchamiaj tego zbiorczego skryptu opakowującego równolegle z osobnymi ścieżkami testów dymnych Parallels dla macOS, Windows lub Linux. Współdzielą one stan maszyny wirtualnej i mogą kolidować podczas przywracania migawki, udostępniania pakietu lub korzystania ze stanu Gateway systemu gościa.

  • Weryfikacja po aktualizacji uruchamia standardową powierzchnię dołączonych pluginów, ponieważ fasady funkcji, takich jak mowa, generowanie obrazów i rozumienie multimediów, są ładowane przez dołączone interfejsy API środowiska uruchomieniowego, nawet jeśli sama tura agenta sprawdza jedynie prostą odpowiedź tekstową.

• pnpm openclaw qa aimock

  • Uruchamia tylko lokalny serwer dostawcy AIMock do bezpośrednich testów dymnych protokołu.

• pnpm openclaw qa matrix

  • Uruchamia ścieżkę testów QA na żywo dla Matrix względem jednorazowego, opartego na Dockerze serwera domowego Tuwunel. Dostępne tylko z kodu źródłowego — instalacje pakietowe nie zawierają qa-lab.
  • Pełny opis CLI, katalog profili/scenariuszy, zmienne środowiskowe i układ artefaktów: QA Matrix.

• pnpm openclaw qa telegram

  • Uruchamia ścieżkę testów QA na żywo dla Telegram względem rzeczywistej grupy prywatnej, używając tokenów bota sterownika i testowanego systemu ze zmiennych środowiskowych.
  • Wymaga OPENCLAW_QA_TELEGRAM_GROUP_ID, OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN oraz OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN. Identyfikator grupy musi być numerycznym identyfikatorem czatu Telegram.
  • Obsługuje --credential-source convex dla współdzielonych danych uwierzytelniających z puli. Domyślnie używaj trybu zmiennych środowiskowych albo ustaw OPENCLAW_QA_CREDENTIAL_SOURCE=convex, aby korzystać z dzierżaw puli.
  • Domyślne ustawienia obejmują wersję canary, bramkowanie wzmianek, adresowanie poleceń, /status, odpowiedzi między botami ze wzmianką oraz odpowiedzi podstawowych poleceń natywnych. Domyślne ustawienia mock-openai obejmują również deterministyczne regresje łańcucha odpowiedzi i strumieniowania wiadomości końcowej Telegram. Użyj --list-scenarios, aby wyświetlić opcjonalne testy, takie jak session_status.
  • Kończy działanie kodem różnym od zera, jeśli którykolwiek scenariusz zakończy się niepowodzeniem. Użyj --allow-failures, aby wygenerować artefakty bez kodu wyjścia wskazującego niepowodzenie.
  • Wymaga dwóch różnych botów w tej samej grupie prywatnej, przy czym bot testowanego systemu musi mieć nazwę użytkownika Telegram.
  • Aby zapewnić stabilną obserwację komunikacji między botami, włącz Bot-to-Bot Communication Mode w @BotFather dla obu botów i upewnij się, że bot sterownika może obserwować ruch botów w grupie.
  • Zapisuje raport QA Telegram, podsumowanie oraz qa-evidence.json w .artifacts/qa-e2e/.... Scenariusze z odpowiedziami uwzględniają RTT od żądania wysłania przez sterownik do zaobserwowanej odpowiedzi testowanego systemu.

Mantis Telegram Live to otoka tej ścieżki służąca do dostarczania dowodów dla PR. Uruchamia wskazaną wersję kandydującą z danymi uwierzytelniającymi Telegram dzierżawionymi przez Convex, renderuje zredagowany pakiet raportu i dowodów QA w przeglądarce pulpitu Crabbox, nagrywa dowód MP4, generuje plik GIF przycięty pod kątem ruchu, przesyła pakiet artefaktów i publikuje dowody bezpośrednio w PR za pomocą aplikacji Mantis GitHub App, gdy ustawiono pr_number. Opiekunowie mogą uruchomić ją z poziomu Actions UI za pomocą Mantis Scenario (scenario_id: telegram-live) lub bezpośrednio z komentarza w pull requeście:

@openclaw-mantis telegram@openclaw-mantis telegram scenario=telegram-status-command@openclaw-mantis telegram scenarios=telegram-status-command,telegram-mentioned-message-reply

Mantis Telegram Desktop Proof to agentowa otoka natywnej aplikacji Telegram Desktop wykonująca dowód wizualny PR przed zmianą i po niej. Uruchom ją z poziomu Actions UI, podając dowolne instructions, za pomocą Mantis Scenario (scenario_id: telegram-desktop-proof) albo z komentarza w PR:

@openclaw-mantis telegram desktop proof

Agent Mantis odczytuje PR, ustala, jakie zachowanie widoczne w Telegram potwierdza zmianę, uruchamia ścieżkę dowodową Crabbox z Telegram Desktop dla rzeczywistego użytkownika na wersji bazowej i kandydującej, iteruje, aż natywne pliki GIF będą użyteczne, zapisuje sparowany manifest motionPreview i publikuje tę samą dwukolumnową tabelę plików GIF za pomocą aplikacji Mantis GitHub App, gdy ustawiono pr_number.

• pnpm openclaw qa mantis telegram-desktop-builder
  • Dzierżawi lub ponownie wykorzystuje pulpit Linux Crabbox, instaluje natywną aplikację Telegram Desktop, konfiguruje OpenClaw przy użyciu dzierżawionego tokenu bota Telegram testowanego systemu, uruchamia Gateway oraz rejestruje zrzuty ekranu i dowody MP4 z widocznego pulpitu VNC.
  • Domyślnie używa --credential-source convex, dzięki czemu przepływy pracy potrzebują tylko sekretu brokera Convex. Użyj --credential-source env z tymi samymi zmiennymi OPENCLAW_QA_TELEGRAM_* co w przypadku pnpm openclaw qa telegram.
  • Telegram Desktop nadal wymaga zalogowania użytkownika lub profilu. Token bota konfiguruje tylko OpenClaw. Użyj --telegram-profile-archive-env <name> dla archiwum profilu .tgz zakodowanego w base64 albo użyj --keep-lease i zaloguj się ręcznie przez VNC jeden raz.
  • Zapisuje mantis-telegram-desktop-builder-report.md, mantis-telegram-desktop-builder-summary.json, telegram-desktop-builder.png oraz telegram-desktop-builder.mp4 w katalogu wyjściowym.

Ścieżki transportu na żywo korzystają ze wspólnego standardowego kontraktu, aby nowe transporty nie zaczęły się różnić; macierz pokrycia poszczególnych ścieżek znajduje się w przeglądzie QA — pokrycie transportu na żywo. qa-channel jest szerokim zestawem testów syntetycznych i nie należy do tej macierzy.

Współdzielone dane uwierzytelniające Telegram za pośrednictwem Convex (v1)

Gdy dla testów QA transportu na żywo włączono --credential-source convex (lub OPENCLAW_QA_CREDENTIAL_SOURCE=convex), laboratorium QA pozyskuje wyłączną dzierżawę ze wspieranej przez Convex puli, wysyła Heartbeat dla tej dzierżawy podczas działania ścieżki i zwalnia ją przy zamykaniu. Nazwa sekcji pochodzi sprzed dodania obsługi Discord, Slack i WhatsApp; kontrakt dzierżawy jest wspólny dla wszystkich rodzajów.

Referencyjny szkielet projektu Convex: qa/convex-credential-broker/

Wymagane zmienne środowiskowe:

• OPENCLAW_QA_CONVEX_SITE_URL (na przykład https://your-deployment.convex.site)
• Jeden sekret dla wybranej roli:
  • OPENCLAW_QA_CONVEX_SECRET_MAINTAINER dla maintainer
  • OPENCLAW_QA_CONVEX_SECRET_CI dla ci
• Wybór roli danych uwierzytelniających:
  • CLI: --credential-role maintainer|ci
  • Wartość domyślna ze środowiska: OPENCLAW_QA_CREDENTIAL_ROLE (domyślnie ci w CI, w przeciwnym razie maintainer)

Opcjonalne zmienne środowiskowe:

• OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS (domyślnie 1200000)
• OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS (domyślnie 30000)
• OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS (domyślnie 90000)
• OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS (domyślnie 15000)
• OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX (domyślnie /qa-credentials/v1)
• OPENCLAW_QA_CREDENTIAL_OWNER_ID (opcjonalny identyfikator śledzenia)
• OPENCLAW_QA_ALLOW_INSECURE_HTTP=1 zezwala na adresy URL Convex http:// korzystające z local loopback wyłącznie podczas lokalnego programowania.

W normalnym działaniu OPENCLAW_QA_CONVEX_SITE_URL powinien używać https://.

Polecenia administracyjne opiekunów (dodawanie, usuwanie i wyświetlanie puli) wymagają konkretnie OPENCLAW_QA_CONVEX_SECRET_MAINTAINER.

Pomocnicze polecenia CLI dla opiekunów:

pnpm openclaw qa credentials doctorpnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.jsonpnpm openclaw qa credentials list --kind telegrampnpm openclaw qa credentials remove --credential-id <credential-id>

Przed uruchomieniami na żywo użyj doctor, aby sprawdzić adres URL witryny Convex, sekrety brokera, prefiks punktu końcowego, limit czasu HTTP oraz dostępność funkcji administracyjnych i wyświetlania listy bez drukowania wartości sekretów. Użyj --json, aby uzyskać dane wyjściowe odczytywalne maszynowo w skryptach i narzędziach CI.

Domyślny kontrakt punktu końcowego (OPENCLAW_QA_CONVEX_SITE_URL + /qa-credentials/v1). Żądania uwierzytelniają się nagłówkiem Authorization: Bearer <role secret>; poniższe treści żądań pomijają ten nagłówek:

• POST /acquire
  • Żądanie: { kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }
  • Powodzenie: { status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }
  • Wyczerpanie puli/możliwość ponowienia: { status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }
• POST /payload-chunk
  • Żądanie: { kind, ownerId, actorRole, credentialId, leaseToken, index }
  • Powodzenie: { status: "ok", index, data }
• POST /heartbeat
  • Żądanie: { kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }
  • Powodzenie: { status: "ok" } (lub pusta odpowiedź 2xx)
• POST /release
  • Żądanie: { kind, ownerId, actorRole, credentialId, leaseToken }
  • Powodzenie: { status: "ok" } (lub pusta odpowiedź 2xx)
• POST /admin/add (tylko sekret opiekuna)
  • Żądanie: { kind, actorId, payload, note?, status? }
  • Powodzenie: { status: "ok", credential }
• POST /admin/remove (tylko sekret opiekuna)
  • Żądanie: { credentialId, actorId }
  • Powodzenie: { status: "ok", changed, credential }
  • Ochrona aktywnej dzierżawy: { status: "error", code: "LEASE_ACTIVE", ... }
• POST /admin/list (tylko sekret opiekuna)
  • Żądanie: { kind?, status?, includePayload?, limit? }
  • Powodzenie: { status: "ok", credentials, count }

Struktura danych dla rodzaju Telegram:

• { groupId: string, driverToken: string, sutToken: string }
• groupId musi być ciągiem znaków zawierającym numeryczny identyfikator czatu Telegram.
• admin/add sprawdza tę strukturę dla kind: "telegram" i odrzuca nieprawidłowe dane.

Struktura danych dla rodzaju rzeczywistego użytkownika Telegram:

• { groupId: string, sutToken: string, testerUserId: string, testerUsername: string, telegramApiId: string, telegramApiHash: string, tdlibDatabaseEncryptionKey: string, tdlibArchiveBase64: string, tdlibArchiveSha256: string, desktopTdataArchiveBase64: string, desktopTdataArchiveSha256: string }
• groupId, testerUserId oraz telegramApiId muszą być ciągami numerycznymi.
• tdlibArchiveSha256 oraz desktopTdataArchiveSha256 muszą być ciągami szesnastkowymi SHA-256.
• kind: "telegram-user" jest zarezerwowany dla przepływu pracy dowodu Mantis Telegram Desktop. Ogólne ścieżki laboratorium QA nie mogą go pozyskiwać.

Weryfikowane przez brokera dane dla wielu kanałów:

• Discord: { guildId: string, channelId: string, driverBotToken: string, sutBotToken: string, sutApplicationId: string, voiceChannelId?: string }
• WhatsApp: { driverPhoneE164: string, sutPhoneE164: string, driverAuthArchiveBase64: string, sutAuthArchiveBase64: string, groupJid?: string }

Ścieżki Slack również mogą dzierżawić dane z puli, ale walidacja danych Slack znajduje się obecnie w programie uruchamiającym QA Slack, a nie w brokerze. Dla wpisów Slack używaj { channelId: string, driverBotToken: string, sutBotToken: string, sutAppToken: string }.

Dodawanie kanału do QA

Architektura i nazwy funkcji pomocniczych scenariuszy dla nowych adapterów kanałów znajdują się w przeglądzie QA — dodawanie kanału. Minimalne wymagania: zaimplementuj program uruchamiający transport na wspólnym punkcie integracji hosta qa-lab, dodaj adapterFactory dla współdzielonych scenariuszy, zadeklaruj qaRunners w manifeście pluginu, zamontuj jako openclaw qa <runner> i utwórz scenariusze w qa/scenarios/.

Zestawy testów (co jest uruchamiane i gdzie)

Traktuj zestawy jako zapewniające „coraz większy realizm” (a zarazem coraz większą niestabilność i wyższy koszt).

Testy jednostkowe/integracyjne (domyślne)

• Polecenie: pnpm test
• Konfiguracja: uruchomienia bez określonego celu używają zestawu fragmentów vitest.full-*.config.ts i mogą rozwijać fragmenty wieloprojektowe do konfiguracji poszczególnych projektów w celu równoległego planowania
• Pliki: podstawowe/jednostkowe zestawy w src/**/*.test.ts, packages/**/*.test.ts oraz test/**/*.test.ts; testy jednostkowe UI są uruchamiane w dedykowanym fragmencie unit-ui
• Zakres:
  • Czyste testy jednostkowe
  • Testy integracyjne wewnątrz procesu (uwierzytelnianie Gateway, routing, narzędzia, analizowanie składni, konfiguracja)
  • Deterministyczne testy regresji znanych błędów
• Oczekiwania:
  • Uruchamiane w CI
  • Nie wymagają rzeczywistych kluczy
  • Powinny być szybkie i stabilne
  • Testy mechanizmu rozwiązywania i programu ładującego powierzchnię publiczną muszą potwierdzać szerokie działanie mechanizmu rezerwowego api.js i runtime-api.js przy użyciu wygenerowanych, minimalnych atrap pluginów, a nie rzeczywistych źródłowych interfejsów API dołączonych pluginów. Ładowanie rzeczywistych interfejsów API pluginów należy do zestawów kontraktowych/integracyjnych będących własnością danego pluginu.

Zasady dotyczące zależności natywnych:

• Domyślne instalacje testowe pomijają opcjonalne natywne kompilacje Opus dla Discord. Głos Discord używa dołączonego libopus-wasm, a @discordjs/opus pozostaje wyłączony w allowBuilds, dzięki czemu testy lokalne i ścieżki Testbox nie kompilują natywnego dodatku.
• Porównuj wydajność natywnego Opus w repozytorium benchmarków libopus-wasm, a nie w domyślnych cyklach instalacji/testów OpenClaw. Nie ustawiaj @discordjs/opus na true w domyślnym allowBuilds; powoduje to kompilowanie kodu natywnego przez niezwiązane z nim cykle instalacji/testów.

Stabilność (Gateway)

• Polecenie: pnpm test:stability:gateway
• Konfiguracja: test/vitest/vitest.gateway.config.ts, test/vitest/vitest.logging.config.ts i test/vitest/vitest.infra.config.ts, każda wymuszona do jednego procesu roboczego
• Zakres:
  • Uruchamia rzeczywisty Gateway local loopback z domyślnie włączoną diagnostyką
  • Generuje syntetyczną rotację wiadomości Gateway, pamięci i dużych ładunków przez ścieżkę zdarzeń diagnostycznych
  • Wysyła zapytania do diagnostics.stability przez RPC WS Gateway
  • Obejmuje funkcje pomocnicze utrwalania pakietu diagnostyki stabilności
  • Sprawdza, czy rejestrator zachowuje ograniczony rozmiar, syntetyczne próbki RSS pozostają poniżej budżetu obciążenia, a głębokości kolejek poszczególnych sesji wracają do zera
• Oczekiwania:
  • Bezpieczne dla CI i niewymagające kluczy
  • Wąska ścieżka do dalszego badania regresji stabilności, a nie zamiennik pełnego zestawu Gateway

E2E (zbiorczo dla repozytorium)

• Polecenie: pnpm test:e2e
• Zakres:
  • Uruchamia ścieżkę testów E2E typu smoke dla Gateway
  • Uruchamia ścieżkę testów E2E przeglądarki z imitacją Control UI
• Oczekiwania:
  • Bezpieczne dla CI i niewymagające kluczy
  • Wymaga zainstalowanego Playwright Chromium

E2E (test smoke Gateway)

• Polecenie: pnpm test:e2e:gateway
• Konfiguracja: test/vitest/vitest.e2e.config.ts
• Pliki: src/**/*.e2e.test.ts, test/**/*.e2e.test.ts oraz testy E2E dołączonych plugins w extensions/
• Domyślne ustawienia środowiska uruchomieniowego:
  • Korzysta z threads Vitest z isolate: false, zgodnie z resztą repozytorium.
  • Korzysta z adaptacyjnej liczby procesów roboczych (CI: maksymalnie 2, lokalnie: domyślnie 1).
  • Domyślnie działa w trybie cichym, aby ograniczyć narzut operacji wejścia/wyjścia konsoli.
• Przydatne ustawienia zastępujące:
  • OPENCLAW_E2E_WORKERS=<n>, aby wymusić liczbę procesów roboczych (maksymalnie 16).
  • OPENCLAW_E2E_VERBOSE=1, aby ponownie włączyć szczegółowe dane wyjściowe konsoli.
• Zakres:
  • Kompleksowe zachowanie wielu instancji Gateway
  • Powierzchnie WebSocket/HTTP, parowanie Node i bardziej złożone operacje sieciowe
• Oczekiwania:
  • Działa w CI (gdy jest włączone w potoku)
  • Nie wymaga rzeczywistych kluczy
  • Więcej elementów ruchomych niż w testach jednostkowych (może działać wolniej)

E2E (przeglądarka z imitacją Control UI)

• Polecenie: pnpm test:ui:e2e
• Konfiguracja: test/vitest/vitest.ui-e2e.config.ts
• Pliki: ui/src/**/*.e2e.test.ts
• Zakres:
  • Uruchamia Control UI Vite
  • Steruje rzeczywistą stroną Chromium za pomocą Playwright
  • Zastępuje WebSocket Gateway deterministycznymi imitacjami w przeglądarce
• Oczekiwania:
  • Działa w CI jako część pnpm test:e2e
  • Nie wymaga rzeczywistego Gateway, agentów ani kluczy dostawców
  • Zależność przeglądarki musi być dostępna (pnpm --dir ui exec playwright install chromium)

E2E: test smoke backendu OpenShell

• Polecenie: pnpm test:e2e:openshell
• Plik: extensions/openshell/src/backend.e2e.test.ts
• Zakres:
  • Ponownie wykorzystuje aktywny lokalny Gateway OpenShell
  • Tworzy piaskownicę z tymczasowego lokalnego pliku Dockerfile
  • Testuje backend OpenShell systemu OpenClaw za pomocą rzeczywistych sandbox ssh-config i wykonywania przez SSH
  • Weryfikuje kanoniczne zachowanie zdalnego systemu plików przez most systemu plików piaskownicy
• Oczekiwania:
  • Tylko opcjonalnie; nie należy do domyślnego uruchomienia pnpm test:e2e
  • Wymaga lokalnego CLI openshell oraz działającego demona Docker
  • Wymaga aktywnego lokalnego Gateway OpenShell i jego źródła konfiguracji
  • Korzysta z izolowanych HOME / XDG_CONFIG_HOME, a następnie niszczy piaskownicę testową
• Przydatne ustawienia zastępujące:
  • OPENCLAW_E2E_OPENSHELL=1, aby włączyć test podczas ręcznego uruchamiania szerszego zestawu e2e
  • OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell, aby wskazać niestandardowy plik binarny CLI lub skrypt opakowujący
  • OPENCLAW_E2E_OPENSHELL_CONFIG_HOME=/path/to/config, aby udostępnić zarejestrowaną konfigurację Gateway izolowanemu testowi
  • OPENCLAW_E2E_OPENSHELL_HOST_IP=172.18.0.1, aby zastąpić adres IP Gateway Docker używany przez dane testowe zasad hosta

Aktywne testy (rzeczywiści dostawcy i rzeczywiste modele)

• Polecenie: pnpm test:live
• Konfiguracja: test/vitest/vitest.live.config.ts
• Pliki: src/**/*.live.test.ts, test/**/*.live.test.ts oraz testy na żywo wbudowanych pluginów w katalogu extensions/
• Domyślnie: włączone przez pnpm test:live (ustawia OPENCLAW_LIVE_TEST=1)
• Zakres:
  • „Czy ten dostawca/model rzeczywiście działa dzisiaj z prawdziwymi danymi uwierzytelniającymi?”
  • Wykrywanie zmian formatów dostawców, niuansów wywoływania narzędzi, problemów z uwierzytelnianiem oraz zachowania limitów szybkości
• Założenia:
  • Z założenia brak stabilności w CI (rzeczywiste sieci, rzeczywiste zasady dostawców, limity, awarie)
  • Generuje koszty / wykorzystuje limity szybkości
  • Zaleca się uruchamianie zawężonych podzbiorów zamiast „wszystkiego”
• Uruchomienia na żywo korzystają z już wyeksportowanych kluczy API i przygotowanych profili uwierzytelniania.
• Domyślnie uruchomienia na żywo nadal izolują HOME oraz kopiują konfigurację i materiały uwierzytelniające do tymczasowego katalogu domowego testów, aby fixtury testów jednostkowych nie mogły zmodyfikować rzeczywistego katalogu ~/.openclaw.
• Ustaw OPENCLAW_LIVE_USE_REAL_HOME=1 tylko wtedy, gdy celowo chcesz, aby testy na żywo korzystały z rzeczywistego katalogu domowego.
• pnpm test:live domyślnie działa w cichszym trybie: zachowuje komunikaty postępu [live] ..., a wycisza dzienniki uruchamiania Gateway i komunikaty Bonjour. Ustaw OPENCLAW_LIVE_TEST_QUIET=0, jeśli chcesz ponownie wyświetlać pełne dzienniki uruchamiania.
• Rotacja kluczy API (zależna od dostawcy): ustaw *_API_KEYS w formacie z przecinkami/średnikami albo *_API_KEY_1, *_API_KEY_2 (na przykład OPENAI_API_KEYS, ANTHROPIC_API_KEYS, GEMINI_API_KEYS) lub nadpisanie dla uruchomienia na żywo przez OPENCLAW_LIVE_*_KEY; testy ponawiają próby po odpowiedziach o przekroczeniu limitu szybkości.
• Komunikaty postępu/Heartbeat:
  • Zestawy testów na żywo wysyłają wiersze postępu do stderr, dzięki czemu długie wywołania dostawców pozostają widocznie aktywne, nawet gdy przechwytywanie konsoli przez Vitest jest wyciszone.
  • test/vitest/vitest.live.config.ts wyłącza przechwytywanie konsoli przez Vitest, dzięki czemu wiersze postępu dostawcy/Gateway są natychmiast wyświetlane podczas uruchomień na żywo.
  • Dostosuj częstotliwość Heartbeat bezpośrednich modeli za pomocą OPENCLAW_LIVE_HEARTBEAT_MS.
  • Dostosuj częstotliwość Heartbeat Gateway/sond za pomocą OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS.

Który zestaw testów należy uruchomić?

Skorzystaj z tej tabeli decyzyjnej:

• Edycja logiki/testów: uruchom pnpm test (oraz pnpm test:coverage, jeśli zakres zmian był duży)
• Zmiany w komunikacji sieciowej Gateway / protokole WS / parowaniu: dodaj pnpm test:e2e
• Diagnozowanie problemu „mój bot nie działa” / błędów właściwych dla dostawcy / wywoływania narzędzi: uruchom zawężone pnpm test:live

Testy na żywo (korzystające z sieci)

Informacje o macierzy modeli na żywo, testach dymnych zaplecza CLI, testach dymnych ACP, środowisku testowym serwera aplikacji Codex oraz wszystkich testach na żywo dostawców multimediów (Deepgram, BytePlus, ComfyUI, obrazy, muzyka, wideo, środowisko testowe multimediów), a także obsłudze danych uwierzytelniających podczas uruchomień na żywo:

• zobacz Testowanie zestawów na żywo. Dedykowana lista kontrolna weryfikacji aktualizacji i pluginów znajduje się w sekcji Testowanie aktualizacji i pluginów.

Programy uruchamiające Docker (opcjonalne kontrole „czy działa w systemie Linux”)

Te programy uruchamiające Docker dzielą się na dwie grupy:

• Programy uruchamiające modele na żywo: test:docker:live-models i test:docker:live-gateway uruchamiają w obrazie Docker repozytorium tylko odpowiadający im plik na żywo z kluczami profili (src/agents/models.profiles.live.test.ts i src/gateway/gateway-models.profiles.live.test.ts), montując lokalny katalog konfiguracji, obszar roboczy i opcjonalny plik środowiskowy profilu. Odpowiadające im lokalne punkty wejścia to test:live:models-profiles i test:live:gateway-profiles.
• Programy uruchamiające Docker na żywo zachowują własne praktyczne ograniczenia tam, gdzie są potrzebne: test:docker:live-models domyślnie używa wyselekcjonowanego, obsługiwanego zestawu zapewniającego wyraźne sygnały, a test:docker:live-gateway domyślnie ustawia OPENCLAW_LIVE_GATEWAY_SMOKE=1, OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8, OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000 oraz OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000. Ustaw OPENCLAW_LIVE_MAX_MODELS lub zmienne środowiskowe Gateway, gdy celowo potrzebujesz mniejszego limitu albo szerszego skanowania.
• test:docker:all jednokrotnie buduje obraz Docker do testów na żywo za pomocą test:docker:live-build, jednokrotnie pakuje OpenClaw jako archiwum npm za pośrednictwem scripts/package-openclaw-for-docker.mjs, a następnie buduje lub ponownie wykorzystuje dwa obrazy scripts/e2e/Dockerfile. Podstawowy obraz zawiera tylko środowisko uruchomieniowe Node/Git dla ścieżek instalacji/aktualizacji/zależności pluginów; ścieżki te montują wcześniej zbudowane archiwum. Obraz funkcjonalny instaluje to samo archiwum w /app dla ścieżek funkcjonalności zbudowanej aplikacji. Definicje ścieżek Docker znajdują się w scripts/lib/docker-e2e-scenarios.mjs; logika planisty znajduje się w scripts/lib/docker-e2e-plan.mjs; scripts/test-docker-all.mjs wykonuje wybrany plan. Agregator używa ważonego lokalnego harmonogramu: OPENCLAW_DOCKER_ALL_PARALLELISM określa liczbę miejsc na procesy, natomiast limity zasobów zapobiegają jednoczesnemu uruchamianiu wszystkich wymagających ścieżek na żywo, instalacji npm i ścieżek wielousługowych. Jeśli pojedyncza ścieżka jest cięższa niż aktywne limity, harmonogram nadal może ją uruchomić, gdy pula jest pusta, a następnie pozostawia ją jako jedyną uruchomioną do czasu ponownego udostępnienia zasobów. Wartości domyślne to 10 miejsc, OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9, OPENCLAW_DOCKER_ALL_NPM_LIMIT=5 i OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7; dostosuj OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT lub OPENCLAW_DOCKER_ALL_DOCKER_LIMIT (oraz inne nadpisania OPENCLAW_DOCKER_ALL_<RESOURCE>_LIMIT) tylko wtedy, gdy host Docker ma większy zapas zasobów. Program uruchamiający domyślnie przeprowadza kontrolę wstępną Docker, usuwa nieaktualne kontenery E2E OpenClaw, wyświetla stan co 30 sekund, zapisuje czasy pomyślnie wykonanych ścieżek w .artifacts/docker-tests/lane-timings.json i wykorzystuje je do wcześniejszego uruchamiania dłuższych ścieżek podczas kolejnych uruchomień. Użyj OPENCLAW_DOCKER_ALL_DRY_RUN=1, aby wyświetlić ważony manifest ścieżek bez budowania ani uruchamiania Docker, lub node scripts/test-docker-all.mjs --plan-json, aby wyświetlić plan CI dla wybranych ścieżek, wymagania dotyczące pakietów/obrazów i dane uwierzytelniające.
• Package Acceptance to natywna dla GitHub kontrola pakietu odpowiadająca na pytanie „czy to instalowalne archiwum działa jako produkt?”. Wyznacza jeden pakiet kandydujący ze źródła source=npm, source=ref, source=url, source=trusted-url lub source=artifact, przesyła go jako package-under-test, a następnie uruchamia wielokrotnego użytku ścieżki E2E Docker dla dokładnie tego archiwum zamiast ponownie pakować wybrane odwołanie. Profile są uporządkowane według zakresu: smoke, package, product i full (oraz custom dla jawnej listy ścieżek). Zobacz Testowanie aktualizacji i pluginów, aby poznać kontrakt pakietów/aktualizacji/pluginów, macierz zachowania stanu po opublikowanej aktualizacji, ustawienia domyślne wydań i diagnostykę błędów.
• Kontrole kompilacji i wydania uruchamiają scripts/check-cli-bootstrap-imports.mjs po tsdown. Mechanizm ochronny przechodzi statyczny graf zbudowanych zależności od dist/entry.js i dist/cli/run-main.js oraz zgłasza błąd, jeśli ten graf uruchamiania przed przekazaniem sterowania statycznie importuje jakikolwiek pakiet zewnętrzny (Commander, interfejs monitów, undici, rejestrowanie i podobne zależności obciążające uruchamianie są brane pod uwagę) przed przekazaniem polecenia; ogranicza także rozmiar pakietowanego fragmentu uruchomieniowego Gateway do 70 KB i odrzuca z tego fragmentu statyczne importy znanych rzadko używanych ścieżek Gateway (control-ui-assets, diagnostic-stability-bundle, onboard-helpers, process-respawn, restart-sentinel, server-close, server-reload-handlers). scripts/release-check.ts niezależnie przeprowadza testy dymne spakowanego CLI za pomocą --help, onboard --help, doctor --help, status --json --timeout 1, config schema i models list --provider openai.
• Zgodność wsteczna Package Acceptance jest ograniczona do wersji 2026.4.25 (włącznie z 2026.4.25-beta.*). Do tej wersji granicznej środowisko testowe toleruje wyłącznie luki w metadanych opublikowanych pakietów: pominięte wpisy prywatnego spisu QA, brak gateway install --wrapper, brak plików poprawek w fixturze Git utworzonej z archiwum, brak utrwalonego update.channel, starsze lokalizacje rekordów instalacji pluginów, brak utrwalania rekordów instalacji z marketplace oraz migrację metadanych konfiguracji podczas plugins update. W przypadku pakietów nowszych niż 2026.4.25 ścieżki te powodują bezwzględne błędy.
• Programy uruchamiające testy dymne kontenerów: test:docker:openwebui, test:docker:onboard, test:docker:npm-onboard-channel-agent, test:docker:release-user-journey, test:docker:release-typed-onboarding, test:docker:release-media-memory, test:docker:release-upgrade-user-journey, test:docker:release-plugin-marketplace, test:docker:skill-install, test:docker:update-channel-switch, test:docker:upgrade-survivor, test:docker:published-upgrade-survivor, test:docker:session-runtime-context, test:docker:agents-delete-shared-workspace, test:docker:gateway-network, test:docker:browser-cdp-snapshot, test:docker:mcp-channels, test:docker:agent-bundle-mcp-tools, test:docker:cron-mcp-cleanup, test:docker:plugins, test:docker:plugin-update, test:docker:plugin-lifecycle-matrix i test:docker:config-reload uruchamiają co najmniej jeden rzeczywisty kontener oraz weryfikują ścieżki integracji wyższego poziomu.
• Ścieżki E2E Docker/Bash, które instalują spakowane archiwum OpenClaw za pośrednictwem scripts/lib/openclaw-e2e-instance.sh, ograniczają czas npm install za pomocą OPENCLAW_E2E_NPM_INSTALL_TIMEOUT (domyślnie 600s; ustaw 0, aby wyłączyć opakowanie na potrzeby debugowania).

Programy uruchamiające Docker dla modeli na żywo montują również tylko niezbędne katalogi domowe uwierzytelniania CLI (lub wszystkie obsługiwane, gdy uruchomienie nie jest zawężone), a następnie kopiują je do katalogu domowego kontenera przed uruchomieniem, dzięki czemu OAuth zewnętrznego CLI może odświeżać tokeny bez modyfikowania magazynu uwierzytelniania hosta:

• Modele bezpośrednie: pnpm test:docker:live-models (skrypt: scripts/test-live-models-docker.sh)

• Test dymny powiązania ACP: pnpm test:docker:live-acp-bind (skrypt: scripts/test-live-acp-bind-docker.sh; domyślnie obejmuje Claude, Codex i Gemini, a ścisłe pokrycie Droid/OpenCode zapewniają pnpm test:docker:live-acp-bind:droid oraz pnpm test:docker:live-acp-bind:opencode)

• Test dymny zaplecza CLI: pnpm test:docker:live-cli-backend (skrypt: scripts/test-live-cli-backend-docker.sh)

• Test dymny środowiska testowego serwera aplikacji Codex: pnpm test:docker:live-codex-harness (skrypt: scripts/test-live-codex-harness-docker.sh)

• Gateway + agent deweloperski: pnpm test:docker:live-gateway (skrypt: scripts/test-live-gateway-models-docker.sh)

• Testy dymne obserwowalności: pnpm qa:otel:smoke, pnpm qa:prometheus:smoke i pnpm qa:observability:smoke są prywatnymi ścieżkami QA dla kopii roboczej kodu źródłowego. Celowo nie należą do ścieżek wydania pakietu Docker, ponieważ archiwum npm pomija QA Lab.

• Test dymny Open WebUI na żywo: pnpm test:docker:openwebui (skrypt: scripts/e2e/openwebui-docker.sh)

• Kreator wdrażania (TTY, pełne tworzenie struktury): pnpm test:docker:onboard (skrypt: scripts/e2e/onboard-docker.sh)

• Test dymny wdrażania/kanału/agenta z archiwum npm: pnpm test:docker:npm-onboard-channel-agent instaluje globalnie spakowane archiwum OpenClaw w Docker, domyślnie konfiguruje OpenAI za pośrednictwem wdrażania z odwołaniem do zmiennej środowiskowej oraz Telegram, uruchamia doctor, a następnie wykonuje jedną pozorowaną turę agenta OpenAI. Ponownie wykorzystaj wcześniej zbudowane archiwum za pomocą OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz, pomiń ponowną kompilację na hoście za pomocą OPENCLAW_NPM_ONBOARD_HOST_BUILD=0 albo zmień kanał za pomocą OPENCLAW_NPM_ONBOARD_CHANNEL=discord lub OPENCLAW_NPM_ONBOARD_CHANNEL=slack.

• Test dymny ścieżki użytkownika wydania: pnpm test:docker:release-user-journey instaluje globalnie spakowane archiwum tar OpenClaw w czystym katalogu domowym Dockera, uruchamia proces wdrożeniowy, konfiguruje atrapę dostawcy OpenAI, wykonuje turę agenta, instaluje i odinstalowuje zewnętrzne pluginy, konfiguruje ClickClack względem lokalnej fixtury, weryfikuje komunikację wychodzącą i przychodzącą, ponownie uruchamia Gateway oraz uruchamia diagnostykę.

• Test dymny wydania z typowanym procesem wdrożeniowym: pnpm test:docker:release-typed-onboarding instaluje spakowane archiwum tar, przeprowadza openclaw onboard przez rzeczywisty TTY, konfiguruje OpenAI jako dostawcę odwołującego się do zmiennej środowiskowej, weryfikuje, że surowy klucz nie jest utrwalany, oraz wykonuje turę agenta z atrapą.

• Test dymny multimediów i pamięci wydania: pnpm test:docker:release-media-memory instaluje spakowane archiwum tar, weryfikuje rozumienie obrazu z załącznika PNG, wynik generowania obrazu zgodnego z OpenAI, przywoływanie przez wyszukiwanie w pamięci oraz zachowanie możliwości przywoływania po ponownym uruchomieniu Gateway.

• Test dymny ścieżki użytkownika podczas uaktualnienia wydania: pnpm test:docker:release-upgrade-user-journey domyślnie instaluje najnowszą opublikowaną wersję bazową starszą od kandydującego archiwum tar, konfiguruje stan dostawcy, pluginu i ClickClack w opublikowanym pakiecie, uaktualnia go do kandydującego archiwum tar, a następnie ponownie wykonuje podstawową ścieżkę agenta, pluginu i kanału. Jeśli nie istnieje starsza opublikowana wersja bazowa, ponownie wykorzystuje wersję kandydującą. Wersję bazową można zastąpić za pomocą OPENCLAW_RELEASE_UPGRADE_BASELINE_SPEC=openclaw@<version>.

• Test dymny sklepu z pluginami wydania: pnpm test:docker:release-plugin-marketplace instaluje plugin z lokalnej fixtury sklepu, aktualizuje zainstalowany plugin, odinstalowuje go i weryfikuje, że CLI pluginu znika wraz z usunięciem metadanych instalacji.

• Test dymny instalowania Skills: pnpm test:docker:skill-install instaluje globalnie spakowane archiwum tar OpenClaw w Dockerze, wyłącza w konfiguracji instalowanie przesłanych archiwów, ustala na podstawie wyszukiwania aktualny identyfikator działającego Skill w ClawHub, instaluje go za pomocą openclaw skills install oraz weryfikuje zainstalowany Skill wraz z metadanymi pochodzenia i blokady .clawhub.

• Test dymny zmiany kanału aktualizacji: pnpm test:docker:update-channel-switch instaluje globalnie spakowane archiwum tar OpenClaw w Dockerze, przełącza się z pakietu stable na gitowy kanał dev, weryfikuje utrwalony kanał i działanie pluginu po aktualizacji, a następnie przełącza się z powrotem na pakiet stable i sprawdza stan aktualizacji.

• Test dymny zachowania stanu po uaktualnieniu: pnpm test:docker:upgrade-survivor instaluje spakowane archiwum tar OpenClaw na nieuporządkowanej fixturze starego użytkownika, zawierającej agentów, konfigurację kanału, listy dozwolonych pluginów, nieaktualny stan zależności pluginów oraz istniejące pliki przestrzeni roboczej i sesji. Uruchamia aktualizację pakietu oraz nieinteraktywną diagnostykę bez aktywnych kluczy dostawcy lub kanału, następnie uruchamia Gateway w local loopback i sprawdza zachowanie konfiguracji oraz stanu, a także limity czasu uruchamiania i pobierania stanu.

• Test dymny zachowania stanu po uaktualnieniu opublikowanej wersji: pnpm test:docker:published-upgrade-survivor domyślnie instaluje openclaw@latest, tworzy realistyczne pliki istniejącego użytkownika, konfiguruje tę wersję bazową przy użyciu wbudowanej sekwencji poleceń, sprawdza wynikową konfigurację, aktualizuje tę opublikowaną instalację do kandydującego archiwum tar, uruchamia nieinteraktywną diagnostykę, zapisuje .artifacts/upgrade-survivor/summary.json, a następnie uruchamia Gateway w local loopback i sprawdza skonfigurowane intencje, zachowanie stanu, uruchamianie, /healthz, /readyz oraz limity czasu stanu RPC. Jedną wersję bazową można zastąpić za pomocą OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC; można polecić zbiorczemu harmonogramowi rozwinięcie dokładnych lokalnych wersji bazowych za pomocą OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS, na przykład openclaw@2026.5.2 openclaw@2026.4.23 openclaw@2026.4.15, oraz rozwinięcie fixtur odpowiadających zgłoszeniom za pomocą OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS, na przykład reported-issues; zestaw zgłoszonych problemów obejmuje configured-plugin-installs, służące do automatycznej naprawy instalacji zewnętrznych pluginów OpenClaw. Akceptacja pakietu udostępnia je jako published_upgrade_survivor_baseline, published_upgrade_survivor_baselines i published_upgrade_survivor_scenarios, rozwiązuje metatokeny wersji bazowych, takie jak last-stable-4 lub all-since-2026.4.23, a pełna walidacja wydania rozwija bramkę pakietową długotrwałego testu wydania do last-stable-4 2026.4.23 2026.5.2 2026.4.15 wraz z reported-issues.

• Test dymny kontekstu środowiska wykonawczego sesji: pnpm test:docker:session-runtime-context weryfikuje utrwalanie ukrytego kontekstu środowiska wykonawczego w transkrypcji oraz naprawę przez diagnostykę powiązanych, zduplikowanych gałęzi przepisywania promptów.

• Test dymny globalnej instalacji Bun: bash scripts/e2e/bun-global-install-smoke.sh pakuje bieżące drzewo, instaluje je za pomocą bun install -g w odizolowanym katalogu domowym i weryfikuje, że openclaw infer image providers --json zwraca wbudowanych dostawców obrazów zamiast się zawieszać. Wstępnie zbudowane archiwum tar można ponownie wykorzystać za pomocą OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz, pominąć kompilację na hoście za pomocą OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0 lub skopiować dist/ ze zbudowanego obrazu Dockera za pomocą OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local.

• Test dymny instalatora w Dockerze: bash scripts/test-install-sh-docker.sh współdzieli jedną pamięć podręczną npm między kontenerami głównym, aktualizacyjnym i bezpośredniego npm. Test dymny aktualizacji domyślnie używa wersji npm latest jako stabilnej wersji bazowej przed uaktualnieniem do kandydującego archiwum tar. Lokalnie można ją zastąpić za pomocą OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22, a w GitHubie za pomocą parametru update_baseline_version przepływu pracy Install Smoke. Kontrole instalatora bez uprawnień użytkownika root zachowują odizolowaną pamięć podręczną npm, aby wpisy pamięci podręcznej należące do użytkownika root nie maskowały zachowania instalacji lokalnej dla użytkownika. Ustaw OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache, aby ponownie używać pamięci podręcznej głównego, aktualizacyjnego i bezpośredniego npm podczas lokalnych powtórzeń.

• CI Install Smoke pomija zduplikowaną bezpośrednią globalną aktualizację npm za pomocą OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1; uruchom skrypt lokalnie bez tej zmiennej środowiskowej, gdy potrzebne jest pokrycie bezpośredniego npm install -g.

• Test dymny CLI usuwania przez agentów współdzielonej przestrzeni roboczej: pnpm test:docker:agents-delete-shared-workspace (skrypt: scripts/e2e/agents-delete-shared-workspace-docker.sh) domyślnie buduje obraz z głównego pliku Dockerfile, tworzy dwóch agentów korzystających z jednej przestrzeni roboczej w odizolowanym katalogu domowym kontenera, uruchamia agents delete --json oraz weryfikuje poprawny JSON i zachowanie pozostawionej przestrzeni roboczej. Obraz testu instalacji można ponownie wykorzystać za pomocą OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1.

• Sieć Gateway i cykl życia hosta: pnpm test:docker:gateway-network (skrypt: scripts/e2e/gateway-network-docker.sh) zachowuje dwukontenerowy test dymny uwierzytelniania i kondycji WebSocket w sieci LAN, a następnie używa administracyjnego interfejsu HTTP w local loopback, aby potwierdzić blokadę przygotowania, dostęp z zachowaniem kontroli, odzyskiwanie po wznowieniu oraz przygotowane zatrzymanie i uruchomienie w tym samym kontenerze. Kontrola ponownego uruchomienia musi zakończyć się przed wygaśnięciem pierwotnej dzierżawy; weryfikuje, że stan zawieszenia jest lokalny dla procesu, podczas gdy utrwalona konfiguracja Gateway i tożsamość kontenera zostają zachowane, oraz generuje możliwy do odczytu maszynowego plik JSON z czasami faz.

• Test dymny migawki CDP przeglądarki: pnpm test:docker:browser-cdp-snapshot (skrypt: scripts/e2e/browser-cdp-snapshot-docker.sh) buduje źródłowy obraz E2E wraz z warstwą Chromium, uruchamia Chromium z bezpośrednim CDP, wykonuje browser doctor --deep i weryfikuje, że migawki ról CDP obejmują adresy URL odnośników, elementy klikalne wykryte za pomocą kursora, odwołania do ramek iframe oraz metadane ramek.

• Regresja minimalnego poziomu wnioskowania dla web_search w OpenAI Responses: pnpm test:docker:openai-web-search-minimal (skrypt: scripts/e2e/openai-web-search-minimal-docker.sh) uruchamia atrapę serwera OpenAI przez Gateway, weryfikuje, że web_search podnosi reasoning.effort z minimal do low, następnie wymusza odrzucenie schematu dostawcy i sprawdza, czy surowe szczegóły pojawiają się w dziennikach Gateway.

• Most kanałów MCP (Gateway ze wstępnie utworzonym stanem + most stdio + test dymny surowej ramki powiadomienia Claude): pnpm test:docker:mcp-channels (skrypt: scripts/e2e/mcp-channels-docker.sh)

• Narzędzia MCP pakietu OpenClaw (rzeczywisty serwer MCP stdio + test dymny zezwalania i blokowania we wbudowanym profilu OpenClaw): pnpm test:docker:agent-bundle-mcp-tools (skrypt: scripts/e2e/agent-bundle-mcp-tools-docker.sh)

• Czyszczenie MCP dla Cron i podagentów (rzeczywisty Gateway + zamykanie procesu potomnego MCP stdio po odizolowanych uruchomieniach Cron i jednorazowych uruchomieniach podagentów): pnpm test:docker:cron-mcp-cleanup (skrypt: scripts/e2e/cron-mcp-cleanup-docker.sh)

• Pluginy (test dymny instalacji i aktualizacji dla ścieżki lokalnej, file:, rejestru npm z wyniesionymi zależnościami, nieprawidłowych metadanych pakietu npm, ruchomych odwołań git, kompleksowej fixtury ClawHub, aktualizacji sklepu oraz włączania i inspekcji pakietu Claude): pnpm test:docker:plugins (skrypt: scripts/e2e/plugins-docker.sh) Ustaw OPENCLAW_PLUGINS_E2E_CLAWHUB=0, aby pominąć blok ClawHub, albo zastąp domyślną parę kompleksowego pakietu i środowiska wykonawczego za pomocą OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC oraz OPENCLAW_PLUGINS_E2E_CLAWHUB_ID. Bez OPENCLAW_CLAWHUB_URL/CLAWHUB_URL test używa hermetycznego lokalnego serwera fixtury ClawHub.

• Test dymny aktualizacji niezmienionego pluginu: pnpm test:docker:plugin-update (skrypt: scripts/e2e/plugin-update-unchanged-docker.sh)

• Test dymny macierzy cyklu życia pluginu: pnpm test:docker:plugin-lifecycle-matrix instaluje spakowane archiwum tar OpenClaw w pustym kontenerze, instaluje plugin npm, przełącza jego stan włączenia i wyłączenia, uaktualnia go i obniża jego wersję za pośrednictwem lokalnego rejestru npm, usuwa zainstalowany kod, a następnie weryfikuje, że odinstalowanie nadal usuwa nieaktualny stan, jednocześnie zapisując metryki RSS i CPU dla każdej fazy cyklu życia.

• Test dymny metadanych ponownego wczytywania konfiguracji: pnpm test:docker:config-reload (skrypt: scripts/e2e/config-reload-source-docker.sh)

• Pluginy: pnpm test:docker:plugins obejmuje testy dymne instalacji i aktualizacji dla ścieżki lokalnej, file:, rejestru npm z wyniesionymi zależnościami, ruchomych odwołań git, fixtur ClawHub, aktualizacji sklepu oraz włączania i inspekcji pakietu Claude. pnpm test:docker:plugin-update obejmuje zachowanie aktualizacji bez zmian dla zainstalowanych pluginów. pnpm test:docker:plugin-lifecycle-matrix obejmuje monitorowane pod względem zasobów instalowanie, włączanie, wyłączanie, uaktualnianie, obniżanie wersji i odinstalowywanie pluginu npm z brakującym kodem.

Aby ręcznie wstępnie zbudować i ponownie wykorzystywać współdzielony obraz funkcjonalny:

OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local pnpm test:docker:e2e-buildOPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels

Ustawienia zastępujące obraz dla poszczególnych zestawów, takie jak OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE, nadal mają pierwszeństwo, gdy są ustawione. Gdy OPENCLAW_SKIP_DOCKER_BUILD=1 wskazuje zdalny obraz współdzielony, skrypty pobierają go, jeśli nie jest jeszcze dostępny lokalnie. Testy QR i instalatora w Dockerze zachowują własne pliki Dockerfile, ponieważ weryfikują zachowanie pakietu i instalacji, a nie środowisko wykonawcze współdzielonej zbudowanej aplikacji.

Mechanizmy uruchamiające modele aktywne w Dockerze również montują bieżące drzewo robocze w trybie tylko do odczytu i przygotowują je w tymczasowym katalogu roboczym wewnątrz kontenera. Dzięki temu obraz środowiska wykonawczego pozostaje niewielki, a Vitest nadal działa dokładnie na lokalnych źródłach i konfiguracji. Etap przygotowania pomija duże pamięci podręczne używane wyłącznie lokalnie oraz wyniki kompilacji aplikacji, takie jak .pnpm-store, .worktrees, __openclaw_vitest__, a także lokalne dla aplikacji katalogi wynikowe .build lub Gradle, dzięki czemu aktywne uruchomienia w Dockerze nie poświęcają wielu minut na kopiowanie artefaktów specyficznych dla danego komputera. Ustawiają również OPENCLAW_SKIP_CHANNELS=1, aby aktywne sondy Gateway nie uruchamiały rzeczywistych procesów roboczych kanałów Telegram, Discord itd. wewnątrz kontenera. test:docker:live-models nadal uruchamia pnpm test:live, dlatego przekaż również OPENCLAW_LIVE_GATEWAY_*, gdy chcesz zawęzić lub wykluczyć aktywne testy Gateway z tej ścieżki Dockera.

test:docker:openwebui to test zgodności wyższego poziomu: uruchamia kontener Gateway OpenClaw z włączonymi punktami końcowymi HTTP zgodnymi z OpenAI, uruchamia przypięty kontener Open WebUI połączony z tym Gateway, loguje się przez Open WebUI, sprawdza, czy /api/models udostępnia openclaw/default, a następnie wysyła rzeczywiste żądanie czatu przez serwer proxy /api/chat/completions Open WebUI. Ustaw OPENWEBUI_SMOKE_MODE=models dla kontroli CI ścieżki wydania, które powinny zakończyć się po zalogowaniu do Open WebUI i wykryciu modelu, bez oczekiwania na odpowiedź aktywnego modelu. Pierwsze uruchomienie może być zauważalnie wolniejsze, ponieważ Docker może wymagać pobrania obrazu Open WebUI, a Open WebUI może wymagać ukończenia własnej konfiguracji po zimnym starcie. Ta ścieżka wymaga użytecznego klucza aktywnego modelu, udostępnionego przez środowisko procesu, przygotowane profile uwierzytelniania lub jawny plik OPENCLAW_PROFILE_FILE. Pomyślne uruchomienia wyświetlają niewielki ładunek JSON, taki jak { "ok": true, "model": "openclaw/default", ... }.

test:docker:mcp-channels jest celowo deterministyczny i nie wymaga rzeczywistego konta Telegram, Discord ani iMessage. Uruchamia kontener Gateway ze wstępnie przygotowanymi danymi, a następnie drugi kontener, który uruchamia openclaw mcp serve, po czym sprawdza kierowane wykrywanie konwersacji, odczyt transkrypcji, metadane załączników, zachowanie kolejki zdarzeń na żywo, kierowanie wysyłania wychodzącego oraz powiadomienia w stylu Claude dotyczące kanałów i uprawnień przez rzeczywisty most MCP stdio. Kontrola powiadomień bezpośrednio analizuje surowe ramki MCP stdio, dzięki czemu test sprawdza to, co most faktycznie emituje, a nie tylko to, co akurat udostępnia określony zestaw SDK klienta.

test:docker:agent-bundle-mcp-tools jest deterministyczny i nie wymaga klucza aktywnego modelu. Buduje obraz Docker repozytorium, uruchamia wewnątrz kontenera rzeczywisty serwer sondujący MCP stdio, materializuje ten serwer przez osadzone środowisko uruchomieniowe MCP pakietu OpenClaw, wykonuje narzędzie, a następnie sprawdza, czy coding i messaging zachowują narzędzia bundle-mcp, natomiast minimal i tools.deny: ["bundle-mcp"] je filtrują.

test:docker:cron-mcp-cleanup jest deterministyczny i nie wymaga klucza aktywnego modelu. Uruchamia Gateway ze wstępnie przygotowanymi danymi oraz rzeczywistym serwerem sondującym MCP stdio, wykonuje izolowaną turę cron i jednorazową turę potomną sessions_spawn, a następnie sprawdza, czy proces potomny MCP kończy działanie po każdym uruchomieniu.

Ręczny test wątku ACP z użyciem języka naturalnego (poza CI):

• bun scripts/dev/discord-acp-plain-language-smoke.ts --channel <discord-channel-id> ...
• Zachowaj ten skrypt na potrzeby procedur regresyjnych i debugowania. Może być ponownie potrzebny do weryfikacji kierowania wątków ACP, dlatego nie należy go usuwać.

Przydatne zmienne środowiskowe:

• OPENCLAW_CONFIG_DIR=... (domyślnie: ~/.openclaw) montowany w /home/node/.openclaw
• OPENCLAW_WORKSPACE_DIR=... (domyślnie: ~/.openclaw/workspace) montowany w /home/node/.openclaw/workspace
• OPENCLAW_PROFILE_FILE=... montowany i wczytywany przed uruchomieniem testów
• OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1, aby sprawdzać wyłącznie zmienne środowiskowe wczytane z OPENCLAW_PROFILE_FILE, z użyciem tymczasowych katalogów konfiguracji i obszaru roboczego oraz bez zewnętrznych montowań uwierzytelniania CLI
• OPENCLAW_DOCKER_CLI_TOOLS_DIR=... (domyślnie: ~/.cache/openclaw/docker-cli-tools, chyba że uruchomienie korzysta już z katalogu montowania zarządzanego lub CI) montowany w /home/node/.npm-global na potrzeby buforowanych instalacji CLI wewnątrz Docker
• Zewnętrzne katalogi i pliki uwierzytelniania CLI w $HOME są montowane tylko do odczytu w /host-auth..., a następnie kopiowane do /home/node/... przed rozpoczęciem testów
  • Domyślne katalogi (używane, gdy uruchomienie nie jest ograniczone do określonych dostawców): .factory, .gemini, .minimax
  • Domyślne pliki: ~/.codex/auth.json, ~/.codex/config.toml, .claude.json, ~/.claude/.credentials.json, ~/.claude/settings.json, ~/.claude/settings.local.json
  • Uruchomienia ograniczone do dostawców montują tylko wymagane katalogi i pliki wywnioskowane z OPENCLAW_LIVE_PROVIDERS / OPENCLAW_LIVE_GATEWAY_PROVIDERS
  • Można to ręcznie zastąpić przez OPENCLAW_DOCKER_AUTH_DIRS=all, OPENCLAW_DOCKER_AUTH_DIRS=none lub listę rozdzielaną przecinkami, taką jak OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex
• OPENCLAW_LIVE_GATEWAY_MODELS=... / OPENCLAW_LIVE_MODELS=..., aby zawęzić uruchomienie
• OPENCLAW_LIVE_GATEWAY_PROVIDERS=... / OPENCLAW_LIVE_PROVIDERS=..., aby filtrować dostawców wewnątrz kontenera
• OPENCLAW_SKIP_DOCKER_BUILD=1, aby ponownie wykorzystać istniejący obraz openclaw:local-live w kolejnych uruchomieniach, które nie wymagają ponownego budowania
• OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1, aby upewnić się, że dane uwierzytelniające pochodzą z magazynu profili, a nie ze środowiska
• OPENCLAW_OPENWEBUI_MODEL=..., aby wybrać model udostępniany przez Gateway na potrzeby testu Open WebUI
• OPENCLAW_OPENWEBUI_PROMPT=..., aby zastąpić monit kontroli wartości jednorazowej używany przez test Open WebUI
• OPENWEBUI_IMAGE=..., aby zastąpić przypięty tag obrazu Open WebUI

Kontrola poprawności dokumentacji

Po edycji dokumentacji uruchom kontrole dokumentacji: pnpm check:docs. Gdy potrzebne jest również sprawdzenie nagłówków wewnątrz stron, uruchom pełną walidację kotwic Mintlify: pnpm docs:check-links:anchors.

Regresje offline (bezpieczne dla CI)

Są to regresje „rzeczywistego potoku” bez rzeczywistych dostawców:

• Wywoływanie narzędzi przez Gateway (atrapa OpenAI, rzeczywisty Gateway i pętla agenta): src/gateway/gateway.test.ts (przypadek: "runs a mock OpenAI tool call end-to-end via gateway agent loop")
• Kreator Gateway (wizard.start/wizard.next przez WS, zapisuje konfigurację i wymusza uwierzytelnianie): src/gateway/gateway.test.ts (przypadek: "runs wizard over ws and writes auth token config")

Testy oceniające niezawodność agenta (Skills)

Mamy już kilka testów bezpiecznych dla CI, które działają jak „testy oceniające niezawodność agenta”:

• Pozorowane wywoływanie narzędzi przez rzeczywisty Gateway i pętlę agenta (src/gateway/gateway.test.ts).
• Kompleksowe przepływy kreatora, które sprawdzają powiązanie sesji i skutki konfiguracji (src/gateway/gateway.test.ts).

Czego nadal brakuje w przypadku Skills (zobacz Skills):

• Podejmowanie decyzji: czy agent wybiera właściwą umiejętność, gdy umiejętności są wymienione w monicie, lub unika nieistotnych?
• Zgodność: czy agent przed użyciem odczytuje SKILL.md i wykonuje wymagane kroki oraz przekazuje wymagane argumenty?
• Kontrakty przepływów pracy: scenariusze wieloturowe, które sprawdzają kolejność narzędzi, przenoszenie historii sesji i granice piaskownicy.

Przyszłe testy oceniające powinny być przede wszystkim deterministyczne:

• Program uruchamiający scenariusze, który używa pozorowanych dostawców do sprawdzania wywołań narzędzi i ich kolejności, odczytów plików umiejętności oraz powiązania sesji.
• Niewielki zestaw scenariuszy dotyczących umiejętności: użycie lub pominięcie, blokady i wstrzykiwanie monitów.
• Opcjonalne testy oceniające na żywo (włączane jawnie i kontrolowane zmiennymi środowiskowymi) dopiero po przygotowaniu zestawu bezpiecznego dla CI.

Testy kontraktowe (struktura Pluginów i kanałów)

Testy kontraktowe sprawdzają, czy każdy zarejestrowany Plugin i kanał jest zgodny ze swoim kontraktem interfejsu. Iterują po wszystkich wykrytych Pluginach i uruchamiają zestaw asercji dotyczących struktury oraz zachowania. Domyślna ścieżka testów jednostkowych pnpm test celowo pomija te współdzielone pliki granic i testów integracyjnych; po zmianie współdzielonych powierzchni kanałów lub dostawców uruchom jawnie polecenia testów kontraktowych.

Polecenia

• Wszystkie kontrakty: pnpm test:contracts
• Tylko kontrakty kanałów: pnpm test:contracts:channels
• Tylko kontrakty dostawców: pnpm test:contracts:plugins

Kontrakty kanałów

Znajdują się w src/channels/plugins/contracts/*.contract.test.ts. Obecne kategorie najwyższego poziomu:

• katalog kanałów — metadane wpisów katalogu kanałów wbudowanych i pochodzących z rejestru
• Plugin (oparty na rejestrze, podzielony na fragmenty) — podstawowa struktura rejestracji Pluginu
• tylko powierzchnie (oparte na rejestrze, podzielone na fragmenty) — kontrole struktury poszczególnych powierzchni dla actions, setup, status, outbound, messaging, threading, directory i gateway
• powiązanie sesji (oparte na rejestrze) — zachowanie powiązania sesji
• ładunek wychodzący — struktura i normalizacja ładunku wiadomości
• zasady grupy (rozwiązanie rezerwowe) — wymuszanie domyślnych zasad grupy dla każdego kanału
• wątki (oparte na rejestrze, podzielone na fragmenty) — obsługa identyfikatorów wątków
• katalog (oparty na rejestrze, podzielony na fragmenty) — API katalogu i listy użytkowników
• rejestr i rdzeń Pluginów.* — rejestr Pluginów kanałów, moduł ładujący i wewnętrzne mechanizmy autoryzacji zapisu konfiguracji

Pomocnicze mechanizmy przechwytywania wysyłania przychodzącego i ładunku wychodzącego używane przez te zestawy są udostępniane wewnętrznie przez src/plugin-sdk/channel-contract-testing.ts (wyłączony z npm, nie jest publiczną podścieżką SDK); w tym katalogu nie ma samodzielnego pliku inbound.contract.test.ts.

Kontrakty dostawców

Znajdują się w src/plugins/contracts/*.contract.test.ts. Obecne kategorie obejmują:

• struktura — struktura manifestu Pluginu, API i eksportów środowiska uruchomieniowego
• rejestracja Pluginu (+ równoległa) — przypadki rejestracji manifestu
• manifest pakietu — wymagania dotyczące manifestu pakietu
• moduł ładujący — zachowanie konfiguracji i zwalniania zasobów modułu ładującego Pluginy
• rejestr — zawartość i wyszukiwanie w rejestrze kontraktów Pluginów
• dostawcy — współdzielone zachowanie dostawców wśród dostawców wbudowanych oraz dostawców wyszukiwania internetowego
• wybór uwierzytelniania — metadane wyboru uwierzytelniania i zachowanie konfiguracji
• wycofanie katalogu dostawców — metadane wycofanych elementów katalogu dostawców
• rozstrzyganie wyboru kreatora, selektor modelu kreatora, opcje konfiguracji kreatora — kontrakty kreatora konfiguracji dostawców
• dostawca osadzania, dostawca osadzania pamięci, dostawca pobierania z internetu, synteza mowy — kontrakty dostawców właściwe dla poszczególnych możliwości
• akcje sesji, załączniki sesji, projekcja wpisu sesji — kontrakty stanu sesji będące własnością Pluginu
• zaplanowane tury — metadane zaplanowanych tur Pluginu i zakresy znaczników czasu
• punkty zaczepienia hosta, cykl życia kontekstu uruchomienia, skutki uboczne importu środowiska uruchomieniowego, granice środowiska uruchomieniowego — kontrakty cyklu życia hosta i środowiska uruchomieniowego Pluginu oraz granic importu
• zależności środowiska uruchomieniowego rozszerzeń — rozmieszczenie zależności środowiska uruchomieniowego rozszerzeń

Kiedy uruchamiać

• Po zmianie eksportów lub podścieżek plugin-sdk
• Po dodaniu lub zmodyfikowaniu Pluginu kanału albo dostawcy
• Po refaktoryzacji rejestracji lub wykrywania Pluginów

Testy kontraktowe działają w CI i nie wymagają rzeczywistych kluczy API.

Dodawanie regresji (wskazówki)

Gdy naprawiasz problem z dostawcą lub modelem wykryty podczas działania na żywo:

• Jeśli to możliwe, dodaj regresję bezpieczną dla CI: pozorowanego dostawcę, atrapę dostawcy lub przechwycenie dokładnego przekształcenia struktury żądania
• Jeśli problem z natury występuje tylko na żywo, na przykład w przypadku limitów szybkości lub zasad uwierzytelniania, test na żywo powinien mieć wąski zakres i być włączany jawnie za pomocą zmiennych środowiskowych
• Preferuj testowanie najmniejszej warstwy, która wykrywa błąd:
  • błąd konwersji lub ponownego odtwarzania żądania dostawcy -> bezpośredni test modeli
  • błąd sesji, historii lub potoku narzędzi Gateway -> test Gateway na żywo albo bezpieczny dla CI test Gateway z atrapą
• Zabezpieczenie przechodzenia po SecretRef:
  • src/secrets/exec-secret-ref-id-parity.test.ts wyprowadza jeden przykładowy cel dla każdej klasy SecretRef z metadanych rejestru (listSecretTargetRegistryEntries()), a następnie sprawdza, czy identyfikatory wykonania z segmentami przechodzenia są odrzucane.
  • Jeśli dodasz nową rodzinę celów SecretRef z includeInPlan w src/secrets/target-registry-data.ts, zaktualizuj classifyTargetClass w tym teście. Test celowo kończy się niepowodzeniem w przypadku niesklasyfikowanych identyfikatorów celów, aby nowe klasy nie mogły zostać po cichu pominięte.

Powiązane

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