Test di API HTTP (.lnh)

File → Nuovo → Nuovo test API apre un client HTTP salvato in un file .lnh. Un file rappresenta un endpoint (metodo, URL, intestazioni e corpo) e conserva diversi test nell'elenco a sinistra — ogni test con i propri valori per le variabili {name} usate nell'URL, nelle intestazioni e nel corpo, oltre al risultato dell'ultima esecuzione (stato, tempo, data, intestazioni e corpo della risposta). Mostra anche il comando curl equivalente. La stessa operazione one-off è disponibile tramite CLI (http) e MCP (http_request). Il tester usa curl, già incluso in Windows 10 e 11; se manca, LightNote apre la guida all'installazione prima dell'invio.

Inviare e leggere la risposta

Ctrl+Invio invia la richiesta. Finché la risposta non torna, lo stesso pulsante diventa Interrompi (o Esc) e l'attesa mostra i secondi. Il badge della risposta riporta lo stato e il tempo; accanto ci sono il tipo, la dimensione e quando il test è stato eseguito. La riga curl segue ciò che digiti, già con le variabili del test selezionato: il pulsante accanto copia il comando, e la sua freccia offre lo stesso in PowerShell, Python, JavaScript, C# e HTTPie. Incollare un comando curl direttamente nell'URL importa metodo, intestazioni e corpo senza cancellare i test.

Una variabile senza valore nel test viene inviata letterale ({id} nell'URL, e il server risponde con un errore che non dice perché): la scheda Variabili la evidenzia e ne dice il nome. Il punto accanto a ogni test nell'elenco ha il colore dell'ultimo stato, e l'anello vuoto è un test non ancora eseguito. Nella risposta, la barra sopra il corpo formatta JSON/XML solo a schermo, manda a capo le righe, copia il corpo e lo salva in un file così com'è arrivato.

Comporre la richiesta. La scheda Parametri mostra la query dell’URL come elenco: modificare una riga cambia l’URL, e modificare l’URL cambia l’elenco. La scheda Autenticazione costruisce da sola l’intestazione — Basic, Bearer o Chiave API, in un’intestazione o nell’URL — e ogni campo accetta una {variable}, così il segreto vive nell’ambiente e non nel file; se la scheda Intestazioni ha già la stessa intestazione, vale quella. Nel Corpo, il Tipo sceglie JSON, XML, SOAP, modulo, multipart (campi di testo e file) o un file inviato in binario, e il Content-Type viene aggiunto quando non ne hai scritto uno. Un percorso di file relativo parte dalla cartella del .lnh. Con multipart o file, la freccia del pulsante di copia rende grigi PowerShell e JavaScript, che non sanno inviare quel corpo. La scheda Opzioni cambia il timeout (60 s per impostazione predefinita) e fa seguire i reindirizzamenti: senza, la risposta mostrata è il 3xx stesso. Aperto in una versione precedente di LightNote, il file parte senza l’autenticazione e senza il tipo, e mai come una richiesta diversa. Per un server locale con un certificato proprio, Non verificare il certificato (HTTPS) disattiva la verifica: finché è attiva, la riga della risposta dice certificato non verificato, e lnote http-run lo dice anche nel rapporto.

Leggere la risposta. Il corpo si apre in un editor di codice in sola lettura, evidenziato secondo il tipo della risposta, con la piegatura dei blocchi e la ricerca della finestra (Ctrl+F). La scheda Cookie elenca ciò che il server ha chiesto di salvare, e la Cronologia mostra la richiesta esatta che è partita — con le intestazioni aggiunte da curl — e le intestazioni grezze della risposta. La cronologia resta solo in memoria: ripete l’Authorization, e il file finisce in Git.

Verifiche

La scheda Verifiche dice se il test è superato. Ogni riga confronta una parte della risposta — lo stato, un'intestazione, il corpo intero, un percorso JSONPath ($.utente.id, $.elementi[0].nome, $.elementi.length()), un percorso XPath (//Prezzo, count(//Item)) o il tempo in millisecondi — con il valore atteso: uguale, diverso, maggiore, minore, contiene, corrisponde a un'espressione regolare, esiste o è di un tipo. In XPath il prefisso del nome viene ignorato, quindi soap:Envelope e Envelope sono lo stesso passo. Con le verifiche sono loro a decidere il risultato: un 404 atteso passa, e un 200 con il campo sbagliato fallisce. Il risultato di ognuna compare nell'ultima colonna, il riepilogo accanto al badge della risposta e il punto del test nell'elenco diventa verde o rosso. Deselezionare una riga la mantiene nel file senza contare nel risultato.

Il pulsante di riproduzione in cima all'elenco esegue tutti i test del file, uno alla volta, e dice quanti sono stati superati. Dopo che un test è stato eseguito due volte, il pulsante di confronto sopra il corpo della risposta apre l'esecuzione precedente e quella attuale affiancate, con il corpo formattato da entrambi i lati. Viene conservata solo l'esecuzione precedente: il file va in Git, e una cronologia lunga riempirebbe ogni diff.

Ambienti, catture e la cartella intera

Gli ambienti usano il formato aperto di JetBrains e VS Code: un http-client.env.json nella cartella (o sopra di essa) con un oggetto per ambiente — {"dev": {"host": "http://localhost:8080"}} — e, accanto, un http-client.private.env.json con i segreti, per tenerli fuori da Git. Nello stesso ambiente vince il file privato, e $shared vale per tutti. Il selettore accanto all'URL sceglie l'ambiente, e il menu di importazione ed esportazione crea il file. Una variabile viene dal test, poi da una cattura, poi dall'ambiente, e la scheda Variabili dice da dove viene ciascuna.

La scheda Catture conserva una parte della risposta come variabile — il token di un login, l'id di una risorsa appena creata — per i test successivi di questo file e degli altri nella stessa cartella. È così che un .lnh di login alimenta la chiamata autenticata di un altro. Il valore catturato resta solo in memoria e non viene mai scritto nel file.

La cartella è la raccolta: lnote http-run --path <cartella> --env dev esegue tutti i suoi .lnh in ordine naturale (01-login prima di 02-profilo) ed esce con errore quando un test fallisce, il che si adatta a una CI. La stessa esecuzione è disponibile via MCP come http_test_run, perché l'agente di IA esegua i test che hai scritto. Per impostazione predefinita i file non cambiano; --save vi scrive l'ultimo risultato di ogni test.

Importare ed esportare

Importare ed esportare OpenAPI. Il pulsante con le frecce in cima all'elenco dei test apre Importa OpenAPI… ed Esporta OpenAPI…. L'importazione legge una specifica in YAML o JSON nelle tre generazioni in uso — Swagger 2.0, OpenAPI 3.0 e 3.1 — e costruisce il test da sola: i {parametri} del percorso usano già la stessa sintassi delle variabili {nome} del file .lnh, gli esempi dichiarati diventano i valori del test, lo schema di sicurezza diventa l'intestazione Authorization e ogni server dichiarato diventa un test a sé (collaudo e produzione affiancati). Poiché un .lnh contiene un endpoint, una specifica con più operazioni chiede quale importare — oppure scrive tutte insieme, un file .lnh per operazione.

L'esportazione fa il percorso inverso e genera una specifica OpenAPI 3.0.3 a partire dal file: server, parametri e corpo derivano dal modello, e le risposte di esempio dalle esecuzioni registrate. È uno scheletro, non un contratto completo — il .lnh descrive chiamate, quindi tipi, descrizioni e schemi non vengono ricostruiti. I tuoi test viaggiano nel campo x-lightnote-tests, e per questo tornano intatti quando reimporti il file.

Importare un comando curl. Nello stesso pulsante, Importa comando curl… apre una casella per incollare — è da lì che arriva il comando, non dal disco, e il campo è già compilato quando negli appunti c'è un curl. Capisce i tre dialetti in cui circola lo stesso comando: Copia come cURL di Chrome/Firefox (apici singoli), Copy as cURL (cmd) su Windows (con ^) e l'esempio della documentazione spezzato con \. Il metodo viene da -X — oppure è dedotto: POST quando c'è un corpo, GET quando non c'è.

L'importazione è letterale: nessun valore diventa da solo una variabile {nome}, perché indovinare quale token sia un segreto sbaglierebbe. Alcuni casi avvisano invece di mentire — un corpo che proviene da un file (-d @file) non può essere letto, e l'invio multipart (-F) non viene riprodotto fedelmente, quindi i campi finiscono nel corpo come testo perché tu li sistemi.

Importare da un altro strumento. Importa da un altro strumento… legge un file .http/.rest (REST Client di VS Code, JetBrains, Visual Studio), la collezione o l’ambiente di Postman, l’export di Insomnia (v4 in JSON o v5 in YAML), l’HAR che il browser salva con Salva tutto come HAR, il .bru di Bruno (o l’intera cartella, con Importa cartella di Bruno…) e il WSDL di un servizio SOAP. Il formato viene riconosciuto dal contenuto, non dall’estensione. Ogni richiesta diventa un .lnh e le cartelle della collezione diventano cartelle: scegline una per questo file o salvale tutte in una volta. {{name}} diventa {name}, l’autenticazione diventa un’intestazione, gli ambienti vanno in http-client.env.json (ciò che l’origine segna come segreto va nel .private) senza cambiare nessun valore già presente, e le verifiche e catture di Bruno — e il pm.response.to.have.status di Postman — diventano verifiche e catture qui. Dall’HAR entrano solo le chiamate API e la pagina, con la risposta ricevuta dal browser come ultima esecuzione; dal WSDL esce una busta SOAP per operazione, con il SOAPAction e ogni campo come variabile.

Ciò che non ha equivalente resta com’è, e viene detto: gli script prima e dopo la richiesta non vengono convertiti, le variabili dinamiche ({{$guid}}) e i concatenamenti restano letterali, e il Basic con variabile, il corpo multipart e il corpo da file passano alla scheda Autenticazione e al Tipo del corpo, con il percorso del file, arrivato dall’altra macchina, elencato per il controllo. Quando la collezione viene salvata, questo rapporto diventa una nota nella cartella di destinazione. Esporta come .http… fa il percorso inverso con il test selezionato: il modello con {{name}} e i valori come @name = valore.