Bir OpenAPI veya GraphQL şemanız varsa, Schemathesis, tek bir doğrulama ifadesi yazmanıza gerek kalmadan bunu binlerce test senaryosuna dönüştürebilir. Şartnameyi okur, çeşitli ve geçerli girdiler oluşturur, bunları API'nize gönderir ve yanıtların sözleşmeyi nerede ihlal ettiğini rapor eder. Bu kılavuz, Schemathesis'in ne olduğunu, nasıl kurulup çalıştırılacağını, özellik tabanlı testin aslında ne anlama geldiğini ve sözleşme testi iş akışının yanı sıra Apidog'daki işlevsel testlerle nasıl birleştiğini açıklar.
Schemathesis Nedir?
Schemathesis, bir şemadan otomatik olarak API testleri oluşturan açık kaynaklı bir Python aracıdır. Bunu bir OpenAPI veya GraphQL tanımına yönlendirirsiniz ve zaten tanımladığınız türlerden, biçimlerden ve kısıtlamalardan test senaryoları oluşturur. Python için özellik tabanlı test kütüphanesi olan Hypothesis üzerine inşa edilmiştir ve MIT lisansı altında dağıtılmaktadır.
Temel fikir basit. Şartnameniz zaten geçerli bir isteğin ve yanıtın nasıl göründüğünü açıklıyor. Schemathesis bu açıklamayı bir doğruluk kaynağı olarak kabul eder ve çalışan API'nizin buna gerçekten uyup uymadığını kontrol eder. API 500 hatası döndürdüğünde, beyan edilen şemayı ihlal eden bir yanıt gönderdiğinde veya reddetmesi gereken bir girişi kabul ettiğinde, Schemathesis bunu işaretler.
Bunu komut satırından schemathesis run (veya daha kısa takma adı olan st run) ile çalıştırırsınız. CLI yerine pytest'ten yönlendirmek isterseniz bir Python entegrasyonu da mevcuttur. Çoğu ekip, neredeyse hiç kurulum gerektirmediği için CLI ile başlar.
Özellik Tabanlı Test Ne Anlama Geliyor?
Çoğu API testi örnek tabanlıdır. Bir istek yazarsınız, belirli bir yanıtı onaylarsınız ve test o tek durumda geçer veya başarısız olur. Bu faydalıdır, ancak yalnızca test yazmayı düşündüğünüz hataları yakalarsınız.
Özellik tabanlı test yaklaşımı tersine çevirir. Tek bir sabit örnek yerine, her zaman geçerli olması gereken bir özelliği tanımlarsınız, ardından aracın bunu bozmaya çalışmak için yüzlerce girdi oluşturmasına izin verirsiniz. Schemathesis için özellik kabaca şudur: “Hiçbir geçerli istek sunucuyu çökertmemeli veya şemayı ihlal eden bir yanıt üretmemelidir.”
Schemathesis, şartnamenizdeki kısıtlamalardan girdiler oluşturur. Bir alan, minimum 1 olan bir tamsayı ise, 1'i, büyük sayıları, sınır değerlerini ve saf doğrulamayı yanıltabilecek türden girdileri deneyecektir. Bir test başarısız olduğunda, Hypothesis girdiyi hatayı hala yeniden üreten en küçük duruma kadar küçültür, böylece 4KB'lık rastgele bir yük yerine minimal, okunabilir bir yeniden üretim elde edersiniz.
Bu, bir arayüze neyin çöktüğünü görmek için rastgele girdiler atan maymun testinden farklıdır. Özellik tabanlı test yapılandırılmıştır. Şemayı, makul ve hedeflenmiş girdiler oluşturmak için kullanır ve şartname kendisine ne söylediği için doğru sonucun neye benzediğini bilir.
Schemathesis Kurulumu ve Çalıştırılması
Schemathesis bir Python paketidir, bu yüzden Python 3 ve pip'e ihtiyacınız var. Normal yolla kurun:
pip install schemathesis
uv kuruluysa uvx schemathesis kullanarak kalıcı bir kurulum olmadan da çalıştırabilirsiniz. Kurulduktan sonra, temel komut bir şemayı ve bir temel URL'yi işaret eder:
st run http://127.0.0.1:8000/openapi.json
Şemanız bir URL yerine diskte yaşıyorsa, dosya yolunu geçirin ve Schemathesis'e canlı API'nin nerede olduğunu söyleyin:
st run ./openapi.yaml --url http://127.0.0.1:8000
Kimlik doğrulaması olan bir API için bir başlık ekleyin:
st run http://127.0.0.1:8000/openapi.json \
--header 'Authorization: Bearer your-token'
Schemathesis, şartnamedeki her işlemi keşfeder, her biri için senaryolar oluşturur ve hangi kontrollerin geçtiği ve hangilerinin başarısız olduğu hakkında bir özet yazdırır. Başarısızlıklar, gönderdiği tam istek ile birlikte gelir, böylece bunları curl ile veya herhangi bir API istemcisinde tekrar oynatabilirsiniz. Ana sürümler arasında bayrak adları ve varsayılanlar değiştiği için, bu blog parçasındaki bilgilere güvenmek yerine yüklü sürümünüze karşı st run --help'i kontrol edin.
Schemathesis Neleri Yakalar?
Varsayılan kontroller, şartnamenizin vaat ettikleri ile sunucunuzun yaptıkları arasındaki boşluğu hedefler. İşte genellikle ortaya çıkanlar.
| Sorun | Nasıl Görünür |
|---|---|
| Sunucu hataları | Bir istek, işlenmiş bir 4xx veya geçerli bir yanıt yerine 500 hatasını tetikler |
| Şema ihlalleri | Yanıt gövdesi, o durum kodu için belirttiğiniz şemayla eşleşmez |
| Durum kodu uyuşmazlıkları | API, şartnamenin hiç belgelemediği bir durum kodu döndürür |
| İçerik türü kayması | Yanıtın içerik türü, şartnamenin belirttiğiyle eşleşmez |
| Durumlu hatalar | Bir işlem tek başına çalışır ancak gerçekçi bir çok adımlı iş akışında başarısız olur |
Sonuncusu daha yakından bakmaya değer. Schemathesis, şartnamenizdeki bağlantılara dayanarak işlemleri bir araya getiren durumlu testler çalıştırabilir, örneğin bir kaynak oluşturur, sonra onu getirir, sonra siler. Bir güncellemeden sonra yanlış durumu bildiren bir kaynak gibi, yalnızca sırayla ortaya çıkan hataları tek istekli testlerle bulmak zordur. Durumlu faz, bu dizileri bir durum makinesi olarak yönlendirir.
Varsayılan davranışı kancalarla genişletebilirsiniz. Kancalar, veri üretimini özelleştirmenize, kendi kontrollerinizi eklemenize veya hangi işlemlerin test edileceğini filtrelemenize olanak tanıyan Python işlevleridir. Ekipler, Schemathesis'i kimlik doğrulama akışları veya şartnamenin ifade edemediği bariz olmayan kısıtlamaları olan API'lere bu şekilde uyarlar.
Schemathesis Ne Zaman Kullanılmalı?
Schemathesis, makul derecede doğru bir OpenAPI veya GraphQL şartnameniz olduğunda ve köşe durumları için geniş, ucuz bir kapsam istediğinizde yerini kazanır. Elle bir test yazmayı asla düşünmeyeceğiniz hataları bulmada güçlüdür: işlenmeyen girdiler, belgelenmemiş hata biçimleri ve şartname ile uygulama arasındaki sözleşme sapması.
Şu durumlarda iyi bir uyum sağlar:
- Bir OpenAPI şartnamesi sürdürüyorsunuz ve bunun gerçek sunucuya karşı uygulanmasını istiyorsunuz.
- İşlenmeyen 500 hataları konusunda endişeleniyorsunuz ve CI'da bir fuzzing katmanı istiyorsunuz.
- API'nizin sıralamanın önemli olduğu durumlu iş akışları var.
- Ekibiniz zaten Python ile çalışıyor ve
pipvepytestkonusunda rahat.
Şartnameniz yetersiz veya güncel değilse, Schemathesis yalnızca şemanın tanımladığını test edebileceği için daha zayıf bir uyum sağlar. Çöp girdi, çöp çıktı. Ayrıca örnek tabanlı işlevsel testlerinizin yerini de almayacaktır. Bir uç noktanın asla çökmediğini bilmek, bilinen bir girdi için doğru değeri döndürdüğünü bilmekle aynı şey değildir. İkisini de istersiniz.
Schemathesis ve Apidog: Her Birinin Yeri
Apidog ve Schemathesis farklı sorunları çözer ve yan yana iyi çalışırlar. Apidog, API'leri tasarlamak, hata ayıklamak, test etmek, taklit etmek ve belgelemek için hepsi bir arada bir platformdur. Schemathesis, odaklanmış özellik tabanlı bir fuzzer'dır. Burada sınır konusunda dürüst olmak önemlidir.
Apidog özellik tabanlı fuzzing yapmaz. En yakın bitişik özelliği, çökmeleri ortaya çıkarmak için rastgele girdiler gönderen maymun testidir. Bu faydalıdır, ancak şema odaklı özellik tabanlı testle aynı değildir. Schemathesis, şartnamenizin kısıtlamalarından girdiler oluşturur ve yanıtları şemaya göre kontrol eder. Yani özellik tabanlı fuzzing'e ihtiyacınız varsa, Apidog yerine Schemathesis'e yönelin.
Apidog'un devreye girdiği yer, o fuzzing geçişinin etrafındaki yaşam döngüsünün geri kalanındadır.
| İş akışı aşaması | Schemathesis | Apidog |
|---|---|---|
| Bir şartnameden özellik tabanlı fuzzing | Evet, temel özellik | Hayır |
| Görsel API tasarımı ve şartname düzenleme | Hayır | Evet |
| Örnek tabanlı işlevsel testler | Sınırlı | Evet, görsel test oluşturucu |
| Bir şartnameye karşı sözleşme testi | Kısmen, şema kontrolleriyle | Evet, özel iş akışı |
| Bir şemadan taklit sunucular | Hayır | Evet, akıllı taklit |
| CI test çalıştırıcısı | Evet, st run |
Evet, apidog run |
| Otomatik oluşturulan belgeler | Hayır | Evet |
Pratik bir eşleştirme şöyle görünür. Şartnameyi Apidog'da tasarlar ve sürdürürsünüz, ondan işlevsel test senaryoları ve bir taklit sunucu oluşturursunuz ve bunları apidog run ile CI'da çalıştırırsınız. Ardından, aynı şartnameyi köşe durumları çökmeleri ve sözleşme ihlalleri için fuzzing yapan bir Schemathesis geçişi eklersiniz. İki katman farklı hata sınıflarını yakalar. Apidog, bilinen durumlar için API'nin doğru şeyi yaptığını onaylar; Schemathesis, onu bozan bilinmeyen durumları avlar.
Amacınız bir şartnameyi bir fuzzing çalıştırması yerine çalıştırılabilir bir işlevsel pakete dönüştürmekse, Apidog OpenAPI şartnamelerinizden doğrudan API test koleksiyonları oluşturabilir ve bu akışı denemek için Apidog'u indirebilirsiniz.
Sıkça Sorulan Sorular
Schemathesis ücretsiz mi?
Evet. Schemathesis, MIT lisansı altında açık kaynaktır ve CLI, pip install schemathesis aracılığıyla ücretsiz olarak kurulabilir ve çalıştırılabilir. Yönetilen bir deneyim isteyen ekipler için barındırılan ticari bir teklif de var, ancak yerel olarak ve CI'da çalıştırdığınız çekirdek araç hiçbir maliyet gerektirmez.
schemathesis run ve st run arasındaki fark nedir?
Aynı komutlardır. st, schemathesis için kısa bir takma addır, bu yüzden st run ve schemathesis run tam olarak aynı şeyi yapar. Hangisini tercih ederseniz onu kullanın. Her ikisi de --url ve --header gibi seçeneklerle birlikte bir şema yolu veya URL alır.
Schemathesis işlevsel API testlerimin yerini alabilir mi?
Hayır, ve bunun için tasarlanmamıştır. Schemathesis, API'nizin çökmemesini ve yanıtların şemayla eşleşmesini kontrol eder. Bir indirim hesaplamasının doğru olup olmadığı gibi iş mantığını doğrulamaz. Bunun için hala örnek tabanlı işlevsel ve sözleşme testine ihtiyacınız var, bunları Apidog'da oluşturup çalıştırabilirsiniz. Schemathesis'i bir yedek olarak değil, ek bir fuzzing katmanı olarak ele alın.
Schemathesis GraphQL ile çalışıyor mu?
Evet. Schemathesis hem OpenAPI hem de GraphQL şemalarını destekler. GraphQL için, şemanın tür tanımlarından sorgular oluşturur ve yanıtları OpenAPI'de tanımlanan REST API'leri için yaptığı gibi kontrol eder.
Sonuç
Schemathesis, tek bir iş için keskin bir araçtır: OpenAPI veya GraphQL şartnamenizi alıp canlı API'nizi özellik tabanlı üretimle ona karşı stres testine sokmak. Örnek tabanlı testlerin kaçırdığı çökmeleri ve sözleşme ihlallerini bulur ve CI'ya eklemeniz neredeyse hiçbir maliyet getirmez. Yapmadığı şeyler ise iş mantığını tasarlamak, taklit etmek, belgelemek veya doğrulamaktır.
Apidog'un onu tamamladığı yer burasıdır. Şartnameyi tasarlayın, işlevsel testler ve taklitler oluşturun, bunları apidog run ile CI'da çalıştırın ve sonucu tek bir yerde belgeleyin, ardından fuzzing için Schemathesis'i üzerine katmanlayın. Bu iş akışının tasarım ve işlevsel tarafını oluşturmak için Apidog'u indirin ve köşe durum avını Schemathesis'e bırakın.