Sezione Mock

La sezione Mock è dove definisci le risposte simulate che Aseptic serve quando una dipendenza è risolta come mock. Ti permette di lavorare senza connessione al cloud e senza avviare il core che il tuo micro chiama.

Non devi avviare nulla per modificare i mock: il catalogo vive su disco (.aseptic/mocks/<servizio>.json) ed è servito con hot reload, così una modifica si applica all’istante anche con lo scenario in esecuzione.

L’albero: servizi → endpoint

Il lato mostra un albero di servizi (i core mockabili) e, dentro ciascuno, i suoi endpoint in un elenco piatto, in ordine alfabetico per percorso. Ogni riga mostra il percorso completo relativo alla base del servizio, così due endpoint con lo stesso finale (/orders/lines e /invoices/lines) non si confondono. Per restringere un catalogo grande, la ricerca del lato filtra per nome del servizio o per percorso.

Un servizio è mockabile se è una dipendenza di qualche micro (o se crei il suo file in .aseptic/mocks). Puoi mostrare o nascondere i servizi che non hanno ancora stub.

Creare uno stub

Premi Nuovo stub (o il menu «⋮») e scegli il servizio di destinazione —uno dal catalogo o uno nuovo che si crea al salvataggio—. Un endpoint si definisce con:

Metodo e percorso (relativo al percorso base del servizio).
Una o più varianti di risposta.

Ci sono due modi di riempire il corpo:

Da OpenAPI: se il servizio dichiara una specifica OpenAPI (nel manifesto del micro, o derivata dal suo URL cloud), seleziona l’operazione e Aseptic genera un modello del corpo.
Manuale: se non c’è OpenAPI, scrivi il corpo JSON a mano.

L’icona OpenAPI accanto al servizio apre la specifica in un visore dedicato, con le sue operazioni navigabili, invece di lasciarti davanti il file grezzo.

Gruppi e servizi

Ogni servizio dell’albero ha la sua scheda («Modifica servizio» nel suo menu, o l’ingranaggio nell’editor di uno stub). In un gruppo creato a mano —per raccogliere stub che non appartengono a nessuna dipendenza, come tutti i /notice/...— si modificano nome, prefisso, URL di base (l’indirizzo reale a cui corrisponde il prefisso, dove va la chiamata reale) e OpenAPI. Di una dipendenza si modifica tutto tranne il nome, che è il suo id nei manifest: prefisso e URL di base si salvano nel manifest di ogni micro che la dichiara, e gli stub sotto il prefisso precedente passano al nuovo.

Scegliendo un’operazione dell’OpenAPI, Aseptic deduce il percorso che chiama il client anche se la specifica dichiara un altro prefisso (i suoi servers, il context-path, un tratto in comune con il prefisso del servizio). Se quell’operazione ha già uno stub, non ne crea un secondo: si apre quello esistente con una nuova variante dall’OpenAPI.

Creando uno stub, oltre a partire da un’operazione dell’OpenAPI, puoi partire da una chiamata già arrivata al mock senza stub: ne prende metodo e percorso.

La porta del server di mock e il token per OpenAPI (inviato come Authorization: Bearer per scaricare specifiche protette) sono in Configurazione del mock, nel menu «⋮» della sezione.

Varianti: l’unità di lavoro

Un endpoint può avere diverse varianti (per esempio una 200 e una 500). Ogni variante ha la sua etichetta, il suo codice di stato, il suo corpo, le sue intestazioni e una latenza opzionale in millisecondi per simulare lentezza.

La variante selezionata si espande in linea con il suo corpo, le intestazioni e le impostazioni insieme. La variante che viene servita si marca a parte con un interruttore (è indipendente da quella che stai modificando): è la risposta che Aseptic restituirà a chi chiama quell’endpoint.

Sopra il corpo ci sono tre pulsanti: Formattare lo indenta (e salva quell’indentazione), Riempire il modello lo genera dall’OpenAPI e Vedere con formato lo apre in un visore grande, che non modifica nulla e serve per leggere una risposta che non entra nel riquadro.

Puoi duplicare una variante per partire da una simile. Un endpoint che non vuoi più servire si elimina dal suo menu.

Corpi di ogni tipo: immagini, PDF, file

Sopra il corpo di ogni variante scegli Testo, Senza corpo, File o Flusso:

Testo: con un selettore di formato —JSON, testo semplice, HTML, XML, JavaScript, CSS, CSV, YAML, Markdown o modulo— che imposta il Content-Type servito e dà a ognuno la sua evidenziazione e il suo Formatta (un modulo viene compattato in a=1&b=2). Un tipo scritto a mano nelle impostazioni della variante ricade nella sua famiglia (application/problem+json è JSON).
File: un’immagine, un PDF, uno zip, un audio… qualsiasi cosa. Premi Scegli file o trascinalo sopra, e viene servito byte per byte. Se è un’immagine piccola, vedrai l’anteprima.
Senza corpo: solo il codice e le intestazioni, per un 204 o un 304; nessun Content-Type inventato.
Flusso: la risposta arriva a frammenti, ognuno dopo la sua pausa, per provare un client che mostra o conta mentre riceve. Scegli come viene scritto ogni frammento: Eventi SSE (text/event-stream, con nome dell’evento e id facoltativi), NDJSON (un JSON per riga) o Testo frammentato.

La dimensione decide dove viene salvato: fino a 256 KB resta dentro il catalogo, e viaggia con esso; se è più grande viene copiato in .aseptic/mocks/files/<servizio>/ e la variante lo referenzia. Senza Content-Type, viene dedotto dall’estensione (.png → image/png, .pdf → application/pdf); le altre intestazioni —Content-Disposition per forzare un download, Cache-Control…— vanno in Intestazioni come sempre. All’esportazione di un servizio o di uno scenario i file vengono incorporati, quindi ciò che condividi non dipende da quella cartella.

Regole: rispondere a seconda della richiesta

Sopra le varianti c’è un blocco Regole. Ogni regola dice «quando queste condizioni sono soddisfatte, servi questa variante», e si valutano in ordine: vince la prima che corrisponde. Se non ne corrisponde nessuna, si serve la variante attiva — quindi un endpoint senza regole si comporta esattamente come prima. L’ultima riga del blocco, fissa, ricorda proprio questo.

Una condizione guarda un dato della richiesta, senza sintassi da imparare: query o intestazione per nome, oppure corpo per un percorso con punti (ordine.cliente.tipo; un numero entra in una lista, ordine.righe.0.sku). Confronta con è uguale a, è diverso da, esiste o non esiste. Tutte le condizioni di una regola devono valere insieme; per un «o» si aggiunge una seconda regola — è a questo che serve la lista ordinata. L’ordine si cambia con le frecce di ogni regola: spostare una regola è cambiarne la priorità.

Una regola punta alla variante tramite la sua etichetta, non la posizione, perché riordinare le varianti non cambi in silenzio quello che si serve. Per questo, in un endpoint con regole, due varianti non possono chiamarsi allo stesso modo. Se rinomini una variante a cui puntava una regola, la regola viene segnalata e smette di essere servita finché non la correggi.

Provare simula una richiesta lì stesso — query, intestazioni e corpo — e dice quale variante uscirebbe e quale regola l’ha scelta. Non serve avere lo scenario in marcia. E quando lo è, il dock Chiamate mock marca ogni chiamata con la regola che l’ha decisa, così due chiamate identiche con risposte diverse si spiegano da sole.

Dal terminale è lo stesso: aseptic mock probe POST "/v1/ordini?tipo=premium", con -H 'X-Vip: 1' per le intestazioni e -d '{...}' per il corpo.

Salvataggio automatico

L’editor di mock salva da solo, con un piccolo ritardo, mentre scrivi; vedrai un indicatore «Salvato». Salvaguardie:

Si persistono solo stati validi: un corpo JSON a metà non rompe il mock servito —si mantiene l’ultimo valido su disco e l’errore si segnala in linea—.
Uno stub nuovo non si persiste finché non ha un metodo e un percorso utilizzabili.
L’eliminazione è sempre esplicita, con conferma.

Mock Studio: da una chiamata reale a uno stub

Quando uno scenario gira e un micro chiama un mock che non ha ancora risposta, quella chiamata appare nel dock Chiamate mock. Da lì puoi creare uno stub con un clic dalla chiamata osservata: vai diritto all’endpoint che vuoi completare, senza cercarlo. Puoi anche testare cosa risponderebbe il mock senza avviare nulla.

Chiamata reale: catturare la risposta del servizio

A volte non vuoi inventarti il corpo: vuoi quello che restituisce il servizio vero. Ogni endpoint ha un interruttore Chiamata reale. Finché è attivo, quell’endpoint smette di servire la sua variante: la richiesta esce verso il servizio reale, la sua risposta viene restituita tale e quale a chi ha chiamato e viene registrata come variante «Real» con il suo codice, che diventa attiva. Disattivandolo, il mock risponde con l’ultima cosa detta dal servizio, senza uscire di nuovo in rete.

Dove chiama: il microservizio dello scenario se è in esecuzione, altrimenti l’URL cloud della dipendenza. L’icona «i» dell’interruttore indica la destinazione esatta; se il servizio non ne ha nessuna, l’interruttore resta spento e spiega perché.
Verbi che modificano dati: attivarlo su un POST, un PUT o un DELETE chiede conferma indicando la destinazione. Non è vietato —catturare la risposta di una creazione è un caso legittimo— ma lì viene eseguito davvero.
Una variante per codice: Real 200, Real 404… Catturare mille chiamate non crea mille varianti; aggiorna quella del codice che arriva.
Ciò che non è testo (un’immagine, un PDF) viene registrato come file della variante; ciò che supera 1 MB viene servito ma non registrato.

Gli endpoint in cattura sono contrassegnati con l’etichetta real nell’albero, così non te ne resta uno che esce in rete senza che tu te ne accorga.

Importare ed esportare

Con le icone di import/export del pannello:

Esportare gli endpoint di un servizio (o di più) in un file JSON.
Importare un JSON proprio o una collezione Postman (le sue cartelle si mappano ai servizi).

Utile per condividere un catalogo di mock o riutilizzarlo tra scenari.

Lo stesso dalla CLI

Tutto questo esiste anche nella CLI: aseptic mock services, mock catalog, mock save, mock set-active, mock skeleton, mock from-call, mock probe, mock capture, mock put-file, mock import / export. Vedi il riferimento CLI.