Tests

• Vollständiges Test-Kit (Testsammlungen, Live-Tests, Docker): Tests
• Validierung von Updates und Plugin-Paketen: Updates und Plugins testen

Agent-Standard

Agent-Sitzungen führen Tests und rechenintensive Validierungen über Crabbox remote aus. Für vertrauenswürdigen Maintainer-Code wird standardmäßig Blacksmith Testbox verwendet. Der konfigurierte Testbox-Workflow stellt Anmeldedaten bereit; nicht vertrauenswürdiger Code von Mitwirkenden oder Forks muss daher stattdessen eine Fork-CI ohne Geheimnisse oder eine bereinigte direkte AWS-Crabbox verwenden.

Wenn eine Aufgabe mit vertrauenswürdigem Code voraussichtlich Tests oder umfangreiche Nachweise erfordert, wärmen Sie die Umgebung sofort in einer Befehlssitzung im Hintergrund vor, arbeiten Sie während der Bereitstellung weiter, verwenden Sie die zurückgegebene tbx_...-ID erneut, synchronisieren Sie bei jedem Lauf den aktuellen Checkout und beenden Sie die Umgebung vor der Übergabe:

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

Nach der ersten erfolgreichen Wiederverwendung zeichnet der Wrapper den Fingerabdruck der Basis, der Abhängigkeiten und des Testbox-Workflows der Lease unter .crabbox/testbox-leases/ auf. Bei reinen Quelltextänderungen wird die vorgewärmte Umgebung weiterverwendet. Eine geänderte Merge-Basis, Lockdatei, Paketmanager-Eingabe, ein geänderter Wrapper oder Testbox-Workflow führt zu einem sicheren Abbruch und erfordert eine neue Lease. Bei jedem Lauf wird weiterhin der aktuelle Checkout synchronisiert. OPENCLAW_TESTBOX_ALLOW_STALE=1 ist ausschließlich für gezielte Diagnosen vorgesehen, nicht als Release-Nachweis.

Die nachstehenden lokalen Testbefehle sind für menschliche Arbeitsabläufe oder einen vom Benutzer ausdrücklich angeforderten lokalen Agent-Fallback vorgesehen. Die Nichtverfügbarkeit eines Remote-Providers muss gemeldet werden; sie berechtigt nicht dazu, stillschweigend eine umfassende lokale Prüfschleuse auszuführen.

Wärmen Sie für nicht vertrauenswürdigen Code mit --provider aws vor. Jeder Lauf muss CRABBOX_ENV_ALLOW=CI setzen, --provider aws --no-hydrate übergeben und vor der Installation von Abhängigkeiten oder der Ausführung von Tests ein frisches temporäres Remote-HOME verwenden. Verwenden Sie eine neu vorgewärmte Lease, die ausschließlich dieser nicht vertrauenswürdigen Quelle zugeordnet ist; verwenden Sie niemals eine vertrauenswürdige oder zuvor mit Anmeldedaten bereitgestellte Lease erneut. Starten Sie eine installierte vertrauenswürdige Crabbox-Binärdatei aus einem sauberen vertrauenswürdigen main-Checkout und rufen Sie mit --fresh-pr ausschließlich den Remote-PR ab; führen Sie niemals lokal den Wrapper oder die Konfiguration des nicht vertrauenswürdigen Checkouts aus. Entfernen Sie CRABBOX_AWS_INSTANCE_PROFILE aus der Umgebung und brechen Sie sicher ab, sofern der aufgelöste Wert von aws.instanceProfile nicht leer ist. Verwenden Sie vor jeder Installation und jedem Test vertrauenswürdige Werkzeuge mit absoluten Pfaden, um ein IMDSv2-Token zu verlangen, nachzuweisen, dass der IAM-Anmeldedaten-Endpunkt den Status 404 zurückgibt, und zu überprüfen, dass das Remote-Ergebnis von git rev-parse HEAD der vollständigen geprüften SHA des PR-Kopfs entspricht. Binden Sie die Lease an diese SHA und beenden beziehungsweise erwärmen Sie sie erneut, wenn sich der Kopf ändert. Laden Sie das vertrauenswürdige Skript scripts/crabbox-untrusted-bootstrap.sh aus einem sauberen main zusammen mit --fresh-pr hoch; es installiert die festgelegten Node-/pnpm-Versionen, überprüft die SHA und die Paketmanager-Festlegung, isoliert HOME, installiert Abhängigkeiten und führt anschließend den angeforderten Test aus. Wenn der Broker nicht nachweisen kann, dass keine Rolle vorhanden ist, oder wenn kein Remote-PR existiert, verwenden Sie eine Fork-CI ohne Geheimnisse. Verwenden Sie weder hydrate-github noch --no-sync oder einen Testbox-Workflow, der mit Anmeldedaten bereitgestellt wurde. Entfernen Sie alle CRABBOX_TAILSCALE*-Überschreibungen aus der Umgebung, erzwingen Sie --network public --tailscale=false, löschen Sie Exit-Node-/LAN-Flags und verlangen Sie vor dem Hochladen eines Skripts, dass crabbox inspect ein öffentliches Netzwerk ohne Tailscale-Zustand meldet.

Reguläre lokale Reihenfolge

1. pnpm test:changed für einen Vitest-Nachweis im geänderten Umfang.
2. pnpm test <path-or-filter> für eine Datei, ein Verzeichnis oder ein explizites Ziel.
3. pnpm test nur, wenn Sie bewusst die vollständige lokale Vitest-Testsammlung benötigen.

In einem Codex-Worktree oder einem verknüpften beziehungsweise Sparse-Checkout vermeiden Agents die direkte lokale Ausführung von pnpm test* / pnpm check* / pnpm crabbox:run:

• Vom Benutzer ausdrücklich angeforderter lokaler Fallback für eine kleine Datei: node scripts/run-vitest.mjs <path-or-filter>.
• Prüfschleusen für Änderungen oder umfassende Nachweise: 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, damit pnpm innerhalb von Testbox ausgeführt wird.
• Der abschließende exitCode und das Zeitmessungs-JSON des Wrappers bilden das Befehlsergebnis. Ein delegierter Blacksmith-GitHub-Actions-Lauf kann nach einem erfolgreichen SSH-Befehl cancelled anzeigen, weil die Testbox von außerhalb der Keepalive-Action beendet wird; prüfen Sie die Wrapper-Zusammenfassung und die Befehlsausgabe, bevor Sie dies als Fehler behandeln.
• OPENCLAW_HEAVY_CHECK_LOCK_SCOPE=worktree <local-heavy-check command>: Beschränkt die Serialisierung rechenintensiver Prüfungen auf den aktuellen Worktree statt auf das gemeinsame Git-Verzeichnis, beispielsweise für Befehle wie pnpm check:changed und gezielte Aufrufe von pnpm test .... Verwenden Sie dies nur auf leistungsfähigen lokalen Hosts, wenn Sie bewusst unabhängige Prüfungen in verknüpften Worktrees ausführen.

Kernbefehle

Läufe des Test-Wrappers enden mit einer kurzen Zusammenfassung im Format [test] passed|failed|skipped ... in ...; die eigene Zeitangabe von Vitest bleibt die Detailangabe pro Shard.

Gemeinsamer Testzustand und Prozesshilfen

• src/test-utils/openclaw-test-state.ts: Verwenden Sie dies aus Vitest, wenn ein Test ein isoliertes HOME, OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, eine Konfigurations-Fixture, einen Workspace, ein Agent-Verzeichnis oder einen Speicher für Authentifizierungsprofile benötigt.
• pnpm test:env-mutations:report: Nicht blockierender Bericht über Tests und Test-Harnesses, die HOME, OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, OPENCLAW_WORKSPACE_DIR oder zugehörige Umgebungsschlüssel direkt ändern. Verwenden Sie ihn, um Migrationskandidaten für die gemeinsame Testzustands-Hilfsfunktion zu finden.
• test/helpers/openclaw-test-instance.ts: Prozessbezogene E2E-Tests, die einen laufenden Gateway, eine CLI-Umgebung, Protokollerfassung und Bereinigung an einer zentralen Stelle benötigen.
• Docker-/Bash-E2E-Lanes, die scripts/lib/docker-e2e-image.sh einbinden, können docker_e2e_test_state_shell_b64 <label> <scenario> an den Container übergeben und den Wert mit scripts/lib/openclaw-e2e-instance.sh dekodieren; Skripte mit mehreren Home-Verzeichnissen können docker_e2e_test_state_function_b64 übergeben und in jedem Ablauf openclaw_test_state_create <label> <scenario> aufrufen. node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json schreibt eine auf dem Host einbindbare Umgebungsdatei (das -- vor create verhindert, dass neuere Node-Laufzeitumgebungen --env-file als Node-Flag behandeln). Lanes, die einen Gateway starten, können scripts/lib/openclaw-e2e-instance.sh einbinden, um den Einstiegspunkt aufzulösen, den OpenAI-Mock zu starten, Vordergrund-/Hintergrundstarts auszuführen, Bereitschaftsprüfungen durchzuführen, die Zustandsumgebung zu exportieren, Protokolle auszugeben und Prozesse zu bereinigen.

Control UI, TUI und Erweiterungs-Lanes

• Gemockte Control-UI-E2E-Tests: pnpm test:ui:e2e führt die Vitest- und Playwright-Teststrecke aus, die die Vite-Control-UI startet und eine echte Chromium-Seite mit einem gemockten Gateway-WebSocket steuert. Die Tests befinden sich in ui/src/**/*.e2e.test.ts; gemeinsam genutzte Mocks und Steuerungen befinden sich in ui/src/test-helpers/control-ui-e2e.ts. pnpm test:e2e schließt diese Teststrecke ein. Agent-Ausführungen verwenden standardmäßig Testbox/Crabbox, auch für gezielte Nachweise; verwenden Sie 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 nur als ausdrücklich vorgesehenen lokalen Fallback.
• TUI-PTY-Tests: node scripts/run-vitest.mjs run --config test/vitest/vitest.tui-pty.config.ts führt die schnelle PTY-Teststrecke mit simuliertem Backend aus. OPENCLAW_TUI_PTY_INCLUDE_LOCAL=1 oder pnpm tui:pty:test:watch --mode local führt den langsameren tui --local-Smoke-Test aus, der nur den externen Modell-Endpunkt simuliert. Prüfen Sie stabilen sichtbaren Text oder Fixture-Aufrufe, nicht rohe ANSI-Snapshots.
• pnpm test:extensions und pnpm test extensions führen alle Erweiterungs-/Plugin-Shards aus. Ressourcenintensive Kanal-Plugins, das Browser-Plugin und OpenAI werden als dedizierte Shards ausgeführt; andere Plugin-Gruppen bleiben gebündelt. pnpm test extensions/<id> führt die Teststrecke eines einzelnen gebündelten Plugins aus.
• Quelldateien mit zugehörigen Tests werden zunächst diesen Tests zugeordnet, bevor auf umfassendere Verzeichnis-Globs zurückgegriffen wird. Änderungen an Hilfsfunktionen unter src/channels/plugins/contracts/test-helpers, src/plugin-sdk/test-helpers und src/plugins/contracts verwenden einen lokalen Importgraphen, um importierende Tests auszuführen, statt jeden Shard umfassend auszuführen, wenn der Abhängigkeitspfad eindeutig ist.
• Ziele für Vertragsverzeichnisse werden auf ihre Vertragsteststrecken aufgefächert: pnpm test src/channels/plugins/contracts führt die vier Konfigurationen für Kanalverträge aus, und pnpm test src/plugins/contracts führt die Konfiguration für Plugin-Verträge aus, da die generischen Projekte channels/plugins contracts/** ausschließen.
• auto-reply ist in drei dedizierte Konfigurationen (core, top-level, reply) aufgeteilt, damit das Antwort-Testsystem nicht die leichteren Status-/Token-/Hilfsfunktionstests der obersten Ebene dominiert.
• Ausgewählte Testdateien für plugin-sdk und commands werden über dedizierte schlanke Teststrecken geleitet, die nur test/setup.ts beibehalten; laufzeitintensive Fälle verbleiben in ihren bestehenden Teststrecken.
• Die Vitest-Basiskonfiguration verwendet standardmäßig pool: "threads" und isolate: false, wobei der gemeinsam genutzte nicht isolierte Runner in allen Repository-Konfigurationen aktiviert ist.
• pnpm test:channels führt vitest.channels.config.ts aus.

Gateway und E2E

• Die Gateway-Integration muss explizit aktiviert werden: OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test oder pnpm test:gateway.
• pnpm test:e2e: Repository-weites E2E-Aggregat = pnpm test:e2e:gateway && pnpm test:ui:e2e.
• pnpm test:e2e:gateway: Gateway-End-to-End-Smoke-Tests (WS-/HTTP-/Node-Kopplung mit mehreren Instanzen). Verwendet standardmäßig threads + isolate: false mit adaptiven Workern in vitest.e2e.config.ts; Anpassung mit OPENCLAW_E2E_WORKERS=<n>, ausführliche Protokolle mit OPENCLAW_E2E_VERBOSE=1.
• pnpm test:live: Live-Tests für Provider (Claude/Minimax/DeepSeek/z.ai usw., gesteuert durch *.live.test.ts). Erfordert API-Schlüssel und LIVE=1 (oder OPENCLAW_LIVE_TEST=1), damit die Tests nicht übersprungen werden; ausführliche Ausgabe mit OPENCLAW_LIVE_TEST_QUIET=0.

Vollständige Docker-Suite (pnpm test:docker:all)

Erstellt das gemeinsam genutzte Live-Test-Image, verpackt OpenClaw einmalig als npm-Tarball, erstellt bzw. verwendet ein minimales Node-/Git-Runner-Image sowie ein funktionales Image, das diesen Tarball unter /app installiert, und führt anschließend Docker-Smoke-Teststrecken über einen gewichteten Scheduler aus. scripts/package-openclaw-for-docker.mjs ist der einzige lokale bzw. CI-Paket-Packer und validiert den Tarball sowie dist/postinstall-inventory.json, bevor Docker ihn verwendet.

• Minimales Image (OPENCLAW_DOCKER_E2E_BARE_IMAGE): Teststrecken für Installation, Aktualisierung und Plugin-Abhängigkeiten; bindet den vorab erstellten Tarball ein, anstatt kopierte Repository-Quelldateien zu verwenden.
• Funktionales Image (OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE): Teststrecken für die normale Funktionalität der erstellten Anwendung.
• Definitionen der Teststrecken: scripts/lib/docker-e2e-scenarios.mjs. Planer: scripts/lib/docker-e2e-plan.mjs. Ausführung: scripts/test-docker-all.mjs.
• node scripts/test-docker-all.mjs --plan-json gibt den vom Scheduler verwalteten CI-Plan aus (Teststrecken, Image-Arten, Anforderungen an Paket-/Live-Images, Zustandsszenarien, Anmeldedatenprüfungen), ohne Docker zu erstellen oder auszuführen.

Planungsoptionen (Umgebungsvariablen, Standardwerte in Klammern):

Das Muster für Umgebungsvariablen zur Begrenzung von Ressourcen lautet OPENCLAW_DOCKER_ALL_<RESOURCE>_LIMIT (Ressourcenname in Großbuchstaben, nicht alphanumerische Zeichen zu _ zusammengefasst).

Weiteres Verhalten: Der Runner führt standardmäßig Vorabprüfungen für Docker durch, bereinigt veraltete OpenClaw-E2E-Container, teilt Caches der Provider-CLI-Tools zwischen kompatiblen Lanes und plant nach dem ersten Fehler keine neuen gepoolten Lanes mehr ein, sofern nicht OPENCLAW_DOCKER_ALL_FAIL_FAST=0 gesetzt ist. Überschreitet eine Lane auf einem Host mit geringer Parallelität die effektive Gewichtungs-/Ressourcenobergrenze, kann sie dennoch aus einem leeren Pool starten und allein ausgeführt werden, bis sie Kapazität freigibt. Lane-spezifische Protokolle, summary.json, failures.json und Phasenzeitmessungen werden unter .artifacts/docker-tests/<run-id>/ geschrieben; verwenden Sie pnpm test:docker:timings <summary.json>, um langsame Lanes zu untersuchen, und pnpm test:docker:rerun <run-id|summary.json|failures.json>, um kostengünstige, gezielte Befehle zur erneuten Ausführung auszugeben.

Wichtige Docker-Lanes

Lokale PR-Prüfung

Führen Sie für lokale Prüfungen vor der Übernahme bzw. Gate-Prüfungen eines PR Folgendes aus:

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

Falls pnpm test auf einem ausgelasteten Host sporadisch fehlschlägt, führen Sie den Test einmal erneut aus, bevor Sie dies als Regression einstufen, und isolieren Sie den Fehler anschließend mit pnpm test <path/to/test>. Für Hosts mit begrenztem Arbeitsspeicher:

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

Werkzeuge zur Testleistungsanalyse

• pnpm test:perf:imports: aktiviert die Berichterstellung zur Vitest-Importdauer und Importaufschlüsselung, verwendet für explizite Datei-/Verzeichnisziele jedoch weiterhin das bereichsbezogene Lane-Routing. pnpm test:perf:imports:changed beschränkt dasselbe Profiling auf Dateien, die sich seit origin/main geändert haben.
• pnpm test:perf:changed:bench -- --ref <git-ref> vergleicht die Leistung des gerouteten Pfads im Änderungsmodus mit der nativen Ausführung des Root-Projekts für denselben eingecheckten Git-Diff; pnpm test:perf:changed:bench -- --worktree führt den Benchmark für die aktuellen Änderungen im Arbeitsverzeichnis aus, ohne diese zuvor einzuchecken.
• pnpm test:perf:profile:main schreibt ein CPU-Profil für den Vitest-Hauptthread (.artifacts/vitest-main-profile); pnpm test:perf:profile:runner schreibt CPU- und Heap-Profile für den Unit-Test-Runner (.artifacts/vitest-runner-profile).
• pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json: führt jede untergeordnete Vitest-Konfiguration der vollständigen Testsuite nacheinander aus und schreibt gruppierte Laufzeitdaten sowie JSON-/Protokollartefakte pro Konfiguration. Berichte der vollständigen Testsuite isolieren Dateien standardmäßig, damit beibehaltene Modulgraphen und GC-Pausen aus früheren Dateien nicht späteren Assertions zugerechnet werden; übergeben Sie -- --no-isolate nur, wenn Sie bewusst die Akkumulation in gemeinsam genutzten Workern profilieren. Der Agent für Testleistung verwendet dies als Ausgangsbasis, bevor er versucht, langsame Tests zu korrigieren. pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json vergleicht gruppierte Berichte nach einer leistungsorientierten Änderung.
• Vollständige, Erweiterungs- und Include-Muster-Shard-Ausführungen aktualisieren lokale Zeitmessdaten in .artifacts/vitest-shard-timings.json; spätere Ausführungen der gesamten Konfiguration verwenden diese Messwerte, um langsame und schnelle Shards auszubalancieren. Include-Muster-CI-Shards hängen den Shard-Namen an den Zeitmessschlüssel an, sodass die Zeitmesswerte gefilterter Shards sichtbar bleiben, ohne die Zeitmessdaten der gesamten Konfiguration zu ersetzen. Setzen Sie OPENCLAW_TEST_PROJECTS_TIMINGS=0, um das lokale Zeitmessartefakt zu ignorieren.

Benchmarks

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

Onboarding-E2E (Docker)

Optional; nur für containerisierte Onboarding-Smoke-Tests erforderlich. Vollständiger Kaltstartablauf in einem sauberen Linux-Container:

scripts/e2e/onboard-docker.sh

Steuert den interaktiven Assistenten über ein Pseudo-TTY, überprüft Konfigurations-, Arbeitsbereichs- und Sitzungsdateien, startet anschließend das Gateway und führt openclaw health aus.

QR-Import-Smoke-Test (Docker)

Stellt sicher, dass der gepflegte QR-Laufzeithelfer unter den unterstützten Docker-Node-Laufzeiten geladen wird (standardmäßig Node 24, kompatibel mit Node 22):

pnpm test:docker:qr

Verwandte Themen

• Tests
• Live-Tests
• Tests von Aktualisierungen und Plugins