Test: aggiornamenti e Plugin

Questa è la checklist dedicata alla validazione degli aggiornamenti e dei plugin. L'obiettivo è semplice: dimostrare che il pacchetto installabile può aggiornare lo stato reale degli utenti, riparare lo stato legacy obsoleto tramite doctor e continuare a installare, caricare, aggiornare e disinstallare plugin dalle sorgenti supportate.

Per la mappa più ampia del test runner, consulta Test. Per le chiavi dei provider live e le suite che toccano la rete, consulta Test live.

# Cosa proteggiamo

I test di aggiornamento e dei plugin proteggono questi contratti:

• Un tarball del pacchetto è completo, ha un dist/postinstall-inventory.json valido e non dipende da file del repository non impacchettati.
• Un utente può passare da un pacchetto pubblicato precedente al pacchetto candidato senza perdere configurazione, agenti, sessioni, workspace, allowlist dei plugin o configurazione dei canali.
• openclaw doctor --fix --non-interactive è responsabile dei percorsi di pulizia e riparazione legacy. L'avvio non dovrebbe accumulare 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 nella root npm gestita, scansionate prima dell'attendibilità e rimosse tramite npm durante la disinstallazione, così le dipendenze hoistate non restano in giro.
• L'aggiornamento dei plugin è stabile quando non è cambiato nulla: record di installazione, sorgente risolta, layout delle dipendenze installate e stato abilitato restano intatti.

# Prova locale durante lo sviluppo

Inizia in modo mirato:

pnpm changed:lanes --json
pnpm check:changed
pnpm test:changed

Per modifiche a installazione, disinstallazione, dipendenze o inventario dei pacchetti dei plugin, esegui anche i test mirati che coprono il punto 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 lane Docker del pacchetto consumi un tarball, verifica l'artefatto del pacchetto:

pnpm release:check

release:check esegue controlli di deriva su configurazione/docs/API, scrive l'inventario dist del pacchetto, esegue npm pack --dry-run, rifiuta file impacchettati vietati, installa il tarball in un prefisso temporaneo, esegue postinstall e fa smoke test degli entrypoint dei canali inclusi.

# Lane Docker

Le lane Docker sono la prova a livello di prodotto. Installano o aggiornano un pacchetto reale dentro container Linux e verificano il comportamento tramite comandi CLI, avvio del Gateway, probe HTTP, stato RPC e stato del filesystem.

Usa lane mirate durante l'iterazione:

pnpm test:docker:plugins
pnpm test:docker:plugin-lifecycle-matrix
pnpm test:docker:plugin-update
pnpm test:docker:upgrade-survivor
pnpm test:docker:published-upgrade-survivor
pnpm test:docker:update-restart-auth
pnpm test:docker:update-migration

Lane importanti:

• test:docker:plugins valida lo smoke test di installazione plugin, le installazioni da cartella locale, il comportamento di salto dell'aggiornamento per cartelle locali, le cartelle locali con dipendenze preinstallate, le installazioni di pacchetti file:, le installazioni git con esecuzione CLI, gli aggiornamenti di riferimenti git mobili, le installazioni da registro npm con dipendenze transitive hoistate, i no-op dell'aggiornamento npm, le installazioni da fixture ClawHub locale e i no-op di aggiornamento, il comportamento di aggiornamento del marketplace e l'abilitazione/ispezione del bundle Claude. Imposta OPENCLAW_PLUGINS_E2E_CLAWHUB=0 per mantenere il blocco ClawHub ermetico/offline.
• test:docker:plugin-lifecycle-matrix installa il pacchetto candidato in un container nudo, fa passare un plugin npm attraverso installazione, ispezione, disabilitazione, abilitazione, upgrade esplicito, downgrade esplicito e disinstallazione dopo aver eliminato il codice del plugin. Registra metriche RSS e CPU per ogni fase.
• test:docker:plugin-update valida che un plugin installato invariato non venga reinstallato e non perda metadati di installazione durante openclaw plugins update.
• test:docker:upgrade-survivor installa il tarball candidato sopra una fixture sporca di un vecchio utente, esegue l'aggiornamento del pacchetto più doctor non interattivo, quindi avvia un Gateway loopback e controlla la conservazione dello stato.
• test:docker:published-upgrade-survivor installa prima una baseline pubblicata, la configura tramite una ricetta openclaw config set incorporata, la aggiorna al tarball candidato, esegue doctor, controlla la pulizia legacy, avvia il Gateway e sonda /healthz, /readyz e lo stato RPC.
• test:docker:update-restart-auth installa il pacchetto candidato, avvia un Gateway gestito con autenticazione token, rimuove dall'ambiente del chiamante l'autenticazione Gateway per openclaw update --yes --json e richiede che il comando di aggiornamento candidato riavvii il Gateway prima dei normali probe.
• test:docker:update-migration è la lane di aggiornamento pubblicato più intensa in termini di pulizia. Parte da uno stato utente configurato in stile Discord/Telegram, esegue doctor sulla baseline così le dipendenze dei plugin configurati hanno una possibilità di materializzarsi, semina residui legacy delle dipendenze di plugin per un plugin pacchettizzato configurato, aggiorna al tarball candidato e richiede che il doctor post-aggiornamento rimuova le root legacy delle dipendenze.

Varianti utili di published-upgrade survivor:

[email protected] \
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

Gli scenari disponibili sono base, feishu-channel, bootstrap-persona, 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 si espande a tutti gli scenari modellati sui problemi segnalati, inclusa la migrazione di installazione dei plugin configurati.

La migrazione completa degli aggiornamenti è intenzionalmente separata dalla CI Full Release. Usa il workflow manuale Update Migration quando la domanda di release è "ogni release stabile pubblicata dalla 2026.4.23 in poi 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

Accettazione del pacchetto è il gate pacchetto nativo di GitHub. Risolve un pacchetto candidato in un tarball package-under-test, registra versione e SHA-256, quindi esegue lane Docker E2E riutilizzabili contro esattamente quel tarball. Il ref dell'harness del workflow è separato dal ref della sorgente del pacchetto, quindi la logica di test corrente può validare release attendibili più vecchie.

Sorgenti candidate:

• source=npm: valida openclaw@beta, openclaw@latest o una versione pubblicata esatta.
• source=ref: impacchetta un branch, tag o commit attendibile con l'harness corrente selezionato.
• source=url: valida un tarball HTTPS con package_sha256 richiesto.
• source=artifact: riusa un tarball caricato da un'altra esecuzione di Actions.

Full Release Validation usa source=artifact per impostazione predefinita, costruito dallo SHA di release risolto. Per la prova post-pubblicazione, passa [email protected] così la stessa matrice di upgrade punta invece al pacchetto npm distribuito.

I controlli di release chiamano Accettazione del pacchetto con il set package/update/restart/plugin:

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

Quando il soak di release è abilitato, passano anche:

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

Questo mantiene migrazione del pacchetto, cambio del canale di aggiornamento, tolleranza ai managed-plugin corrotti, pulizia delle dipendenze obsolete dei plugin, copertura plugin offline, comportamento di aggiornamento dei plugin e QA del pacchetto Telegram sullo stesso artefatto risolto senza far percorrere al gate pacchetto di release predefinito ogni release pubblicata.

last-stable-4 si risolve nelle quattro release OpenClaw stabili più recenti pubblicate su npm. L'accettazione del pacchetto di release fissa 2026.4.23 come primo confine di compatibilità per l'aggiornamento dei plugin, 2026.5.2 come confine di churn dell'architettura dei plugin e 2026.4.15 come baseline di aggiornamento pubblicato più vecchia della serie 2026.4.1x; il resolver deduplica i pin che sono già nelle ultime quattro. Per una copertura esaustiva della migrazione degli aggiornamenti pubblicati, usa all-since-2026.4.23 nel workflow Update Migration separato invece della CI Full Release. release-history resta disponibile per un campionamento manuale più ampio quando vuoi anche l'ancora legacy precedente alla data.

Quando sono selezionate più baseline published-upgrade survivor, il workflow Docker riutilizzabile suddivide ogni baseline in un proprio job runner mirato. Ogni shard di baseline esegue comunque il set di scenari selezionato, ma log e artefatti restano per baseline e il tempo totale è limitato dallo shard più lento invece che da un grande job seriale.

Esegui manualmente un profilo pacchetto quando validi un candidato prima della release:

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

Usa suite_profile=product quando la domanda di release include canali MCP, pulizia cron/subagent, ricerca web OpenAI o OpenWebUI. Usa suite_profile=full solo quando hai bisogno della copertura Docker completa del percorso di release.

# Predefinito di release

Per i candidati di release, lo stack di prova predefinito è:

1. pnpm check:changed e pnpm test:changed per regressioni a livello sorgente.
2. pnpm release:check per l'integrità dell'artefatto del pacchetto.
3. Profilo package di Accettazione del pacchetto o lane pacchetto personalizzate di release-check per i contratti di installazione/aggiornamento/riavvio/plugin.
4. Controlli di release cross-OS per installer, onboarding e comportamento di piattaforma specifici del sistema operativo.
5. Suite live solo quando la superficie modificata tocca il comportamento di provider o servizi ospitati.

Sulle macchine dei maintainer, i gate ampi e la prova di prodotto Docker/pacchetto dovrebbero essere eseguiti in Testbox salvo prova locale esplicita.

# Compatibilità legacy

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

• I pacchetti fino a 2026.4.25, inclusi 2026.4.25-beta.*, possono tollerare lacune nei metadati del pacchetto già distribuite in Accettazione del pacchetto.
• Il pacchetto 2026.4.26 pubblicato può emettere un avviso per file di stamp dei metadati di build locali già distribuiti.
• I pacchetti successivi devono soddisfare i contratti moderni. Le stesse lacune falliscono invece di generare avvisi o venire saltate.

Non aggiungere nuove migrazioni all'avvio per queste vecchie forme. Aggiungi o estendi una riparazione doctor, quindi dimostrala con upgrade-survivor, published-upgrade-survivor o update-restart-auth quando il comando di aggiornamento è responsabile del riavvio.

# Aggiunta di copertura

Quando modifichi il comportamento di aggiornamento o dei plugin, aggiungi copertura al livello più basso che può fallire per il motivo corretto:

• Logica pura di percorso o metadati: unit test accanto al sorgente.
• Inventario del pacchetto o comportamento dei file impacchettati: test package-dist-inventory o del verificatore di tarball.
• Comportamento CLI di installazione/aggiornamento: asserzione o fixture di lane Docker.
• Comportamento di migrazione da release pubblicata: scenario published-upgrade-survivor.
• Comportamento di riavvio posseduto dall'aggiornamento: update-restart-auth.
• Comportamento di sorgente registro/pacchetto: fixture test:docker:plugins o server fixture ClawHub.
• Comportamento di layout o pulizia delle dipendenze: asserisci sia l'esecuzione runtime sia il confine del filesystem. Le dipendenze npm possono essere hoistate sotto la root npm gestita, quindi i test dovrebbero dimostrare che la root viene scansionata/pulita invece di assumere un albero node_modules locale al pacchetto.

Mantieni le nuove fixture Docker ermetiche per impostazione predefinita. Usa registri fixture locali e pacchetti finti salvo quando lo scopo del test è il comportamento live del registro.

# Triage dei fallimenti

Inizia dall'identità dell'artefatto:

• Riepilogo di Package Acceptance resolve_package: origine, versione, SHA-256 e nome dell'artefatto.
• Artefatti Docker: .artifacts/docker-tests/**/summary.json, failures.json, log delle lane e comandi di riesecuzione.
• Riepilogo dei superstiti dell'upgrade: .artifacts/upgrade-survivor/summary.json, inclusi versione di riferimento, versione candidata, scenario, tempi delle fasi e passaggi della ricetta.

Preferisci rieseguire la lane esatta non riuscita con lo stesso artefatto del pacchetto invece di rieseguire l'intero ombrello di release.