Yanıt döndüren bir API isteği geçen bir test değildir. Bu sadece bir yanıttır. Test, ancak bir şey yanıtın doğru olduğunu kontrol ettiğinde var olur. Bu kontrol bir onaylamadır (assertion) ve onaylamalarınızın kalitesi, test paketinizin gerçek hataları yakalayıp yakalamadığına veya sadece sunucunun ayakta olduğunu doğrulamadığına karar verir.
Bu kılavuz, API onaylamalarının ne olduğunu, yazmaya değer türlerini, ekiplerin nerede yanlış yaptığını ve Apidog'da komut dosyası kullanmadan onaylamaları görsel olarak nasıl oluşturacağınızı açıklar.
API onaylaması nedir?
Onaylama, testin geçmesi için doğru olması gereken bir yanıt hakkındaki bir ifadedir. Bir istek gönderirsiniz, API yanıt verir ve onaylama, o yanıtın bir kısmını beklenen bir değerle karşılaştırır. Eşleşirse geçer. Eşleşmezse başarısız olur.
Onaylamalar olmadan, otomatik bir test yalnızca uç noktanın erişilebilir olduğunu kanıtlar. Onaylamalarla birlikte, uç noktanın doğru olduğunu kanıtlar. Bu ikisi arasındaki boşluk, çoğu üretim olayının yaşandığı yerdir: API çalışıyordu, 200 döndürdü ve gövde yanlıştı.
Faydalı bir onaylama spesifik ve bağımsızdır. Spesifiktir, böylece bir hata tek bir şeyi işaret eder. Bağımsızdır, böylece başka bir onaylamanın önce geçmesine sessizce bağlı olmaz. Tek bir test adımı genellikle aynı yanıtın farklı bir yönünü kontrol eden birkaç onaylama taşır.
Durum kodu onaylaması ve neden yeterli değil
En yaygın onaylama HTTP durum kodunu kontrol eder: başarılı bir okuma için 200, oluşturulan bir kaynak için 201, yanlış giriş için 400, eksik yetkilendirme için 401 bekleyin. Bu gereklidir. Durum kodlarını doğru ayarlamak başlı başına bir disiplindir; API'nız bu konuda tutarsızsa REST API'lerinin hangi HTTP durum kodlarını kullanması gerektiği okunmaya değerdir.
Ancak tek başına bir durum kodu onaylaması zayıftır. Bir API, boş bir gövdeyle, eski bir değerle, bir nesnenin olması gereken yerde bir null ile veya bir başarı olarak giydirilmiş bir hata mesajıyla 200 OK döndürebilir. Durum, isteğin işlendiğini söyler. Verilerin doğru olup olmadığı hakkında hiçbir şey söylemez.
Durum onaylamasını bir test adımının ilk satırı olarak ele alın, asla tek satırı olarak değil.
Yazmaya değer onaylama türleri
Gövde içeriği onaylamaları. Yanıttaki gerçek değerleri kontrol edin. id alanı mevcut ve boş değil. email gönderdiğinizle eşleşiyor. total satır öğelerinin toplamına eşit. Bunlar, durum kodlarının kaçırdığı mantık hatalarını yakalar.
Şema onaylamaları. Yanıtın şeklini bir JSON Şeması veya bir OpenAPI tanımına göre doğrulayın: gerekli alanlar mevcut, türler doğru, beklenmedik alanlar görünmedi. Şema onaylamaları, arka ucun bir alanı dizeden nesneye sessizce değiştirdiği ve her istemciyi bozduğu sözleşme kaymasını yakalar. Bu, üretici ve tüketici arasında fikri resmileştiren API sözleşme testi ile çakışır.
Başlık onaylamaları. Content-Type'ın application/json olduğunu, önbelleğe alma başlıklarının istendiği gibi ayarlandığını, CORS başlıklarının mevcut olduğunu ve Strict-Transport-Security gibi güvenlik başlıklarının bulunduğunu onaylayın.
Yanıt süresi onaylamaları. Bir gecikme bütçesi belirleyin, örneğin 800 ms, ve yanıt daha yavaş olduğunda testi başarısız yapın. Performans regresyonları diğer tüm onaylama türleri için görünmezdir, bu yüzden bunları fonksiyonel bir pakette yakalayan tek tür budur.
Hata şekli onaylamaları. Negatif durumlar için, sadece 4xx kodu değil, hata gövdesini onaylayın. error alanı validation_error'a eşit, details dizisi hataya neden olan alanı adlandırıyor ve mesajda hassas veri sızıntısı yok.
Güvenlik onaylamaları. Uç noktanın jetonsuz istekleri reddettiğini, süresi dolmuş jetonları reddettiğini, kullanıcılar arasında yetkilendirmeyi uyguladığını ve enjeksiyon yüklerini kaçırılmamış olarak geri yansıtmadığını onaylayın.
Durumu, iki veya üç gövde alanını, şemayı ve bir yanıt süresi bütçesini onaylayan bir test adımı gerçek iş yapıyor demektir. Sadece durumu onaylayan bir adım dekoratiftir.
Onaylama mantığı nerede yanlış gider?
Değişken veriler üzerinde aşırı onaylama. Tam bir created_at zaman damgasını veya oluşturulmuş bir UUID'yi onaylamak, testin her çalıştırmada sebepsiz yere başarısız olmasına neden olur. Alanın mevcut olduğunu ve doğru türe sahip olduğunu onaylayın, tam değerini değil.
Mutlu yolda yetersiz onaylama. Mutlu yol testi, sadece durum kodunu onaylaması en muhtemel olanıdır. Aynı zamanda kullanıcıların en çok karşılaştığı durumdur. Ona en kapsamlı onaylamaları verin, en az olanları değil.
Sıraya bağlı onaylamalar. Eğer onaylama B sadece onaylama A geçtiğinde anlamlıysa, ancak ikisi de körü körüne çalışıyorsa, A'daki bir hata B'de kafa karıştırıcı ikinci bir hata üretir. Bağımlılıkların açıkça belirtildiği adımlar yapılandırın.
Tek bir onaylamanın iki iş yapması. “Yanıt doğru” bir onaylama değildir. Bunu ayırın: durum 200, token mevcut, expires_in 3600'e eşit. Üç kontrol, üç net hata mesajı.
Negatif durumları göz ardı etmek. Ekipler başarıya çok yoğun bir şekilde onaylar, ancak başarısızlığa neredeyse hiç onaylamazlar. Gövde onaylaması olmayan negatif bir durum sadece API'nin "hayır" dediğini kanıtlar, "doğru" bir şekilde hayır dediğini değil.
Apidog'da onaylamalar oluşturma
Apidog'da onaylamalar görsel test oluşturucunun bir parçasıdır, bu yüzden bunları komut dosyası kullanmak yerine tıklayarak tanımlarsınız.
Bir test senaryosundaki herhangi bir istek için, onaylama panelini açın ve kontroller ekleyin:
- Durum onaylaması. "Yanıt durumu"nu seçin ve
200'e eşit olarak ayarlayın. - Gövde alanı onaylamaları.
$.tokengibi bir JSONPath ifadesi kullanın ve mevcut ve boş olmayan bir dize olduğunu onaylayın;$.expires_in'in3600'e eşit olduğunu onaylayın. Apidog yanıt yapısını okur, böylece yolları körü körüne yazmak yerine alanları seçersiniz. - Şema onaylaması. Yanıtı uç noktanın tanımlanmış şemasına göre doğrulayın. Apidog API tasarımını ve testleri tek bir çalışma alanında tuttuğu için, onaylamanızın kullandığı şema, belgelerinizin yayınladığı şemayla aynıdır; kayma yapacak ikinci bir kopyası yoktur.
- Yanıt süresi onaylaması. Yanıt süresinin bütçenizin altında olduğunu kontrol eden bir kontrol ekleyin.
- Yalnızca gerektiğinde özel komut dosyası. Görsel kontrollerin ifade edemediği mantık için, bir JavaScript son işlemcisine geçin. Çoğu onaylama buna asla ihtiyaç duymaz.
Onaylamaları bir senaryo genelinde gruplandırın ve Apidog bunları birlikte çalıştırır. Ölçeklenen kapsama için, bir veri dosyası ekleyerek bir onaylama kümesinin veri odaklı test girişinin her satırına karşı çalışmasını sağlayın. Senaryo çalıştığında, oluşturulan rapor, hangi isteğin, beklenen ve gerçek değerler yan yana olmak üzere, tam olarak hangi onaylamanın başarısız olduğunu gösterir.
Aynı senaryo CI'da değişmeden çalışır, bu nedenle her commit her onaylamayı yeniden kontrol eder; CI/CD'de API testlerini otomatikleştirme bu bağlantıyı kapsar. Kendi uç noktanıza karşı bir onaylama kümesi oluşturmak için Apidog'u indirin.
Çalışılmış bir onaylama kümesi
Bir kullanıcı nesnesi döndüren GET /users/{id} örneğini ele alalım. Mutlu yol için sağlam bir onaylama kümesi:
- Durum
200'e eşit Content-Typebaşlığıapplication/jsoniçerir$.idistenen id'ye eşit$.emailmevcut ve bir e-posta desenine uygun$.roleadmin,member,viewer'dan biri- Yanıt gövdesi
Userşemasına uygun - Yanıt süresi 600 ms'nin altında
Ve bilinmeyen bir id ile GET /users/{id} için:
- Durum
404'e eşit $.errornot_found'a eşit- Yanıt gövdesi
email,idveya diğer kullanıcı alanlarını içermiyor
İki istek, on bir onaylama ve sözleşmeyi, verileri, başlıkları, performansı ve hata davranışını doğrulamış olursunuz. İşte bu, bir sürümü koruyan bir test paketi ile sadece sunucuyu pingleyen bir test paketi arasındaki farkı ayırt eder.
CI hattındaki onaylamalar
Onaylamalar, otomatik olarak çalıştıklarında tam değerlerini kazanırlar. Birinin haftada bir elle çalıştırdığı bir paket, hataları bir hafta geç yakalar. CI'ya bağlanan aynı paket, bunları çekme isteğinde yakalar.
Onaylamalar bir hatta çalıştığında, iki tasarım seçimi önemlidir. Birincisi, hata açık olmalıdır. "Test başarısız" diyen bir CI günlüğü, bir geliştiriciyi çalıştırmayı yerel olarak yeniden üretmeye zorlar; "POST /auth/login'de $.expires_in'in 3600 olması bekleniyordu, 7200 alındı" diyen bir günlük, nereye bakmaları gerektiğini hemen söyler. Güçlü, spesifik onaylamalar, o anlaşılır hatayı üretenlerdir.
İkincisi, onaylamaların ortamlar arasında istikrarlı olması gerekir. Bir üretim kullanıcı kimliğini sabit kodlayan bir onaylama, kodla hiçbir ilgisi olmayan bir nedenle hazırlık ortamında başarısız olacaktır. Ortama özel değerleri değişkenlerde tutun ve tam değerin ortama bağlı olduğu yerlerde yapı ve tür üzerinde onaylayın. Bir şema onaylaması ortamlar arasında iyi seyahat eder; belirli bir oluşturulmuş kimlik üzerindeki bir onaylama etmez.
Pratik desen: her uç noktada bir temel olarak durumu ve şemayı onaylayın, bu her yerde çalışır, sonra bunun üzerine ortam farkında değer onaylamalarını katmanlayın. Temel, herhangi bir ortamdaki sözleşme kaymasını yakalar; değer onaylamaları, istikrarlı verilere sahip olduğunuz yerlerdeki mantık hatalarını yakalar. Her committe ikisini de çalıştırın ve paket bir rapor olmaktan ziyade bir geçit haline gelir.
Sıkça sorulan sorular
Bir onaylama ile bir test durumu arasındaki fark nedir? Bir test durumu tüm kontrolü ifade eder: bir istek artı beklenen sonucu. Onaylamalar ise içinde geçip geçmediğini belirleyen bireysel karşılaştırmalardır. API test durumları nasıl yazılır bölümüne bakın.
Bir isteğin kaç tane onaylaması olmalı? Durumu, ana gövde alanlarını, şemayı ve bir gecikme bütçesini kapsayacak kadar. Çoğu uç nokta için bu dört ila sekizdir. Her biri farklı bir şeyi kontrol ediyorsa daha fazlası da sorun değil.
Tam yanıt gövdelerini onaylamalı mıyım? İstikrarlı alanları tam olarak, değişken alanları ise tür veya varlıklarına göre onaylayın. Zaman damgaları ve oluşturulmuş kimlikleri içeren tam bir gövdeyi onaylamak, her çalıştırmada başarısız olan testler oluşturur.
Fonksiyonel bir testte API performansını onaylayabilir miyim? Evet. Bir yanıt süresi onaylaması, normal fonksiyonel çalıştırmalar sırasında gecikme regresyonlarını yakalar, temel bütçe kontrolü için ayrı bir yük testi gerekmez.
Negatif test durumlarında da onaylamalar olmalı mı? Kesinlikle, ve bunlar genellikle en çıplak bırakılan durumlardır. Sadece durum kodu kontrolü olan negatif bir durum, API'nin hayır dediğini kanıtlar, doğru bir şekilde hayır dediğini değil. Hata alanını, hataya neden olan alan detayını ve mesajdaki hassas verilerin yokluğunu onaylayın.
Özel onaylama komut dosyaları nerede kullanılmalı? Komut dosyalarını görsel oluşturucunun ifade edemediği mantık için ayırın: istekler arası karşılaştırmalar, türetilmiş değerler veya önceki yanıtlara bağlı koşullu kontroller. Çoğu onaylama, durum, şema, gövde alanları ve zamanlama, görsel kontroller olarak daha temiz ve daha gözden geçirilebilirdir.