Düz İngilizce gibi okunan, kodunuzun yanında Git'te yaşayan ve herhangi bir CI hattında çalışabilen API testleri istersiniz. Karate tam olarak bunun için tasarlandı. Java metotları yerine testleri Given / When / Then adımları olarak yazmanızı sağlayan bir etki alanına özgü dil (DSL) kullanır. Bu kılavuz, Karate'nin ne olduğunu, özellik dosyalarının nasıl çalıştığını ve çalıştırılabilir bir örneği anlatmaktadır.
Karate Nedir
Karate, API'ler için açık kaynaklı, Java tabanlı bir test otomasyon çerçevesidir. Her testi, Davranış Odaklı Geliştirme'den (Behavior-Driven Development) gelen aynı Given/When/Then yapısı olan Gherkin kullanarak bir .feature dosyasında bir senaryo olarak tanımlarsınız. Cucumber gibi araçlardan farkı, adım tanımlama bağlantı kodu yazmamanızdır. Karate, HTTP adımlarını, doğrulama (assertion) ve JSON işleme yeteneklerini yerleşik olarak sunar, bu nedenle çalışan bir API testi için hiç Java'ya gerek duyulmaz.
Proje, API testinden daha fazlasını içerir. Depo, mock'lar, performans testi (Gatling aracılığıyla) ve UI otomasyonu için modüller barındırır. Bu kılavuz için odak noktası, çoğu ekibin ilk başvurduğu API testi çekirdeğidir.
Testler düz metin dosyaları olduğundan, versiyonlamaya çok uygundur. Bir çekme isteği diff'i, tam olarak hangi doğrulamanın değiştiğini gösterir. Bu, kod incelemesi ve Git-yerlisi, kod tabanlı bir iş akışı ile güzel bir uyum sağlar.
Given/When/Then stiline yeni başlıyorsanız, Davranış Odaklı Geliştirme hakkındaki başlangıç kılavuzumuz, nereden geldiğini ve ekiplerin neden kullandığını açıklar.
Nasıl Çalışır: Özellik Dosyaları ve karate-config.js
Bir Karate testi bir özellik dosyasıyla başlar. Her dosya bir Feature: ve bir veya daha fazla Scenario: bloğuna sahiptir. Bir senaryonun içinde, isteği Given ile ayarlarsınız, When ile tetiklersiniz ve Then ile doğrularsınız.
Karate'nin kendi hızlı başlangıcının gösterdiği yapı şöyledir:
Feature: User API
Scenario: List all users
Given url 'https://jsonplaceholder.typicode.com'
And path 'users'
When method get
Then status 200
And match response == '#[10]'
Yukarıdan aşağıya okuyun. url temel adresi ayarlar. path kaynağı ekler. method get isteği gönderir. status 200 HTTP kodunu kontrol eder. Son satır, yanıtın tam olarak 10 öğeli bir JSON dizisi olduğunu doğrular. #[10] bir Karate işaretleyicisidir, JavaScript değil. Bu işaretleyiciler hakkında daha fazlası doğrulama bölümünde.
Buradaki Gherkin standart Given/When/Then yapısıdır. Bu sözdizimine daha derinlemesine bakmak isterseniz, BDD ve API testi için Gherkin kılavuzumuza göz atın.
Çoğu proje ortama özgü değerlere ihtiyaç duyar: bir geliştirme taban URL'si, bir hazırlık ortamı (staging) token'ı, bir üretim (prod) uç noktası. Karate bunu karate-config.js adlı tek bir dosya ile yönetir. Testlerinizden önce bir kez çalışır ve her senaryonun okuyabileceği bir yapılandırma nesnesi döndürür.
function fn() {
var env = karate.env || 'dev';
var config = {
baseUrl: 'https://jsonplaceholder.typicode.com'
};
if (env === 'qa') {
config.baseUrl = 'https://qa.example.com';
}
return config;
}
karate.env, çalışma zamanında ilettiğiniz bir sistem özelliğinden gelir. Tek bir özellik dosyasına dokunmadan ortamlar arasında geçiş yapın. Bir senaryoda adresi doğrudan yazmak yerine Given url baseUrl yazarsınız.
Örnek Bir Senaryo
Bir istek gövdesi içeren bir şeyler yazalım. Bu senaryo bir kullanıcı oluşturur, durumu kontrol eder ve yanıtın yapısını doğrular.
Feature: Create user
Background:
* url baseUrl
Scenario: Create a new user returns 201
Given path 'users'
And request { name: 'Ada', job: 'engineer' }
When method post
Then status 201
And match response.name == 'Ada'
And match response.id == '#string'
Dikkat edilmesi gereken birkaç şey var. Background: bloğu dosyadaki her senaryodan önce çalışır, bu nedenle temel URL'yi bir kez ayarlarsınız. * bir joker adım; Karate, * öğesini Given, When veya Then ile aynı şekilde ele alır, bu da dilbilgisi hakkında endişelenmeden kurulum adımları yazmanıza olanak tanır. request anahtar kelimesi doğrudan bir JSON yükü alır. Seri hale getirici yok, POJO yok. Ve #string ise, id alanının var olduğunu ve belirli bir değere sabitlemeden bir dize olduğunu doğrulayan esnek bir eşleştiricidir.
Doğrulamalar (Assertions) ve JSON Eşleştirme
Doğrulamalar, Karate'nin değerini gösterdiği yerdir. Temel anahtar kelime match'tir. Gerçek bir değeri beklenen bir değerle karşılaştırır ve herhangi bir uyumsuzlukta testi başarısız yapar.
Tam eşleşme eşitliği kontrol eder:
And match response == { id: '#number', name: 'Ada', job: 'engineer' }
#number, #string, #boolean ve #uuid belirteçleri esnek eşleştiricilerdir. Bir literal değer talep etmeden türü ve varlığını doğrularlar, bu da sunucu tarafından oluşturulan kimlikler veya zaman damgaları döndüğünde testlerin kararlı kalmasını sağlar.
Yalnızca alanların bir alt kümesini önemsediğinizde, contains kullanın:
And match response contains { name: 'Ada' }
Bu, yanıtın on başka alanı olsa bile, name değeri Ada'ya eşit olduğu sürece geçerlidir. Karate ayrıca kısmi eşleştirmeler üzerinde daha ince kontrol için !contains, contains only, contains any ve contains deep'i de destekler.
Dizileri de doğrulayabilirsiniz. match response == '#[10]' 10 uzunluğunda bir diziyi doğrular. Her öğeye each ile bir şema uygulayabilirsiniz:
And match each response == { id: '#number', name: '#string' }
Bu tek satır, dizideki her nesnenin sayısal bir id'ye ve bir dize name'e sahip olduğunu kontrol eder. Bu tür bir şekil doğrulaması, genel amaçlı bir test çerçevesinde bir döngü ve birkaç doğrulama gerektirir. Yanıtları doğrulama konusunda daha geniş bir resim isterseniz, API doğrulamalarına yönelik pratik kılavuzumuz araçlar arası modelleri kapsar.
Veri Odaklı Test (Data-Driven Testing) ve CI
Gerçek test paketleri, aynı mantığı birçok girişe karşı çalıştırır. Karate bunu Scenario Outline ve bir Examples tablosu ile ele alır. Köşeli parantez içindeki yer tutucular her satırdan doldurulur.
Scenario Outline: Create users from a table
Given url baseUrl
And path 'users'
And request { name: '<name>', job: '<job>' }
When method post
Then status 201
And match response.name == '<name>'
Examples:
| name | job |
| Ada | engineer |
| Grace | scientist |
| Alan | analyst |
Bu, senaryoyu her satır için bir kez olmak üzere üç kez çalıştırır. Ayrıca, büyük veri kümelerini özellik dosyalarınızdan uzak tutarak, satır içi bir tablo yerine harici bir dosyadan satırları okuyabilirsiniz:
Examples:
| read('classpath:test-data/users.json') |
Karate, JSON ve CSV dosyalarını bu şekilde okur, böylece test verileriniz ekibinizin yönetmeyi tercih ettiği her yerde bulunabilir.
Sürekli entegrasyon (CI) için iki yolunuz var. Bir Maven veya Gradle projesinde, Karate JUnit 5 üzerinden çalışır. karate-junit5 bağımlılığını ekler ve özellik dosyalarınıza bir çalıştırıcı (runner) yönlendirirsiniz, böylece mvn test bunları diğer birim testleri gibi yürütür. Bu, mevcut CI adımınızın özel bir araca ihtiyaç duymadığı anlamına gelir.
İkinci yol, herhangi bir yapı aracına ihtiyaç duymayan bağımsız jar dosyasıdır. Projenin yayınlarından karate.jar dosyasını indirin ve özellik dosyalarını doğrudan çalıştırın. Jar dosyasının yakın tarihli bir Java sürümü gerektirdiğini unutmayın, bu nedenle minimum sürüm için sürüm notlarını kontrol edin.
java -jar karate.jar src/test/java/features
Etikete göre filtreleyebilir, paralel çalıştırabilir ve bir çıktı dizini seçebilirsiniz:
java -jar karate.jar --tags @smoke --threads 4 --output reports src/test/java/features
Bir sistem özelliği ile bir ortam geçirebilirsiniz, bu da karate-config.js içindeki karate.env'e akış sağlar:
java -jar karate.jar -Dkarate.env=qa src/test/java/features
Karate, her çalıştırmadan sonra çıktı dizinine bir HTML raporu yazar, böylece hatalar bir pipeline artefaktında kolayca incelenebilir. Daha geniş CI resmi için, CI/CD'de API testlerini nasıl otomatikleştireceğinizi görün.
Güçlü Yönler ve Dezavantajlar
Karate'nin belirgin güçlü yönleri vardır. Testler düz İngilizce'ye yakın okunur, bu da Java'da akıcı olmayan kişiler için engeli azaltır. Esnek eşleştiriciler ve each dahil olmak üzere yerleşik JSON eşleştirme, birçok doğrulama (assertion) kalabalığını ortadan kaldırır. Her şey Git altında metin dosyalarında yaşar, bu nedenle testler kaynak kodu gibi incelenir ve farklılıkları gösterir. Ve HTTP'den daha fazlasını kapsar, böylece bir ekip daha sonra araç değiştirmeden mock'lar veya performans testleri ekleyebilir.
Dezavantajları da gerçektir. Karate JVM üzerinde çalışır, bu nedenle Java'nın kurulu olması ve temel şeylerin ötesinde JVM ekosistemiyle rahatlık seviyesi gereklidir. DSL kendi başına öğrenilmesi gereken bir şeydir; sözdizimi kolay okunur ancak doğru eşleştiriciler ve yeniden kullanım desenleri yazmak pratik gerektirir. Yeniden kullanılabilir mantık, özel yardımcılar ve karmaşık kurulum genellikle sizi JavaScript fonksiyonlarına veya Java birlikte çalışabilirliğine geri çeker. Ve testler kod olduğu için, ekipteki geliştirici olmayanlar genellikle yardım almadan bunları yazamaz veya düzenleyemez.
Bunların hiçbiri bir eleştiri değildir. Bu, kod-odaklı bir çerçevenin profilidir. Soru, bu profilin ekibinizin çalışma şekline uyup uymadığıdır.
Karate ile Kodsuz Yaklaşım Karşılaştırması (Apidog)
Karate kod tabanlı ve Git-yerlisidir. Özellik dosyaları yazar, taahhüt eder ve bir yapı aracından veya jar dosyasından çalıştırırsınız. Bu, testlerini uygulamanın yanında sürüm kontrolünde isteyen ve JVM'ye alışkın mühendisler için uygundur.
Apidog, aynı hedefe görsel, kodsuz bir yol sunar. Test senaryolarını bir UI'de oluşturur, istekleri zincirler ve DSL yazmak yerine tıklayarak doğrulamalar eklersiniz. Tüm API yaşam döngüsü (tasarım, hata ayıklama, mocklama, dokümantasyon) tek bir yerde yaşadığı için, testler zaten tanımladığınız uç noktaları ve şemaları yeniden kullanabilir. Bu, bir Java projesini yönetmek istemeyen QA mühendisleri ve ürün uzmanları için engeli azaltır.
Görsel test paketleri UI'de takılı kalmaz. Apidog bunları CI'de Apidog CLI aracılığıyla başsız olarak çalıştırır, bu nedenle kodsuz bir paket yine de otomatik bir pipeline'a uyar. Node ile kurarsınız:
npm install -g apidog-cli
Ardından, bir ortamı işaret ederek ve rapor formatlarını seçerek bir kimlik ile kaydedilmiş bir senaryoyu veya paketi tetikleyin:
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t <scenarioOrSuiteId> -e <environmentId> -r cli,html,junit
-t bayrağı bir senaryoyu, klasörü veya paketi hedefler; -e ortamı seçer; -r bir veya daha fazla raporlayıcıyı (cli, html, json, junit) seçer. Veri odaklı çalıştırmalar için, -d (veya --iteration-data) bir veri dosyası yolunu veya test verisi kimliğini alır. CLI başsızdır ve Node çalıştırabilen herhangi bir CI adımında çalışır. Kaydedilmiş Apidog senaryolarınızı çalıştırır; etkileşimli bir istek gönderici veya yük oluşturucu değildir. CI/CD için Apidog CLI'da tam bir incelemeyi ve başka bir çalıştırıcı ile yan yana karşılaştırmayı Apidog CLI vs Newman'da görün.
Her iki yaklaşım da CI'de başsız çalışan otomatik API testleri üretir. Ayrım yazma stilindedir: Karate sizden Git'te DSL yazmanızı ister; Apidog ise pipeline'a da dışa aktarılabilen bir UI'de tıklamanızı ister.
Nasıl Seçilir
Ekibiniz geliştirici ağırlıklıysa, JVM'ye alışkınsa ve testleri uygulamanın hemen yanında kod olarak versiyonlamak istiyorsa Karate'yi seçin. Düz metin özellik dosyaları ve yerleşik JSON eşleştirme, mühendisler test paketini baştan sona sahiplendiğinde faydalı olur.
Yazarlar arasında QA ve ürün uzmanları varsa, testleri mevcut bir tasarım ve dokümantasyon iş akışına bağlamak istiyorsanız veya API kontrollerini çalıştırmak için bir Java derlemesi sürdürmeyi tercih etmiyorsanız Apidog gibi kodsuz bir araç seçin. CLI aracılığıyla yine de CI kapsamı elde edersiniz.
Bazı ekipler her ikisini de kullanır: derinlemesine, kod tabanlı regresyon paketleri için Karate'yi ve geliştirici olmayanların genişletebileceği geniş, hızlı kapsam için görsel bir aracı. Hala seçenekleri değerlendiriyorsanız, bir API otomasyon test çerçevesini nasıl seçeceğinize dair genel bakışımız karar kriterlerini ortaya koymaktadır.
Sıkça Sorulan Sorular
Karate kullanmak için Java bilmem gerekiyor mu? Hayır, temel API testlerini yazmak için gerekmez. Özellik dosyaları Gherkin DSL kullanır ve Karate HTTP ve doğrulama adımlarını yerleşik olarak sunar. Testleri çalıştırmak için Java'nın kurulu olmasını isteyeceksiniz ve özel yardımcılar veya karmaşık yeniden kullanım gerektiğinde biraz Java veya JavaScript bilgisi yardımcı olur.
Karate'nin Cucumber'dan farkı nedir? Her ikisi de Gherkin'in Given/When/Then sözdizimini kullanır. Cucumber ile her adımı desteklemek için adım tanımlama kodu yazarsınız. Karate sizin için API test adımlarını sağlar, bu nedenle standart HTTP testleri için sürdürülecek bir bağlantı kodu yoktur.
Karate Maven veya Gradle olmadan çalışabilir mi? Evet. Projenin yayınlarından bağımsız karate.jar dosyasını indirin ve özellik dosyalarını java -jar karate.jar <yol> komutuyla çalıştırın. Herhangi bir yapı aracına ihtiyaç duymadan etiketleri, paralel iş parçacıklarını ve özel bir çıktı dizinini destekler.
#string veya #[10] sözdizimi ne anlama geliyor? Bunlar Karate'nin esnek eşleştiricileridir. #string bir alanın herhangi bir değerde bir dize olduğunu, #number bir sayı olduğunu ve #[10] 10 uzunluğunda bir JSON dizisi olduğunu doğrular. Oluşturulan değerleri doğrudan kodlamadan yanıtın şeklini doğrulamanızı sağlarlar.
Kodsuz API testleri yine de CI'de çalışabilir mi? Evet. Apidog gibi görsel bir araç, kaydedilmiş senaryoları başsız olan ve Node ile herhangi bir CI adımında çalışan Apidog CLI'ye aktarır. Böylece testleri bir UI'de yazarsınız ve yine de otomatik pipeline çalıştırmaları elde edersiniz.