openclaw-test-performance

OpenClaw Test Performance

Verwende zuerst Beweise. Das Ziel ist eine echte pnpm test-, Plugin-Suite- und Plugin-Inspector-Geschwindigkeits-/RSS-Verbesserung bei intakter Abdeckung, nicht Runner-Optimierung durch Raten.

Arbeitsablauf

1. Lies die relevanten lokalen AGENTS.md-Dateien, bevor du Änderungen vornimmst:
   • src/agents/AGENTS.md für Agenten/Import-Hotspots.
   • src/channels/AGENTS.md und src/plugins/AGENTS.md für Plugin/Channel-Trägheit.
   • src/gateway/AGENTS.md für Serverlebenszyklus-Tests.
   • test/helpers/AGENTS.md und src/channels/plugins/contracts/test-helpers/AGENTS.md für gemeinsame Contract-Helfer.
   • src/infra/outbound/AGENTS.md für Outbound/Medien/Aktions-Tests.
2. Erstelle eine Basislinie, bevor du Code änderst:
   • Bevorzuge pnpm test:perf:groups --full-suite --allow-failures --output <datei> für das Ranking der gesamten Suite.
   • Für die Breite gebündelter Plugins führe den kleinsten relevanten pnpm test:extensions:batch <plugin[,plugin...]>- oder Plugin-Inspector-Befehl aus, bevor du zum vollständigen Extension-Durchlauf springst.
   • Für einen eingegrenzten Hotspot verwende: /usr/bin/time -l pnpm test <datei-oder-dateien> --maxWorkers=1 --reporter=verbose
   • Bei Import-Verdacht füge hinzu: OPENCLAW_VITEST_IMPORT_DURATIONS=1 OPENCLAW_VITEST_PRINT_IMPORT_BREAKDOWN=1.
3. Trenne Wand-/Runner-Rauschen von echten Dateikosten:
   • Vergleiche Vitest-Dauer, Testkörper-Zeit, Import-Aufschlüsselung, Wandzeit und maximalen RSS.
   • Führe einzelne Dateien erneut aus, wenn die Zahlen der Gruppe/vollen Suite veraltet oder verrauscht erscheinen.
   • Wenn ein Gruppenlauf der gesamten Suite einen Lane-Fehler meldet, JSON aber bestandene Tests anzeigt, erfasse dies als Rauschen und überprüfe die verdächtige Datei direkt.
4. Wähle den nächsten Angriffspunkt nach Ertrag und Risiko:
   • Hoher Ertrag: Eine Datei/ein Test dominiert Sekunden oder RSS und hat eine klare Ursache.
   • Hohe Hebelwirkung: Ein Plugin- oder SDK-Barrel führt dazu, dass jeder Plugin-Inspector- oder Extension-Batch-Lauf die breite Laufzeit lädt.
   • Geringeres Risiko: Statische Deskriptoren, Zielparsing, Routing, Auth-Bypass, Setup-Hinweise, Registry-Fixtures oder Testserver-Lebenszyklus.
   • Höheres Risiko: Echtes Speicher-/Laufzeitverhalten, Live-Anbieter, Protokoll- Contracts oder breite Produktions-Refactorings.
5. Behebe die Grundursache, nicht das Symptom:
   • Verschiebe statische Metadaten/Parsing in schmale Helfer oder leichtgewichtige Artefakte, die von der vollständigen Laufzeit und schnellen Pfaden wiederverwendet werden.
   • Bevorzuge Dependency Injection, Suche nur nach geladenen Plugins, explizite Fixtures und reine Helfer gegenüber breiten Mocks.
   • Verwende Suite-Level-Server/Clients wieder, wenn ein neuer Handshake irrelevant ist.
   • Halte Scheduler/Hintergrundschleifen ausgeschaltet, es sei denn, der Test beweist Scheduling.
   • Verschiebe in Plugin-Pfaden statische Metadaten in Manifest/leichtgewichtige Artefakte und halte Laufzeit-Plugin-Lasten hinter expliziten Ausführungsgrenzen.
6. Bewahre die Abdeckungsstruktur:
   • Lösche keinen langsamen Integrationsnachweis, es sei denn, die exakte Produktions- Komposition wird in einen benannten Helfer extrahiert und getestet.
   • Behalte einen billigen Integrations-Smoke-Test bei, wenn die komponentenübergreifende Verdrahtung wichtig ist.
   • Gib explizit an, welche zufällige Abdeckung entfernt wurde, falls vorhanden.
7. Wiederhole die Benchmark mit demselben Befehl nach der Änderung und berechne Sekunden sowie prozentualen Gewinn.
8. Aktualisiere den laufenden Bericht, wenn dies angefordert wird oder dieser Thread einen verfolgt. Füge Vorher/Nachher-Befehle, Artefakte, Abdeckungshinweise, Verifizierung und nächste Angriffsreihenfolge hinzu.
9. Stage die beabsichtigten Pfade, committe mit Standard-Git und pushe, wenn der Benutzer um Commits/Pushes gebeten hat. Stage nur Dateien, die für diesen Angriff berührt wurden.

Plugin-Suite-Workflow

Verwende diesen Abschnitt, wenn Perf-Arbeit gebündelte Plugins, Plugin-Inspector, SDK-Barrels, Package-Grenz-Tests oder Extension-Suiten umfasst.

1. Kartiere zuerst die Suite-Struktur:
   • Quell-Tests: pnpm test extensions/<id> oder pnpm test:extensions:batch <id>
   • Package-Grenzen: pnpm run test:extensions:package-boundary:canary und pnpm run test:extensions:package-boundary:compile
   • alle gebündelten Quell-Tests: pnpm test:extensions
   • Plugin-Import-Speicher: pnpm test:extensions:memory -- --json .artifacts/test-perf/extensions-memory.json
   • Plugin-Inspector/Report-Arbeit: halte Report-Primitive in plugin-inspector; halte Wrapper dünn und sammle den maximalen RSS, wenn der Befehl dies unterstützt.
2. Beginne eng, dann erweitern:
   • ein geändertes Plugin: führe die Tests dieses Plugins und den Plugin-Inspector-Teil aus.
   • geändertes SDK/öffentliches Barrel: füge repräsentative Provider-, Channel-, Memory-, und Feature-Plugins hinzu.
   • geänderter Loader/Runtime-Spiegel: füge Package-Grenz-Prüfungen und Build/Package- Nachweis nach Bedarf hinzu.
   • unbekanntes gemeinsames Plugin-Verhalten: führe test:extensions:batch-Gruppen vor pnpm test:extensions aus.
3. Behandle Plugin-Inspector-Fehler als Produktsignale:
   • JSON muss parsen.
   • Warnungen/Fehler müssen klassifiziert, nicht versteckt werden.
   • Die Laufzeiterfassung sollte leise und konfigurationstolerant sein.
   • Die Befehlsausgabe sollte Wandzeit, Exit-Code und maximalen RSS enthalten, wenn verfügbar.
4. Folge $openclaw-testing für die Host-Auswahl. Vertrauenswürdige Quell-Benchmarks können lokal mit vergleichbaren Maschinen-/Lastbedingungen ausgeführt werden. Verwende $crabbox, wenn sauberes Packaging, Linux/Plattform-Verhalten, Isolation oder eine explizite Remote- Anforderung Teil des Nachweises sind; verwende den gemieteten Lease erneut und räume nur ihn auf.
5. Wenn die Plugin-Leistung package-artefaktempfindlich ist, wechsle zu release-openclaw-plugin-testing und Package Acceptance, anstatt sich nur auf Quell-Timing zu verlassen.

Metriksammlung

Sammle vor und nach der Änderung mindestens eine stabile Metrik. Bevorzuge dieselbe Maschine und denselben Befehl. Verwende für Testbox-Vergleiche nach Möglichkeit dieselbe tbx_...-ID.

Metrik	Verwendung für	Bevorzugte Quelle
Wandzeit	benutzersichtbare Suite-Kosten	/usr/bin/time -l, Test-Wrapper-Dauer, Testbox-Laufzeit
Vitest-Dauer	Testkörper/Import-Kosten	Vitest-Ausgabe pro Datei/Shard
Import-Dauer	breite Barrel-/Laufzeit-Ladungen	OPENCLAW_VITEST_IMPORT_DURATIONS=1
max RSS	Speicherdruck und OOM-Risiko	/usr/bin/time -l, pnpm test:extensions:memory, Wrapper-Speicherzusammenfassungen
CPU/user/sys	CPU-gebunden vs. Warte-gebunden-Aufteilung	/usr/bin/time -l lokal, Testbox-Job-Timing bei verrauschter lokaler CPU
Heap-Nachweis	echtes Leck vs. beibehaltenes Modulgraph	openclaw-test-heap-leaks-Workflow

Lokaler eingegrenzter Befehl mit CPU/RSS:

timeout 240 /usr/bin/time -l pnpm test <datei> --maxWorkers=1 --reporter=verbose

Plugin-Import-Speicherprofil:

pnpm build
pnpm test:extensions:memory -- --top 20 --json .artifacts/test-perf/extensions-memory.json

Gezieltes Plugin-Import-Speicherprofil:

pnpm test:extensions:memory -- --extension discord --extension telegram --skip-combined

Heap/RSS-Eskalation:

pnpm test:perf:groups \
  --config test/vitest/vitest.unit-fast.config.ts \
  --allow-failures \
  --output .artifacts/test-perf/unit-fast-memory.json
pnpm test:perf:profile:runner -- \
  --output-dir .artifacts/test-perf/vitest-runner-profile -- <datei>

Verwende openclaw-test-heap-leaks, wenn der RSS über Intervalle hinweg weiter wächst, Worker OOM werden oder der verdächtige Befehl App-Objekt-Retention aufweist. Bezeichne RSS-Wachstum erst als Leck, wenn Snapshots oder Retainer dies unterstützen.

Häufige Ursachen

• Vollständig gebündelte Channel-/Plugin-Laufzeit wird für statische Daten geladen.
• getChannelPlugin()-Fallback wird verwendet, obwohl ein bereits geladener Fixture oder reiner Parser ausreichen würde.
• Breite api.ts, runtime-api.ts, test-api.ts oder Plugin-SDK-Barrels werden in heiße Tests gezogen.
• SDK-Root-Alias oder Package-Barrels ziehen fokussierte Unterpfade zurück in einen breiten Plugin-Graphen.
• Plugin-Inspector lädt Laufzeitcode nur, um Metadaten, Reports oder CI-Richtlinienergebnisse darzustellen.
• Gebündelte Plugin-Erfassung verwendet echten Konfigurations-/Home-Zustand anstelle von synthetischem, redigiertem, isoliertem Zustand.
• Teilweise echte Mocks verwenden importActual() um breite Module.
• vi.resetModules() plus frische Imports in Pro-Test-Schleifen.
• Test-Plugin-Registry wird in beforeAll initialisiert, während der Laufzeitzustand in afterEach zurückgesetzt wird.
• Pro-Test-Gateway/Server/Client-Start, obwohl ein Zustands-Reset ausreichen würde.
• Standardlaufzeit/modell/Auth-Auswahl wird von Leerlauf-Snapshots oder Fixtures bezahlt.
• Plugin-eigene Medien-/Aktionserkennung wird ausgelöst, bevor geprüft wird, ob Argumente Plugin-eigene Felder enthalten.
• Parallele Vitest-Läufe teilen sich node_modules/.experimental-vitest-cache ohne unterschiedliche OPENCLAW_VITEST_FS_MODULE_CACHE_PATH-Werte.

Benchmark-Befehle

Eingegrenzte Datei:

timeout 240 /usr/bin/time -l pnpm test <datei> --maxWorkers=1 --reporter=verbose

Eingegrenzte Datei mit Import-Aufschlüsselung:

timeout 240 /usr/bin/time -l env \
  OPENCLAW_VITEST_IMPORT_DURATIONS=1 \
  OPENCLAW_VITEST_PRINT_IMPORT_BREAKDOWN=1 \
  pnpm test <datei> --maxWorkers=1 --reporter=verbose

Gruppierte Suite:

pnpm test:perf:groups --full-suite --allow-failures \
  --output .artifacts/test-perf/<name>.json

Extension-Batch:

pnpm test:extensions:batch <plugin[,plugin...]> -- --reporter=verbose

Alle Extension-Tests:

pnpm test:extensions

Package-Grenz-Plugin-Prüfungen:

pnpm run test:extensions:package-boundary:canary
pnpm run test:extensions:package-boundary:compile

Vorhandenen Vitest-JSON-Report wiederverwenden:

pnpm test:perf:groups --report <vitest-json> \
  --output .artifacts/test-perf/<name>.json

Verifizierung

• Führe immer die gezielte Testoberfläche aus, die die Änderung beweist.
• Folge den OpenClaw-Testrichtlinien für fokussierte Tests, erforderliche Builds, Beweis-Routing und Veröffentlichungszeitpunkt.
• Für reine Teständerungen führe die exakt bearbeiteten Tests mit dem unterstützten Befehl des Eigentümers aus.
• Für Änderungen am Plugin-SDK/Barrel/Runtime vergleiche exakte Commits mit pnpm plugin-sdk:api:diff -- --base <base-sha> --head <head-sha>, wenn die öffentliche API-Oberfläche abweichen könnte. Verwende für PR-lokale Beweise die Merge-Basis des Branches als <base-sha> und den exakt getesteten Head-Commit als <head-sha>.
• Für Plugin-Suite-Perf-Fixes verifiziere mindestens einen repräsentativen Plugin-Batch plus das geänderte Gate; verwende Package Acceptance, wenn der Fehler nur in einem gepackten Artefakt existiert.
• Für fehlende oder veraltete Abhängigkeiten folge den Quellabhängigkeiten und den aktuellen Owner-Anweisungen des Arbeitsbaums. Verwende eine qualifizierte Beweisroute.
• Verwende das Berichtsformat:

| Metrik          | Vorher |  Nachher |          Gewinn |
| --------------- | -----: | -------: | --------------: |
| Datei-Wandzeit  |   `Xs` |     `Ys` |  `-Zs` (`P%`)   |
| Max RSS         |  `XMB` |    `YMB` | `-ZMB` (`P%`)   |
| CPU user/sys    | `X/Ys` |   `A/Bs` |       erklären  |

Übergabe

Halte die Zusammenfassung kurz:

• Grundursache.
• Suite-/Plugin-Umfang.
• Geänderte Dateien.
• Vorher/Nachher-Wand-, Vitest-/Import-, CPU- und RSS-Zahlen, wo verfügbar.
• Leck-Klassifizierung, falls Speicher involviert war: echtes Leck, beibehaltenes Modulgraph oder nicht schlüssig.
• Abdeckung beibehalten.
• Verifizierungsbefehle.
• Testbox-ID oder Workflow-URL für den Remote-Nachweis.
• Commit-Hash und Push-Status.