Testare un Claude Code Mod senza login o chiamate al modello

Puoi testare un Claude Code Mod senza sessione, login o rete attraverso claude plugin test e il kit claude-code/testing. Il test invia eventi al plugin, sostituisce le risposte esterne con stub e controlla il risultato. È una verifica del comportamento del componente, non una valutazione della qualità di Claude. Guida ufficiale ai test Mods.

Le fonti sono verificate il 9 ottobre 2026. In questa guida i casi sono progettati, senza risultati di suite inventati. Il percorso parte da due funzioni piccole: un contatore e un lookup ticket read-only. Per la struttura del pacchetto leggi creare il primo mod TypeScript; per l’integrazione vedi comandi e tool della Mods API.

Cosa verifica validate e cosa verifica plugin test?

claude plugin validate controlla il manifest e l’analisi statica del modulo. Può scoprire un evento sconosciuto, un collegamento mancante o una forma che il caricatore non riconosce. La modalità stretta considera anche i warning secondo la reference. Questo aiuta a sapere cosa Claude Code leggerà dal pacchetto, prima di attribuire un errore alla sessione. Reference dei comandi plugin.

Un test verifica invece una promessa: dato un input noto, quale risultato produce la funzione? Un comando può essere registrato correttamente e mostrare un valore sbagliato. Un tool può avere uno schema valido e confondere un record assente con un errore di rete. Sono problemi che richiedono aspettative sul comportamento, non soltanto una confezione leggibile.

La sequenza ragionevole è validare, testare il contratto e poi provare le superfici interessate. Non serve una chiamata al modello per dimostrare che un contatore conta due eventi sintetici. Serve invece un’altra valutazione se la domanda è «Claude sceglie questo tool quando è opportuno?». Il confine deve essere esplicito nel report.

Come scegliere casi utili invece di testare ogni riga?

Parti dal comportamento promesso, non dall’implementazione. Per un contatore chiedi se aumenta con l’evento corretto, ignora eventi estranei e riparte o conserva il valore secondo il requisito. Per un lookup chiedi se restituisce i campi previsti, distingue record assente e errore e impedisce di esporre dati non autorizzati.

Un test che ripete esattamente la struttura interna può passare anche quando cambia ciò che l’utente osserva. Il caso deve quindi usare un ingresso del componente e verificare un risultato riconoscibile. Se il requisito è mostrare «chiamate osservate», l’aspettativa deve controllare quel significato, non la presenza di una variabile chiamata count.

Scrivi anche una prova negativa prima di concludere il lavoro. La funzione deve sapere cosa fare quando manca un campo, quando la fonte non risponde o quando l’utente annulla. Non tutti gli errori devono essere bloccanti, ma ogni risultato deve essere interpretabile. La guida alla review del codice aiuta a collegare queste aspettative alla decisione del reviewer.

Fixture e stub: qual è la differenza pratica?

Una fixture è il dato preparato per la prova: ticket fittizio, evento o risposta attesa. Uno stub è il comportamento controllato che risponde al posto di una dipendenza. Puoi avere una fixture valida ma uno stub sbagliato, che restituisce una forma impossibile nel sistema reale. Il test passerebbe su una finzione troppo comoda.

Nel lookup progettato prepara, per esempio, un record con identificativo sintetico, titolo tecnico e stato. Poi prepara l’assenza del record e una risposta di errore. La fixture non deve usare dati clienti copiati «per realismo»: il suo scopo è rappresentare il contratto. AI e sicurezza dei dati spiega perché anche il materiale di test merita un confine definito.

Gli stub devono rispettare le risposte documentate delle API usate dal mod. Il $ del kit di test invia eventi e non coincide con l’API ricevuta dal codice del mod. La guida ufficiale distingue queste due responsabilità. Prima di scrivere una simulazione verifica quindi quale lato del contratto stai sostituendo.

Quali risultati dovrebbe controllare il test positivo?

Per il contatore usa una sequenza nota, poi richiama il comando e controlla il valore. Decidi prima se un tentativo rifiutato conta: non lasciare che sia il codice scritto per primo a fissare il requisito. Un numero ha significato soltanto quando la definizione di ciò che conta è stabile.

Per il lookup positivo controlla input, campi restituiti e assenza di effetti di scrittura. Il risultato deve essere coerente con la fonte simulata, senza arricchimenti inventati. Se il tool legge solo titolo e stato, un test che accetta una lunga sintesi libera nasconde un allargamento della promessa. Meglio un contratto piccolo e verificabile.

Il caso può includere anche il dato temporale quando serve. Se la funzione dichiara «stato attuale», deve chiarire quando il dato viene letto o quale cache usa. Una fixture senza questo aspetto non prova la freschezza del risultato. Non introdurre però un clock in ogni test: usalo quando il tempo modifica davvero il comportamento.

Come progettare errore, ritardo e annullamento?

La prova d’errore deve descrivere un esito che il responsabile può riconoscere. Per la consultazione, servizio indisponibile e record non trovato sono differenti. Per una UI di decisione, rifiuto dell’utente e errore del componente possono richiedere messaggi diversi. Non usare un generico «ok» per ogni ramo soltanto per far passare la suite.

Il ritardo serve quando il tempo è parte del requisito. La documentazione offre un clock controllato attraverso mock.clock(on): il test avanza il tempo senza attendere la durata reale. Puoi verificare che un messaggio non appaia prima della scadenza e che arrivi una volta quando deve. È un controllo della sequenza, non un benchmark di prestazioni. Test dei timer.

Per l’annullamento verifica ciò che non deve avvenire. Un pulsante Annulla non è corretto soltanto perché mostra una scritta: il percorso successivo deve rispettare il rifiuto. Una prova utile osserva risultato e chiamate consentite. Se il componente tratta operazioni delicate, isola completamente il caso con stub e dati sintetici.

Un piano di prova per un lookup read-only

Successo: restituisce i campi previsti del ticket sintetico. Assenza: dichiara che il record non esiste. Errore: comunica che il dato non è stato verificato. Accesso negato: non rivela il record. Input invalido: non chiama la fonte. Ritardo, se rilevante: non produce un successo anticipato. Nessun caso deve avviare una scrittura.

Come verificare la UI su terminale e desktop?

Il kit permette di montare un punto della UI, trovare elementi e interagire con pulsanti o campi. La superficie va scelta esplicitamente quando il progetto ne supporta più di una. Un componente leggibile sul terminale non va considerato automaticamente identico nel desktop. La guida ai test della UI mostra il principio.

Non copiare però un caso desktop per una demo che dichiara soltanto il terminale. La matrice delle prove deve seguire il contratto del plugin. Per un indicatore come Token Weather, cadenza e dati contano; per una vista come Replay Theater, navigazione e interpretazione dei passaggi sono parte del requisito.

Il test dell’interazione può dimostrare che un pulsante aggiorna un valore, ma la prova reale deve ancora controllare leggibilità, spazio e messaggi. Conserva una distinzione nel report: comportamento simulato e osservazione sulla superficie. Così un difetto di layout non viene nascosto da una suite che verifica soltanto il valore interno.

Come leggere il risultato della suite senza inventare una verifica?

Un file .test.ts o .test.tsx deve dichiarare test reali. La documentazione specifica che un file senza test() fallisce: non basta avere una cartella chiamata tests. Il comando restituisce un errore quando una prova fallisce. Nel report conserva nome del caso ed esito, evitando di pubblicare una schermata di esempio come risultato della tua esecuzione.

I comandi da considerare nel percorso sono distinti:

claude plugin validate ./mod-esaminato --strict
claude plugin test ./mod-esaminato

mod-esaminato è un placeholder di directory. Questi comandi non sono stati eseguiti per produrre un plugin cliente in questa guida. Prima di lanciarli sul tuo pacchetto devi averne esaminato il codice e il contesto. Test senza rete non significa che qualsiasi file esterno sia affidabile o che tu debba eseguirlo alla cieca.

Due scenari ipotetici di verifica per una PMI

Esempio ipotetico: una software house di Lecce mantiene un comando di riepilogo. Il team definisce una fixture con eventi noti e verifica il risultato senza chiamare il modello. Un errore nel conteggio viene riprodotto con un caso piccolo. La correzione modifica il comportamento e il test continua a controllare l’ingresso pubblico, senza dipendere dal nome delle variabili interne.

Prima della distribuzione il responsabile prova il comando nella superficie adottata e annota la versione di Claude Code. La suite non viene venduta come prova di maggiore produttività: dimostra il contratto dei casi eseguiti. Se la funzione cambia significato, anche la descrizione e le aspettative vengono aggiornate.

Esempio ipotetico: una PMI di Trento prepara un lookup ticket. Il team usa dati sintetici per successo, assenza e accesso negato. La prova controlla che il messaggio d’errore non riveli configurazioni interne. Soltanto dopo il contratto viene collegato al servizio autorizzato in un ambiente di prova, con una verifica separata dell’integrazione.

Quando un collega non riesce a caricare il plugin, il gruppo non riscrive i test per farli passare sulla sua macchina. Confronta versione, policy e messaggio di rifiuto attraverso la diagnosi dei Mods. Un problema di disponibilità non è necessariamente un errore nella funzione verificata.

Quali test inutili o mancanti indeboliscono il progetto?

Il primo errore è testare soltanto che una funzione esiste. Il secondo è usare uno stub che risponde sempre con successo. Il terzo è controllare il testo di un pulsante senza verificare il risultato della sua azione. Il quarto è ignorare stato e reload quando sono parte del requisito. Il quinto è dichiarare «tutto verificato» da un unico caso positivo.

Evita anche suite enormi che ripetono l’implementazione senza coprire nuove conseguenze. Ogni caso dovrebbe proteggere un contratto importante o un difetto riproducibile. Se una modifica di copy non altera il comportamento, non serve costruire un’infrastruttura di test sproporzionata. Il minimo insieme significativo resta più facile da mantenere e da capire.

Quale prova aggiungere dopo aver trovato un bug?

Prima conserva il caso minimo che lo riproduce. Il nuovo test deve fallire con il comportamento difettoso e passare con la correzione, controllando il contratto osservabile. Se passa già prima del cambiamento, non dimostra di proteggere quel problema. Usa una fixture piccola e un’aspettativa precisa, evitando di copiare un intero transcript.

Annota perché il caso esiste e quale conseguenza evita. Questa nota aiuta chi modificherà il plugin a mantenere il significato del test. Non occorre duplicare ogni ramo interno: basta proteggere l’errore riproducibile e i confini che la correzione può avere alterato.

Come rendere i test parte della distribuzione?

Assegna un responsabile al contratto e conserva fixture, versione e casi nel progetto del plugin. Prima di pubblicare un cambiamento controlla ciò che quel cambiamento può alterare. Se cambia lo schema, prova input e output; se cambia la UI, prova l’interazione; se cambia la persistenza, prova il ciclo di vita. Una lista mirata rende il risultato reviewabile.

Per costruire una personalizzazione con prove comprensibili al team, una software house può preparare il pacchetto e il suo percorso di verifica. La guida ai Mods e quella alla Mods API aiutano a mantenere il progetto piccolo prima di aggiungere integrazioni e autorità nuove.