OpenClaw Tests ausführen: Test-Suites effizient steuern

Wenn du dich ständig mit instabilen Testumgebungen oder unklaren Performance-Engpässen in deinem Workflow herumschlägst, kennst du das Gefühl, wenn ein einfacher Build plötzlich zur Geduldsprobe wird. Genau hier setzt OpenClaw an, um dir mit einer robusten Test-Suite und präzisen Benchmarking-Tools den Rücken freizuhalten.

Hier ist dein Leitfaden für OpenClaw Tests und Performance-Analysen, damit du deine Entwicklung effizient und fehlerfrei gestaltest.

Tests

Hier findest du das komplette Test-Kit inklusive Suites, Live-Tests und Docker-Integration: Testing

1. pnpm test:force: Beendet jeden hängengebliebenen Gateway-Prozess, der den Standard-Control-Port blockiert, und führt dann die komplette Vitest-Suite mit einem isolierten Gateway-Port aus, damit Server-Tests nicht mit einer laufenden Instanz kollidieren. Nutze dies, wenn ein vorheriger Gateway-Lauf Port 18789 belegt hat.
2. pnpm test:coverage: Führt die Unit-Suite mit V8-Coverage aus (via vitest.unit.config.ts). Dies ist ein Gate für geladene Dateien, kein Full-Repo-Coverage. Die Schwellenwerte liegen bei 70 % für Zeilen/Funktionen/Statements und 55 % für Branches. Da coverage.all auf false steht, misst das Gate die Dateien, die von der Unit-Coverage-Suite geladen wurden.
3. pnpm test:coverage:changed: Führt die Unit-Coverage nur für Dateien aus, die seit origin/main geändert wurden.
4. pnpm test:changed: Erweitert geänderte GitHub-Pfade in gescopte Vitest-Lanes, wenn der Diff nur routbare Quell-/Testdateien betrifft. Änderungen an Konfiguration/Setup fallen auf die nativen Root-Projekte zurück, damit Anpassungen bei Bedarf breit neu ausgeführt werden.
5. pnpm changed:lanes: Zeigt die architektonischen Lanes, die durch den Diff gegenüber origin/main ausgelöst wurden.
6. pnpm check:changed: Führt das intelligente Changed-Gate für den Diff gegenüber origin/main aus. Es führt Kernarbeit mit Kern-Test-Lanes aus, Erweiterungsarbeit mit Erweiterungs-Test-Lanes, Test-only-Arbeit mit Test-Typecheck/Tests und erweitert Änderungen am öffentlichen Plugin SDK oder Plugin-Contract auf die Erweiterungsvalidierung.
7. pnpm test: Routet explizite Datei-/Verzeichnisziele durch gescopte Vitest-Lanes. Nicht-zielgerichtete Läufe nutzen feste Shard-Gruppen und erweitern sich auf Leaf-Configs für lokale parallele Ausführung; die Erweiterungsgruppe erweitert sich immer auf die Shard-Configs pro Erweiterung statt auf einen riesigen Root-Projekt-Prozess.
8. Vollständige und Erweiterungs-Shard-Läufe aktualisieren lokale Timing-Daten in .artifacts/vitest-shard-timings.json; spätere Läufe nutzen diese Timings, um langsame und schnelle Shards auszubalancieren. Setze OPENCLAW_TEST_PROJECTS_TIMINGS=0, um das lokale Timing-Artefakt zu ignorieren.
9. Ausgewählte plugin-sdk und commands Testdateien routen jetzt durch dedizierte Light-Lanes, die nur test/setup.ts behalten, während laufzeitintensive Fälle auf ihren bestehenden Lanes verbleiben.
10. Ausgewählte plugin-sdk und commands Helper-Quelldateien mappen pnpm test:changed ebenfalls auf explizite Schwester-Tests in diesen Light-Lanes, sodass kleine Helper-Änderungen das erneute Ausführen der schweren laufzeitbasierten Suites vermeiden.
11. auto-reply ist jetzt ebenfalls in drei dedizierte Configs (core, top-level, reply) unterteilt, damit der Reply-Harness nicht die leichteren Top-Level-Status/Token/Helper-Tests dominiert.
12. Die Basis-Vitest-Config nutzt standardmäßig pool: "threads" und isolate: false, wobei der geteilte, nicht-isolierte Runner über die Repo-Configs hinweg aktiviert ist.
13. pnpm test:channels führt vitest.channels.config.ts aus.
14. pnpm test:extensions und pnpm test extensions führen alle Erweiterungs-/Plugin-Shards aus. Schwere Channel-Erweiterungen und OpenAI laufen als dedizierte Shards; andere Erweiterungsgruppen bleiben gebatcht. Nutze pnpm test extensions/<id> für eine gebündelte Plugin-Lane.
15. pnpm test:perf:imports: Aktiviert Vitest Import-Duration + Import-Breakdown Reporting, während weiterhin gescoptes Lane-Routing für explizite Datei-/Verzeichnisziele genutzt wird.
16. pnpm test:perf:imports:changed: Gleiches Import-Profiling, aber nur für Dateien, die seit origin/main geändert wurden.
17. pnpm test:perf:changed:bench — —ref <git-ref> benchmarkt den gerouteten Changed-Mode-Pfad gegen den nativen Root-Projekt-Lauf für denselben committed GitHub-Diff.
18. pnpm test:perf:changed:bench — —worktree benchmarkt das aktuelle Worktree-Change-Set, ohne vorher zu committen.
19. pnpm test:perf:profile:main: Schreibt ein CPU-Profil für den Vitest-Main-Thread (.artifacts/vitest-main-profile).
20. pnpm test:perf:profile:runner: Schreibt CPU + Heap-Profile für den Unit-Runner (.artifacts/vitest-runner-profile).
21. Gateway-Integration: Opt-in via OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test oder pnpm test:gateway.
22. pnpm test:e2e: Führt Gateway End-to-End Smoke-Tests aus (Multi-Instanz WS/HTTP/Node.js-Pairing). Standardmäßig threads + isolate: false mit adaptiven Workern in vitest.e2e.config.ts; anpassbar mit OPENCLAW_E2E_WORKERS=<n> und setze OPENCLAW_E2E_VERBOSE=1 für ausführliche Logs.
23. pnpm test:live: Führt Provider-Live-Tests aus (minimax/zai). Erfordert API-Keys und LIVE=1 (oder Provider-spezifische *_LIVE_TEST=1), um das Überspringen aufzuheben.
24. pnpm test:docker:openwebui: Startet Docker-isiertes OpenClaw + Open WebUI, loggt sich über Open WebUI ein, prüft /api/models und führt dann einen echten proxied Chat durch /api/chat/completions. Erfordert einen nutzbaren Live-Modell-Key (z. B. OpenAI in ~/.profile), zieht ein externes Open WebUI-Image und ist nicht als CI-stabil wie die normalen Unit/E2E-Suites gedacht.
25. pnpm test:docker:mcp-channels: Startet einen geseedeten Gateway-Container und einen zweiten Client-Container, der openclaw mcp serve spawnt, und verifiziert dann die geroutete Konversationserkennung, Transcript-Reads, Attachment-Metadaten, Live-Event-Queue-Verhalten, Outbound-Send-Routing und Claude-Style Channel + Permission-Benachrichtigungen über die echte stdio-Bridge. Die Claude-Benachrichtigungs-Assertion liest die rohen stdio MCP-Frames direkt, sodass der Smoke-Test widerspiegelt, was die Bridge tatsächlich emittiert.

Lokales PR-Gate

Für lokale PR-Land/Gate-Checks führe folgende Befehle aus:

1. pnpm check:changed
2. pnpm check
3. pnpm check:test-types
4. pnpm build
5. pnpm test
6. pnpm check:docs

Wenn pnpm test auf einem geladenen Host flakt, führe es einmal erneut aus, bevor du es als Regression behandelst, und isoliere es dann mit pnpm test <path/to/test>. Für speicherbeschränkte Hosts nutze:

OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

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

Modell-Latenz-Bench (lokale Keys)

Das Skript scripts/bench-model.ts hilft dir dabei, die Latenz deiner Modelle direkt zu messen.

1. source ~/.profile && pnpm tsx scripts/bench-model.ts —runs 10
2. Optionale Umgebungsvariablen: MINIMAX_API_KEY, MINIMAX_BASE_URL, MINIMAX_MODEL, ANTHROPIC_API_KEY
3. Standard-Prompt: “Reply with a single word: ok. No punctuation or extra text.”

Letzter Lauf (2025-12-31, 20 Läufe):

• minimax median 1279ms (min 1114, max 2431)
• opus median 2454ms (min 1224, max 3170)

CLI Startup-Bench

Mit dem Skript scripts/bench-cli-startup.ts kannst du die Startgeschwindigkeit deiner CLI analysieren.

1. pnpm test:startup:bench
2. pnpm test:startup:bench:smoke
3. pnpm test:startup:bench:save
4. pnpm test:startup:bench:update
5. pnpm test:startup:bench:check
6. pnpm tsx scripts/bench-cli-startup.ts
7. pnpm tsx scripts/bench-cli-startup.ts —runs 12
8. pnpm tsx scripts/bench-cli-startup.ts —preset real
9. pnpm tsx scripts/bench-cli-startup.ts —preset real —case status —case gatewayStatus —runs 3
10. pnpm tsx scripts/bench-cli-startup.ts —entry openclaw.mjs —entry-secondary dist/entry.js —preset all
11. pnpm tsx scripts/bench-cli-startup.ts —preset all —output .artifacts/cli-startup-bench-all.json
12. pnpm tsx scripts/bench-cli-startup.ts —preset real —case gatewayStatusJson —output .artifacts/cli-startup-bench-smoke.json
13. pnpm tsx scripts/bench-cli-startup.ts —preset real —cpu-prof-dir .artifacts/cli-cpu
14. pnpm tsx scripts/bench-cli-startup.ts —json

Presets:

• startup: --version, --help, health, health --json, status --json, status
• real: health, status, status --json, sessions, sessions --json, agents list --json, gateway status, gateway status --json, gateway health --json, config get gateway.port
• all: beide Presets

Die Ausgabe enthält sampleCount, Durchschnitt, p50, p95, min/max, Exit-Code/Signal-Verteilung und max RSS-Zusammenfassungen für jeden Befehl. Optional schreiben --cpu-prof-dir / --heap-prof-dir V8-Profile pro Lauf, sodass Timing und Profil-Erfassung denselben Harness nutzen.

Gespeicherte Output-Konventionen:

• pnpm test:startup:bench:smoke schreibt das gezielte Smoke-Artefakt nach .artifacts/cli-startup-bench-smoke.json
• pnpm test:startup:bench:save schreibt das Full-Suite-Artefakt nach .artifacts/cli-startup-bench-all.json unter Verwendung von runs=5 und warmup=1
• pnpm test:startup:bench:update aktualisiert das eingecheckte Baseline-Fixture unter test/fixtures/cli-startup-bench.json unter Verwendung von runs=5 und warmup=1

Eingechecktes Fixture:

• test/fixtures/cli-startup-bench.json
• Aktualisiere mit pnpm test:startup:bench:update
• Vergleiche aktuelle Ergebnisse mit dem Fixture mittels pnpm test:startup:bench:check

Onboarding E2E (Docker)

Docker ist optional; dies wird nur für containerisierte Onboarding-Smoke-Tests benötigt.

Vollständiger Cold-Start-Flow in einem sauberen Linux-Container:

scripts/e2e/onboard-docker.sh

Dieses Skript steuert den interaktiven Wizard über ein Pseudo-TTY, verifiziert Konfigurations-/Workspace-/Session-Dateien, startet dann das Gateway und führt openclaw health aus.

QR Import Smoke (Docker)

Stellt sicher, dass qrcode-terminal unter den unterstützten Docker Node.js-Runtimes lädt (Standard Node.js 24, kompatibel mit Node.js 22):

pnpm test:docker:qr

---

Nächste Schritte

• Testing
• AI Setup Assistant