API şeması sapmasını önceden yakalayın

Durum kodunu ve birkaç alanı denetleyen bir test, API bir alan eklediğinde, doğrulamadığınız bir alanı kaldırdığında veya bir sayıyı dizeye dönüştürdüğünde başarılı olmaya devam eder. Nexus Studio, her API yanıtının yapısını, yani alan adlarını ve türlerini saklar; değerleri ise asla saklamaz. Bu yapıyı önceki çalıştırmayla karşılaştırır ve değiştiğinde API_DRIFTED bildirir. NEXUS_API_DRIFT_STRICT=true ayarıyla aynı değişiklik, test paketinin başarısız olmasına neden olur.

Nexus Studio ekibi, Verdict System LLC tarafından. 27 Ekim 2026.

API şema sapması nedir?

Şema sapması, bir yanıtın yapısının çalıştırmalar arasında değişmesidir: bir alanın eklenmesi, kaldırılması veya türünün değişmesi. Bir API zamanla gelişebilir. Sorun, test paketinde bu değişikliği bildiren hiçbir şey olmadığı için API'yi kullananların bunu üretim ortamında fark etmesidir.

Başarılı bir sözleşme testi bunu neden gözden kaçırır?

Çünkü yalnızca yazarının aklına gelenleri doğrular. validate(res, { status: 200, hasFields: ['id'] }) gibi bir kural, price sayıdan dizeye dönüştüğünde başarılı olmaya devam eder; çünkü price kuralda yer almaz. Bozulan, fiyatları toplayan istemcidir.

Bunun nasıl olduğunu çalıştırılabilir bir örnekte görebilir miyim?

Bunu server.mjs olarak kaydedin. Tek bir uç noktaya yanıt verir ve SHAPE değişkeni, uç noktanın ne döndüreceğini belirler: sayı olarak bir fiyat veya yeni bir currency alanıyla birlikte dize olarak bir fiyat.

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');

Bu API testini çalışma alanınızın api-tests/rest klasörüne APIT900_drift_demo.api.js olarak kaydedin. Gerçek hayattaki birçok test paketi gibi, durum kodunu ve tek bir alanı doğrular.

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

Sunucuyu bir PowerShell penceresinde başlatın ve testi başka bir pencerede çalıştırın. İlk çalıştırmada karşılaştırılacak bir şey olmadığından, yapı kaydedilir ve test başarılı olur.

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

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

Sunucuyu durdurun, $env:SHAPE = "v2" ile yeniden başlatın ve aynı testi çalıştırın. Test hâlâ başarılıdır, ancak çalıştırma artık API_SECURE değildir. İşte yalnızca önemli satırları içerecek şekilde kısaltılmış çıktı:

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

Sapma, derlemenin başarısız olmasına neden olabilir mi?

Evet, istenirse. API'nin değişmesi bir kusur değil, bilgi olduğundan API_DRIFTED varsayılan olarak başarı sayılır ve 0 çıkış kodu döndürür. Ayrı bir satırda yazdırılır ve farkla birlikte çalıştırmanın kanıtlarına kaydedilir; böylece sorunsuz bir başarı olarak değerlendirilmez. NEXUS_API_DRIFT_STRICT=true ayarını yaparsanız aynı değişiklik 1 çıkış kodu döndürür. Bunu görmek için bu değişken ayarlıyken testi bir kez v1 ile, bir kez de v2 ile çalıştırın.

Referans her zaman önceki çalıştırmadır. Sapma olan bir çalıştırmadan sonra yeni yapı referans alınır; dolayısıyla aynı yanıtla yapılan sonraki çalıştırmada sapma bildirilmez.

Sınırlar nelerdir?

• Bir testin ilk çalıştırılması yalnızca yapıyı kaydeder. Henüz sapmanın ölçülebileceği bir referans yoktur.
• Yapı, anlamdan değil, adlardan ve türlerden oluşur. price sayı olarak kalır ancak dolardan sente geçerse hiçbir değişiklik algılanmaz.
• Karşılaştırma, üzerinde anlaştığınız bir sözleşmeyle değil, önceki çalıştırmayla yapılır. Bir şeyin değiştiğini söyler; değişikliğe izin verilip verilmediğini değil.
• Her test senaryosu, son isteğinin gövdesinden alınan tek bir yapı saklar. Bir liste ilk elemanıyla, bir nesne en fazla 200 anahtarıyla tanımlanır ve iç içe yapıların incelenmesi altı düzeyde durur.

Nerede görebilirim?

Kararlar kılavuzu test kararlarını açıklar, Kanıtlar sayfası ise bir çalıştırmanın diskinizde bıraktığı dosyaları listeler. 30 günlük deneme sürümü aynı motoru kendi API testlerinizde çalıştırır.