Eğer bir OpenAPI dosyasını tutuyorsanız ancak çalışan hizmetiniz ondan yavaşça uzaklaşıyorsa, Specmatic tam da bu boşluk için geliştirilmiştir. Şartnamenizi yürütülebilir bir sözleşme olarak ele alır, ardından gerçek bir hizmeti buna karşı test eder ve aynı şartnameyi akıllı bir taslak (stub) olarak çalıştırır. Bu kılavuz, Specmatic'in ne yaptığını, sözleşme testinin örnek tabanlı testten nasıl farklılaştığını ve aracın nereye oturduğunu, Apidog'un API sözleşme testi gibi daha geniş bir platform yaklaşımıyla nasıl karşılaştırıldığına dair bir notla birlikte açıklar. Tüm bunların temelindeki şartname formatı için, Specmatic'in okuduğu doğruluk kaynağı OpenAPI Specification'dır.
Specmatic Nedir
Specmatic, sözleşme odaklı geliştirme için açık kaynaklı bir araçtır. Temel fikir kısadır: API şartnameniz sözleşmedir ve Specmatic bu sözleşmeyi yürütülebilir hale getirir. Bir OpenAPI dosyasına işaret ettiğinizde, iki tamamlayıcı iş yapabilir.
- Şartnameyi canlı bir hizmete karşı test olarak çalıştırır, hizmetin şartnamenin vaat ettiği her yolu, durum kodunu ve şemayı yerine getirdiğini kontrol eder.
- Şartnameyi bir taslak sunucu olarak çalıştırır, böylece tüketiciler sözleşmenin belirttiği şekilde yanıt veren bir sahteye (mock) karşı geliştirme yapabilirler.
Her iki iş de aynı dosyayı okur. Senkronize tutulacak ayrı bir "test tanımı" ve "şartname" yoktur, ki önemli olan da budur. Specmatic, OpenAPI'nin ötesine de geçer. Sürüm 2.0, GraphQL ve gRPC'yi ekledi ve Kafka tarzı olay sözleşmeleri için AsyncAPI'yi, ayrıca WSDL ve Avro gibi formatları destekler. Ancak çoğu ekip için giriş noktası, basit bir OpenAPI YAML veya JSON dosyasıdır.
Komut satırından veya bir Docker görüntüsünden çalıştırırsınız, böylece çok fazla seremoniye gerek kalmadan CI'a entegre olur. Arkasındaki şirket ticari eklentiler sunar, ancak sözleşme motoru kendisi ücretsiz ve açık kaynaktır.
Sözleşme testi ile örnek tabanlı test karşılaştırması
Bu, çoğu kişiyi karıştıran bir ayrımdır, bu yüzden kesin olmakta fayda var.
Örnek tabanlı test, çoğu API istemcisinde yaptığınız şeydir. Bir istek yazarsınız, aldığınız yanıtı doğrularsınız, belki bir durum kodunu ve bir veya iki alanı kontrol edersiniz. Her test el yazımı bir örnektir. Şartnamenizde 40 uç nokta varsa, birçok örnek yazıp sürdürürsünüz ve boşlukları kaçırmak kolaydır.
Sözleşme testi modeli tersine çevirir. Belirli örnekler üzerinde doğrulama yapmak yerine, hizmetin sözleşmeye uyduğunu doğrulayın. Specmatic şemayı okur ve ondan testler üretir. Yanıtların belirtilen tiplere uygun olduğunu, gerekli alanların mevcut olduğunu, durum kodlarının hizalı olduğunu ve hizmetin bozuk istekleri şartnamenin ima ettiği şekilde reddettiğini kontrol eder. Doğrulamaları tek tek yazmazsınız. Şartname, doğrulamanın kendisidir.
| Yön | Örnek tabanlı test | Specmatic ile sözleşme testi |
|---|---|---|
| Doğruluk kaynağı | El yazımı test senaryoları | OpenAPI şartnamesinin kendisi |
| Sürdürdüğünüz şey | Her istek ve doğrulama | Zaten tuttuğunuz şartname |
| Kapsam | Sadece yazmayı hatırladıklarınız | Şartnamenin beyan ettiği her işlem |
| Sapma tespiti | Manuel | Şartname değiştiğinde otomatik |
| Tipik hata | Belirli bir örnek bozuldu | Hizmet artık sözleşmeyle eşleşmiyor |
Adlandırmaya değer ikinci bir eksen var. Sözleşme testi çeşitleri bulunur ve Specmatic belirli bir tanesine odaklanır. Pact tarzı tüketici odaklı sözleşme testinde, tüketiciler beklentilerini bir aracıya (broker) yayınlar ve sağlayıcılar bunlara karşı doğrular. Specmatic bunun yerine sözleşme odaklı test yapar: şartname, her iki tarafın da anlaştığı tek sözleşmedir ve Specmatic sağlayıcıyı buna karşı doğrular ve tüketiciler için sağlayıcıyı taslak (stub) olarak kullanır. Bir Pact aracısı değildir ve tüketici tarafından yayınlanan pact'leri yönetmez. Daha geniş bir resim görmek isterseniz, API sözleşme testi ve sahteleme (mocking) araçları hakkındaki bu genel bakışı inceleyin.
Specmatic nasıl çalışır
CLI'ı doğrudan kurabilir veya Docker görüntüsünü çekebilirsiniz. Docker, yerel çalışma zamanı kurulumundan kaçındığı için CI'da yaygın bir seçimdir.
Sözleşme testlerini çalıştırma
Test komutu, Specmatic'i bir şartnameye ve çalışan bir hizmete yönlendirir. Minimal bir yerel çalıştırma şöyle görünür.
# Native CLI
specmatic test api.yaml --testBaseURL=http://localhost:8080
# Docker
docker run -v "$(pwd):/usr/src/app" specmatic/specmatic \
test api.yaml --testBaseURL=http://host.docker.internal:8080
Specmatic, api.yaml dosyasını okur, tanımladığı işlemler için istekler oluşturur, bunları temel URL'ye gönderir ve her yanıtı şemaya karşı doğrular. Başarısız bir test, hizmet ile sözleşmenin uyuşmadığı anlamına gelir. Ya birini ya diğerini düzeltirsiniz. Döngü budur.
Şartnameyi bir taslak (stub) olarak çalıştırma
Taslak sunucu diğer yarıdır. Onu başlattığınızda Specmatic, sözleşmeye uygun yanıtlar sunar, böylece gerçek arka uç var olmadan önce bir ön uç veya aşağı akış hizmeti ona karşı geliştirme yapabilir.
specmatic stub api.yaml --port=9000
Varsayılan olarak, anında şemaya uygun yanıtlar üretir. Ayrıca somut örnekleri şartnamenin yanındaki bir _examples dizinine kaydedebilir ve bir istek eşleştiğinde taslak bunları döndürecektir. Bu size gerçek bir arka uç kurmadan gerçekçi, kontrol edilebilir veriler sağlar. Araçlar arasında taslak ve sahteleme (mock) seçeneklerini karşılaştırıyorsanız, sözleşme testi ve sahte sunucular özeti Specmatic'i bağlamına oturtur.
Specmatic, şartnameyi ilk etapta oluşturmanıza da yardımcı olabilir. Mevcut bir hizmetin önünde bir proxy olarak durabilir, gerçek trafiği yakalayabilir ve gördüklerinden bir OpenAPI belgesi ile örnek dosyalar oluşturabilir. Bu, bir hizmetiniz varken henüz bir şartnameniz olmadığında kullanışlıdır.
Şartnameyi sözleşme ve taslak olarak kullanma modeli
Tek bir dosyayı hem test hem de taslak olarak çalıştırmanın neden önemli olduğunu burada açıklıyoruz. Şartname sözleşme olduğunda, test tarafı ve taslak tarafı asla anlaşmazlık yaşayamaz, çünkü aynı belgeyi okurlar.
- Sağlayıcı ekibi CI'da
specmatic testkomutunu çalıştırır. API'yi şartnameyi güncellemeden değiştirirlerse, sözleşme testleri başarısız olur. - Tüketici ekibi yerel olarak
specmatic stubkomutunu çalıştırır. Aynı sözleşmeyle eşleşmesi garanti edilen yanıtlara karşı geliştirme yaparlar.
Böylece şartname, kimsenin güvenmediği eski bir belge değil, canlı bir anlaşma haline gelir. Bu, bir taslak (stub) ile daha zengin bir sahte (mock) arasındaki farktır ve etrafında bir iş akışı tasarlamadan önce API taslağı oluşturma (stubbing) ve sahteleme (mocking) temelindeki fikirleri anlamakta fayda var.
Specmatic ayrıca geriye dönük uyumluluk kontrolü de ekler. backward-compatibility-check komutu, bir şartnamenin yeni sürümünden bir taslak başlatır, önceki sürümden testler oluşturur ve bunları yeni taslağa karşı çalıştırır. Eskiden çalışan bir şey artık çalışmıyorsa, dağıtımdan önce öğrenirsiniz. Bu, bağımsız olarak dağıtılan mikro hizmetler için güçlü bir güvenlik önlemidir ve çift yönlü sözleşme testi kapsamında ele alınan daha geniş bir fikrin bir çeşididir.
Specmatic'in yeri
Specmatic, ekibiniz için aşağıdaki durumlar geçerli olduğunda yerini sağlamlaştırır:
- OpenAPI (veya AsyncAPI, GraphQL, gRPC) şartnameniz gerçek ve yeterince eksiksizdir.
- Senkronize kalması gereken ayrı sağlayıcı ve tüketici ekipleriniz veya hizmetleriniz var.
- Şartname sapmasının otomatik olarak bir derlemeyi başarısız etmesini, incelemede yakalanmamasını istersiniz.
- CLI ve CI öncelikli bir iş akışına alışıksınız.
Eğer bir şartname tutmuyorsanız, API'leri tasarlamak ve keşfetmek için görsel bir çalışma alanı istiyorsanız veya geçici hata ayıklama, belgeleme ve ekip işbirliğini de tek bir aracın halletmesini istiyorsanız, daha az uygun bir çözümdür. Specmatic sözleşme motoruna odaklanmıştır ve bu tek işi iyi yapar.
Bu odak noktası aynı zamanda Apidog gibi bir platformun farklı bir şekil aldığı yerdir. Apidog da aynı şekilde şema odaklıdır: OpenAPI şartnamenizi okur, yanıtları şemaya göre doğrular ve kodsuz bir şekilde OpenAPI şemanızdan bir sahte sunucu başlatır. Dürüst fark kapsamdır. Specmatic keskin, CLI yerel bir sözleşme aracıdır. Apidog, tasarım, test, sahteleme ve belgeleri görsel bir düzenleyici ile tek bir çalışma alanında birleştirir, böylece siz çalışırken şartname, testler ve sahte bir arada yaşar ve senkronize kalır. Apidog da Pact tarzı tüketici odaklı bir sözleşme aracısı değildir, bu nedenle ekibiniz özellikle bir pact aracısına ihtiyaç duyuyorsa, bu araçlardan hiçbiri bunu sağlamaz.
Bu tür bir çalışma alanı içinde bir şartnameden doğrudan çalıştırılabilir testler oluşturmak isterseniz, Apidog'un OpenAPI şartnamelerinden API test koleksiyonu oluşturmayı nasıl ele aldığını görün.
Sıkça sorulan sorular
Specmatic ücretsiz mi?
Evet. Temel sözleşme motoru açık kaynaklıdır ve CLI veya Docker'dan ücretsiz olarak kullanılabilir. Etrafında ticari teklifler bulunmaktadır, ancak OpenAPI şartnamelerinden sözleşme testleri ve taslak sunucuları ücret ödemeden çalıştırabilirsiniz. Ücretli katmanlar hakkında güncel ayrıntılar için resmi siteyi ve GitHub'ı kontrol edin.
Specmatic sadece OpenAPI ile mi çalışır?
Hayır. OpenAPI en yaygın giriş noktasıdır, ancak Specmatic ayrıca olay odaklı sözleşmeler için AsyncAPI'yi, sürüm 2.0'dan beri GraphQL ve gRPC'yi, WSDL ve Avro gibi formatlarla birlikte destekler. Model hepsinde aynıdır: şartname yürütülebilir sözleşmedir. Formatın kendisine yeni başlıyorsanız, bu OpenAPI Specification eğitimine göz atın.
Specmatic, Pact ile aynı mı?
Tam olarak değil. Pact tüketici odaklıdır: tüketiciler beklentilerini bir aracıya yayınlar ve sağlayıcılar bunlara karşı doğrular. Specmatic sözleşme odaklıdır: şartname tek, paylaşılan sözleşmedir ve Specmatic sağlayıcıyı buna karşı doğrular, aynı zamanda tüketiciler için sağlayıcıyı taslak (stub) olarak kullanır. Her ikisi de entegrasyon sürprizlerini azaltır, ancak sözleşmeyi farklı şekilde organize ederler.
Specmatic benim için bir OpenAPI şartnamesi oluşturabilir mi?
Evet. Specmatic mevcut bir hizmetin önünde bir proxy olarak çalışabilir, gerçek istek ve yanıt trafiğini yakalayabilir ve buradan bir OpenAPI belgesi ile örnek dosyalar oluşturabilir. Bu, çalışan bir hizmetiniz varken henüz test edilecek resmi bir şartnameniz olmadığında kullanışlıdır.
Sonuç
Specmatic, belirli ve gerçek bir soruna yanıt verir: çalışan bir hizmetin, uyması gereken OpenAPI şartnamesine karşı dürüst kalmasını sağlamak. Şartnameyi yürütülebilir hale getirerek, geriye dönük uyumluluk kontrolleriyle birlikte, tek bir dosyadan sözleşme testleri ve eşleşen bir taslak (stub) sunar. Eğer terminal ve CI ortamında yaşıyorsanız ve sağlam bir şartname tutuyorsanız, tam uyum sağlar.
Eğer sözleşmeyi, testleri, sahteyi ve belgeleri aynı OpenAPI dosyasını okuyan tek bir görsel çalışma alanında tutmak isterseniz, Apidog'u deneyin. Yanıtları şemanıza göre doğrular, uç noktaları kodsuz olarak taklit eder ve şartnameleri çalıştırılabilir test koleksiyonlarına dönüştürür. Apidog'u indirin, şartnamenize işaret edin ve tüm tasarımdan teste döngüsünü tek bir yerde görün.