Rilevare divergenze schema API prima dei test

Un test che controlla il codice di stato e alcuni campi continua a passare quando l'API aggiunge un campo, ne elimina uno non verificato dalle asserzioni o trasforma un numero in una stringa. Nexus Studio memorizza la struttura di ogni risposta API, i nomi e i tipi dei campi e mai i valori, la confronta con quella dell'esecuzione precedente e segnala API_DRIFTED quando cambia. Con NEXUS_API_DRIFT_STRICT=true, la stessa modifica fa fallire la suite.

A cura del team di Nexus Studio, Verdict System LLC. 27 ottobre 2026.

Che cos'è la deriva dello schema API?

La deriva dello schema è un cambiamento nella struttura di una risposta tra un'esecuzione e l'altra: un campo aggiunto, un campo rimosso o un campo il cui tipo è cambiato. Un'API può evolversi. Il problema nasce quando chi la utilizza se ne accorge in produzione, perché nulla nella suite di test aveva segnalato il cambiamento.

Perché un test di contratto che passa non la rileva?

Perché verifica solo ciò a cui ha pensato chi lo ha scritto. Una regola come validate(res, { status: 200, hasFields: ['id'] }) continua a passare quando price passa da numero a stringa, perché price non è incluso nella regola. A smettere di funzionare è il client che somma i prezzi.

Posso vederlo in azione con un esempio eseguibile?

Salva questo codice come server.mjs. Risponde su un solo endpoint e la variabile SHAPE determina cosa restituisce l'endpoint: un prezzo come numero oppure un prezzo come stringa con un nuovo campo currency.

import http from 'node:http';

// SHAPE=v1 answers {id, price: 9.99}; SHAPE=v2 answers {id, price: "9.99", currency: "USD"}.
const v2 = process.env.SHAPE === 'v2';
http.createServer((req, res) => {
    res.setHeader('Content-Type', 'application/json');
    res.end(JSON.stringify(v2 ? { id: 7, price: '9.99', currency: 'USD' } : { id: 7, price: 9.99 }));
}).listen(4010, '127.0.0.1');

Salva questo test API come APIT900_drift_demo.api.js nella cartella api-tests/rest della tua area di lavoro. Verifica lo stato e un campo, come fanno molte suite reali.

// type: rest
import { runApiSuite } from '../../utils/base-api-fixture.js';

await runApiSuite([{
    id: 'APIT900-1',
    name: 'GET /product/7 returns 200 with an id',
    fn: async ({ request, validate }) => {
        const res = await request({ method: 'GET', url: '/product/7' });
        validate(res, { status: 200, hasFields: ['id'] });
    },
}]);

Avvia il server in una finestra di PowerShell ed esegui il test in un'altra. La prima esecuzione non ha nulla con cui fare il confronto, quindi registra la struttura e passa.

$env:SHAPE = "v1"; node server.mjs

$env:API_BASE_URL = "http://127.0.0.1:4010"; nexus api APIT900 --no-app

Arresta il server, riavvialo con $env:SHAPE = "v2" ed esegui lo stesso test. Continua a passare, ma l'esecuzione non è più API_SECURE. Questo è l'output, ridotto alle righe rilevanti:

schema drift: +1 field, 1 type change
   + currency
   ~ price: number → string
API_DRIFTED  7ms
1/1 passed
1 endpoint changed shape since the last run, set NEXUS_API_DRIFT_STRICT=true to fail the suite on it

La deriva può far fallire la compilazione?

Sì, se lo richiedi. Per impostazione predefinita API_DRIFTED conta come esito positivo e termina con codice 0, perché il cambiamento dell'API è un'informazione e non un difetto. Viene stampato su una riga a sé e registrato insieme alla differenza nelle evidenze dell'esecuzione, così non viene mai interpretato come un esito positivo senza riserve. Imposta NEXUS_API_DRIFT_STRICT=true e la stessa modifica determina l'uscita con codice 1. Per verificarlo, esegui il test una volta su v1 e una volta su v2 con quella variabile impostata.

Il riferimento è sempre l'esecuzione precedente. Dopo un'esecuzione che rileva una deriva, la nuova struttura diventa il riferimento, quindi l'esecuzione successiva sulla stessa risposta non segnala alcuna deriva.

Quali sono i limiti?

• La prima esecuzione di un test si limita a registrare una struttura. Non esiste ancora un riferimento da cui rilevare una deriva.
• La struttura comprende nomi e tipi, non il significato. Se price rimane un numero ma passa da dollari a centesimi, non viene rilevato alcun cambiamento.
• Il confronto avviene con l'esecuzione precedente, non con un contratto concordato. Ti indica che qualcosa è cambiato, non se la modifica fosse consentita.
• Ogni caso di test conserva una sola struttura, ricavata dal corpo della sua ultima richiesta. Una lista è descritta dal suo primo elemento, un oggetto da un massimo di 200 chiavi e l'annidamento si ferma a sei livelli.

Dove posso vederlo?

La guida ai verdetti illustra i verdetti dei test e la pagina delle evidenze elenca i file che un'esecuzione lascia sul disco. La prova di 30 giorni esegue lo stesso motore sui tuoi test API.