API-Schema-Drift erkennen, bevor Ihre Tests versagen

Ein Test, der den Statuscode und einige wenige Felder prüft, bleibt weiterhin erfolgreich, wenn die API ein Feld hinzufügt, eines weglässt, das Sie nicht überprüfen, oder eine Zahl in eine Zeichenkette umwandelt. Nexus Studio speichert die Struktur jeder API-Antwort – Feldnamen und -typen, niemals Werte –, vergleicht sie mit dem vorherigen Durchlauf und meldet API_DRIFTED, wenn sie sich ändert. Mit NEXUS_API_DRIFT_STRICT=true lässt dieselbe Änderung die Testsuite fehlschlagen.

Vom Nexus Studio-Team, Verdict System LLC. 27. Oktober 2026.

Was ist API-Schema-Drift?

Schema-Drift bezeichnet die Veränderung der Struktur einer Antwort zwischen Testläufen: Ein Feld wurde hinzugefügt, ein Feld wurde entfernt oder der Typ eines Feldes hat sich geändert. Eine API darf sich weiterentwickeln. Das Problem entsteht, wenn deren Konsumenten dies erst in der Produktion bemerken, weil kein Test in der Testsuite darauf hingewiesen hat.

Warum übersieht ein erfolgreicher Contract-Test dies?

Weil er nur das überprüft, woran sein Autor gedacht hat. Eine Regel wie validate(res, { status: 200, hasFields: ['id'] }) bleibt weiterhin erfolgreich, wenn price von einer Zahl in eine Zeichenkette geändert wird, da price nicht Teil der Regel ist. Der Client, der Preise zusammenrechnet, ist derjenige, der ausfällt.

Kann ich das an einem ausführbaren Beispiel sehen?

Speichern Sie dies als server.mjs. Es bedient einen Endpunkt, und die Variable SHAPE bestimmt, was der Endpunkt zurückgibt: einen Preis als Zahl oder einen Preis als Zeichenkette mit einem neuen Feld 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');

Speichern Sie diesen API-Test als APIT900_drift_demo.api.js im Ordner api-tests/rest Ihres Arbeitsbereichs. Er überprüft den Status und ein Feld, wie es viele reale Test-Suites tun.

// 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'] });
    },
}]);

Starten Sie den Server in einem PowerShell-Fenster und führen Sie den Test in einem anderen aus. Der erste Durchlauf hat keine Vergleichsbasis, daher zeichnet er die Struktur auf und ist erfolgreich.

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

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

Stoppen Sie den Server, starten Sie ihn erneut mit $env:SHAPE = "v2" und führen Sie denselben Test aus. Er ist weiterhin erfolgreich, aber der Durchlauf ist nicht mehr API_SECURE. Dies ist die Ausgabe, gekürzt auf die relevanten Zeilen:

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

Kann Drift den Build fehlschlagen lassen?

Ja, auf Anfrage. Standardmäßig gilt API_DRIFTED als bestanden und wird mit Exit-Code 0 beendet, da eine Änderung der API eine Information und kein Fehler ist. Sie wird in einer eigenen Zeile ausgegeben und mit der Differenz im Nachweis des Durchlaufs protokolliert, sodass sie niemals als vollständig sauberer Durchlauf interpretiert wird. Setzen Sie NEXUS_API_DRIFT_STRICT=true, und dieselbe Änderung wird mit Exit-Code 1 beendet. Um dies zu sehen, führen Sie den Test einmal gegen v1 und einmal gegen v2 mit dieser gesetzten Variable aus.

Die Baseline ist immer der vorherige Durchlauf. Nach einem Durchlauf mit Drift ist die neue Struktur die Baseline, sodass der nächste Durchlauf gegen dieselbe Antwort keine Drift meldet.

Wo liegen die Grenzen?

• Der erste Durchlauf eines Tests zeichnet nur eine Struktur auf. Es gibt noch nichts, wovon eine Drift ausgehen könnte.
• Die Struktur besteht aus Namen und Typen, nicht aus Bedeutungen. Wenn price eine Zahl bleibt, sich jedoch von Dollar zu Cent ändert, verschiebt sich nichts.
• Der Vergleich erfolgt mit dem vorherigen Durchlauf, nicht mit einem vereinbarten Vertrag. Er zeigt Ihnen, dass sich etwas geändert hat, nicht jedoch, ob die Änderung zulässig war.
• Jeder Testfall behält eine Struktur bei, die aus dem Body seiner letzten Anfrage übernommen wird. Eine Liste wird durch ihr erstes Element beschrieben, ein Objekt durch bis zu 200 Schlüssel, und die Verschachtelung stoppt bei sechs Ebenen.

Wo kann ich das sehen?

Der Leitfaden zu Verdicts behandelt die Test-Verdicts, und die Evidence-Seite listet die Dateien auf, die ein Durchlauf auf Ihrer Festplatte hinterlässt. Die 30-Tage-Testversion führt dieselbe Engine auf Ihren eigenen API-Tests aus.