Bir web kancasını test etmek için, sağlayıcıya erişilebilir bir URL verir, gerçek bir olayı tetikler ve ardından işleyicinizin yükü kabul ettiğini ve doğru şekilde tepki verdiğini doğrularsınız. Zor kısım, uygulamanızın arayan değil, alıcı olmasıdır, bu nedenle sadece "Gönder" tuşuna basıp yanıtı okuyamazsınız. Bu kılavuz, işleyicinizi baştan sona doğrulamak için ihtiyacınız olan araçları (inceleme hizmetleri, yerel tüneller, sağlayıcı tetikleyicileri) ve tekrarlanabilir bir süreci anlatmaktadır.
Web Kancalarını Normal API'lerden Daha Zor Test Etmenin Nedenleri
Normal bir API çağrısında, isteği siz kontrol edersiniz. Yöntemi seçersiniz, gövdeyi ayarlarsınız, ateşlersiniz ve yanıtı okursunuz. Web kancaları bunu tersine çevirir. Sağlayıcı, kendi zaman çizelgesinde, tanımladığı bir yük ile isteği size gönderir. Bu rol değişimi dört test problemi yaratır.
İlk olarak, olayı varsayılan olarak kendiniz tetikleyemezsiniz. Bir payment_intent.succeeded olayı yalnızca Stripe karar verdiğinde tetiklenir, bu yüzden bir tanesini zorlamak için sağlayıcı araçlarına ihtiyacınız vardır.
İkincisi, teslimat asenkrondur. Olay, yukarı akış eylemi tamamlandığında gelir, bu nedenle testiniz bir dönüş değeri üzerinde bloklamak yerine gelen bir isteği yakalamalıdır.
Üçüncüsü, yük şekli sağlayıcı tarafından tanımlanır. İşleyicinizin GitHub, Stripe veya Slack'in tam olarak ne gönderdiğini ayrıştırması gerekir.
Dördüncüsü, çoğu sağlayıcı isteklerini imzalar. Uç noktanızın, gövdeye güvenmeden önce bir imza başlığını doğrulaması gerekir ve bunu atlayan bir test gerçek hataları gizler. Daha derinlemesine bir inceleme için, web kancası imza doğrulama kılavuzumuza bakın.
Hala web kancalarının entegrasyonunuz için doğru model olup olmadığına karar vermeye çalışıyorsanız, web kancaları ve yoklama ile web kancası ve WebSocket karşılaştırmaları, avantaj ve dezavantajları inceler.
Web Kancası Test Araç Seti
Genellikle aynı oturumda dört tür araca başvurursunuz: ham yükleri görmek için bir yakalama hizmeti, dizüstü bilgisayarınıza ulaşmak için bir tünel, gerçek olayları tetiklemek için sağlayıcı tetikleyicileri ve işleyicinizi doğrulamak için bir onaylama aracı.
1. İnceleme ve Yakalama Hizmetleri
Tek bir işleyici kodu yazmadan önce, sağlayıcıyı tek kullanımlık bir URL'ye yönlendirin ve gerçekten ne gönderdiğine bakın. Bu hizmetler size herkese açık bir uç nokta sağlar ve her isteği gerçek zamanlı olarak gösterir.
webhook.site, sayfa yüklendiği anda size benzersiz, rastgele bir URL ve e-posta adresi verir. Ona gönderilen her şey anında görünür: tam gövde, başlıklar ve yöntem. Ücretsiz URL'ler 7 gün sonra sona erer ve 100 istekle, maksimum 10 MB istek boyutuyla sınırlıdır. Ücretli planlar kalıcı URL'ler, sınırsız istek ve son 10.000 isteğin geçmişini ekler.
Beeceptor, bir web kancası alıcısı olarak kullanabileceğiniz ve gelen yükleri gerçek zamanlı olarak inceleyebileceğiniz ücretsiz bir HTTPS uç noktası sunar. Ayrıca taklit sunucu uç noktaları da sağlar, böylece aynı araçtan yakalama ve simülasyon yapabilirsiniz.
Pipedream RequestBin, yaygın olarak kullanılan başka bir istek yakalama aracıdır. Yakalama hizmetleri ücretsiz limitlerini sık sık değiştirdiğinden, katman özelliklerini öğrenmek için mevcut belgelerine bakın.
Bunları tek bir soruyu yanıtlamak için kullanın: gerçek yük neye benziyor? Tekrarlanabilir testler oluşturduğunuzda kullanmak üzere bir örnek kopyalayın.
2. Yerel Geliştirme: localhost'u Bir Tünel ile Açığa Çıkarma
Sağlayıcılar makinenizdeki localhost:3000 adresine ulaşamazlar. Bir tünel, trafiği yerel bağlantı noktanıza yönlendiren herkese açık bir HTTPS URL'si oluşturur, böylece işleyicinizi düzenleyicinizde çalıştırabilir ve canlı olarak hata ayıklayabilirsiniz.
ngrok yaygın bir seçimdir. Kurun, bir kez kimlik doğrulaması yapın, ardından bir bağlantı noktasını yönlendirin.
brew install ngrok # macOS
ngrok config add-authtoken $YOUR_TOKEN
ngrok http 3000 # herkese açık bir HTTPS URL'sini localhost:3000'e yönlendirir
Ücretsiz ngrok hesapları otomatik olarak seçilen bir geliştirme alan adı alır. Özel alan adları ücretli bir plan gerektirir.
Cloudflare'ı tercih ediyorsanız, cloudflared tek bir komutla hızlı bir tünel çalıştırır.
cloudflared tunnel --url http://localhost:3000
Tünelin yazdırdığı herkese açık URL'yi sağlayıcının web kancası ayarlarına yapıştırın ve gelen olaylar yerel sunucunuza düşer. Bu kalıbın daha kapsamlı bir incelemesi için, web kancası hizmetleriyle localhost API'lerini nasıl test edeceğinize bakın.
3. Sağlayıcıdan Test Olaylarını Tetikleme
Bir yakalama URL'si yalnızca bir şey gönderildikten sonra yardımcı olur. Çoğu büyük sağlayıcı, isteğe bağlı olarak test olaylarını tetiklemek için araçlar sunar, böylece gerçek ödemeler veya push'lar üretmek zorunda kalmazsınız.
Stripe CLI en temiz örnektir. stripe listen komutu, Stripe sanal alanınızdan gelen canlı olayları yerel bir yola iletir ve uygulamanızın yapılandırmasına koyacağınız bir web kancası imza sırrı yazdırır.
# Tüm olayları yerel işleyicinize iletin:
stripe listen --forward-to localhost:3000/webhooks
# Yalnızca belirli olaylara filtreleyin:
stripe listen --events payment_intent.succeeded,checkout.session.completed \
--forward-to localhost:3000/webhooks
Dinleyici çalışırken, stripe trigger bir test olayı tetikler. Tetiklemenin düzgün bir şekilde desteklenen API nesneleri oluşturduğunu ve yan etkileri olduğunu unutmayın: payment_intent.succeeded ayrıca payment_intent.created olayını da yayar.
stripe trigger payment_intent.succeeded
stripe trigger checkout.session.completed
stripe trigger --help # desteklenen tüm olayları listeler
GitHub, tekrar oynatabileceğiniz kısa bir teslimat geçmişi tutar. Deponuza gidin, ardından Ayarlar'a, sonra "Kod ve otomasyon" altında Web Kancaları'na gidin. Web kancası URL'sine tıklayın, "Son teslimatlar" sekmesini açın, bir teslimat GUID'sine tıklayın ve "Yeniden Teslim Et"e tıklayın. İki kısıtlama önemlidir: yalnızca son 3 gündeki teslimatları yeniden teslim edebilirsiniz ve depoya yönetici erişimine ihtiyacınız vardır. GitHub başarısız teslimatları otomatik olarak yeniden teslim etmez, bu nedenle tekrar oynatma manueldir.
Slack gelen web kancalarını test etmek en basitidir. Web kancası URL'sine JSON'u POST ederek bir mesaj gönderirsiniz. Minimum yük sadece bir text alanıdır.
curl -X POST https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX \
-H 'Content-type: application/json' \
-d '{"text":"Merhaba dünya."}'
Slack web kancası URL'si bir sırdır. Slack sızan URL'leri iptal eder, bu nedenle istemci tarafı kodundan ve herkese açık depolardan uzak tutun.
4. İşleyicinizi Doğrulama
Yakalama ve tetikleme, tesisatın çalıştığını kanıtlar. İşleyicinizin doğru olduğunu kanıtlamazlar. Son araç, oluşturulmuş bir yük gönderir ve yanıtı ve yan etkileri kontrol eder. En temel haliyle, bu, temsili bir gövdeye sahip bir curl komutudur.
curl -X POST http://localhost:3000/webhooks \
-H 'Content-Type: application/json' \
-H 'Stripe-Signature: t=...,v1=...' \
-d '{"id":"evt_test","type":"payment_intent.succeeded","data":{"object":{"id":"pi_123","status":"succeeded"}}}'
Tek bir curl, hızlı bir test için iyidir. CI'da çalışan tekrarlanabilir, onaylanmış testler istediğinizde yetersiz kalır. İşte bu noktada özel bir API aracı yerini bulur.
Apidog ile Web Kancalarını Test Etme
Apidog, API'leri tasarlamak, hata ayıklamak, test etmek, taklit etmek ve belgelemek için hepsi bir arada bir API platformudur. Özel bir "web kancası gelen kutusu" yoktur, bu nedenle bu bölüm, gerçekten neyi iyi yaptığını dürüstçe belirtir: yükler oluşturma, kaydetme, yanıtları onaylama ve bir taklit sunucuyla sağlayıcı yerine geçme.
Örnek Bir Yükü Oluşturun ve Yeniden Kullanılabilir Bir İstek Olarak Kaydedin
webhook.site'tan yakaladığınız (veya sağlayıcının belgelerinden kopyaladığınız) yükü alın ve bunu bir Apidog isteği haline getirin. Yöntemi POST olarak ayarlayın, JSON gövdesini yapıştırın ve işleyicinizin kontrol ettiği imza başlığı dahil olmak üzere sağlayıcının gönderdiği başlıkları ekleyin.
Bu isteği uç noktanıza kaydedin. Artık her seferinde bir curl komutunu yeniden yazmak yerine, işleyicinize bilinen iyi (veya kasıtlı olarak hatalı biçimlendirilmiş) bir yükü POST etmek için tekrarlanabilir, sürüm kontrollü bir yolunuz var.
Görsel Onay Oluşturucu ile Yanıtı Doğrulayın
Yükü göndermek testin yarısıdır. Diğer yarısı, işleyicinizin ne döndürdüğünü kontrol etmektir. İstek veya senaryo adımında, Son İşleyicileri açın, "+ Ekle"ye tıklayın ve "Onaylama"yı seçin. Apidog, kod olmadan yapılandırdığınız bir doğrulama kuralı ekler.
Onaylamayı yanıt gövdesine yöneltin ve JSON kökü için $ kullanın. Örneğin, $.data.status'u hedefleyin, koşulu Eşittir olarak ayarlayın ve succeeded ile karşılaştırın. İsteği çalıştırın ve sonuç Onaylama sekmesinde görünür. Görsel onaylamalar değerleri dizeler olarak karşılaştırır. Tür hassasiyetli kontroller (gerçek bir sayı, bir boolean) gerektiğinde, Postman uyumlu pm.test sözdizimini kullanarak özel bir betiğe geçin.
Bu, "200 döndürdü" ifadesini "200 döndürdü, durum alanı 'succeeded' ve sipariş kimliği eşleşiyor" haline getirir. Başarılı yolu, eksik alan durumunu ve kötü imza reddini kapsamak için bir senaryoya birden fazla onaylama oluşturun.
Sağlayıcı Yerine Taklit Sunucu Kullanın
Bazen diğer yönü test etmek istersiniz: yığınınızdaki bir hizmetin bir sağlayıcıyı çağırması. Yerel test sırasında gerçek sağlayıcıya hiç vurmak istemeyebilirsiniz. Apidog'un taklit sunucusu, onun yerine geçmenizi sağlar.
Apidog üç tür taklit sunucu sunar. Yerel Taklit (Local Mock) masaüstü istemcisiyle çalışır ve yalnızca istemci açıkken çalışır. Bulut Taklit (Cloud Mock) Apidog sunucularında barındırılır, 7/24 çalışır ve açılır veya kapanır (varsayılan olarak kapalıdır). Koşucu Taklit (Runner Mock) kendi barındırdığınız koşucu altyapısında çalışır ve ekibinizle paylaşılır. Her HTTP uç noktasının bir Taklit modülü vardır; Taklit URL'sini Tasarım modundaki API sekmesinden veya Hata Ayıklama modundaki Taklit sekmesinden kopyalayın. Yalnızca / ile başlayan yollar taklit ortamına yönlendirilir. Testler sırasında kodunuzu bu taklit URL'ye yönlendirin ve entegrasyonunuz, gerçek API çağrıları veya yan etkiler olmadan öngörülebilir sağlayıcı yanıtları alır.
Apidog CLI ile CI'da Web Kancası Testlerini Çalıştırma
Senaryonuz yerel olarak geçtikten sonra, her push işleminde Apidog CLI ile çalıştırın. Node.js v16 veya sonraki bir sürümünü gerektirir.
npm install -g apidog-cli
node -v && apidog -v && which node && which npm && which apidog # kurulumu doğrulayın
Kaydedilmiş bir senaryoyu çevrimiçi çalıştırın, senaryonun CI/CD "Komut satırı" sekmesinden erişim belirtecini ve kimliklerini geçirin.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -d 3497013 -r html,cli
Burada -t test senaryosudur, -e ortamdır (zorunlu), -d test verisidir (bir CSV veya JSON dosya yolu veya depolanmış bir veri kümesi kimliği) ve -r, cli, html, json ve junit kabul eden raporlayıcıları ayarlar. Tam bir komut satırı incelemesi için, Apidog CLI eğitimine bakın.
Kendi web kancası testlerinizi görsel olarak oluşturmak ve onaylamak ister misiniz? Apidog'u ücretsiz deneyin, kredi kartı gerekmez.
Adım Adım Bir Web Kancası Test İş Akışı
Araçları bir araya getirerek, tekrarlanabilir bir sıra aşağıdadır.
- Gerçek yükü inceleyin. Sağlayıcıyı webhook.site URL'sine yönlendirin ve gerçek bir olayı yakalayın. Gövde şeklini, başlıkları ve imza biçimini not alın.
- Kodunuza ulaşın. İşleyicinizi yerel olarak başlatın,
ngrok http 3000veyacloudflaredile bir tünel açın ve herkese açık URL'yi sağlayıcının web kancası yapılandırmasına yerleştirin. - Gerçek bir olay tetikleyin. Tünel aracılığıyla gerçek bir olay göndermek için
stripe trigger, GitHub'ın Yeniden Teslim Et düğmesini veya bir Slack POST'unu kullanın. - İmza işlemeyi doğrulayın. Aynı yükü geçerli bir imza ile gönderin ve ardından bozuk bir imza ile tekrar gönderin. İşleyicinizin ilkini kabul etmesi ve ikincisini reddetmesi gerekir.
- Yanıtı ve yan etkileri onaylayın. Yükü bir Apidog isteği olarak kaydedin, yanıt gövdesine ve durumuna onaylamalar ekleyin ve veritabanı satırının veya aşağı akış çağrısının gerçekleştiğini doğrulayın.
- Otomatikleştirin. Senaryoyu Apidog CLI'ya taşıyın, böylece her değişiklikte CI'da çalışır.
Sadece bir web kancası tüketmek yerine, web kancası sistemini tasarlıyorsanız, güvenilir web kancaları nasıl tasarlanır ve ödeme web kancası en iyi uygulamaları yeniden denemeleri, ıdempotence'ı ve güvenliği kapsar. Daha geniş bir resim için, web kancaları API kılavuzu ve web kancaları ve olay odaklı mimari, web kancalarının daha büyük bir sisteme nasıl uyduğunu açıklar.
Sıkça Sorulan Sorular
Bir web kancasını nasıl test edersiniz?
Sağlayıcıya erişilebilir bir URL verin, gerçek veya test olayını tetikleyin, ardından işleyicinizin yükü aldığını, imzayı doğruladığını, doğru durumu döndürdüğünü ve beklenen yan etkiyi gerçekleştirdiğini doğrulayın. Önce gerçek bir yükü yakalayın, ardından testin her seferinde aynı şekilde çalışması için onaylamalarla tekrarlanabilir bir istek oluşturun.
Web kancalarını yerel olarak nasıl test edersiniz?
İşleyicinizi yerel bir bağlantı noktasında çalıştırın, ardından sağlayıcının makinenize ulaşabilmesi için bir tünel ile açığa çıkarın. ngrok http 3000 veya cloudflared tunnel --url http://localhost:3000 kullanın, herkese açık HTTPS URL'sini sağlayıcının web kancası ayarlarına yapıştırın ve bir olay tetikleyin. Gelen istekler, kesme noktaları ayarlayıp canlı olarak inceleyebileceğiniz yerel sunucunuza düşer.
Postman ile bir web kancasını nasıl test edersiniz?
Postman, oluşturulmuş bir yükü uç noktanıza POST edebilir ve yanıtı onaylayabilir, ancak kendi başına gerçek bir gelen web kancasını alamaz. Aynısı Apidog için de geçerlidir: sağlayıcının yükü ve başlıklarıyla bir istek oluşturursunuz, yanıt gövdesine ve durumuna onaylamalar eklersiniz ve bunu yeniden kullanılabilir bir test olarak kaydedersiniz. Gerçek bir gelen olayı yakalamak için aracı bir yakalama hizmeti veya bir tünel ile eşleştirin.
Stripe web kancalarını nasıl test edersiniz?
Stripe CLI'yi kullanın. Sanal alan olaylarını işleyicinize yönlendirmek ve bir imza sırrı almak için stripe listen --forward-to localhost:3000/webhooks komutunu çalıştırın. Ardından gerçek bir test olayını tetiklemek için stripe trigger payment_intent.succeeded (veya stripe trigger --help'den herhangi bir olay) komutunu çalıştırın. Tetikleme, desteklenen API nesneleri oluşturur ve basamaklı olabilir, bu nedenle payment_intent.succeeded ayrıca payment_intent.created olayını da yayar.
Bir Slack web kancasını nasıl test edersiniz?
Gelen web kancası URL'sine JSON'u POST edin. Minimum geçerli yük, Content-type: application/json başlığıyla gönderilen {"text":"Merhaba dünya."} şeklindedir. Başarılı bir test, yapılandırılmış kanala mesajı gönderir. Slack sızan web kancası URL'lerini iptal ettiği için URL'yi gizli tutun.
Bir web kancası URL'sini nasıl test edersiniz?
URL'ye örnek bir POST gönderin ve başarılı bir durum döndürdüğünü ve doğru davrandığını doğrulayın. En hızlı kontrol, temsili bir gövdeye sahip tek bir curl'dir. Gerçek bir test için, önce gerçek bir yükü yakalayın, geçerli ve geçersiz imzalarla gönderin ve sadece 200 durumunu kontrol etmek yerine yanıtı ve yan etkileri onaylayın.