--- read_when: - Tests ausführen oder korrigieren summary: So führen Sie Tests lokal aus (vitest) und wann Sie erzwungene Ausführung bzw. Abdeckungsmodi verwenden sollten title: Tests x-i18n: generated_at: "2026-07-12T02:09:50Z" model: gpt-5.6 postprocess_version: locale-links-v1 provider: openai source_hash: 63806ea72da1579f4aa0b92c14a6d2d3e67990d6c10cb6d9b1b2bb4a63c8e140 source_path: reference/test.md workflow: 16 --- - Vollständiges Test-Kit (Testsammlungen, Live-Tests, Docker): [Tests](/de/help/testing) - Validierung von Updates und Plugin-Paketen: [Updates und Plugins testen](/de/help/testing-updates-plugins) ## 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: ```bash 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 ` 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 `. - 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 `: 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. | Befehl | Funktion | | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pnpm test` | Explizite Datei-/Verzeichnisziele werden über bereichsspezifische Vitest-Lanes geleitet. Läufe ohne Ziel dienen als Nachweis für die vollständige Testsammlung: Feste Shard-Gruppen werden für die lokale parallele Ausführung in einzelne Konfigurationen aufgeteilt; der erwartete Shard-Fanout wird vor dem Start ausgegeben. Die Erweiterungsgruppe wird stets in Shard-Konfigurationen pro Erweiterung aufgeteilt, statt in einem einzigen riesigen Root-Projekt-Prozess ausgeführt zu werden. | | `pnpm test:changed` | Kostengünstiger intelligenter Testlauf für Änderungen: präzise Ziele aus direkten Teständerungen, benachbarten `*.test.ts`-Dateien, expliziten Quellzuordnungen und dem lokalen Importgraphen. Umfassende Änderungen an Konfigurationen oder Paketen werden übersprungen, sofern sie keinen präzisen Tests zugeordnet werden können. | | `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` | Expliziter umfassender Testlauf für Änderungen; verwenden Sie ihn, wenn eine Änderung am Test-Harness, an der Konfiguration oder an einem Paket auf das umfassendere Verhalten von Vitest für geänderte Tests zurückfallen soll. | | `pnpm test:force` | Gibt den konfigurierten OpenClaw-Gateway-Port frei (standardmäßig `18789`) und führt anschließend die vollständige Testsammlung mit einem isolierten Gateway-Port aus, damit Servertests nicht mit einer laufenden Instanz kollidieren. | | `pnpm test:coverage` | Erstellt einen informativen V8-Abdeckungsbericht für die standardmäßige Unit-Lane (`vitest.unit.config.ts`); es werden keine Mindestwerte für die Abdeckung durchgesetzt. | | `pnpm test:coverage:changed` | Unit-Testabdeckung nur für Dateien, die seit `origin/main` geändert wurden. | | `pnpm changed:lanes` | Zeigt die durch den Diff gegenüber `origin/main` ausgelösten Architekturbereiche. | | `pnpm check:changed` | Delegiert außerhalb der CI standardmäßig an Crabbox/Testbox und führt anschließend die intelligente Prüfschleuse für Änderungen im Remote-Unterprozess aus: Formatierung sowie Typprüfung, Linting und Schutzbefehle für betroffene Lanes. Führt Vitest nicht aus; verwenden Sie `pnpm test:changed` oder `pnpm test ` als Testnachweis. | ## 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