Tests : mises à jour et plugins

Liste de contrôle pour la validation des mises à jour et des plugins : prouver que le paquet installable peut mettre à jour l’état réel d’un utilisateur, réparer l’état hérité obsolète via doctor, tout en continuant à installer, charger, mettre à jour et désinstaller des plugins depuis toutes les sources prises en charge.

Pour la vue d’ensemble des exécuteurs de tests, consultez Tests. Pour les clés de fournisseurs en direct et les suites qui accèdent au réseau, consultez Tests en direct.

Ce que nous protégeons

• L’archive tar d’un paquet est complète, possède un fichier dist/postinstall-inventory.json valide et ne dépend pas de fichiers de dépôt non empaquetés.
• Un utilisateur peut passer d’un ancien paquet publié au paquet candidat sans perdre sa configuration, ses agents, ses sessions, ses espaces de travail, ses listes d’autorisation de plugins ni la configuration de ses canaux.
• openclaw doctor --fix --non-interactive prend en charge les chemins de nettoyage et de réparation hérités. Le démarrage ne doit pas accumuler de migrations de compatibilité masquées pour l’état obsolète des plugins.
• L’installation de plugins fonctionne depuis des répertoires locaux, des dépôts git, des paquets npm et le chemin du registre ClawHub.
• Les dépendances npm d’un plugin sont installées dans un projet npm géré par plugin, sont analysées avant d’être approuvées et sont supprimées avec npm uninstall lors de la désinstallation du plugin, afin que les dépendances remontées ne persistent pas.
• La mise à jour d’un plugin ne fait rien lorsqu’aucun changement n’a eu lieu : les enregistrements d’installation, la source résolue, la disposition des dépendances installées et l’état d’activation restent intacts.

Validation locale pendant le développement

Commencez par un périmètre restreint :

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

Pour les modifications concernant l’installation, la désinstallation, les dépendances ou l’inventaire des paquets des plugins, exécutez également les tests ciblés couvrant l’interface modifiée :

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

Avant qu’un parcours Docker de paquet n’utilise une archive tar, validez l’artefact du paquet :

pnpm release:check

release:check exécute les vérifications de dérive de la configuration, de la documentation et de l’API (schéma de configuration, référence de la documentation de configuration, référence et exportations de l’API du SDK de plugins, versions et inventaire des plugins), écrit l’inventaire de distribution du paquet, exécute npm pack --dry-run, rejette les fichiers empaquetés interdits, installe l’archive tar dans un préfixe temporaire, exécute le script de post-installation et effectue des tests de fumée sur les points d’entrée des canaux intégrés.

Parcours Docker

Les parcours Docker constituent la validation au niveau du produit. Ils installent ou mettent à jour un paquet réel dans des conteneurs Linux et vérifient le comportement au moyen de commandes CLI, du démarrage du Gateway, de sondes HTTP, de l’état RPC et de l’état du système de fichiers.

Utilisez des parcours ciblés pendant les itérations :

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

Parcours importants :

• test:docker:plugins couvre les tests de fumée d’installation des plugins, les installations depuis un dossier local, le comportement d’omission des mises à jour de dossiers locaux, les dossiers locaux avec des dépendances préinstallées, les installations de paquets file:, les installations git avec exécution de la CLI, les mises à jour de références git mobiles, les installations depuis le registre npm avec des dépendances transitives remontées, les mises à jour npm sans effet, le rejet des métadonnées de paquet npm mal formées, les installations depuis un environnement de test ClawHub local et les mises à jour sans effet, le comportement de mise à jour de la place de marché, ainsi que l’activation et l’inspection du lot Claude. Définissez OPENCLAW_PLUGINS_E2E_CLAWHUB=0 pour conserver le bloc ClawHub hermétique et hors ligne.
• test:docker:plugin-lifecycle-matrix installe le paquet candidat dans un conteneur minimal, puis soumet un plugin npm à l’installation, à l’inspection, à la désactivation, à l’activation, à une mise à niveau explicite, à une rétrogradation explicite et à la désinstallation après suppression du code du plugin. Il journalise les métriques RSS et CPU pour chaque phase.
• test:docker:plugin-update vérifie qu’un plugin installé inchangé n’est ni réinstallé ni privé de ses métadonnées d’installation pendant openclaw plugins update.
• test:docker:upgrade-survivor installe l’archive tar candidate sur un environnement de test représentant un ancien utilisateur avec un état non nettoyé, exécute la mise à jour du paquet puis doctor en mode non interactif, démarre ensuite un Gateway en local loopback et vérifie la conservation de l’état.
• test:docker:published-upgrade-survivor installe d’abord une version de référence publiée, la configure à l’aide d’une recette intégrée utilisant openclaw config set, la met à jour vers l’archive tar candidate, exécute doctor, vérifie le nettoyage des éléments hérités, démarre le Gateway et sonde /healthz, /readyz ainsi que l’état RPC.
• test:docker:update-restart-auth installe le paquet candidat, démarre un Gateway géré avec authentification par jeton, retire de l’environnement l’authentification du Gateway appelant pour openclaw update --yes --json et exige que la commande de mise à jour candidate redémarre le Gateway avant les sondes habituelles.
• test:docker:update-migration est le parcours de mise à jour publiée axé sur le nettoyage. Il part d’un état utilisateur configuré dans le style de Discord/Telegram, exécute le doctor de référence afin que les dépendances des plugins configurés puissent être matérialisées, injecte des résidus hérités de dépendances de plugin pour un plugin empaqueté configuré, effectue la mise à jour vers l’archive tar candidate et exige que le doctor exécuté après la mise à jour supprime les racines de dépendances héritées.

Variantes utiles du parcours de survie aux mises à jour publiées :

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

Scénarios disponibles : 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 et versioned-runtime-deps. Lors des exécutions agrégées, OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues (alias far-reaching) développe la sélection pour inclure tous les scénarios, y compris la migration d’installation des plugins configurés.

La migration complète des mises à jour est intentionnellement séparée de la CI complète de publication. Utilisez le workflow manuel Update Migration lorsque la question liée à la publication est : « chaque version stable publiée depuis la version 2026.4.23 peut-elle être mise à jour vers ce candidat et nettoyer les résidus de dépendances de plugins ? » :

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

Acceptation des paquets

L’acceptation des paquets est le contrôle de paquet natif de GitHub. Elle résout un paquet candidat en une archive tar package-under-test, enregistre sa version et son SHA-256, puis exécute des parcours E2E Docker réutilisables sur cette archive tar exacte. La référence du harnais de workflow est distincte de la référence source du paquet, afin que la logique de test actuelle puisse valider d’anciennes versions de confiance.

Sources candidates :

• source=npm : valide openclaw@extended-stable, openclaw@beta, openclaw@latest ou une version publiée précise.
• source=ref : empaquette une branche, une étiquette ou un commit de confiance avec le harnais actuel sélectionné.
• source=url : valide une archive tar HTTPS publique avec le paramètre package_sha256 obligatoire. Ce chemin rejette les identifiants intégrés aux URL, les ports HTTPS non standards, les noms d’hôtes ou résultats DNS/IP privés ou internes, les plages d’adresses IP à usage spécial et les redirections non sûres.
• source=trusted-url : valide une archive tar HTTPS avec les paramètres package_sha256 et trusted_source_id obligatoires selon la politique détenue par les responsables dans .github/package-trusted-sources.json. Utilisez cette option pour les miroirs privés ou d’entreprise au lieu d’affaiblir source=url avec un commutateur d’entrée autorisant les sources privées. Lorsqu’elle est configurée par la politique, l’authentification par jeton Bearer utilise le secret fixe OPENCLAW_TRUSTED_PACKAGE_TOKEN.
• source=artifact : réutilise une archive tar téléversée par une autre exécution d’Actions.

La validation complète de publication utilise source=artifact par défaut, généré à partir du SHA de publication résolu. Pour une validation postérieure à la publication, transmettez package_acceptance_package_spec=openclaw@YYYY.M.PATCH afin que la même matrice de mise à niveau cible plutôt le paquet npm publié.

Les vérifications de publication appellent l’acceptation des paquets avec l’ensemble de parcours de paquet, mise à jour, redémarrage et plugin :

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

Lorsque la période d’observation de la publication est activée (forcée pour release_profile=stable et full), elles transmettent également :

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

Cela permet de valider la migration des paquets, le changement de canal de mise à jour, la tolérance aux plugins gérés corrompus, le nettoyage des dépendances de plugins obsolètes, la couverture hors ligne des plugins, le comportement de mise à jour des plugins et l’assurance qualité du paquet Telegram sur le même artefact résolu, sans obliger le contrôle de paquet de publication par défaut à parcourir toutes les versions publiées.

last-stable-4 désigne les quatre dernières versions stables d’OpenClaw publiées sur npm. L’acceptation du paquet de publication épingle 2026.4.23 comme première limite de compatibilité des mises à jour de plugins, 2026.5.2 comme limite marquant une période de remaniement de l’architecture des plugins et 2026.4.15 comme ancienne référence de mise à jour publiée de la série 2026.4.1x ; le résolveur déduplique les versions épinglées déjà présentes parmi les quatre plus récentes. Pour une couverture exhaustive des migrations de mises à jour publiées, utilisez all-since-2026.4.23 dans le workflow séparé Update Migration plutôt que dans la CI complète de publication. release-history reste disponible pour un échantillonnage manuel plus large lorsque vous souhaitez également inclure l’ancien point d’ancrage antérieur à cette date.

Lorsque plusieurs références de survie aux mises à jour publiées sont sélectionnées, le workflow Docker réutilisable répartit chaque référence dans sa propre tâche d’exécution ciblée. Chaque partition de référence exécute toujours l’ensemble de scénarios sélectionné, mais les journaux et les artefacts restent propres à chaque référence et la durée totale est limitée par la partition la plus lente plutôt que par une unique tâche séquentielle volumineuse.

Exécutez manuellement un profil de paquet lors de la validation d’un candidat avant sa publication :

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

Pour une version canari étendue stable publiée, définissez package_spec=openclaw@extended-stable. L’acceptation des paquets résout ce sélecteur en une archive tar exacte avant l’exécution des parcours Docker.

Utilisez suite_profile=product lorsque les critères de publication incluent les canaux MCP, le nettoyage de Cron et des sous-agents, la recherche web OpenAI ou OpenWebUI. Utilisez suite_profile=full uniquement lorsqu’une couverture complète des chemins de publication Docker est nécessaire.

Valeurs par défaut de publication

Pour les versions candidates, la pile de validation par défaut est la suivante :

1. pnpm check:changed et pnpm test:changed pour les régressions au niveau du code source.
2. pnpm release:check pour l’intégrité de l’artefact du paquet.
3. Le profil package de l’acceptation des paquets ou les parcours personnalisés de paquet des vérifications de publication pour les contrats d’installation, de mise à jour, de redémarrage et de plugins.
4. Les vérifications de publication multiplateformes pour le programme d’installation, l’intégration initiale et le comportement propre à chaque système d’exploitation.
5. Les suites en direct uniquement lorsque la surface modifiée concerne le comportement d’un fournisseur ou d’un service hébergé.

Sur les machines des responsables, les contrôles larges et les validations produit Docker ou de paquet doivent s’exécuter dans Testbox, sauf si une validation locale est explicitement effectuée.

Compatibilité héritée

La tolérance de compatibilité est limitée et temporaire :

• Les paquets jusqu’à 2026.4.25, y compris 2026.4.25-beta.*, peuvent tolérer les lacunes de métadonnées de paquet déjà publiées dans l’acceptation des paquets.
• Le paquet publié 2026.4.26 peut émettre un avertissement pour les fichiers d’horodatage des métadonnées de compilation locale déjà publiés.
• Les paquets ultérieurs doivent respecter les contrats modernes. Les mêmes lacunes provoquent un échec au lieu d’un avertissement ou d’une omission.

N’ajoutez pas de nouvelles migrations au démarrage pour ces anciennes structures. Ajoutez ou étendez une réparation dans doctor, puis validez-la avec upgrade-survivor, published-upgrade-survivor ou update-restart-auth lorsque la commande de mise à jour est responsable du redémarrage.

Ajout de couverture

Lorsque vous modifiez le comportement des mises à jour ou des plugins, ajoutez une couverture au niveau le plus bas susceptible d’échouer pour la bonne raison :

• Logique pure de chemin ou de métadonnées : test unitaire à côté de la source.
• Inventaire du paquet ou comportement des fichiers empaquetés : test de vérification package-dist-inventory ou de l’archive tar.
• Comportement d’installation/de mise à jour de la CLI : assertion ou fixture du scénario Docker.
• Comportement de migration d’une version publiée : scénario published-upgrade-survivor.
• Comportement de redémarrage géré par la mise à jour : update-restart-auth.
• Comportement de la source du registre/paquet : fixture test:docker:plugins ou serveur de fixtures ClawHub.
• Comportement de la disposition ou du nettoyage des dépendances : vérifiez à la fois l’exécution à l’exécution et la limite du système de fichiers. Les dépendances npm peuvent être remontées dans le projet npm géré du Plugin ; les tests doivent donc prouver que ce projet est analysé/nettoyé, au lieu de supposer que seule l’arborescence node_modules locale au paquet du Plugin l’est.

Conservez par défaut les nouvelles fixtures Docker hermétiques. Utilisez des registres de fixtures locaux et de faux paquets, sauf si le test porte précisément sur le comportement d’un registre réel.

Triage des échecs

Commencez par l’identité de l’artefact :

• Résumé resolve_package de l’acceptation du paquet : source, version, SHA-256 et nom de l’artefact.
• Artefacts Docker : .artifacts/docker-tests/**/summary.json, failures.json, journaux des scénarios et commandes de réexécution.
• Résumé de la survie à la mise à niveau : .artifacts/upgrade-survivor/summary.json, notamment la version de référence, la version candidate, le scénario, les durées des phases et la couverture des recettes de configuration.

Préférez réexécuter exactement le scénario ayant échoué avec le même artefact de paquet plutôt que l’ensemble global des tests de publication.