Tests

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

Agent-Standard

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 bestehende Abhängigkeitsinstallation bereit ist. Führen Sie niemals Werkzeuge eines nicht vertrauenswürdigen Repositorys lokal aus. Größere Suites, Gates für Änderungen mit Typecheck-/Lint-Fan-out, Builds, Docker, Paket-Lanes, E2E, Live-Nachweise und plattformübergreifende Validierungen werden remote über Crabbox ausgeführt. Aufwendige Nachweise durch vertrauenswürdige Maintainer werden standardmäßig in der Blacksmith Testbox ausgeführt. Der konfigurierte Testbox-Workflow stellt Anmeldedaten bereit, daher muss nicht vertrauenswürdiger Code von Mitwirkenden oder Forks stattdessen geheimnislose Fork-CI oder eine bereinigte direkte AWS-Crabbox verwenden.

Wärmen Sie die Umgebung nicht für erwartete Arbeiten vor. Fordern Sie das Backend erst dann 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 jedem Lauf den aktuellen Checkout und stoppen Sie es vor der Übergabe.

Nach der ersten erfolgreichen Wiederverwendung speichert der Wrapper die Fingerabdrücke der Basis, der Abhängigkeiten und des Testbox-Workflows der Lease unter .crabbox/testbox-leases/. Bei reinen Quelltextänderungen wird die vorgewärmte Box weiterverwendet. 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 jedem Lauf wird weiterhin der aktuelle Checkout synchronisiert. OPENCLAW_TESTBOX_ALLOW_STALE=1 dient nur der gezielten Diagnose, nicht als Release-Nachweis.

Die folgenden lokalen Testbefehle sind für menschliche Arbeitsabläufe und begrenzte Agent-Nachweise vorgesehen. Die Nichtverfügbarkeit eines Remote-Providers muss gemeldet werden; sie ist keine Erlaubnis, stillschweigend ein breites lokales Gate auszuführen.

Für nicht vertrauenswürdige aufwendige Nachweise wärmen Sie die Umgebung bei Bedarf 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 eine neue temporäre Remote-HOME verwenden. Verwenden Sie eine neu vorgewärmte Lease, die ausschließlich dieser nicht vertrauenswürdigen Quelle gewidmet ist; verwenden Sie niemals eine vertrauenswürdige oder zuvor mit Anmeldedaten ausgestattete 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 den Wrapper oder die Konfiguration des nicht vertrauenswürdigen Checkouts lokal aus. Entfernen Sie CRABBOX_AWS_INSTANCE_PROFILE und brechen Sie sicher ab, sofern der aufgelöste Wert aws.instanceProfile nicht leer ist. Verwenden Sie vor jeder Installation bzw. jedem Test vertrauenswürdige Werkzeuge mit absoluten Pfaden, um ein IMDSv2-Token zu erzwingen, nachzuweisen, dass der IAM-Anmeldedaten- Endpunkt 404 zurückgibt, und zu überprüfen, dass der Remote-Wert git rev-parse HEAD der vollständigen geprüften SHA des PR-Heads entspricht. Binden Sie die Lease an diese SHA und stoppen bzw. wärmen Sie sie neu vor, wenn sich der Head ändert. Laden Sie die vertrauenswürdige Datei scripts/crabbox-untrusted-bootstrap.sh aus einem sauberen main zusammen mit --fresh-pr hoch; sie 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 kein Remote-PR existiert, verwenden Sie geheimnislose 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 ein öffentliches Netzwerk ohne Tailscale-Status meldet, bevor Sie ein Skript hochladen.

Reguläre lokale Reihenfolge

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

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

• Begrenzter fokussierter Nachweis bei bereiten Abhängigkeiten: node scripts/run-vitest.mjs <path-or-filter>.
• Prüfung von Änderungen mit vorheriger Klassifizierung: node scripts/check-changed.mjs; reine Dokumentations-, unveränderte und kleine Metadatenpläne bleiben lokal, wenn die Abhängigkeiten bereit sind, während aufwendige Pläne oder solche mit fehlenden Abhängigkeiten an die Testbox delegiert werden.
• Expliziter breiter 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, sodass pnpm innerhalb der Testbox ausgeführt wird.
• Die abschließende exitCode-Meldung 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 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>: Behält die Serialisierung aufwendiger Prüfungen innerhalb des aktuellen Worktrees statt im gemeinsamen Git-Verzeichnis bei, etwa 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

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

Gemeinsamer Teststatus und Prozesshilfen

• src/test-utils/openclaw-test-state.ts: Verwenden Sie dies aus Vitest, wenn ein Test isolierte HOME, OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, eine Konfigurations-Fixture, einen Workspace, ein Agent-Verzeichnis oder einen Authentifizierungsprofilspeicher 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 den gemeinsamen Teststatus-Helfer zu ermitteln.
• test/helpers/openclaw-test-instance.ts: E2E-Tests auf Prozessebene, die einen laufenden Gateway, eine CLI-Umgebung, Protokollerfassung und Bereinigung an zentraler 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> in 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, Vordergrund-/Hintergrundstarts, 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-Teststrecke 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 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, 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-Teststrecke mit einem simulierten 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, keine unverarbeiteten 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 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 alle Shards umfassend auszuführen, wenn der Abhängigkeitspfad eindeutig ist.
• Ziele in Vertragsverzeichnissen werden auf ihre Vertragsteststrecken 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 (core, top-level, reply) aufgeteilt, damit das Antwort-Testsystem nicht die leichteren übergeordneten Status-/Token-/Hilfsfunktionstests dominiert.
• Ausgewählte Testdateien unter plugin-sdk und commands werden über dedizierte schlanke Teststrecken geleitet, die nur test/setup.ts beibehalten, während laufzeitintensive Fälle auf ihren vorhandenen Teststrecken verbleiben.
• Die grundlegende Vitest-Konfiguration verwendet standardmäßig pool: "threads" und isolate: false, wobei der gemeinsame 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 ist optional zu aktivieren: OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test oder pnpm test:gateway.
• pnpm test:e2e: Repository-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), 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 gemeinsam genutzte Live-Test-Image, packt OpenClaw einmal als npm-Tarball, erstellt/verwendet erneut ein minimales Node-/Git-Runner-Image sowie ein funktionales Image, das diesen Tarball in /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/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, statt kopierte Repository-Quellen 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ührungsmodul: scripts/test-docker-all.mjs.
• node scripts/test-docker-all.mjs --plan-json gibt den CI-Plan im Besitz des Schedulers aus (Teststrecken, Image-Typen, Anforderungen an Paket-/Live-Images, Zustandsszenarien, Anmeldedatenprüfungen), ohne Docker zu erstellen oder auszuführen.

Steuerungsoptionen für die Planung (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 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 die effektive Gewichtungs-/Ressourcenobergrenze auf einem Host mit geringer Parallelität überschreitet, kann sie dennoch aus einem leeren Pool starten und allein ausgeführt werden, bis sie Kapazität freigibt. Pro-Lane-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 einfache gezielte Befehle für erneute Ausführungen auszugeben.

Erwähnenswerte Docker-Lanes

Lokales PR-Gate

Führen Sie für lokale Prüfungen zum Landen/Gaten 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 zur Testleistungsanalyse

• pnpm test:perf:imports: Aktiviert die Berichterstellung zu Vitest-Importdauer und -Importaufschlüsselung, während für explizite Datei-/Verzeichnisziele weiterhin bereichsspezifisches Lane-Routing verwendet wird. 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 Änderungsmodus-Pfads mit der nativen Ausführung des Root-Projekts für denselben committeten Git-Diff; pnpm test:perf:changed:bench -- --worktree misst die Leistung der aktuellen Worktree-Änderungsmenge, ohne sie 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-Leaf-Konfiguration der vollständigen Suite seriell aus und schreibt gruppierte Laufzeitdaten sowie JSON-/Protokollartefakte pro Konfiguration. Berichte für vollständige Suites 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 die Akkumulation gemeinsam genutzter Worker bewusst profilieren. Der Test Performance Agent verwendet dies als Ausgangsbasis, bevor er Korrekturen für langsame Tests versucht. pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json vergleicht gruppierte Berichte nach einer leistungsorientierten Änderung.
• Ausführungen vollständiger Suites, von Erweiterungen und von Include-Pattern-Shards aktualisieren lokale Zeitmessungsdaten in .artifacts/vitest-shard-timings.json; spätere Ausführungen vollständiger Konfigurationen verwenden diese Zeitmessungen, um langsame und schnelle Shards auszubalancieren. Include-Pattern-CI-Shards hängen den Shard-Namen an den Zeitmessungsschlüssel an, sodass die Zeitmessungen gefilterter Shards sichtbar bleiben, ohne die Zeitmessungsdaten vollständiger Konfigurationen zu ersetzen. Setzen Sie OPENCLAW_TEST_PROJECTS_TIMINGS=0, um das lokale Zeitmessungsartefakt 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
• Tests von Updates und Plugins