Sözleşme Testi Neyi Çözer?

Bir SaaS ürünü ödeme, kimlik doğrulama, bildirim, CRM veya veri aktarımı gibi servislerle konuştuğunda yalnızca birim testlerine güvenmek yeterli değildir. Sağlayıcının JSON alanını yeniden adlandırması, zorunlu bir alan eklemesi ya da hata yanıtını değiştirmesi, uygulamanızdaki kod doğru çalışsa bile entegrasyonu bozabilir.

Sözleşme testi; tüketici ile sağlayıcı arasındaki teknik beklentileri istek yöntemi, URL, kimlik doğrulama, başlıklar, veri tipleri, zorunlu alanlar, hata kodları ve yanıt yapısı üzerinden doğrular. Amaç her değişiklikte pahalı uçtan uca testler çalıştırmak değil, bir tarafın diğer tarafın varsayımlarını bozup bozmadığını erken yakalamaktır.

Sözleşmeyi Koddan Önce Tanımlayın

Önce kritik kullanıcı akışlarını seçin: abonelik oluşturma, fatura sorgulama, ödeme iadesi ve webhook işleme gibi. Her akış için başarılı, hatalı ve sınır durumlarını yazılı hale getirin.

• İstek alanları, veri tipleri, biçim ve doğrulama kuralları
• Başarılı yanıtın şeması ve geriye dönük uyumluluk beklentisi
• Yetkisiz, geçersiz, bulunamayan ve oran sınırına takılan isteklerin davranışı
• Zaman aşımı, tekrar deneme ve idempotency kuralları
• Webhook imzası, tekrar gönderim, olay sıralaması ve işlenmiş olayların takibi

OpenAPI gibi makine tarafından işlenebilen bir tanım yararlı bir başlangıçtır; ancak yalnızca dokümantasyon üretmek sözleşme testi değildir. Tanımdaki kurallar CI sürecinde doğrulanmalı ve gerçek tüketici senaryolarıyla ilişkilendirilmelidir. Test payload'larında müşteri verisi kullanmayın; anonim, sabit ve temsil gücü yüksek veriler tercih edin.

Tüketici ve Sağlayıcı Testlerini Ayırın

Tüketici testi, uygulamanın gerçekten kullandığı davranışı tanımlar. Örneğin ödeme yanıtında yalnızca işlem kimliği ve durum alanları kullanılıyorsa, test sağlayıcıya kullanılmayan alanları da zorunlu kılmamalıdır. Böylece ihtiyaç duyulmayan bir alan değiştiğinde gereksiz kırılmalar oluşmaz.

Sağlayıcı testi ise yayımlanan API'nin tanımlanan sözleşmeyi karşıladığını kontrol eder. Sözleşme çıktıları sürüm kontrollü biçimde paylaşılabilir; her iki tarafın aynı test ortamına sürekli bağlı olması gerekmez. Başarısız test raporu, değişen alanı, beklenen ve gelen veri tipini, durum kodunu ve etkilenen tüketiciyi açıkça göstermelidir.



Mock sunucular hızlı geri bildirim sağlar; ancak gerçek API'den kopmamaları için düzenli aralıklarla sağlayıcı testleriyle karşılaştırılmalıdır. Mock dosyasını elle güncellemek, testi yapay biçimde başarılı gösterebilir. Kimlik bilgileri test koduna gömülmemeli, kısa ömürlü ve en az yetkili test erişimleri kullanılmalıdır.

Kırıcı Değişiklikleri Yönetme

Bir alanı silmek, veri tipini değiştirmek, alanın anlamını değiştirmek veya mevcut bir isteği zorunlu hale getirmek kırıcı değişikliktir. Böyle bir değişiklik gerektiğinde önce yeni davranışı ekleyin, tüketicileri taşıyın ve eski davranış için ölçülebilir bir kaldırılma takvimi belirleyin.

• Yeni alanları başlangıçta opsiyonel ekleyin.
• Eski alanları geçiş süresince okumaya devam edin; yeni yazımlarda tek bir kanonik biçim kullanın.
• API sürümünü yalnızca isim değişikliği için değil, anlamlı davranış farkları oluştuğunda artırın.
• Kaldırılacak alanlar için kullanım ölçümü ve uyarı logları ekleyin.
• Tüm tüketiciler taşınmadan eski davranışı kapatmayın.

Dağıtım öncesinde veritabanı migrasyonları, geriye dönük uyumlu şema değişiklikleri, rollback planı ve özellik bayrakları birlikte değerlendirilmelidir. Sözleşme testi başarılı olsa bile veri dönüşümü geri alınamıyorsa operasyonel risk sürer. Webhook tüketicilerinde imza doğrulaması, tekrar işleme güvenliği ve idempotent iş akışı ayrıca test edilmelidir.

Bakım Maliyeti ve Takım Çalışması

Sözleşmeler tek bir ekibin kişisel bilgisinde kalmamalıdır. Her değişiklik pull request içinde gerekçesi, etkilenen tüketiciler, sözleşme test sonucu, sürümleme kararı ve geri dönüş planıyla incelenmelidir. CI kontrolleri zorunlu olmalı; başarısız uyumluluk testleri uyarı olarak gizlenmemelidir.

Başlangıçta en kritik iki veya üç entegrasyonu seçip küçük ama gerçek kullanım senaryolarını kapsayan bir sözleşme seti oluşturun. Başarı ölçütü test dosyası sayısı değil; üretimdeki uyumsuzlukların azalması ve değişikliklerin güvenle yayımlanabilmesidir. Başarısız uyumluluk kontrolü, eski sürüm kullanım oranı, entegrasyon hata oranı ve rollback sayısı gibi göstergeleri izlemek, zamanla bakım maliyetini görünür kılar.