Test: aggiornamenti e plugin

Checklist per la convalida di aggiornamenti e plugin: dimostrare che il pacchetto installabile può aggiornare lo stato reale dell'utente, riparare lo stato legacy obsoleto tramite doctor e continuare a installare, caricare, aggiornare e disinstallare plugin da ogni origine supportata.

Per la panoramica generale degli strumenti di esecuzione dei test, vedere Test. Per le chiavi dei provider live e le suite che accedono alla rete, vedere Test live.

Cosa proteggiamo

• Un tarball del pacchetto è completo, dispone di un file dist/postinstall-inventory.json valido e non dipende da file del repository non inclusi nel pacchetto.
• Un utente può passare da un pacchetto pubblicato meno recente al pacchetto candidato senza perdere configurazione, agenti, sessioni, aree di lavoro, elenchi di plugin consentiti o configurazione dei canali.
• openclaw doctor --fix --non-interactive gestisce i percorsi di pulizia e riparazione legacy. L'avvio non deve introdurre migrazioni di compatibilità nascoste per lo stato obsoleto dei plugin.
• Le installazioni dei plugin funzionano da directory locali, repository git, pacchetti npm e dal percorso del registro ClawHub.
• Le dipendenze npm dei plugin vengono installate in un singolo progetto npm gestito per ogni plugin, sottoposte a scansione prima di essere considerate attendibili e rimosse tramite npm uninstall durante la disinstallazione del plugin, affinché le dipendenze elevate di livello non rimangano presenti.
• L'aggiornamento dei plugin non esegue alcuna operazione quando non è cambiato nulla: record di installazione, origine risolta, struttura delle dipendenze installate e stato di abilitazione rimangono invariati.

Verifica locale durante lo sviluppo

Iniziare con controlli mirati:

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

Per modifiche all'installazione, alla disinstallazione, alle dipendenze o all'inventario del pacchetto dei plugin, eseguire anche i test mirati che coprono il punto di integrazione modificato:

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

Prima che qualsiasi percorso Docker del pacchetto utilizzi un tarball, verificare l'artefatto del pacchetto:

pnpm release:check

release:check esegue i controlli di divergenza di configurazione/documentazione/API (schema di configurazione, baseline della documentazione di configurazione, baseline ed esportazioni dell'API SDK dei plugin, versioni/inventario dei plugin), scrive l'inventario della distribuzione del pacchetto, esegue npm pack --dry-run, rifiuta i file vietati inclusi nel pacchetto, installa il tarball in un prefisso temporaneo, esegue il post-installazione e verifica sommariamente i punti di ingresso dei canali inclusi.

Percorsi Docker

I percorsi Docker costituiscono la verifica a livello di prodotto. Installano o aggiornano un pacchetto reale all'interno di container Linux e verificano il comportamento tramite comandi CLI, avvio del Gateway, sonde HTTP, stato RPC e stato del file system.

Durante le iterazioni, utilizzare percorsi mirati:

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

Percorsi importanti:

• test:docker:plugins copre la verifica preliminare dell'installazione dei plugin, le installazioni da cartelle locali, il comportamento di esclusione dell'aggiornamento per le cartelle locali, le cartelle locali con dipendenze preinstallate, le installazioni di pacchetti file:, le installazioni git con esecuzione della CLI, gli aggiornamenti git dei riferimenti mobili, le installazioni dal registro npm con dipendenze transitive elevate di livello, gli aggiornamenti npm senza operazioni, il rifiuto dei metadati non validi dei pacchetti npm, le installazioni da fixture ClawHub locale e gli aggiornamenti senza operazioni, il comportamento degli aggiornamenti del marketplace e l'abilitazione/ispezione del bundle Claude. Impostare OPENCLAW_PLUGINS_E2E_CLAWHUB=0 per mantenere il blocco ClawHub ermetico/offline.
• test:docker:plugin-lifecycle-matrix installa il pacchetto candidato in un container vuoto ed esegue per un plugin npm le operazioni di installazione, ispezione, disabilitazione, abilitazione, aggiornamento esplicito, downgrade esplicito e disinstallazione dopo l'eliminazione del codice del plugin. Registra le metriche RSS e CPU per ogni fase.
• test:docker:plugin-update verifica che un plugin installato e invariato non venga reinstallato e non perda i metadati di installazione durante openclaw plugins update.
• test:docker:upgrade-survivor installa il tarball candidato su una fixture di un vecchio utente con stato non pulito, esegue l'aggiornamento del pacchetto insieme a doctor non interattivo, quindi avvia un Gateway local loopback e verifica la conservazione dello stato.
• test:docker:published-upgrade-survivor installa prima una baseline pubblicata, la configura tramite una procedura openclaw config set incorporata, la aggiorna al tarball candidato, esegue doctor, verifica la pulizia legacy, avvia il Gateway e interroga /healthz, /readyz e lo stato RPC.
• test:docker:update-restart-auth installa il pacchetto candidato, avvia un Gateway gestito con autenticazione tramite token, rimuove dall'ambiente l'autenticazione del Gateway del chiamante per openclaw update --yes --json e richiede che il comando di aggiornamento candidato riavvii il Gateway prima delle normali sonde.
• test:docker:update-migration è il percorso di aggiornamento pubblicato con pulizia intensiva. Parte da uno stato utente configurato in stile Discord/Telegram, esegue doctor sulla baseline affinché le dipendenze dei plugin configurati possano essere materializzate, inserisce residui legacy delle dipendenze dei plugin per un plugin distribuito e configurato, esegue l'aggiornamento al tarball candidato e richiede che doctor, dopo l'aggiornamento, rimuova le radici delle dipendenze legacy.

Varianti utili del percorso di sopravvivenza agli aggiornamenti pubblicati:

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

Scenari disponibili: 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 e versioned-runtime-deps. Nelle esecuzioni aggregate, OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues (alias far-reaching) si espande a tutti gli scenari, inclusa la migrazione dell'installazione dei plugin configurati.

La migrazione completa degli aggiornamenti è intenzionalmente separata dalla CI completa di rilascio. Utilizzare il workflow manuale Update Migration quando la domanda relativa al rilascio è: «ogni versione stabile pubblicata a partire dalla 2026.4.23 può aggiornarsi a questo candidato e ripulire i residui delle dipendenze dei plugin?»:

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

Accettazione del pacchetto

L'accettazione del pacchetto è il controllo del pacchetto nativo di GitHub. Risolve un pacchetto candidato in un tarball package-under-test, ne registra la versione e il valore SHA-256, quindi esegue percorsi E2E Docker riutilizzabili su quel tarball esatto. Il riferimento dell'infrastruttura del workflow è separato dal riferimento dell'origine del pacchetto, quindi la logica di test corrente può convalidare versioni attendibili meno recenti.

Origini candidate:

• source=npm: convalida openclaw@extended-stable, openclaw@beta, openclaw@latest o una versione pubblicata esatta.
• source=ref: crea il pacchetto da un ramo, tag o commit attendibile con l'infrastruttura corrente selezionata.
• source=url: convalida un tarball HTTPS pubblico con package_sha256 obbligatorio. Questo percorso rifiuta credenziali negli URL, porte HTTPS non predefinite, nomi host o risultati DNS/IP privati/interni, spazi di indirizzi IP per usi speciali e reindirizzamenti non sicuri.
• source=trusted-url: convalida un tarball HTTPS con package_sha256 e trusted_source_id obbligatori secondo la policy gestita dai manutentori in .github/package-trusted-sources.json. Utilizzare questa opzione per mirror aziendali/privati invece di indebolire source=url con un'opzione di input che consenta risorse private. L'autenticazione bearer, quando configurata dalla policy, utilizza il secret fisso OPENCLAW_TRUSTED_PACKAGE_TOKEN.
• source=artifact: riutilizza un tarball caricato da un'altra esecuzione di Actions.

La convalida completa del rilascio utilizza source=artifact per impostazione predefinita, generato dallo SHA del rilascio risolto. Per la verifica successiva alla pubblicazione, passare package_acceptance_package_spec=openclaw@YYYY.M.PATCH, affinché la stessa matrice di aggiornamento utilizzi invece il pacchetto npm distribuito.

I controlli di rilascio invocano l'accettazione del pacchetto con l'insieme pacchetto/aggiornamento/riavvio/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

Quando il collaudo prolungato del rilascio è abilitato (obbligatorio per release_profile=stable e full), passano anche:

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

Ciò mantiene la migrazione del pacchetto, il cambio del canale di aggiornamento, la tolleranza dei plugin gestiti danneggiati, la pulizia delle dipendenze obsolete dei plugin, la copertura offline dei plugin, il comportamento di aggiornamento dei plugin e la QA del pacchetto Telegram sullo stesso artefatto risolto, senza obbligare il controllo predefinito del pacchetto di rilascio a esaminare ogni versione pubblicata.

last-stable-4 viene risolto nelle quattro versioni stabili più recenti di OpenClaw pubblicate su npm. L'accettazione del pacchetto di rilascio fissa 2026.4.23 come primo limite di compatibilità degli aggiornamenti dei plugin, 2026.5.2 come limite per le modifiche sostanziali all'architettura dei plugin e 2026.4.15 come baseline precedente per gli aggiornamenti pubblicati della serie 2026.4.1x; il risolutore elimina i duplicati delle versioni fissate già incluse nelle quattro più recenti. Per una copertura esaustiva della migrazione degli aggiornamenti pubblicati, utilizzare all-since-2026.4.23 nel workflow separato Update Migration invece della CI completa di rilascio. release-history resta disponibile per un campionamento manuale più ampio quando si desidera includere anche il riferimento legacy precedente alla data.

Quando vengono selezionate più baseline per la sopravvivenza agli aggiornamenti pubblicati, il workflow Docker riutilizzabile suddivide ogni baseline in un processo di esecuzione mirato separato. Ogni partizione della baseline esegue comunque l'insieme di scenari selezionato, ma log e artefatti rimangono separati per baseline e la durata complessiva è limitata dalla partizione più lenta, anziché da un unico grande processo seriale.

Eseguire manualmente un profilo del pacchetto durante la convalida di un candidato prima del rilascio:

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

Per un canary extended-stable pubblicato, impostare package_spec=openclaw@extended-stable. L'accettazione del pacchetto risolve tale selettore in un tarball esatto prima dell'esecuzione dei percorsi Docker.

Utilizzare suite_profile=product quando la domanda relativa al rilascio include canali MCP, pulizia di cron/sottoagenti, ricerca web OpenAI o OpenWebUI. Utilizzare suite_profile=full solo quando è necessaria la copertura completa del percorso di rilascio Docker.

Impostazione predefinita del rilascio

Per i candidati al rilascio, la sequenza di verifica predefinita è:

1. pnpm check:changed e pnpm test:changed per le regressioni a livello di sorgente.
2. pnpm release:check per l'integrità dell'artefatto del pacchetto.
3. Il profilo package dell'accettazione del pacchetto o i percorsi personalizzati del pacchetto per il controllo del rilascio, per verificare i contratti di installazione/aggiornamento/riavvio/plugin.
4. Controlli di rilascio multipiattaforma per il programma di installazione specifico del sistema operativo, l'onboarding e il comportamento della piattaforma.
5. Suite live solo quando la superficie modificata riguarda il comportamento del provider o del servizio ospitato.

Sui computer dei manutentori, i controlli estesi e la verifica del prodotto Docker/pacchetto devono essere eseguiti in Testbox, salvo quando si esegue esplicitamente una verifica locale.

Compatibilità legacy

La tolleranza di compatibilità è limitata e vincolata nel tempo:

• I pacchetti fino alla versione 2026.4.25, inclusi quelli 2026.4.25-beta.*, possono tollerare lacune nei metadati del pacchetto già distribuite nell'accettazione del pacchetto.
• Il pacchetto 2026.4.26 pubblicato può generare avvisi per file di marcatura dei metadati della build locale già distribuiti.
• I pacchetti successivi devono soddisfare i contratti moderni. Le stesse lacune causano un errore anziché un avviso o un'esclusione.

Non aggiungere nuove migrazioni all'avvio per questi formati obsoleti. Aggiungere o estendere una riparazione di doctor, quindi verificarla con upgrade-survivor, published-upgrade-survivor o update-restart-auth quando il comando di aggiornamento è responsabile del riavvio.

Aggiunta della copertura

Quando si modifica il comportamento degli aggiornamenti o dei plugin, aggiungere la copertura al livello più basso che può produrre un errore per il motivo corretto:

• Logica pura relativa a percorsi o metadati: test unitario accanto al sorgente.
• Inventario del pacchetto o comportamento dei file impacchettati: test di verifica package-dist-inventory o del tarball.
• Comportamento di installazione/aggiornamento della CLI: asserzione o fixture della corsia Docker.
• Comportamento della migrazione delle versioni pubblicate: scenario published-upgrade-survivor.
• Comportamento di riavvio gestito dall'aggiornamento: update-restart-auth.
• Comportamento dell'origine del registro/pacchetto: fixture test:docker:plugins o server di fixture ClawHub.
• Layout delle dipendenze o comportamento di pulizia: verificare sia l'esecuzione in fase di runtime sia il confine del filesystem. Le dipendenze npm possono essere sollevate all'interno del progetto npm gestito del plugin, quindi i test devono dimostrare che tale progetto viene analizzato/ripulito, anziché presupporre esclusivamente l'albero node_modules locale del pacchetto del plugin.

Per impostazione predefinita, mantenere ermetiche le nuove fixture Docker. Utilizzare registri di fixture locali e pacchetti fittizi, a meno che lo scopo del test non sia verificare il comportamento del registro in tempo reale.

Analisi degli errori

Iniziare dall'identità dell'artefatto:

• Riepilogo resolve_package di Package Acceptance: origine, versione, SHA-256 e nome dell'artefatto.
• Artefatti Docker: .artifacts/docker-tests/**/summary.json, failures.json, log delle corsie e comandi di riesecuzione.
• Riepilogo della sopravvivenza all'aggiornamento: .artifacts/upgrade-survivor/summary.json, inclusi versione di riferimento, versione candidata, scenario, tempi delle fasi e copertura delle procedure di configurazione.

Preferire la riesecuzione dell'esatta corsia non riuscita con lo stesso artefatto del pacchetto, anziché rieseguire l'intero insieme di test della versione.