Tests

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

Standardvorgehen für Agents

Agent-Sitzungen führen einen oder wenige fokussierte Tests und kostengünstige statische Prüfungen nur dann lokal aus, wenn die Quelle vertrauenswürdig und die vorhandene Abhängigkeitsinstallation einsatzbereit ist. Führen Sie niemals Repository-Werkzeuge aus nicht vertrauenswürdigen Quellen lokal aus. Größere Testsuiten, Änderungsprüfungen mit Typecheck-/Lint-Auffächerung, Builds, Docker-, Paket- und E2E-Lanes, Live-Nachweise sowie plattformübergreifende Validierungen werden über Crabbox remote ausgeführt. Für aufwendige Nachweise durch vertrauenswürdige Maintainer wird standardmäßig Blacksmith Testbox verwendet. Der konfigurierte Testbox-Workflow stellt Anmeldedaten bereit. Daher muss nicht vertrauenswürdiger Code von Mitwirkenden oder Forks stattdessen geheimnisfreie Fork-CI oder eine bereinigte direkte AWS-Crabbox verwenden.

Wärmen Sie die Umgebung nicht vorsorglich für erwartete Arbeiten vor. Fordern Sie das Backend erst dann bei Bedarf an, wenn der erste aufwendige Befehl bereit ist, verwenden Sie die zurückgegebene tbx_...-ID für spätere aufwendige Befehle erneut, synchronisieren Sie bei jeder Ausführung den aktuellen Checkout und stoppen Sie das Backend vor der Übergabe.

Nach der ersten erfolgreichen Wiederverwendung zeichnet der Wrapper die Basis, die Abhängigkeiten und den Fingerabdruck des Testbox-Workflows der Lease unter .crabbox/testbox-leases/ auf. Bei reinen Quelltextänderungen wird die vorgewärmte Box weiterhin verwendet. Eine geänderte Merge-Basis, Lockfile, Paketmanager-Eingabe, ein geänderter Wrapper oder Testbox-Workflow führt zu einem sicheren Abbruch und erfordert eine neue Lease. Bei jeder Ausführung wird weiterhin der aktuelle Checkout synchronisiert. OPENCLAW_TESTBOX_ALLOW_STALE=1 dient ausschließlich der gezielten Diagnose, nicht dem Release-Nachweis.

Die nachstehenden lokalen Testbefehle sind für menschliche Workflows und begrenzte Agent-Nachweise vorgesehen. Die Nichtverfügbarkeit des Remote-Providers muss gemeldet werden; sie erlaubt nicht, stillschweigend eine umfassende lokale Prüfung auszuführen.

Wärmen Sie für aufwendige Nachweise mit nicht vertrauenswürdigem Code bei Bedarf mit --provider aws vor. Jede Ausführung muss CRABBOX_ENV_ALLOW=CI setzen, --provider aws --no-hydrate übergeben und vor der Installation von Abhängigkeiten oder der Ausführung von Tests eine neue temporäre Remote-HOME verwenden. Verwenden Sie eine neu vorgewärmte Lease, die ausschließlich dieser nicht vertrauenswürdigen Quelle dient; verwenden Sie niemals eine vertrauenswürdige oder zuvor mit Anmeldedaten ausgestattete Lease erneut. Starten Sie ein installiertes, vertrauenswürdiges Crabbox- Binary aus einem sauberen, vertrauenswürdigen main-Checkout und rufen Sie mit --fresh-pr ausschließlich den Remote-PR ab; führen Sie niemals den Wrapper oder die Konfiguration des nicht vertrauenswürdigen Checkouts lokal aus. Entfernen Sie CRABBOX_AWS_INSTANCE_PROFILE und brechen Sie sicher ab, sofern das aufgelöste aws.instanceProfile nicht leer ist. Verwenden Sie vor jeder Installation bzw. jedem Test vertrauenswürdige Werkzeuge mit absoluten Pfaden, um ein IMDSv2-Token zu verlangen, nachzuweisen, dass der Endpunkt für IAM-Anmeldedaten 404 zurückgibt, und zu überprüfen, dass die Remote-git rev-parse HEAD dem vollständigen SHA des geprüften PR-Heads entspricht. Binden Sie die Lease an diesen SHA und stoppen bzw. erwärmen Sie sie erneut, wenn sich der Head ändert. Laden Sie die vertrauenswürdige Datei scripts/crabbox-untrusted-bootstrap.sh aus dem sauberen main zusammen mit --fresh-pr hoch; sie installiert festgelegte Node-/pnpm-Versionen, überprüft den 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 kein Remote-PR existiert, verwenden Sie geheimnisfreie Fork-CI. Verwenden Sie weder hydrate-github noch --no-sync oder einen mit Anmeldedaten ausgestatteten Testbox-Workflow. Entfernen Sie alle CRABBOX_TAILSCALE*-Überschreibungen, erzwingen Sie --network public --tailscale=false, löschen Sie Exit-Node-/LAN-Flags und verlangen Sie, dass crabbox inspect öffentliche Netzwerkanbindung ohne Tailscale-Status meldet, bevor Sie ein Skript hochladen.

Übliche lokale Reihenfolge

1. pnpm test:changed für Vitest-Nachweise 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-Testsuite benötigen.

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

• Begrenzter fokussierter Nachweis mit einsatzbereiten Abhängigkeiten: node scripts/run-vitest.mjs <path-or-filter>.
• Änderungsprüfung mit vorheriger Klassifizierung: node scripts/check-changed.mjs; reine Dokumentations-, unveränderte und kleine Metadatenpläne bleiben lokal, wenn die Abhängigkeiten einsatzbereit sind, während aufwendige Pläne oder Pläne mit fehlenden Abhängigkeiten an Testbox delegiert werden.
• Expliziter umfassender Nachweis mit beibehaltener Lease: 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.
• Die abschließende exitCode-Meldung und das Zeitmessungs-JSON des Wrappers bilden das Befehlsergebnis. Eine delegierte Ausführung über Blacksmith GitHub Actions kann nach einem erfolgreichen SSH-Befehl cancelled anzeigen, weil Testbox außerhalb der Keepalive-Action gestoppt 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>: hält die Serialisierung aufwendiger Prüfungen innerhalb des aktuellen Worktrees statt im gemeinsamen Git-Verzeichnis für Befehle wie pnpm check:changed und gezielte pnpm test .... Verwenden Sie dies nur auf leistungsfähigen lokalen Hosts, wenn Sie bewusst unabhängige Prüfungen über verknüpfte Worktrees hinweg ausführen.

Kernbefehle

Ausführungen des Test-Wrappers enden mit einer kurzen [test] passed|failed|skipped ... in ...-Zusammenfassung; die eigene Laufzeitzeile von Vitest bleibt die Detailangabe je Shard.

Gemeinsamer Teststatus und Prozesshilfen

• src/test-utils/openclaw-test-state.ts: in Vitest verwenden, wenn ein Test eine isolierte HOME, OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, 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/Harnesses, die HOME, OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, OPENCLAW_WORKSPACE_DIR oder zugehörige Umgebungsschlüssel direkt verändern. Verwenden Sie ihn, um Migrationskandidaten für die gemeinsame Teststatus-Hilfsfunktion zu finden.
• test/helpers/openclaw-test-instance.ts: E2E-Tests auf Prozessebene, 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 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 einbindbare Host-Umgebungsdatei (das -- vor create verhindert, dass neuere Node-Laufzeiten --env-file als Node-Flag behandeln). Lanes, die einen Gateway starten, können scripts/lib/openclaw-e2e-instance.sh für die Auflösung des Einstiegspunkts, den Start eines OpenAI-Mocks, den Start im Vorder- bzw. Hintergrund, Bereitschaftsprüfungen, den Export der Statusumgebung, Protokollausgaben und die Prozessbereinigung einbinden.

Control UI, TUI und Erweiterungs-Lanes

• Gemockte E2E-Tests der Control UI: pnpm test:ui:e2e führt die Vitest- und Playwright-Lane aus, die die Vite Control UI startet und eine echte Chromium-Seite gegen einen gemockten Gateway-WebSocket steuert. Die Tests befinden sich in ui/src/**/*.e2e.test.ts; gemeinsame Mocks und Steuerelemente befinden sich in ui/src/test-helpers/control-ui-e2e.ts. pnpm test:e2e umfasst diese Lane. Agent-Ausführungen verwenden standardmäßig Testbox/Crabbox, einschließlich gezielter 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 für einen ausdrücklich festgelegten lokalen Fallback.
• TUI-PTY-Tests: node scripts/run-vitest.mjs run --config test/vitest/vitest.tui-pty.config.ts führt die schnelle PTY-Lane 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 Modellendpunkt mockt. 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 eine Lane für ein einzelnes gebündeltes Plugin aus.
• Quelldateien mit Tests in Geschwisterdateien werden zunächst diesen Geschwisterdateien zugeordnet, bevor auf breitere 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 bei einem eindeutigen Abhängigkeitspfad jeden Shard umfassend auszuführen.
• Ziele in Vertragsverzeichnissen werden auf ihre Vertrags-Lanes verteilt: 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 wird in drei dedizierte Konfigurationen aufgeteilt (core, top-level, reply), damit das Antwort-Testgerüst die leichteren übergeordneten Status-/Token-/Hilfsfunktionstests nicht dominiert.
• Ausgewählte Testdateien aus plugin-sdk und commands werden über dedizierte ressourcenschonende Lanes geleitet, die nur test/setup.ts enthalten; laufzeitintensive Fälle verbleiben auf ihren bestehenden Lanes.
• Die Vitest-Basiskonfiguration verwendet standardmäßig pool: "threads" und isolate: false, wobei der gemeinsame nicht isolierte Runner für alle Repository-Konfigurationen aktiviert ist.
• pnpm test:channels führt vitest.channels.config.ts aus.

Gateway und E2E

• Die Gateway-Integration ist optional zu aktivieren: OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test oder pnpm test:gateway.
• pnpm test:e2e: Repository-E2E-Gesamtlauf = 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), um die Tests nicht zu überspringen; ausführliche Ausgabe mit OPENCLAW_LIVE_TEST_QUIET=0.

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

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

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

Scheduler-Einstellungen (Umgebungsvariablen, Standardwerte in Klammern):

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

Weiteres Verhalten: Der Runner führt standardmäßig einen Docker-Preflight durch, bereinigt veraltete OpenClaw-E2E-Container, teilt Caches für Provider-CLI-Tools zwischen kompatiblen Lanes und plant nach dem ersten Fehler keine neuen gepoolten Lanes mehr ein, sofern OPENCLAW_DOCKER_ALL_FAIL_FAST=0 nicht gesetzt ist. Wenn eine Lane auf einem Host mit geringer Parallelität die effektive Gewichtungs-/Ressourcenobergrenze überschreitet, 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 Phasenzeiten 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 Befehle für gezielte Wiederholungsläufe auszugeben.

Wichtige Docker-Lanes

Lokales PR-Gate

Führen Sie für lokale Prüfungen zum Landen/Gating eines PR Folgendes aus:

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

Wenn pnpm test auf einem ausgelasteten Host sporadisch fehlschlägt, führen Sie es einmal erneut aus, bevor Sie es als Regression behandeln, und isolieren Sie es 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

Tools für die Testleistung

• pnpm test:perf:imports: Aktiviert die Berichterstellung zu Vitest-Importdauer und Importaufschlüsselung, verwendet für explizite Datei-/Verzeichnisziele jedoch weiterhin das bereichsspezifische Lane-Routing. pnpm test:perf:imports:changed beschränkt dasselbe Profiling auf Dateien, die seit origin/main geändert wurden.
• pnpm test:perf:changed:bench -- --ref <git-ref> vergleicht die Leistung des gerouteten Modus für Änderungen mit dem nativen Lauf des Root-Projekts für denselben committeten Git-Diff; pnpm test:perf:changed:bench -- --worktree misst den aktuellen Änderungssatz im Worktree, ohne ihn zuvor zu committen.
• 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-Runner (.artifacts/vitest-runner-profile).
• pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json: Führt jede Vitest-Blattkonfiguration der vollständigen Suite seriell aus und schreibt gruppierte Laufzeitdaten sowie JSON-/Protokollartefakte pro Konfiguration. Berichte der vollständigen Suite 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 beheben. pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json vergleicht gruppierte Berichte nach einer leistungsorientierten Änderung.
• Läufe für vollständige Suites, Erweiterungen und Include-Muster aktualisieren lokale Zeitmessdaten in .artifacts/vitest-shard-timings.json; spätere Läufe der gesamten Konfiguration verwenden diese Messwerte, um langsame und schnelle Shards auszugleichen. CI-Shards mit Include-Muster hängen den Shard-Namen an den Zeitmessschlüssel an, wodurch die Zeitmessungen 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-, Workspace- 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
• Testen von Updates und Plugins