Tests: Updates und Plugins

Checkliste für die Validierung von Updates und Plugins: Weisen Sie nach, dass das installierbare Paket echte Benutzerdaten aktualisieren, veraltete Legacy-Daten über doctor reparieren und weiterhin Plugins aus jeder unterstützten Quelle installieren, laden, aktualisieren und deinstallieren kann.

Eine umfassendere Übersicht der Test-Runner finden Sie unter Tests. Informationen zu Schlüsseln für Live-Provider und Testsuiten mit Netzwerkzugriff finden Sie unter Live-Tests.

Was wir schützen

• Ein Paket-Tarball ist vollständig, enthält eine gültige dist/postinstall-inventory.json und ist nicht von entpackten Repository-Dateien abhängig.
• Benutzer können von einem älteren veröffentlichten Paket zum Kandidatenpaket wechseln, ohne Konfiguration, Agenten, Sitzungen, Arbeitsbereiche, Plugin-Zulassungslisten oder Kanalkonfiguration zu verlieren.
• openclaw doctor --fix --non-interactive ist für die Bereinigung und Reparatur von Legacy-Daten zuständig. Der Startvorgang sollte nicht um versteckte Kompatibilitätsmigrationen für veraltete Plugin-Daten erweitert werden.
• Plugin-Installationen funktionieren aus lokalen Verzeichnissen, Git-Repositorys, npm-Paketen und über den ClawHub-Registrierungspfad.
• npm-Abhängigkeiten von Plugins werden in einem verwalteten npm-Projekt pro Plugin installiert, vor der Vertrauensfreigabe geprüft und bei der Plugin-Deinstallation mit npm uninstall entfernt, damit hochgezogene Abhängigkeiten nicht zurückbleiben.
• Ein Plugin-Update führt keine Änderungen aus, wenn sich nichts geändert hat: Installationsdatensätze, aufgelöste Quelle, Layout der installierten Abhängigkeiten und Aktivierungsstatus bleiben unverändert.

Lokaler Nachweis während der Entwicklung

Beginnen Sie mit einem engen Prüfumfang:

pnpm changed:lanes --jsonpnpm check:changedpnpm test:changed

Führen Sie bei Änderungen an Plugin-Installation, -Deinstallation, -Abhängigkeiten oder dem Paketbestand außerdem die fokussierten Tests aus, die die bearbeitete Schnittstelle abdecken:

pnpm test src/plugins/uninstall.test.ts src/infra/package-dist-inventory.test.ts test/scripts/package-acceptance-workflow.test.ts

Weisen Sie das Paketartefakt nach, bevor eine Docker-Paketspur einen Tarball verwendet:

pnpm release:check

release:check führt Prüfungen auf Abweichungen bei Konfiguration, Dokumentation und API aus (Konfigurationsschema, Referenzstand der Konfigurationsdokumentation, Referenzstand und Exporte der Plugin-SDK-API, Plugin-Versionen und -Bestand), schreibt den Paket-Distributionsbestand, führt npm pack --dry-run aus, lehnt unzulässige gepackte Dateien ab, installiert den Tarball in ein temporäres Präfix, führt die Nachinstallation aus und unterzieht die Einstiegspunkte gebündelter Kanäle einem Smoke-Test.

Docker-Spuren

Die Docker-Spuren bilden den Nachweis auf Produktebene. Sie installieren oder aktualisieren ein echtes Paket in Linux-Containern und prüfen das Verhalten über CLI-Befehle, Gateway-Start, HTTP-Prüfungen, RPC-Status und Dateisystemzustand.

Verwenden Sie während der iterativen Entwicklung fokussierte Spuren:

pnpm test:docker:pluginspnpm test:docker:plugin-lifecycle-matrixpnpm test:docker:plugin-updatepnpm test:docker:upgrade-survivorpnpm test:docker:published-upgrade-survivorpnpm test:docker:update-restart-authpnpm test:docker:update-migration

Wichtige Spuren:

• test:docker:plugins deckt den Smoke-Test der Plugin-Installation, Installationen aus lokalen Ordnern, das Überspringen von Updates bei unveränderten lokalen Ordnern, lokale Ordner mit vorinstallierten Abhängigkeiten, Installationen von file:-Paketen, Git-Installationen mit CLI-Ausführung, Aktualisierungen bei verschobenen Git-Referenzen, Installationen aus der npm-Registry mit hochgezogenen transitiven Abhängigkeiten, wirkungslose npm-Updates, die Ablehnung fehlerhafter npm-Paketmetadaten, Installationen aus lokalen ClawHub-Testdaten und wirkungslose Updates, das Aktualisierungsverhalten des Marktplatzes sowie die Aktivierung und Inspektion von Claude-Paketen ab. Setzen Sie OPENCLAW_PLUGINS_E2E_CLAWHUB=0, um den ClawHub-Block hermetisch und offline zu halten.
• test:docker:plugin-lifecycle-matrix installiert das Kandidatenpaket in einem leeren Container und führt ein npm-Plugin durch Installation, Inspektion, Deaktivierung, Aktivierung, explizites Upgrade, explizites Downgrade und Deinstallation nach dem Löschen des Plugin-Codes. Dabei werden RSS- und CPU-Metriken pro Phase protokolliert.
• test:docker:plugin-update prüft, dass ein unverändertes installiertes Plugin während openclaw plugins update weder neu installiert wird noch Installationsmetadaten verliert.
• test:docker:upgrade-survivor installiert den Kandidaten-Tarball über eine verunreinigte Testumgebung eines alten Benutzers, führt die Paketaktualisierung sowie den nicht interaktiven Doctor aus, startet anschließend ein local-loopback-Gateway und prüft die Erhaltung des Zustands.
• test:docker:published-upgrade-survivor installiert zunächst einen veröffentlichten Referenzstand, konfiguriert ihn über ein integriertes openclaw config set-Rezept, aktualisiert ihn auf den Kandidaten-Tarball, führt Doctor aus, prüft die Legacy-Bereinigung, startet das Gateway und prüft /healthz, /readyz sowie den RPC-Status.
• test:docker:update-restart-auth installiert das Kandidatenpaket, startet ein verwaltetes Gateway mit Token-Authentifizierung, entfernt für openclaw update --yes --json die Umgebungsvariable für die Gateway-Authentifizierung des Aufrufers und verlangt, dass der Aktualisierungsbefehl des Kandidaten das Gateway vor den regulären Prüfungen neu startet.
• test:docker:update-migration ist die bereinigungsintensive Spur für Aktualisierungen veröffentlichter Pakete. Sie beginnt mit einem konfigurierten Benutzerzustand im Stil von Discord/Telegram, führt den Doctor des Referenzstands aus, damit Abhängigkeiten konfigurierter Plugins angelegt werden können, legt Legacy-Rückstände von Plugin-Abhängigkeiten für ein konfiguriertes paketiertes Plugin an, aktualisiert auf den Kandidaten-Tarball und verlangt, dass der Doctor nach der Aktualisierung die Legacy- Abhängigkeitsstammverzeichnisse entfernt.

Nützliche Varianten für den Überlebenstest veröffentlichter Upgrades:

OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC=openclaw@2026.4.23 \OPENCLAW_UPGRADE_SURVIVOR_SCENARIO=versioned-runtime-deps \pnpm test:docker:published-upgrade-survivor OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC=openclaw@latest \OPENCLAW_UPGRADE_SURVIVOR_SCENARIO=bootstrap-persona \pnpm test:docker:published-upgrade-survivor

Verfügbare Szenarien: base, acpx-openclaw-tools-bridge, feishu-channel, bootstrap-persona, channel-post-core-restore, plugin-deps-cleanup, configured-plugin-installs, stale-source-plugin-shadow, tilde-log-path und versioned-runtime-deps. Bei Gesamtläufen wird OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues (Alias far-reaching) auf alle Szenarien erweitert, einschließlich der Migration für die Installation konfigurierter Plugins.

Die vollständige Aktualisierungsmigration ist absichtlich von der vollständigen Release-CI getrennt. Verwenden Sie den manuellen Workflow Update Migration, wenn die Release-Frage lautet: „Kann jede seit 2026.4.23 veröffentlichte stabile Version auf diesen Kandidaten aktualisiert werden und Rückstände von Plugin-Abhängigkeiten bereinigen?“:

gh workflow run update-migration.yml \  --ref main \  -f workflow_ref=main \  -f package_ref=main \  -f baselines=all-since-2026.4.23 \  -f scenarios=plugin-deps-cleanup

Paketabnahme

Die Paketabnahme ist die GitHub-native Paketprüfung. Sie löst ein Kandidatenpaket in einen package-under-test-Tarball auf, zeichnet Version und SHA-256 auf und führt anschließend wiederverwendbare Docker-E2E-Spuren gegen genau diesen Tarball aus. Die Workflow-Harness- Referenz ist von der Referenz der Paketquelle getrennt, sodass die aktuelle Testlogik ältere vertrauenswürdige Releases validieren kann.

Kandidatenquellen:

• source=npm: Validiert openclaw@extended-stable, openclaw@beta, openclaw@latest oder eine exakt veröffentlichte Version.
• source=ref: Packt einen vertrauenswürdigen Branch, ein Tag oder einen Commit mit dem ausgewählten aktuellen Harness.
• source=url: Validiert einen öffentlichen HTTPS-Tarball mit erforderlichem package_sha256. Dieser Pfad lehnt URL-Anmeldedaten, vom Standard abweichende HTTPS-Ports, private/interne Hostnamen oder DNS-/IP-Ergebnisse, IP-Adressräume für Sonderzwecke und unsichere Weiterleitungen ab.
• source=trusted-url: Validiert einen HTTPS-Tarball mit erforderlichem package_sha256 und trusted_source_id anhand der von den Maintainern verwalteten Richtlinie in .github/package-trusted-sources.json. Verwenden Sie dies für Unternehmens-/private Spiegelserver, statt source=url durch einen Schalter auf Eingabeebene zur Zulassung privater Quellen abzuschwächen. Wenn die Richtlinie Bearer-Authentifizierung konfiguriert, wird das festgelegte Secret OPENCLAW_TRUSTED_PACKAGE_TOKEN verwendet.
• source=artifact: Verwendet einen von einem anderen Actions-Lauf hochgeladenen Tarball erneut.

Die vollständige Release-Validierung verwendet standardmäßig source=artifact, erstellt aus dem aufgelösten Release-SHA. Übergeben Sie für den Nachweis nach der Veröffentlichung package_acceptance_package_spec=openclaw@YYYY.M.PATCH, damit dieselbe Upgrade-Matrix stattdessen das ausgelieferte npm-Paket prüft.

Release-Prüfungen rufen die Paketabnahme mit der folgenden Zusammenstellung für Paket, Aktualisierung, Neustart und Plugins auf:

doctor-switch update-channel-switch skill-install update-corrupt-plugin upgrade-survivor published-upgrade-survivor root-managed-vps-upgrade update-restart-auth plugins-offline plugin-update plugin-binding-command-escape

Wenn die Release-Beobachtungsphase aktiviert ist (für release_profile=stable und full erzwungen), übergeben sie außerdem:

published_upgrade_survivor_baselines=last-stable-4 2026.4.23 2026.5.2 2026.4.15published_upgrade_survivor_scenarios=reported-issuestelegram_mode=mock-openai

Dadurch werden Paketmigration, Wechsel des Aktualisierungskanals, Toleranz gegenüber beschädigten verwalteten Plugins, Bereinigung veralteter Plugin-Abhängigkeiten, Offline-Abdeckung für Plugins, Plugin- Aktualisierungsverhalten und Telegram-Paket-QA anhand desselben aufgelösten Artefakts geprüft, ohne dass die standardmäßige Release-Paketprüfung jede veröffentlichte Version durchlaufen muss.

last-stable-4 wird in die vier neuesten stabilen, auf npm veröffentlichten OpenClaw- Versionen aufgelöst. Die Release-Paketabnahme legt 2026.4.23 als erste Kompatibilitätsgrenze für Plugin-Aktualisierungen, 2026.5.2 als Grenze für Änderungen an der Plugin-Architektur und 2026.4.15 als älteren Referenzstand für Aktualisierungen veröffentlichter Versionen aus der Reihe 2026.4.1x fest; der Resolver entfernt festgelegte Versionen, die bereits unter den neuesten vier enthalten sind. Verwenden Sie für eine vollständige Abdeckung der Migration veröffentlichter Aktualisierungen all-since-2026.4.23 im separaten Workflow „Update Migration“ statt in der vollständigen Release-CI. release-history bleibt für eine manuelle, breitere Stichprobe verfügbar, wenn Sie zusätzlich den Legacy- Referenzpunkt vor diesem Datum einbeziehen möchten.

Wenn mehrere Referenzstände für Überlebenstests veröffentlichter Upgrades ausgewählt sind, teilt der wiederverwendbare Docker-Workflow jeden Referenzstand in einen eigenen gezielten Runner-Job auf. Jeder Referenzstand-Shard führt weiterhin die ausgewählte Szenariengruppe aus, Protokolle und Artefakte bleiben jedoch nach Referenzstand getrennt, und die Gesamtdauer wird durch den langsamsten Shard statt durch einen großen seriellen Job begrenzt.

Führen Sie bei der Validierung eines Kandidaten vor der Veröffentlichung manuell ein Paketprofil aus:

gh workflow run package-acceptance.yml \  --ref main \  -f workflow_ref=main \  -f source=npm \  -f package_spec=openclaw@beta \  -f suite_profile=package \  -f published_upgrade_survivor_baselines="last-stable-4 2026.4.23 2026.5.2 2026.4.15" \  -f published_upgrade_survivor_scenarios=reported-issues \  -f telegram_mode=mock-openai

Setzen Sie für einen veröffentlichten Canary der erweiterten stabilen Version package_spec=openclaw@extended-stable. Die Paketabnahme löst diesen Selektor in einen exakten Tarball auf, bevor die Docker-Spuren ausgeführt werden.

Verwenden Sie suite_profile=product, wenn die Release-Frage MCP-Kanäle, die Bereinigung von Cron/Subagenten, die OpenAI-Websuche oder OpenWebUI umfasst. Verwenden Sie suite_profile=full nur, wenn Sie eine vollständige Docker-Abdeckung der Release-Pfade benötigen.

Release-Standard

Für Release-Kandidaten ist dies die standardmäßige Nachweiskette:

1. pnpm check:changed und pnpm test:changed für Regressionen auf Quellcodeebene.
2. pnpm release:check für die Integrität des Paketartefakts.
3. Das Paketprofil der Paketabnahme oder die benutzerdefinierten Paketspuren der Release-Prüfung für Installations-, Aktualisierungs-, Neustart- und Plugin-Verträge.
4. Betriebssystemübergreifende Release-Prüfungen für betriebssystemspezifische Installations-, Onboarding- und Plattform- Verhaltensweisen.
5. Live-Testsuiten nur, wenn die geänderte Oberfläche das Verhalten von Providern oder gehosteten Diensten betrifft.

Auf Rechnern der Maintainer sollten umfassende Prüfungen und Produktnachweise für Docker/Pakete in Testbox ausgeführt werden, sofern nicht ausdrücklich ein lokaler Nachweis durchgeführt wird.

Legacy-Kompatibilität

Die Nachsicht bei der Kompatibilität ist eng begrenzt und zeitlich befristet:

• Pakete bis einschließlich 2026.4.25, einschließlich 2026.4.25-beta.*, dürfen bereits ausgelieferte Lücken in Paketmetadaten bei der Paketabnahme tolerieren.
• Das veröffentlichte Paket 2026.4.26 darf bei bereits ausgelieferten Stempeldateien für lokale Build-Metadaten eine Warnung ausgeben.
• Spätere Pakete müssen moderne Verträge erfüllen. Dieselben Lücken führen dann zu einem Fehler, statt lediglich eine Warnung auszugeben oder übersprungen zu werden.

Fügen Sie für diese alten Formen keine neuen Startmigrationen hinzu. Fügen Sie eine Doctor- Reparatur hinzu oder erweitern Sie sie und weisen Sie diese anschließend mit upgrade-survivor, published-upgrade-survivor oder update-restart-auth nach, wenn der Aktualisierungsbefehl für den Neustart zuständig ist.

Abdeckung hinzufügen

Wenn Sie das Aktualisierungs- oder Plugin-Verhalten ändern, ergänzen Sie die Abdeckung auf der niedrigsten Ebene, die aus dem richtigen Grund fehlschlagen kann:

• Reine Pfad- oder Metadatenlogik: Unit-Test neben dem Quellcode.
• Paketbestand oder Verhalten gepackter Dateien: package-dist-inventory- oder Tarball-Prüftest.
• CLI-Installations-/Aktualisierungsverhalten: Assertion oder Fixture der Docker-Lane.
• Migrationsverhalten veröffentlichter Releases: Szenario published-upgrade-survivor.
• Neustartverhalten im Zuständigkeitsbereich der Aktualisierung: update-restart-auth.
• Verhalten von Registry-/Paketquellen: Fixture für test:docker:plugins oder ClawHub-Fixture-Server.
• Abhängigkeitslayout oder Bereinigungsverhalten: Prüfen Sie sowohl die Laufzeitausführung als auch die Dateisystemgrenze. npm-Abhängigkeiten können innerhalb des verwalteten npm-Projekts des Plugins nach oben verlagert werden. Tests sollten daher nachweisen, dass dieses Projekt durchsucht/bereinigt wird, statt anzunehmen, dass ausschließlich der paketlokale node_modules-Baum des Plugins berücksichtigt wird.

Halten Sie neue Docker-Fixtures standardmäßig hermetisch. Verwenden Sie lokale Fixture-Registrys und Scheinpakete, sofern nicht gerade das Verhalten einer Live-Registry Gegenstand des Tests ist.

Fehlertriage

Beginnen Sie mit der Artefaktidentität:

• Zusammenfassung von Package Acceptance für resolve_package: Quelle, Version, SHA-256 und Artefaktname.
• Docker-Artefakte: .artifacts/docker-tests/**/summary.json, failures.json, Lane-Protokolle und Befehle zur erneuten Ausführung.
• Zusammenfassung des Upgrade-Survivors: .artifacts/upgrade-survivor/summary.json, einschließlich Ausgangsversion, Kandidatenversion, Szenario, Phasenlaufzeiten und Abdeckung der Konfigurationsrezepte.

Führen Sie vorzugsweise exakt die fehlgeschlagene Lane mit demselben Paketartefakt erneut aus, statt den gesamten übergeordneten Release-Testlauf zu wiederholen.