API Test Senaryolarında Hata Ayıklama Adımları

API test senaryolarında hata ayıklama, gönderilen istek ile dönen yanıt arasındaki uyumsuzlukları inceleyerek servis aksaklıklarını çözme sürecidir. Doğru HTTP durum kodlarını, veri yüklerini ve yetkilendirme parametrelerini denetleyerek hataları hızlıca izole edebilirsiniz. Düzenli inceleme adımları sistemlerin güvenli ve kararlı çalışmasını sağlar.

HTTP durum kodları ile gelen yanıtları doğru okuma

Servis haberleşmesinde sunucunun ürettiği ilk tepki durum kodudur. Yanıt gövdesini satır satır taramadan önce üç haneli bu koda bakmak, sorunun kaynağını doğrudan istemci veya sunucu tarafında aramanızı sağlar. Bir API test çalıştırırken beklenmeyen bir aksaklıkla karşılaşırsanız, durum kodunun ait olduğu sayı aralığı ilk ipucunu verir. Böylece uygulamanın mantıksal katmanlarında kaybolmadan inceleme alanınızı daraltabilirsiniz.

İstemci hatalarını ayrıştırma

İstemci kaynaklı pürüzler 4xx serisi yanıtlarla kendisini belli eder. Ekranınızda 400 Bad Request gördüyseniz, sunucuya gönderdiğiniz gövde yapısında zorunlu bir alan eksik kalmış olabilir ya da alan isimlerinde bir yazım yanlışı yapmışsınızdır. Örneğin "user_id" yerine sehven "userId" yazdığınızda sunucu veriyi ayrıştıramaz ve bu hatayı döner. Benzer şekilde, 404 Not Found yanıtı aldığınızda uç nokta yolunu ya da sorguladığınız dinamik kayıt kimliğini denetlemeniz gerekir. URL satırındaki fazladan bir eğik çizgi veya veritabanında henüz bulunmayan dinamik bir ID numarası, kaynağın doğrudan yok sayılmasına yol açar.

Yetkilendirme adımlarında ise 401 Unauthorized ile 403 Forbidden kodları arasındaki sınır çizgisine dikkat etmelisiniz. 401 kodu aldığınızda sunucu kimliğinizi doğrulayamamıştır; yani oturum anahtarı isteğe eklenmemiştir ya da geçersizdir. 403 Forbidden yanıtında ise kimliğiniz gayet iyi bilinir, ancak hesabınızın erişmek istediğiniz veri üzerinde görüntüleme veya silme hakkı yoktur. Bu iki yanıtı birbirine karıştırmamak, yetki seviyesi eksikliklerini sunucu arızası gibi görüp yanlış yerlerde zaman kaybetmenizi önler.

Sunucu hatalarını yorumlama

Sunucu tarafındaki aksaklıklar 5xx serisiyle karşımıza çıkar. 500 Internal Server Error, sunucunun isteğinizi işlerken beklemediği bir durumla karşılaştığını ve uygulamanın çökmesini önlemek için genel bir hata fırlattığını belirtir. Bu kod geldiğinde istemci tarafını kurcalamak yerine sunucu tarafındaki uygulama log kayıtlarını kontrol etmeniz gerekir; çünkü hatanın gerçek sebebi sadece o log dökümünde yatar. 503 Service Unavailable yanıtı ise sunucunun anlık olarak aşırı yüklendiğini ya da bakım modunda olduğunu, yani servisin o an ayakta olmadığını gösterir.

Flaky test nedir?

Kod tabanında hiçbir değişiklik yapılmadığı halde aynı koşullarda bazen başarılı bazen de başarısız sonuç veren tutarsız otomasyon senaryolarına flaky test denir. Yanıt kodlarını okurken sunucunun geçici olarak 503 dönmesi veya ağdaki anlık bir gecikme yüzünden istemcinin zamanaşımına uğraması bu kararsızlığı tetikleyebilir. Kodları doğru ayrıştırmayı öğrendiğinizde, testinizin gerçekten yazılım hatası mı yakaladığını yoksa bu tür geçici dalgalanmalardan mı etkilendiğini kolayca süzebilirsiniz.

API test senaryolarında hata ayıklama için izlenecek temel adımlar

Beklenmeyen bir yanıt aldığınızda karmaşık test adımları arasında kaybolmak yerine doğrudan isteğin omurgasını denetlemeniz gerekir. İlk olarak ana sunucu adresini (base URL), tanımladığınız ortam değişkenlerini ve kullandığınız HTTP metodunu gözden geçirmelisiniz. Yanlışlıkla test ortamı yerine geliştirme sunucusuna istek atmak ya da GET bekleyen bir servise POST göndermek senaryoyu doğrudan kırar. Bu nedenle dinamik değişken havuzunda kayıtlı sunucu URL bilgisinin doğruluğunu her deneme öncesinde teyit etmek mantıklıdır.

İstek kurgusunu doğruladıktan sonra, sorunu ortamdan ayırmak için bir cURL komutu çıktısı üretebilirsiniz. Hazırladığınız bu cURL komutunu izole terminal penceresinde doğrudan çalıştırdığınızda, arayüzdeki olası önbellek veya eklenti kaynaklı sapmaları tamamen devre dışı bırakırsınız. Böylece aldığınız yanıtın istemci aracından mı yoksa doğrudan uzak sunucudan mı kaynaklandığını anında görürsünüz. Terminal üzerinden dönen ham yanıt, sistemin gerçekte ne tür bir veri beklediğini anlamanız için en temiz ortamı sunar.

Servislerin veri alışverişi yapabilmesi, başlık alanında belirttiğiniz tanımların uyumuna bağlıdır. İstek başlığı (request header) içerisindeki Content-Type ve Accept değerlerini eksiksiz şekilde sağlamalısınız. Örneğin gövdede veri aktarırken Content-Type değerini "application/json" yapmazsanız, sunucu gönderdiğiniz veriyi düz metin sayarak isteği reddeder. Aynı şekilde Accept başlığıyla beklediğiniz formatı belirtmediğinizde sunucu desteklenmeyen bir biçim dönebilir ve kurguladığınız API test yapısı bu uyumsuzluk yüzünden durabilir.

Uç noktalara erişim sağlarken yaşanan aksaklıkların büyük bölümü kimlik doğrulama aşamasında ortaya çıkar. Yetkilendirme token süresini ve başlığa eklenen Bearer önekini istek öncesi kontrol etmeniz gerekir. Süresi dolmuş bir erişim belirteci ya da önek ile anahtar arasında unutulan tek bir boşluk bile erişim hatası almanıza yol açar. Token değerini istek zincirine iletmeden önce geçerlilik zamanını kontrol eden ufak kontroller kurmak, sizi uzun süren gereksiz arayışlardan korur.

Bu temel adımları bir alışkanlık haline getiren uzmanlar, ekiplerine doğrudan hız ve kalite kazandırır. Sektördeki teknik yetkinlik düzeyi arttıkça Türkiye pazarında QA engineer maaşları da bu teknik becerilere ve hata çözme hızına göre şekillenir. Siz de karşılaştığınız her hatayı adım adım ayırarak analiz ettiğinizde, hem sistem üzerindeki hakimiyetinizi artırabilir hem de sorunları dakikalar içinde çözüme kavuşturabilirsiniz.

Siz de bir çağrının neden tıkandığını ararken sorgu dizgilerini (query string) ve yol değişkenlerini (path variables) gözden kaçırıyor olabilirsiniz. Adres çubuğundaki özel karakterlerin ya da Türkçe harflerin URL kodlamasına (URL encoding) girmemesi, sunucunun yolu tanıyamamasına yol açar. Boşluk yerine gelen artı işaretlerini veya eksik kalan eğik çizgileri kontrol ettiğinizde istek doğrudan hedefe varır. Uç noktanın beklediği sıralamayı ve zorunlu alanları API dökümanıyla tek tek eşleştirdiğinizde, senaryonun akışını bozan ufak bir yazım hatasını bile kolayca yakalayabilirsiniz.

JSON gövdesindeki veri uyuşmazlıklarını tespit etme yolları

Servisler arasında akan veriler büyüdükçe, yanıt gövdesindeki küçük bir biçim sapması bile tüm akışı kesintiye uğratabilir. Otomatik kontroller kurarken JSON şema doğrulama (schema validation) araçlarıyla zorunlu alan kontrolü yapmak bu nedenle ilk adımdır. Hazırladığınız şema tanımı; hangi anahtarların yanıtta kesinlikle yer alması gerektiğini, hangilerinin ise isteğe bağlı bırakıldığını kurallara bağlar. Böyle bir denetim mekanizması kurduğunuzda, arka planda eksik dönen bir kullanıcı kimliği veya adres alanı anında kırmızı bayrak kaldırır ve hatayı derinlemesine aramadan kaynağında yakalarsınız.

Veri tipleri ve alan adları

Veri türlerindeki gizli tutarsızlıklar, ayrıştırma adımlarında beklenmedik çökmelere yol açar. Sayısal değerlerin string tırnak içine alınması kaynaklı tip hataları bu durumun en bilinen örneğidir. Örneğin, sunucunun "fiyat": 150 biçiminde yalın bir tamsayı beklediği yerde istemci "fiyat": "150" şeklinde metin gönderdiğinde, arka uç kodu bu değeri matematiksel işleme sokamaz ya da doğrudan reddeder. Kod tabanınızda veri modellerini incelerken sayıların ve doğru-yanlış bildiren boolean değerlerin tırnak işaretlerinden arındırıldığını doğrulayabilirsiniz.

Büyük ve küçük harf kullanımı da ekipler arasında sıkça gözden kaçar. Sunucu sizden userId biçiminde deve dikeni (camelCase) beklerken isteğinizde user_id gönderirseniz, sistem bu anahtarı tanımsız sayar. Alanın yok sayılması, veritabanına eksik kayıt düşmesine veya doğrulama adımlarının başarısız olmasına sebep olur. Bu uyuşmazlıkları engellemek için servis sözleşmelerindeki isimlendirme standartlarını dikkatle karşılaştırabilirsiniz.

Şema doğrulama teknikleri

Zaman damgaları, servislerin farklı coğrafyalarda ve sunucularda barınması nedeniyle karmaşık sorunlar çıkarabilir. Tarih-saat formatlarında ISO 8601 ve UTC saat dilimi uyuşmazlığı, kayıtların sisteme birkaç saat ileri ya da geri işlenmesine yol açar. Bir yanıt 2024-03-15T10:30:00Z şeklinde standart sıfır meridyeni gösterirken, başka bir servisin saat dilimi bilgisi içermeyen 15-03-2024 10:30 metnini üretmesi eşleştirmeleri bozar. API test süreçlerinde tarih alanlarını denetlerken, gelen bilginin biçim kuralına tam uyup uymadığını düzenli ifadelerle (regex) ya da tarih ayrıştırıcılarıyla kontrol edebilirsiniz.

Kayıtların bulunmadığı durumlarda üretilen yanıt yapıları da dikkat gerektirir. Boş dönen diziler (array) ile null değerlerin serileştirme farkları istemci tarafında doğrudan çökme üretebilir. Örneğin, sistemde sipariş bulunmadığında yanıtın "siparisler": [] şeklinde boş bir liste dönmesi beklenirken doğrudan "siparisler": null iletilmesi durumunda, döngü kurmaya çalışan istemci nesne bulamadığı için kırılır. Şemanızda bir alanın hem dizi hem de boş değer alıp alamayacağını önceden tanımlayarak bu tür tutarsızlıkların önüne geçebilirsiniz.

Postman konsolu üzerinden istek trafiğini inceleme

Gönderdiğiniz bir çağrının arka planda tam olarak hangi duraklardan geçtiğini görmek, beklenmedik yanıtları anlamlandırmanın en kestirme yoludur. Postman arayüzünün sol alt köşesinde yer alan konsol penceresi, uygulamanın işletim sistemi ve ağ kartı seviyesinde gerçekleştirdiği tüm veri alışverişini kaydeder. Bir API test adımı çalıştırdığınızda, arayüzdeki şık alanların ötesine geçip giden ve gelen ham baytları doğrudan bu ekranda izleyebilirsiniz. Böylece istemcinin hazırladığı veri paketi ile sunucunun karşıladığı içerik arasındaki farkları anında yakalarsınız.

Ağ trafiğini izleme ve ham inceleme

Konsol kaydını açtığınızda karşınıza çıkan ilk somut bilgi, alan adının hangi gerçek IP adresine çözümlendiği ve isteğin tam olarak hangi adrese ulaştığıdır. DNS kaynaklı bir gecikme yaşadığınızda veya istek yanlış bir sunucu kümesine yöneldiğinde, konsoldaki hedef IP satırı size yolu gösterir. Çoğu zaman şirket içi geliştirme ortamlarında tanımlı özel alan adları beklenmedik adreslerle eşleşebilir; bu tür yönlendirme sapmalarını doğrudan konsoldan okuyabilirsiniz. Giden istek satırını genişlettiğinizde sistemin eklediği gizli proxy yönlendirmeleri de açıkça listelenir.

İstek gövdesinin yanı sıra giden ham başlıklar (raw headers) sekmesi, yetkilendirme veya içerik tipi gibi alanların sunucuya nasıl iletildiğini doğrular. Otomatik eklenen başlıklar bazen sunucu tarafında beklenmeyen davranışlara yol açar; konsol bu gizli eklemeleri gizlemeden önünüze serer. Ayrıca uzak sunucuyla kurulan bağlantıda SSL el sıkışma hatalarını ve ağ zaman aşımı (timeout) sürelerini de burada adım adım takip edebilirsiniz. Sertifika süresi dolmuş bir test sunucusu ya da yanıt vermeyen bir ağ geçidi, hata fırlattığında konsolda kırmızı renkli ayrıntılı bir iz kaydı bırakır.

Ön-istek scriptleri ve filtreleme

İstek gönderilmeden hemen önce çalışan ön-istek (pre-request) scriptlerindeki değişken atamalarını console.log komutları ile konsola yazdırabilirsiniz. Dinamik olarak üretilen bir oturum anahtarı, zaman damgası ya da şifrelenmiş bir imza metninin o an hangi değere ulaştığını görmek için bu kayıtlar büyük kolaylık sunar. Kodunuzun içine yerleştireceğiniz küçük bir yazdırma komutu, çalışma anındaki değişken durumunu açıkça gösterir. Böylece istek gövdesine aktarılan verinin daha yola çıkmadan bozulup bozulmadığını saniyeler içinde anlarsınız.

Günün sonunda yüzlerce çağrının art arda dizildiği kapsamlı bir koşumda konsol penceresi hızla karmaşık bir döküme dönüşebilir. Arama çubuğunu ve filtre butonlarını kullanarak yalnızca uyarı ve hata düzeyindeki kayıtları ekranda tutabilirsiniz. Ağ bağlantısı kopukluklarını, geçersiz kılınan güvenlik sertifikalarını ya da yanıt dönmeyen zaman aşımı kayıtlarını süzdüğünüzde doğrudan arızanın merkezine odaklanırsınız. Konsol geçmişini temizleyip tek bir adımı yeniden tetiklemek, izole edilmiş berrak bir hata izi elde etmenizi sağlar.

API testlerinde hata giderme yöntemleri ve otomasyon stratejileri

Sürekli dağıtım hatlarında koşan adımların beklenmedik anlarda durması, yazılım teslimatını yavaşlatır. Otomasyon mimarisinde dış servislerin yanıt vermemesi ya da anlık sunucu gecikmeleri sıklıkla yalancı alarmlar üretir. Boru hattındaki bu pürüzleri ayıklamak adına üçüncü taraf sistemleri WireMock yardımıyla izole bir kurguya dönüştürebilirsiniz. Dış sistemden beklenen HTTP gövdesini taklit ettiğinizde, uzaktaki sağlayıcının planlı bakım çalışması veya bant genişliği daralması kontrollerinizi kesintiye uğratmaz.

Ağ katmanında yaşanan milisaniyelik paket kayıpları isteklerin zamanaşımına uğramasına yol açar. Başarısız olan her çağrıyı peş peşe ve aynı hızda yinelemek sunucu yükünü artırır, hatta sistemin kendini korumaya almasına neden olur. Bunun yerine üstel geri çekilme (exponential backoff) algoritmasıyla çalışan bir yeniden deneme mekanizması kurabilirsiniz. İlk hata sonrasında bir saniye bekleyen sistem, ikinci denemede iki, üçüncüsünde ise dört saniye ara vererek hatta nefes payı tanır.

Entegrasyon testi nedir?

Farklı modüllerin, veritabanının ve mikroservislerin birbiriyle kurduğu iletişimin sözleşmelere uygun biçimde akıp akmadığını doğrulayan denetim türüdür. Tek başına hatasız çalışan iki bağımsız bileşen, ağ üzerinden bağlandığında veri aktarımında uyumsuzluk gösterebilir. Örneğin sipariş servisi onay üretirken ödeme servisinin bunu zamanında teslim alamaması akışı bozar. Bu nedenle modüller arası köprüleri düzenli aralıklarla sınamak gerekir.

Asenkron çalışan yapılarda istek gönderildikten hemen sonra doğrulama adımına geçmek senaryoları yanıltır. Sabit süreler koyup beş saniye boyunca akışı körü körüne durdurmak koşum sürelerini gereksiz yere uzatır. Dinamik bekleme (polling) yaklaşımında ise yanıt gövdesindeki durum verisi belirli periyotlarla sorgulanır. İstenen veri üçüncü saniyede hazır hale geldiğinde sonraki adıma geçilir; böylece hem gereksiz duraklamaların önüne geçilir hem de zamana bağlı kırılmalar engellenir.

Bir test senaryosunun veritabanına eklediği bir kayıt, ardından gelen başka bir senaryonun beklenmedik sonuçlar üretmesine sebep olabilir. Her çalıştırma bittiğinde veritabanını temizleyen ve başlangıç durumuna getiren temizlik scriptleri kullanmanız gerekir. Tablolardaki yabancı anahtar kısıtlamalarını dikkate alarak oluşturulan silme veya sıfırlama komutları, bir sonraki koşumun temiz bir zemin üzerinde başlamasını sağlar.

Aşağıdaki tabloda otomasyon altyapılarında tercih edilen test ve bakım destek modellerinin kapsamları özetlenmiştir.

Doğru kurgulanmış bir API test süreci, kod tabanındaki değişikliklerin canlı ortama aktarılma hızını güvenle artırır. Hata kaynaklarını izole ederek sunucu dalgalanmalarını doğru stratejilerle yönettiğinizde ekipler hata aramak yerine ürün geliştirmeye odaklanır.

API test süreçleriniz için uzman desteği alın

Servis hatalarını hızla izole etmek ve test süreçlerinizi iyileştirmek için teknik ekibimizle görüşün.

Bilgi Al WhatsApp