Insomnia, Kong tarafından istek göndermek ve yanıtları incelemek için geliştirilmiş bir API istemcisidir. Temiz, dikkat dağıtmayan arayüzü ve HTTP, REST, GraphQL, gRPC, SOAP ve WebSocket'i tek bir yerden desteklemesiyle bilinir. Geliştiriciler, ağır bir IDE tarzı araçtan daha hafif, ancak gerçek test işlerini yapabilecek kapasitede bir şey istediklerinde Insomnia'yı tercih ederler.
Bu kılavuz, bir API'yi Insomnia'da baştan sona nasıl test edeceğinizi gösterir. Bir istek koleksiyonu oluşturacak, bir yanıt gönderip inceleyecek, temel URL'leri ve belirteçleri değiştirebilmek için ortamlar ayarlayacak ve otomatik olarak çalışan onaylamalar (assertions) yazmak için test paketleri özelliğini kullanacaksınız. Örnekler genel bir API kullandığından hemen takip edebilirsiniz.
Insomnia'yı kurun ve bir istek oluşturun
Insomnia'yı resmi Kong sitesinden indirin ve platformunuza kurun. İlk başlatmada Insomnia, oturum açmak isteyip istemediğinizi sorar. İsterseniz hesap olmadan yerel olarak çalışmayı seçebilirsiniz ve Insomnia verilerinizi kendi makinenizde saklar. Bulut senkronizasyonu isteğe bağlıdır ve aşağıda ele alacağımız 8. sürümde değişen şey budur.
Insomnia, çalışmaları koleksiyonlar ve belgeler halinde düzenler. Panoda Oluştur'a tıklayın ve İstek Koleksiyonu'nu seçin. Buna "Kullanıcı API testleri" gibi net bir ad verin. Koleksiyonun içinde + düğmesine tıklayın ve HTTP İsteği'ni seçin.
Bir istek bir metot ve bir URL gerektirir. GET'i seçin ve gerçek bir uç nokta girin. JSONPlaceholder hizmeti pratik için iyi çalışır:
GET https://jsonplaceholder.typicode.com/users/1
Gönder'e tıklayın. Sağ bölme, yanıt gövdesini, durum kodunu, yanıt süresini ve boyutunu gösterir. Insomnia, JSON'ı otomatik olarak güzel biçimde yazdırır ve yanıt büyük olduğunda kullanışlı olan bir JSONPath veya XPath sorgusuyla gövdeyi filtrelemenizi sağlar.
Metotları, parametreleri ve kimlik doğrulamayı yapılandırın
Basit bir okumadan daha fazlası için isteğe daha fazla ayar yapacaksınız. Insomnia bunları URL çubuğunun altındaki sekmelerde gruplandırır.
Gövde sekmesi istek yüklerini yönetir. Bir POST için JSON'ı seçin ve verileri girin:
{
"name": "Daniel Okafor",
"email": "daniel.okafor@example.com"
}
Bir gövde türü seçtiğinizde Insomnia sizin için Content-Type başlığını ayarlar. Sorgu sekmesi, URL'yi elle düzenlemeden sorgu dizesi parametreleri eklemenizi sağlar, bu da uzun bir URL'yi okunabilir tutar ve tek tek parametreleri açıp kapatmanıza olanak tanır. Başlıklar sekmesi, özel bir X-Request-Id veya yanıt biçimini müzakere etmek için bir Accept başlığı gibi API'nin beklediği diğer her şey içindir.
Kimlik Doğrulama sekmesi kimlik bilgilerini yönetir. Insomnia uzun bir şema listesini destekler: Bearer Token, Basic Auth, API Key, OAuth 1.0 ve 2.0, AWS IAM ve diğerleri. API'nizin kullandığı şemayı seçin ve alanları doldurun. Belirteçle korunan bir API için Bearer Token'ı seçin ve belirteci yapıştırın veya daha iyisi, belirtecin sabit kodlanmaması için bir ortam değişkenine başvurun. Hangi durum kodlarını bekleyeceğinizden emin değilseniz, REST API'lerinin kullanması gereken HTTP durum kodları hakkındaki referans iyi bir yardımcıdır.
Ortamları ve değişkenleri ayarlayın
Ortamlar, değerleri tekrarlamaktan kaçınmanızı sağlar ve hedefleri değiştirmeyi kolaylaştırır. Insomnia'da, bir ortam, bir koleksiyona bağlı değişkenlerden oluşan bir JSON nesnesidir.
Yan çubuğun üst kısmındaki ortam açılır menüsüne tıklayın ve Ortamları Yönet'i açın. Temel Ortam paylaşılan değerleri tutar. Her hedef için alt ortamlar ekleyin:
{
"base_url": "https://jsonplaceholder.typicode.com",
"auth_token": "your-token-here"
}
Farklı değerlerle üretim için ikinci bir alt ortam oluşturun. Herhangi bir istekte {{ _.base_url }} şablon sözdizimi ile bir değişkene başvurun, böylece bir URL şöyle olur:
GET {{ _.base_url }}/users/1
Etkin ortamı açılır menüden değiştirin ve değişkeni kullanan her istek güncellenir. Insomnia ayrıca, bir zaman damgası, bir UUID oluşturmak veya önceki bir yanıttan bir değer çekmek için bir alana bırakabileceğiniz küçük fonksiyonlar olan şablon etiketlerini de destekler. Bu sonuncusu, örneğin bir oturum açma yanıtından bir belirteci yakalayıp daha sonraki isteklere besleyerek istekleri zincirlemenizi sağlar.
Yanıt şablon etiketi daha yakından incelenmeye değerdir, çünkü Insomnia'nın istek bağımlılıklarını betikleme olmadan bu şekilde ele almasını sağlar. "Giriş isteğinin gövdesini $.token JSONPath'inde kullan" diyen bir etiket eklersiniz ve bunu her korunan isteğin Authorization başlığına bırakırsınız. Korunan bir istek çalıştırdığınızda, Insomnia gerekirse önce giriş isteğini çalıştırır, belirteci çıkarır ve yerine koyar. Zincir bildirimsel kalır, bu nedenle sürdürülmesi gereken yapıştırma kodu yoktur. İlgili kontrolleri gruplama konusundaki daha geniş fikir için, API test durumu örneği kılavuzuna bakın.
Onaylamalarla (assertions) test paketleri yazın
Bir istek göndermek size yanıtı gösterir. Yanıtın doğru olup olmadığını otomatik olarak kontrol etmek için Insomnia'nın test paketleri özelliğini kullanırsınız, bu bazen bir koleksiyondaki Birim Testleri sekmesi olarak gösterilir.
Koleksiyonunuzu açın ve Testler görünümüne geçin. Bir test paketi oluşturun, ardından içine ayrı ayrı testler ekleyin. Her test küçük bir JavaScript parçasıdır. Insomnia, Chai onaylama kütüphanesini kullanır ve size bir istek göndermek ve yanıtını almak için bir yardımcı sağlar. Bir test şöyle görünür:
const response = await insomnia.send();
expect(response.status).to.equal(200);
Gövdeyi ayrıştırarak ve alanları kontrol ederek daha spesifik olabilirsiniz:
const response = await insomnia.send();
const body = JSON.parse(response.data);
expect(response.status).to.equal(200);
expect(body.email).to.equal("daniel.okafor@example.com");
expect(body).to.have.property("id");
Paketteki her test, koleksiyonunuzdan seçilen bir isteği hedefler, böylece test ne göndereceğini bilir. Testleri Çalıştır'a tıklayın ve Insomnia paketteki her testi çalıştırır, her birini geçen veya başarısız olan ve ne kadar sürdüğünü gösteren şekilde listeler. Bu sizin regresyon kontrolünüzdür: bir değişiklikten sonra paketi çalıştırın ve API'nin hala beklediğiniz gibi çalışıp çalışmadığını hemen görün.
Paketleri nasıl düzenlediğiniz, sayıları arttıkça önem kazanır. Yaygın bir düzen, kaynak başına bir pakettir, böylece tüm makale testleri bir arada ve tüm kullanıcı testleri bir arada bulunur. Bir paketin içinde, her testi tek bir davranışa odaklı tutun: başarılı yol için bir test, bulunamayan durum ve doğrulama hatası durumu için ayrı testler. Bir test başarısız olduğunda, adı ve dar kapsamı, onaylama kodunu okumanıza gerek kalmadan neyin bozulduğunu size söylemelidir. İyi kontroller yazmaya daha derinlemesine bir bakış için, API onaylamaları hakkındaki kılavuz neyi onaylayacağınızı ve neyi atlayacağınızı açıklar ve API test otomasyonu için test paketleri makalesi, paketlerin büyüdükçe nasıl yapılandırılacağını kapsar.
Inso ile komut satırından çalıştırın
Bir GUI geliştirme için iyidir, ancak otomasyon başsız (headless) bir şeye ihtiyaç duyar. Insomnia, Inso adlı bir komut satırı arkadaşıyla birlikte gelir. Koleksiyonunuzu dışa aktardıktan veya senkronize ettikten sonra, test paketinizi bir terminalden çalıştırırsınız:
inso run test "User API tests"
Herhangi bir test başarısız olursa Inso sıfır olmayan bir durum koduyla çıkar; bu, bir CI hattının bir derlemeyi bozuk olarak işaretlemesi için tam olarak ihtiyacı olan şeydir. Bunu GitHub Actions'a veya başka herhangi bir çalıştırıcıya bağlayarak Insomnia testlerinizin her gönderimde yürütülmesini sağlayabilir, bozuk bir uç noktayı bir ekip arkadaşına veya üretime ulaşmadan önce yakalayabilirsiniz. Inso ayrıca API spesifikasyonunuzu lint edebilir ve test raporlarını standart formatlarda oluşturabilir, bu da onu sadece paket çalıştırmanın ötesinde kullanışlı hale getirir. CI/CD'de API testlerini otomatikleştirmek hakkındaki makale, Inso'ya sorunsuz bir şekilde uygulanan genel kalıbı gösterir.
Sürüm 8'deki bulut değişikliği ve bir alternatif
Insomnia 8, bulut öncelikli bir modele doğru ilerledi. Varsayılan olarak kullanıcıları bir Kong hesabına oluşturmaya ve projeleri bulutta saklamaya yönlendirdi. Bu karar, önceki sürümler tamamen yerel ve çevrimdışı dostu olduğundan, topluluğun bir kısmını hayal kırıklığına uğrattı. Daha sonraki sürümler daha net bir sadece yerel veya "Scratch Pad" seçeneğini geri getirdi, ancak bu olay bazı ekipleri, özellikle verilerin bina dışına çıkamadığı ortamlarda alternatifler aramaya itti.
Eğer bu sizi tanımlıyorsa, Apidog'a bir göz atmaya değer. Tasarım, hata ayıklama, taklit etme, test etme ve dokümantasyonu kapsayan hepsi bir arada bir API platformudur ve Insomnia dışa aktarımlarını içe aktarır, böylece baştan başlamanıza gerek kalmaz. Apidog, JavaScript yazmadan görsel olarak onaylamalar oluşturmanızı sağlar, istediğinizde komut dosyalarını da destekler. API spesifikasyonu, test verileri ve taklit sunucu tek bir projeyi paylaştığından, testleriniz kaymadan gerçek sözleşme ile uyumlu kalır. Apidog'u indirebilir ve yan yana karşılaştırmak için bir Insomnia koleksiyonu içe aktarabilirsiniz. Daha geniş bir inceleme için, ücretsiz çevrimiçi API test araçları listesi çeşitli seçenekleri kapsar.
Insomnia, özellikle minimalist, dikkat dağıtmayan arayüzünü ve hızlı başlangıcını takdir eden tek başına geliştiriciler ve küçük ekipler için hala güçlü, odaklanmış bir istemcidir. Doğru seçim, ekibinizin nasıl çalıştığına ve API yaşam döngüsünün ne kadarını ayrı araçlara yaymak yerine tek bir yerde ele almak istediğinize bağlıdır.
Sıkça sorulan sorular
Insomnia ücretsiz mi?
Insomnia'nın, istek gönderme ve test paketlerini yerel olarak çalıştırma dahil olmak üzere bireysel kullanımı kapsayan ücretsiz bir katmanı vardır. Ücretli planlar ekip işbirliği ve daha büyük bulut senkronizasyon limitleri ekler. Temel istemciyi ödeme yapmadan kullanabilirsiniz ve son sürümler, bulut senkronizasyonu kullanmayı tercih etmiyorsanız tamamen yerel olarak çalışmanıza olanak tanır.
Insomnia hangi protokolleri destekler?
Insomnia HTTP, REST, GraphQL, gRPC, SOAP ve WebSocket'i yönetir. İstek kurulumu protokole göre farklılık gösterir, ancak yanıt incelemesi ve HTTP tabanlı istekler için test paketi onaylamaları hepsinde tutarlı çalışır.
Insomnia'da onaylamaları (assertions) nasıl yazarım?
Test paketleri özelliğini kullanın. Bir koleksiyonda Testler görünümünü açın, bir paket oluşturun ve testler ekleyin. Her test, bir isteği çalıştırmak için insomnia.send()'i çağıran, ardından durum, başlıklar veya ayrıştırılmış gövde üzerinde Chai tarzı expect onaylamaları kullanan JavaScript kodudur. Tüm paketi Testleri Çalıştır düğmesiyle çalıştırın.
Insomnia 8'de ne değişti?
Insomnia 8, bulut öncelikli bir varsayılan modele geçti ve kullanıcıları bir Kong hesabına oturum açmaya ve projeleri buluta senkronize etmeye teşvik etti. Bazı kullanıcılar zorunlu hesap akışını ve tamamen yerel bir uygulamadan uzaklaşmayı beğenmedi. Daha sonraki güncellemeler daha net sadece yerel seçenekler ekledi, ancak bu değişiklik bazı ekipleri alternatifleri değerlendirmeye itti.
Insomnia testlerini bir CI hattında çalıştırabilir miyim?
Evet. Komut satırı arkadaşı Inso'yu kullanın. Koleksiyonunuzu dışa aktarın veya senkronize edin, ardından hattınızda inso run test "<paket adı>" komutunu çalıştırın. Inso başarısızlık durumunda sıfır olmayan bir çıkış kodu döndürür, böylece bir API testi bozulduğunda CI derlemeyi otomatik olarak başarısız edebilir.