Testen: Updates und Plugins

Dies ist die dedizierte Checkliste für Update- und Plugin-Validierung. Das Ziel ist einfach: Beweisen, dass das installierbare Paket echten Benutzerzustand aktualisieren, veralteten Legacy-Zustand über doctor reparieren und weiterhin Plugins aus den unterstützten Quellen installieren, laden, aktualisieren und deinstallieren kann.

Die breitere Übersicht zum Test-Runner finden Sie unter Tests. Für Live-Provider- Schlüssel und Suites, die das Netzwerk berühren, siehe Live testen.

Was wir schützen

Update- und Plugin-Tests schützen diese Verträge:

• Ein Paket-Tarball ist vollständig, hat eine gültige dist/postinstall-inventory.json und hängt nicht von entpackten Repo-Dateien ab.
• Ein Benutzer kann von einem älteren veröffentlichten Paket zum Kandidatenpaket wechseln, ohne Konfiguration, Agenten, Sitzungen, Arbeitsbereiche, Plugin-Zulassungslisten oder Channel-Konfiguration zu verlieren.
• openclaw doctor --fix --non-interactive besitzt Legacy-Bereinigungs- und Reparaturpfade. Der Start sollte keine versteckten Kompatibilitätsmigrationen für veralteten Plugin-Zustand erweitern.
• Plugin-Installationen funktionieren aus lokalen Verzeichnissen, Git-Repos, npm-Paketen und dem ClawHub-Registry-Pfad.
• npm-Abhängigkeiten von Plugins werden in einem verwalteten npm-Projekt pro Plugin installiert, vor dem Vertrauen gescannt und während der Deinstallation über npm entfernt, damit gehobene Abhängigkeiten nicht zurückbleiben.
• Plugin-Updates sind stabil, wenn sich nichts geändert hat: Installationsdatensätze, aufgelöste Quelle, installiertes Abhängigkeitslayout und aktivierter Zustand bleiben intakt.

Lokaler Nachweis während der Entwicklung

Beginnen Sie eng gefasst:

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

Führen Sie bei Änderungen an Plugin-Installation, Deinstallation, Abhängigkeiten oder Paket-Inventar 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

Bevor eine Paket-Docker-Lane einen Tarball verwendet, beweisen Sie das Paket-Artefakt:

pnpm release:check

release:check führt Drift-Prüfungen für Konfiguration/Dokumentation/API aus, schreibt das Paket-Dist- Inventar, führt npm pack --dry-run aus, weist verbotene gepackte Dateien zurück, installiert den Tarball in ein temporäres Präfix, führt postinstall aus und smoke-testet gebündelte Channel- Einstiegspunkte.

Docker-Lanes

Die Docker-Lanes sind der Nachweis auf Produktebene. Sie installieren oder aktualisieren ein echtes Paket innerhalb von Linux-Containern und prüfen Verhalten über CLI-Befehle, Gateway-Start, HTTP-Probes, RPC-Status und Dateisystemzustand.

Verwenden Sie beim Iterieren fokussierte Lanes:

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 Lanes:

• test:docker:plugins validiert Plugin-Installations-Smoke, Installationen lokaler Ordner, Skip-Verhalten bei Updates lokaler Ordner, lokale Ordner mit vorinstallierten Abhängigkeiten, file:-Paketinstallationen, Git-Installationen mit CLI-Ausführung, Git- Moving-Ref-Updates, npm-Registry-Installationen mit gehobenen transitiven Abhängigkeiten, npm-Update-No-Ops, Zurückweisung fehlerhafter npm-Paketmetadaten, lokale ClawHub-Fixture-Installationen und Update-No-Ops, Marketplace-Update-Verhalten und Claude-Bundle-Aktivierung/Inspektion. Setzen Sie OPENCLAW_PLUGINS_E2E_CLAWHUB=0, um den ClawHub-Block hermetisch/offline zu halten.
• test:docker:plugin-lifecycle-matrix installiert das Kandidatenpaket in einem leeren Container, führt ein npm-Plugin durch Installation, Inspektion, Deaktivierung, Aktivierung, explizites Upgrade, explizites Downgrade und Deinstallation nach dem Löschen des Plugin- Codes. Es protokolliert RSS- und CPU-Metriken für jede Phase.
• test:docker:plugin-update validiert, dass ein unverändertes installiertes Plugin während openclaw plugins update nicht neu installiert wird und keine Installationsmetadaten verliert.
• test:docker:upgrade-survivor installiert den Kandidaten-Tarball über eine schmutzige Altbenutzer-Fixture, führt Paket-Update plus nicht interaktiven doctor aus, startet dann einen Loopback-Gateway und prüft die Zustandserhaltung.
• test:docker:published-upgrade-survivor installiert zuerst eine veröffentlichte Baseline, konfiguriert sie über ein eingebettetes openclaw config set-Rezept, aktualisiert sie auf den Kandidaten-Tarball, führt doctor aus, prüft Legacy-Bereinigung, startet den Gateway und probt /healthz, /readyz und RPC-Status.
• test:docker:update-restart-auth installiert das Kandidatenpaket, startet einen verwalteten Token-Auth-Gateway, entfernt Gateway-Auth-Umgebungsvariablen des Aufrufers für openclaw update --yes --json und verlangt, dass der Update-Befehl des Kandidaten den Gateway vor den normalen Probes neu startet.
• test:docker:update-migration ist die bereinigungsintensive Published-Update-Lane. Sie startet aus einem konfigurierten Discord/Telegram-artigen Benutzerzustand, führt Baseline- doctor aus, damit konfigurierte Plugin-Abhängigkeiten materialisiert werden können, seetet Legacy-Plugin-Abhängigkeitsreste für ein konfiguriertes paketiertes Plugin, aktualisiert auf den Kandidaten-Tarball und verlangt, dass post-update doctor die Legacy- Abhängigkeitswurzeln entfernt.

Nützliche Published-Upgrade-Survivor-Varianten:

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 sind base, feishu-channel, bootstrap-persona, plugin-deps-cleanup, configured-plugin-installs, stale-source-plugin-shadow, tilde-log-path und versioned-runtime-deps. In aggregierten Läufen wird OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues auf alle gemeldeten Issue-förmigen Szenarien erweitert, einschließlich der Migration für konfigurierte Plugin-Installation.

Die vollständige Update-Migration ist bewusst von Full Release CI getrennt. Verwenden Sie den manuellen Workflow Update Migration, wenn die Release-Frage lautet: „Kann jede veröffentlichte stabile Version ab 2026.4.23 auf diesen Kandidaten aktualisieren und Plugin-Abhängigkeitsreste 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

Package Acceptance ist das GitHub-native Paket-Gate. Es löst ein Kandidatenpaket in einen package-under-test-Tarball auf, zeichnet Version und SHA-256 auf und führt dann wiederverwendbare Docker-E2E-Lanes gegen genau diesen Tarball aus. Die Workflow-Harness- Ref ist von der Paketquellen-Ref getrennt, sodass aktuelle Testlogik ältere vertrauenswürdige Releases validieren kann.

Kandidatenquellen:

• source=npm: validiert openclaw@beta, openclaw@latest oder eine exakte veröffentlichte Version.
• source=ref: packt einen vertrauenswürdigen Branch, Tag oder Commit mit dem ausgewählten aktuellen Harness.
• source=url: validiert einen öffentlichen HTTPS-Tarball mit erforderlichem package_sha256. Dieser Pfad weist URL-Zugangsdaten, nicht standardmäßige HTTPS-Ports, private/interne Hostnamen oder DNS/IP-Ergebnisse, Special-Use-IP-Bereiche und unsichere Redirects zurück.
• source=trusted-url: validiert einen HTTPS-Tarball mit erforderlichem package_sha256 und trusted_source_id gegen die von Maintainern kontrollierte Richtlinie in .github/package-trusted-sources.json. Verwenden Sie dies für Enterprise-/private Spiegel statt source=url mit einem eingabeseitigen Allow-Private-Schalter abzuschwächen. Bearer-Auth verwendet, wenn per Richtlinie konfiguriert, das feste OPENCLAW_TRUSTED_PACKAGE_TOKEN-Secret.
• source=artifact: verwendet einen von einem anderen Actions-Lauf hochgeladenen Tarball erneut.

Full Release Validation verwendet standardmäßig source=artifact, gebaut aus dem aufgelösten Release-SHA. Für Nachweise nach der Veröffentlichung übergeben Sie package_acceptance_package_spec=openclaw@YYYY.M.PATCH, damit dieselbe Upgrade-Matrix stattdessen das ausgelieferte npm-Paket anvisiert.

Release-Prüfungen rufen Package Acceptance mit dem Paket-/Update-/Restart-/Plugin-Set auf:

doctor-switch update-channel-switch update-corrupt-plugin upgrade-survivor published-upgrade-survivor update-restart-auth plugins-offline plugin-update

Wenn Release-Soak aktiviert ist, ü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

Dies hält Paketmigration, Update-Channel-Umschaltung, Toleranz für korrupte verwaltete Plugins, Bereinigung veralteter Plugin-Abhängigkeiten, Offline-Plugin-Abdeckung, Plugin- Update-Verhalten und Telegram-Paket-QA auf demselben aufgelösten Artefakt, ohne das Standard-Release-Paket-Gate über jede veröffentlichte Version laufen zu lassen.

last-stable-4 wird zu den vier neuesten stabilen, per npm veröffentlichten OpenClaw- Releases aufgelöst. Release Package Acceptance pinnt 2026.4.23 als erste Plugin-Update- Kompatibilitätsgrenze, 2026.5.2 als Grenze für Plugin-Architekturänderungen und 2026.4.15 als ältere Published-Update-Baseline aus 2026.4.1x; der Resolver dedupliziert Pins, die bereits in den neuesten vier enthalten sind. Für exhaustive Published- Update-Migrationsabdeckung verwenden Sie all-since-2026.4.23 im separaten Update- Migration-Workflow statt Full Release CI. release-history bleibt für manuelles breiteres Sampling verfügbar, wenn Sie auch den Legacy-Anker vor diesem Datum wünschen.

Wenn mehrere Published-Upgrade-Survivor-Baselines ausgewählt sind, shardet der wiederverwendbare Docker-Workflow jede Baseline in einen eigenen gezielten Runner-Job. Jeder Baseline-Shard führt weiterhin das ausgewählte Szenario-Set aus, aber Logs und Artefakte bleiben pro Baseline getrennt und die Laufzeit wird durch den langsamsten Shard begrenzt statt durch einen großen seriellen Job.

Führen Sie ein Paketprofil manuell aus, wenn Sie einen Kandidaten vor dem Release validieren:

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

Verwenden Sie suite_profile=product, wenn die Release-Frage MCP-Channels, Cron-/Subagent-Bereinigung, OpenAI-Websuche oder OpenWebUI umfasst. Verwenden Sie suite_profile=full nur, wenn Sie vollständige Docker-Release-Pfad-Abdeckung benötigen.

Release-Standard

Für Release-Kandidaten ist der Standard-Nachweisstapel:

1. pnpm check:changed und pnpm test:changed für Regressionen auf Quellcodeebene.
2. pnpm release:check für Integrität des Paket-Artefakts.
3. Package Acceptance package-Profil oder die benutzerdefinierten Paket-Lanes der Release-Prüfung für Installations-/Update-/Restart-/Plugin-Verträge.
4. Cross-OS-Release-Prüfungen für OS-spezifischen Installer, Onboarding und Plattform- Verhalten.
5. Live-Suites nur, wenn die geänderte Oberfläche Provider- oder Hosted-Service- Verhalten berührt.

Auf Maintainer-Maschinen sollten breite Gates und Docker-/Paket-Produktnachweise in Testbox laufen, sofern nicht ausdrücklich ein lokaler Nachweis durchgeführt wird.

Legacy-Kompatibilität

Kompatibilitätsnachsicht ist eng gefasst und zeitlich begrenzt:

• Pakete bis einschließlich 2026.4.25, einschließlich 2026.4.25-beta.*, dürfen bereits ausgelieferte Lücken in Paketmetadaten in Package Acceptance tolerieren.
• Das veröffentlichte Paket 2026.4.26 darf bei bereits ausgelieferten lokalen Build-Metadaten- Stamp-Dateien warnen.
• Spätere Pakete müssen moderne Verträge erfüllen. Dieselben Lücken führen zum Fehlschlag, statt zu warnen oder zu überspringen.

Fügen Sie für diese alten Formen keine neuen Startmigrationen hinzu. Fügen Sie eine doctor- Reparatur hinzu oder erweitern Sie sie und beweisen Sie sie dann mit upgrade-survivor, published-upgrade-survivor oder update-restart-auth, wenn der Update-Befehl den Neustart besitzt.

Abdeckung hinzufügen

Wenn Sie Update- oder Plugin-Verhalten ändern, fügen Sie Abdeckung auf der niedrigsten Ebene hinzu, die aus dem richtigen Grund fehlschlagen kann:

• Reine Pfad- oder Metadatenlogik: Unit-Test neben der Quelle.
• Paketbestand oder Verhalten gepackter Dateien: package-dist-inventory- oder Tarball- Prüftest.
• CLI-Installations-/Updateverhalten: Docker-Lane-Assertion oder Fixture.
• Migrationsverhalten veröffentlichter Releases: published-upgrade-survivor-Szenario.
• Update-eigenes Neustartverhalten: update-restart-auth.
• Registry-/Paketquellenverhalten: test:docker:plugins-Fixture oder ClawHub- Fixture-Server.
• Abhängigkeitslayout oder Bereinigungsverhalten: Sowohl die Laufzeitausführung als auch die Dateisystemgrenze prüfen. npm-Abhängigkeiten können innerhalb des vom Plugin verwalteten npm-Projekts hoisted werden. Tests sollten daher nachweisen, dass dieses Projekt gescannt/bereinigt wird, anstatt anzunehmen, dass nur der paketlokale node_modules-Baum des Plugins verwendet wird.

Halten Sie neue Docker-Fixtures standardmäßig hermetisch. Verwenden Sie lokale Fixture-Registries und Fake-Pakete, es sei denn, der Zweck des Tests ist Live-Registry-Verhalten.

Fehlersuche

Beginnen Sie mit der Artefaktidentität:

• Package-Acceptance-resolve_package-Zusammenfassung: Quelle, Version, SHA-256 und Artefaktname.
• Docker-Artefakte: .artifacts/docker-tests/**/summary.json, failures.json, Lane-Logs und Befehle zum erneuten Ausführen.
• Upgrade-Survivor-Zusammenfassung: .artifacts/upgrade-survivor/summary.json, einschließlich Baseline-Version, Kandidatenversion, Szenario, Phasen-Timings und Rezeptschritte.

Führen Sie vorzugsweise die exakt fehlgeschlagene Lane mit demselben Paketartefakt erneut aus, anstatt den gesamten Release-Umbrella erneut auszuführen.