Güvenilir API Test Stratejileri: Pratik Kılavuz

Çoğu API hatası egzotik değildir. Eksik bir alan, yanlış bir durum kodu, yük altında bir zaman aşımı veya kimsenin sözleşmeyi kontrol etmediği için gönderilen bozucu bir değişiklik olabilirler. Ad-hoc testler bunların bazılarını şans eseri yakalar. Bir strateji ise bunları bilerek yakalar.

Bir API test stratejisi, neyi, hangi katmanda ve teslimat döngüsünün neresinde test edeceğinize dair bir plandır. Hangi kontrollerin her commit'te, hangilerinin her gece ve hangilerinin bir sürümden önce çalıştırılacağına karar verir. En az bakımla en fazla kapsama alanı elde etmek için çabayı nereye harcayacağınızı söyler.

Düğme

Bir API Test Stratejisi Aslında Ne Anlama Geliyor?

Bir strateji, tek bir doğrulama yazmadan önce dört soruyu yanıtlar.

Ne test edersiniz? İş değeri taşıyan uç noktaları ve akışları. Bir ödeme API'si, bir sağlık kontrolü uç noktasından daha fazla kapsama alanına ihtiyaç duyar. Risk ve trafiğe göre sıralayın, uç noktanın vurulmasının ne kadar kolay olduğuna göre değil.

Hangi katmanda? Bazı kontroller tek bir isteğe aittir. Diğerleri ise iki veya üç hizmetin birbiriyle konuşmasını gerektirir. Her kontrolü en üst katmana koymak, test takımınızı yavaş ve kırılgan yapar.

Ne zaman çalışır? Hızlı kontroller her push işleminde çalışır. Yavaş kontroller bir zamanlamaya göre veya sürümden önce çalışır. İkisini karıştırmak, geri bildiriminizin yavaş olduğu veya kapsama alanınızın yetersiz olduğu anlamına gelir.

Ne başarılı sayılır? Yalnızca 200 yanıtını kontrol eden bir test size neredeyse hiçbir şey söylemez. Beklediğiniz durum kodunu, şemayı, alan değerlerini ve yanıt süresini tanımlayın.

API'nız için bu dört soruyu yanıtlayabildiğinizde, bir stratejiniz var demektir. Bu kılavuzun geri kalanı ayrıntıları tamamlar.

Bir Strateji Neden Ad-Hoc Testi Geride Bırakır?

Ad-hoc test, bir istek gönderip, yanıtı gözden geçirip ilerlemek anlamına gelir. Bir demo için işe yarar. Gerçek bir hizmette ise üç nedenden dolayı çöker.

Tekrar etmez. Bir sonraki kişi manuel kontrolünüzü tekrar çalıştıramaz, bu yüzden regresyonlar geri sızar. Kaydedilmiş, otomatik bir test her seferinde aynı şekilde çalışır.

Mutlu yola doğru eğilim gösterir. Elle test yaparken, çalışmasını beklediğiniz şeyi test edersiniz. Bozuk yüklü veriyi, süresi dolmuş belirteci veya 10.000 maddelik listeyi nadiren gönderirsiniz. İşte bunlar üretimde bozulan durumlardır.

Ölçeklenmez. 40 uç noktası ve 5 ortamı olan bir hizmet, sürüm başına 200 manuel kontrol demektir. Kimse bunu elle yapmaz, bu yüzden API büyüdükçe kapsama alanı küçülür. Bir strateji, tekrarlanabilir kapsama alanı için tek seferlik bir kurulum maliyetini takas eder: testleri bir kez yazarsınız ve onlar sizin olmadan her değişiklikte çalışır.

API Test Piramidi

Test piramidi, her katmanda kaç test yazılacağına dair genel bir kuraldır. Altta geniş, üstte dar.

        /\
       /  \      Uçtan uca / iş akışı testleri (az, yavaş, yüksek değerli)
      /----\
     /      \    Entegrasyon / sözleşme testleri (bazı, orta hızda)
    /--------\
   /          \  Birim / tek istek testleri (çok, hızlı, ucuz)
  /____________\

Alt katman: tek istek kontrolleri. Her test bir uç noktayı vurur ve yanıtta doğrulama yapar. Bunlar hızlıdır, yazması ucuzdur ve hata ayıklaması kolaydır. Biri başarısız olduğunda, tam olarak hangi uç noktanın bozulduğunu bilirsiniz. Testlerinizin çoğu burada bulunur.

Orta katman: entegrasyon ve sözleşme kontrolleri. Bunlar, hizmetlerin değişim yaptıkları veri şekli üzerinde anlaştığını ve iki veya üç sistemi etkileyen bir isteğin doğru sonucu döndürdüğünü doğrular. Daha fazla hareketli parça içerdikleri için daha yavaştırlar, ancak tek istek testlerinin kaçırdığı hataları yakalarlar.

Üst katman: uçtan uca iş akışları. Bunlar, birden çok uç nokta üzerinden tam bir kullanıcı yolculuğunu çalıştırır: sipariş oluşturma, ödeme yapma, durumu kontrol etme. En fazla güveni verirler ve bakımı en pahalı olanlardır, bu yüzden sayılarını az tutun ve kritik yollar için ayırın.

Ekiplerin yaptığı hata piramidi tersine çevirmektir: bir yığın yavaş uçtan uca test ve neredeyse hiç hızlı test olmaması. Bu size uzun geri bildirim döngüleri ve kararsız hatalar verir. Aynı hatayı daha alt bir katman yakalayabildiğinde kapsama alanını piramitte aşağı doğru itin.

Test Türleri ve Her Birinin Ne Zaman Uygulanacağı

Tam bir strateji, her biri farklı bir hata sınıfını hedefleyen çeşitli test türlerini kullanır. Her birinin neyi kontrol ettiği ve ne zaman başvurulması gerektiği aşağıdadır.

Fonksiyonel Test

Fonksiyonel test, bir uç noktanın belirtiminde yazdığı şeyi yapıp yapmadığını doğrular. Geçerli bir istek gönderin, durum kodunu, yanıt şemasını ve alan değerlerini doğrulayın. Bu, test takımınızın temelidir ve herhangi yeni bir uç noktada otomatikleştireceğiniz ilk şeydir. Daha derinlemesine bir inceleme için API fonksiyonel testine bakın.

Bir kullanıcı uç noktası için fonksiyonel bir kontrol şöyle görünür:

GET /api/users/42 HTTP/1.1
Host: api.example.com
Authorization: Bearer <token>

Doğrulamalar:

Durum 200.
Gövde User şemasıyla eşleşir.
id 42'ye eşit.
email geçerli bir e-posta dizesidir.

Entegrasyon Testi

Entegrasyon testi, uç noktaların birlikte çalıştığını ve API'nizin bağımlılıklarıyla (veritabanı, bir ödeme sağlayıcı, bir aşağı akış hizmeti) doğru şekilde iletişim kurduğunu kontrol eder. Fonksiyonel bir test, sahte bir bağımlılıkta başarılı olabilir ve gerçek olan bağlandığında yine de başarısız olabilir. Entegrasyon testleri bu boşluğu kapatır. Tam yöntem API entegrasyon testinde ele alınmıştır.

Regresyon Testi

Regresyon testi, daha önce çalışan bir şeyi bozmadığınızdan emin olmak için her değişiklikten sonra mevcut test takımınızı yeniden çalıştırır. Kaydedilmiş, otomatik bir test takımının değerini gösterdiği yer burasıdır. Yeni regresyon testleri yazmazsınız; zaten sahip olduğunuz testleri, bir zamanlamaya göre ve sürümden önce çalıştırırsınız. Bunu nasıl yapılandıracağınızı öğrenmek için regresyon testine bakın.

Sözleşme Testi

Sözleşme testi, bir API'nin sağlayıcısı ve tüketicisinin tam istek ve yanıt şekli üzerinde anlaştığını doğrular. Tüketiciye ulaşmadan önce bozucu değişiklikleri (yeniden adlandırılmış bir alan, bir tür değişikliği, kaldırılmış bir uç nokta) yakalar. Başka ekiplerin veya müşterilerin bağımlı olduğu bir API yayınlıyorsanız, sözleşme testi isteğe bağlı değildir. Ayrıntılar API sözleşme testinde bulunmaktadır.

Yük ve Performans Testi

Yük testi, API'nizin eşzamanlı trafik altında nasıl davrandığını ölçer: 95. yüzdelik dilimde yanıt süresi, hata oranı, verim ve bozulmaya başladığı nokta. Bir lansmandan önce, bilinen bir trafik yoğunluğundan önce ve yavaş kaymayı yakalamak için periyodik olarak çalıştırın. Bu, fonksiyonel testten ayrı bir disiplindir ve farklı araçlar kullanır; seçenekler için yük testi araçlarına bakın.

Güvenlik Testi

Güvenlik testi, API'nizin reddetmesi gerekenleri reddettiğini kontrol eder: jetonsuz istekler, yanlış kapsama alanına sahip istekler, enjeksiyon girişimleri ve başka bir kullanıcının verilerine erişim. Hassas verilere dokunan her uç nokta en azından kimlik doğrulama ve yetkilendirme kontrollerine ihtiyaç duyar. Tekniklerin tamamı API güvenlik testinde bulunmaktadır.

Her türün ne zaman çalıştığına dair kabaca bir kılavuz aşağıdadır:

Test türü	Yakalananlar	Çalışma zamanı
Fonksiyonel	Yanlış durum, şema veya değerler	Her commit
Entegrasyon	Bozulmuş hizmetten hizmete akışlar	Her commit veya geceleri
Regresyon	Yeni bozulmuş mevcut davranış	Her commit ve sürüm öncesi
Sözleşme	Arayüzde bozucu değişiklikler	Sağlayıcıdaki her commit'te
Yük	Trafik altında yavaşlama ve başarısızlık	Lansman öncesi ve zamanlanmış
Güvenlik	Kimlik doğrulama, enjeksiyon, veri açığa çıkması	Sürüm öncesi ve zamanlanmış

Pozitif, Negatif ve Uç Durumlar

Her uç nokta için üç tür girişi kapsayın. İkinci ve üçüncüyü atlamak, gerçek bir test takımındaki en yaygın boşluktur.

Pozitif durumlar geçerli giriş gönderir ve başarı bekler. İyi biçimlendirilmiş bir gövdeye sahip bir kullanıcı oluşturma isteği 201 ve yeni kaydı döndürür. Bunlar uç noktanın çalıştığını doğrular.

Negatif durumlar geçersiz giriş gönderir ve temiz, doğru bir hata bekler. Eksik bir zorunlu alan 500 değil, 400 döndürmelidir. Jetonsuz bir istek 401 döndürmelidir. Sahip olmadığınız bir kayıt için yapılan bir istek 403 veya 404 döndürmelidir, asla kaydın kendisini döndürmemelidir. Negatif test, API'lerin en sık sızıntı yaptığı veya çöktüğü yer olan hata yönetiminizi doğrular.

Uç durumlar geçerli girişin sınırlarını zorlar: boş bir liste, izin verilen maksimum dize uzunluğu, sıfır, negatif bir sayı, bir Unicode adı, bir yaz saati uygulaması sınırındaki bir zaman damgası. Bunlar, bir eksik veya bir fazla ve taşma hatalarını bulur.

Sağlam bir kural: her pozitif test için en az bir negatif test yazın. Sipariş oluşturma uç noktanızın bir mutlu yol testi varsa ve negatif bir miktar veya eksik bir müşteri kimliği için test yoksa, kapsama alanınız göründüğünden daha zayıftır.

POST /api/orders HTTP/1.1
Content-Type: application/json

{ "customerId": "c_123", "quantity": -5 }

Beklenen: durum 400, gövde quantity adını taşıyan açık bir doğrulama hatası içeriyor. Eğer bu 201 veya 500 döndürürse, mutlu yol testinin asla yakalayamayacağı bir hata buldunuz demektir.

Test Verileri ve Ortamlar

Testler, yalnızca çalıştıkları veri ve ortam kadar güvenilirdir.

Özel test verileri kullanın. Üretim kayıtlarına karşı test yapmayın ve belirli bir satırın varlığına bağımlı olmayın. Testinizin ihtiyaç duyduğu veriyi oluşturun veya çalıştırmanın başlangıcında bilinen bir fikstür ile besleyin. Gerçekçi, çeşitli girdiler için bir veri jeneratörü saatler kazandırır; gerçekçi API test verileri nasıl oluşturulur makalesine bakın.

Testleri bağımsız hale getirin. Her test kendi durumunu kurmalı ve sonra kendini temizlemelidir. Önceki bir testin çalışmasına bağlı olan bir test, rastgele bir sırada başarısız olan bir testtir. Bir değeri bir istekten diğerine (bir kimlik, bir jeton) geçirmeniz gerektiğinde, bunu senaryo içinde açıkça yapın, paylaşılan genel durum üzerinden değil.

Ortamları izole edin. Yerel geliştirme, CI, hazırlık ve üretim için ayrı ortamlar bulundurun. Temel URL'yi, jetonları ve diğer ayarları her ortam için saklayın, böylece aynı test tek bir değişkeni değiştirerek her yerde çalışır. Bir sanal alan ile tam bir test ortamı arasındaki farkı anlamak, doğru hedefi seçmenize yardımcı olur; sanal alan ve test ortamı makalesine bakın.

Değişkenlerle parametreleştirin. Bir testte asla bir ana bilgisayarı veya bir sırrı sabit kodlamayın. Aynı senaryonun yerel, hazırlık ve CI ortamlarına karşı düzenleme yapmadan çalışması için bir ortam değişkenine başvurun.

Sola Kaydırın: Sadece Daha Fazla Değil, Daha Erken Test Edin

Sola kaydırmak, test etmeyi teslimat döngüsünde daha erkene, kodun yazıldığı ana daha yakın bir zamana taşımak anlamına gelir. Bir hata ne kadar geç bulunursa, düzeltme maliyeti o kadar artar. Tasarım aşamasında yakalanan bir şema uyuşmazlığı beş dakikalık bir düzenlemedir. Üretimde yakalanan aynı uyuşmazlık bir olaydır.

Üç pratik hamle, testinizi sola kaydırır:

Önce sözleşmeyi tasarlayın. Uç noktayı oluşturmadan önce API'nin istek ve yanıt şemalarını tanımlayın. Artık bu sözleşmeden testler ve sahte nesneler (mock) oluşturabilir ve uygulama var olmadan önce arayüzü test etmeye başlayabilirsiniz.

Arka uç tamamlanmamışken bir sahte nesneye karşı test edin. Ön uç ve entegrasyon çalışması, gerçek uç noktayı beklemek zorunda değildir. Şemadan oluşturulmuş bir sahte sunucu, tüketicilerin kendi taraflarını paralel olarak test etmelerini sağlar.

Her commit'te hızlı kontroller çalıştırın. Saniyeler içinde çalışan fonksiyonel ve sözleşme testleri, geliştiricinin iç döngüsüne aittir, gece çalışan bir toplu işe değil. Bir geliştirici kırmızı bir test gördüğünde ne kadar erken olursa, düzeltme o kadar ucuz olur.

Bunun tam açıklaması API geliştirmede sola kaydırmalı test makalesindedir. Getirisi basittir: hataları ne kadar erken bulursanız, maliyeti o kadar az olur.

CI'da Testleri Otomatikleştirmek

Bir strateji, ancak sizin müdahaleniz olmadan çalışıyorsa gerçektir. Amaç, her push işleminde test takımınızı çalıştıran, başarısızlık durumunda birleştirmeyi engelleyen ve okuyabileceğiniz bir rapor üreten bir ardışık düzen (pipeline) oluşturmaktır.

API testleri için tipik bir CI ardışık düzeni üç aşamadan oluşur:

Her push işleminde: hızlı fonksiyonel ve sözleşme testlerini çalıştırın. Herhangi bir doğrulama başarısız olursa derlemeyi başarısız sayın. Bu sizin geçidinizdir.
Geceleri veya sürüm öncesi: daha yavaş entegrasyon ve uçtan uca test takımlarını, ayrıca yük ve güvenlik kontrollerini çalıştırın.
Her zaman: makine tarafından okunabilir bir rapor (JUnit XML yaygın formattır) yayınlayın, böylece CI gösterge tablonuz başarılı ve başarısız sayılarını gösterir.

Her push işleminde bir API test takımını çalıştıran minimal bir GitHub Actions işi şöyle görünür:

name: api-tests
on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Run API tests
        run: npm test

Kesin komut kullandığınız araçlara bağlıdır. Desen her yerde aynıdır: kodu dışarı çıkarın, çalışma zamanını kurun, test takımını çalıştırın ve sıfır olmayan bir çıkış kodunun derlemeyi başarısız yapmasına izin verin. Önbelleğe alma, ortam sırları ve raporlama dahil tam CI uygulaması için CI/CD'de API testleri nasıl otomatikleştirilir makalesine bakın.

Apidog Stratejiye Nasıl Uyar?

Yukarıdaki strateji araç bağımsızdır. Tasarım, test, sahtecilik (mocking) ve dokümantasyon için ayrı araçlardan bir araya getirebilirsiniz. Bunun maliyeti sapmadır: belirtim, testler ve sahte nesne (mock) senkronizasyon dışına çıkar ve bunları uzlaştırmak için zaman harcarsınız.

Apidog bunu tek bir yerde birleştirir. API sözleşmesini tasarlar, buna karşı test senaryoları yazarsınız, aynı şemadan bir sahte nesne (mock) oluşturur ve dokümanları yayınlarsınız; hepsi tek bir doğru kaynaktan. Testler ve sahte nesne aynı sözleşmeden geldiği için, sözleşme testi ve sola kaydırmalı test ek bir iş olmaktan çıkar: bunlar varsayılandır.

Stratejinin CI yarısı için, Apidog CLI, kaydettiğiniz test senaryolarını ve test takımlarını arayüzsüz (headless) olarak çalıştırır. Bir Node paketi olduğu için, Node çalıştırabilen herhangi bir CI adımına kolayca entegre edilebilir.

Kurun:

npm install -g apidog-cli

CI'da kaydedilmiş bir senaryoyu veya test takımını çalıştırın. Çalıştırma komutu bayrak tabanlıdır; hedef kimliği, ortam kimliğini ve istediğiniz raporlayıcıları geçirirsiniz:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t <scenarioOrSuiteId> \
  -e <environmentId> \
  -r cli,html,junit

--access-token çalıştırmayı doğrular. Jetonu bir CI sırrı olarak saklayın ve bir ortam değişkeni olarak referans gösterin.
-t, çalıştırmak istediğiniz senaryonun, klasörün veya test takımının kimliğidir.
-e ortam kimliğidir, böylece aynı test takımı bu değeri değiştirerek hazırlık veya CI ortamlarına karşı çalışır.
-r, cli, html, json ve junit'den bir veya daha fazla raporlayıcı seçer. junit çıktısı CI gösterge tablonuzu besler; html insan tarafından okunabilir bir rapor verir.

Veri odaklı bir çalıştırma için, CLI'yi bir veri dosyasına veya kaydedilmiş bir test verisi kimliğine yönlendirin:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t <scenarioId> \
  -e <environmentId> \
  -d ./data/users.csv \
  -r cli,junit

Raporu buluta göndermek için `--upload-report` ekleyin veya belirli bir dalda çalıştırmak için `--branch` kullanın. CLI, kaydedilmiş Apidog senaryolarını ve test takımlarını çalıştırır. Etkileşimli bir istek gönderici veya yük jeneratörü değildir, bu nedenle piramidinizin performans katmanı için özel bir yük aracıyla eşleştirin.

Başlangıç Stratejisi Kontrol Listesi

Bir stratejiyi sıfırdan oluşturuyorsanız, bu listeyi sırasıyla uygulayın.

[ ] Uç noktalarınızı risk ve trafiğe göre sıralayın. İlk olarak en üsttekileri kapsayın.
[ ] Sıralanmış her uç nokta için pozitif bir fonksiyonel test yazın.
[ ] Uç nokta başına en az bir negatif test ekleyin (eksik kimlik doğrulama, geçersiz giriş).
[ ] Liste, sayı veya serbest metin alan uç noktalar için uç durum testleri ekleyin.
[ ] Diğer ekiplerin veya müşterilerin tükettiği her API için sözleşme testleri ekleyin.
[ ] İki veya daha fazla hizmeti geçen akışlar için entegrasyon testleri ekleyin.
[ ] Ortam başına değişkenler ve sırlarla ayrı ortamlar kurun.
[ ] Oluşturulmuş veya önceden belirlenmiş test verileri kullanın; testleri bağımsız tutun.
[ ] CI'da her push işleminde hızlı testleri çalıştırın; başarısızlık durumunda derlemeyi başarısız sayın.
[ ] Yavaş test takımlarını (entegrasyon, yük, güvenlik) geceleri veya sürüm öncesi için zamanlayın.
[ ] Başarılı ve başarısız sayıların görünür olması için bir JUnit raporu yayınlayın.
[ ] API değiştiğinde test takımını gözden geçirin; kaldırılan uç noktalar için testleri silin.

İlk günden hepsine ihtiyacınız yok. En yüksek riskli uç noktalarınızda fonksiyonel ve negatif testlerle başlayın, bunları CI'da çalışır hale getirin ve test takımını oradan dışarı doğru büyütün.

Sıkça Sorulan Sorular

Bir API test stratejisi ile bir test planı arasındaki fark nedir?

Bir strateji, üst düzey yaklaşımdır: hangi test türlerini kullanacağınız, hangi katmanda ve ne zaman çalışacakları. Bir test planı ise belirli bir sürüm veya özellik için somut belgedir: tam uç noktalar, durumlar, veriler ve başarı kriterleri. Strateji stabildir; plan sürümden sürüme değişir.

Piramidin her katmanında kaç test olmalı?

Sabit bir oran yoktur, ancak sayıdan çok şekil önemlidir. Çoğu test altta hızlı tek istek kontrolleri olmalı, ortada daha az entegrasyon ve sözleşme testi olmalı ve en üstte sadece bir avuç uçtan uca iş akışı testi bulunmalıdır. Yavaş üst katman testleriniz hızlı alt katman testlerinizden fazlaysa, dengeyi yeniden kurun.

Fonksiyonel testlerim zaten varsa sözleşme testine ihtiyacım var mı?

Evet, başka ekipler veya müşteriler API'nizi tüketiyorsa. Fonksiyonel testler, bir uç noktanın doğru davrandığını kontrol eder. Sözleşme testleri ise arayüzünün bir tüketiciyi bozacak şekilde değişmediğini kontrol eder. Bir değişiklik, bir uç noktanın çalışmasını sürdürürken yine de onu çağıran herkesi bozabilir.

Yük testlerini ne sıklıkla çalıştırmalıyım?

Her lansmandan veya bilinen trafik yoğunluğundan önce ve performans kaymasını yakalamak için belirli bir zamanlamaya göre (haftalık veya aylık) çalıştırın. Yük testleri yavaş ve kaynak yoğun olduğu için her commit'te yer almazlar. Hızlı katmanları CI'da tutun ve yük testlerini ayrı çalıştırın.

Tüm stratejiyi CI'da otomatikleştirebilir miyim?

Tekrarlanabilir kısımları, evet. Fonksiyonel, entegrasyon, sözleşme ve regresyon testleri bir ardışık düzende sorunsuz çalışır ve birleştirmelerinizi denetler. Yük ve güvenlik testleri genellikle daha yavaş oldukları veya özel altyapıya ihtiyaç duydukları için kendi programlarında çalışır. Apidog CLI gibi arayüzsüz bir test çalıştırıcı, kaydedilmiş senaryolarınızı her push işleminde yürüterek CI kısmını kapsar.