DEV Community

Cover image for Karate API Testleri: DSL ile Uygulamalı Kılavuz
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

Karate API Testleri: DSL ile Uygulamalı Kılavuz

Düz İngilizce gibi okunan, kodunuzun yanında Git'te yaşayan ve herhangi bir CI hattında çalışabilen API testleri istiyorsanız Karate iyi bir adaydır. Karate, Java metotları yazmak yerine testleri Given / When / Then adımlarıyla tanımlamanızı sağlayan bir DSL kullanır. Bu yazıda Karate ile API testi yapısını, .feature dosyalarını, ortam yapılandırmasını, doğrulamaları, veri odaklı testleri ve CI çalıştırmalarını uygulamalı olarak ele alacağız.

Apidog'u bugün deneyin

Karate Nedir?

Karate, API'ler için açık kaynaklı, Java tabanlı bir test otomasyon çerçevesidir. Testleri .feature dosyalarında, Davranış Odaklı Geliştirme'den gelen Gherkin söz dizimiyle yazarsınız:

Given ...
When ...
Then ...
Enter fullscreen mode Exit fullscreen mode

Cucumber gibi araçlardan farkı, her adım için ayrıca step definition yazmanız gerekmemesidir. Karate, HTTP isteklerini, doğrulamaları ve JSON eşleştirmeyi yerleşik olarak sağlar. Bu nedenle basit ve orta seviye API testleri için Java kodu yazmadan ilerleyebilirsiniz.

Karate yalnızca API testiyle sınırlı değildir. Depoda mock, performans testi ve UI otomasyonu için modüller de bulunur. Ancak günlük kullanımda çoğu ekip Karate'yi önce API testi için kullanır.

Testler düz metin dosyaları olduğu için Git ile iyi çalışır. Bir pull request içinde hangi endpoint'in, hangi assertion'ın veya hangi test verisinin değiştiğini net şekilde görebilirsiniz. Bu, Git-yerlisi, kod tabanlı bir iş akışı isteyen ekipler için pratiktir.

Given/When/Then yaklaşımına yeniyseniz, Davranış Odaklı Geliştirme kılavuzu bu yapının neden kullanıldığını açıklar.

Proje Yapısı: .feature Dosyaları ve karate-config.js

Karate'de temel bir test dosyası şu üç parçadan oluşur:

  1. Feature: Test dosyasının konusu
  2. Scenario: Çalıştırılacak test senaryosu
  3. Given / When / Then: İstek hazırlama, çalıştırma ve doğrulama adımları

Basit bir GET testi:

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]'
Enter fullscreen mode Exit fullscreen mode

Bu senaryo şunları yapar:

  • url ile temel adresi ayarlar.
  • path ile endpoint yolunu ekler.
  • method get ile GET isteğini gönderir.
  • status 200 ile HTTP durum kodunu doğrular.
  • match response == '#[10]' ile yanıtın 10 elemanlı bir JSON dizisi olduğunu kontrol eder.

#[10], JavaScript değil, Karate'nin eşleştirici söz dizimidir.

Gherkin söz dizimini daha detaylı öğrenmek isterseniz BDD ve API testi için Gherkin kılavuzuna bakabilirsiniz.

Ortam Yönetimi: karate-config.js

Gerçek projelerde endpoint URL'leri genellikle ortama göre değişir:

  • dev
  • qa
  • staging
  • prod

Karate bunu karate-config.js dosyasıyla yönetir. Bu dosya testlerden önce çalışır ve tüm senaryolarda kullanılabilecek değişkenleri 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;
}
Enter fullscreen mode Exit fullscreen mode

Bundan sonra test içinde URL'yi doğrudan yazmak yerine baseUrl kullanabilirsiniz:

Feature: User API

Background:
  * url baseUrl

Scenario: List users
  Given path 'users'
  When method get
  Then status 200
Enter fullscreen mode Exit fullscreen mode

Ortamı çalıştırma sırasında verebilirsiniz:

java -jar karate.jar -Dkarate.env=qa src/test/java/features
Enter fullscreen mode Exit fullscreen mode

Bu komut karate-config.js içindeki karate.env değerini qa yapar.

POST İsteği Yazma

Bir istek gövdesi gönderen örnek senaryo:

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'
Enter fullscreen mode Exit fullscreen mode

Bu testte:

  • Background dosyadaki her senaryodan önce çalışır.
  • * url baseUrl tüm senaryolar için temel URL'yi ayarlar.
  • request doğrudan JSON gövdesi alır.
  • status 201 kaynak oluşturma sonucunu doğrular.
  • #string, id alanının string tipinde olduğunu kontrol eder.

Karate'de POJO, serializer veya ayrı HTTP client kodu yazmanız gerekmez. JSON doğrudan .feature dosyasında tanımlanır.

Doğrulamalar ve JSON Eşleştirme

Karate'de ana doğrulama komutu matchtir.

Tam eşleşme örneği:

And match response == { id: '#number', name: 'Ada', job: 'engineer' }
Enter fullscreen mode Exit fullscreen mode

Burada:

  • #number: alan sayı olmalı
  • #string: alan string olmalı
  • #boolean: alan boolean olmalı
  • #uuid: alan UUID formatında olmalı

Bu eşleştiriciler, özellikle sunucu tarafından üretilen id, createdAt veya benzeri dinamik alanlarda testlerin kırılmasını azaltır.

Yalnızca belirli alanları kontrol etmek için contains kullanabilirsiniz:

And match response contains { name: 'Ada' }
Enter fullscreen mode Exit fullscreen mode

Bu assertion, yanıt içinde başka alanlar olsa bile name değerinin Ada olduğunu doğrular.

Karate ayrıca şu varyasyonları da destekler:

And match response !contains { error: 'Unauthorized' }
And match response contains only { id: 1, name: 'Ada' }
And match response contains any [{ role: 'admin' }, { role: 'editor' }]
And match response contains deep { user: { name: 'Ada' } }
Enter fullscreen mode Exit fullscreen mode

Dizi doğrulama örneği:

And match response == '#[10]'
Enter fullscreen mode Exit fullscreen mode

Bu, yanıtın 10 elemanlı bir JSON dizisi olduğunu kontrol eder.

Dizideki her elemanın şemasını doğrulamak için each kullanabilirsiniz:

And match each response == { id: '#number', name: '#string' }
Enter fullscreen mode Exit fullscreen mode

Bu tek satır, dizideki tüm nesnelerin şu yapıya sahip olduğunu doğrular:

{
  "id": "number",
  "name": "string"
}
Enter fullscreen mode Exit fullscreen mode

API yanıt doğrulamalarına daha geniş bir açıdan bakmak isterseniz API doğrulamalarına yönelik pratik kılavuza göz atabilirsiniz.

Veri Odaklı Test Yazma

Aynı senaryoyu farklı girdilerle çalıştırmak için Scenario Outline ve Examples kullanılır.

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   |
Enter fullscreen mode Exit fullscreen mode

Bu senaryo üç kez çalışır:

  1. Ada / engineer
  2. Grace / scientist
  3. Alan / analyst

Daha büyük test verileri için tabloyu .feature dosyasında tutmak yerine harici JSON veya CSV dosyasından okuyabilirsiniz:

Examples:
  | read('classpath:test-data/users.json') |
Enter fullscreen mode Exit fullscreen mode

Bu yaklaşım test mantığını ve test verisini ayırır. Özellikle çok sayıda input kombinasyonu olan endpoint'lerde daha sürdürülebilirdir.

CI'de Karate Çalıştırma

Karate'yi CI'de çalıştırmanın iki yaygın yolu vardır.

1. Maven veya Gradle ile Çalıştırma

Bir Java projesindeyseniz Karate'yi JUnit 5 üzerinden çalıştırabilirsiniz. Bu durumda karate-junit5 bağımlılığını ekler, bir runner sınıfı oluşturur ve testleri normal birim testleri gibi çalıştırırsınız.

Örnek Maven komutu:

mvn test
Enter fullscreen mode Exit fullscreen mode

Bu yaklaşım, mevcut Java CI pipeline'ına kolayca entegre olur.

2. Bağımsız karate.jar ile Çalıştırma

Maven veya Gradle kullanmak istemiyorsanız bağımsız jar dosyasını kullanabilirsiniz.

java -jar karate.jar src/test/java/features
Enter fullscreen mode Exit fullscreen mode

Etikete göre çalıştırmak için:

java -jar karate.jar --tags @smoke src/test/java/features
Enter fullscreen mode Exit fullscreen mode

Paralel çalıştırmak ve rapor dizini belirlemek için:

java -jar karate.jar --tags @smoke --threads 4 --output reports src/test/java/features
Enter fullscreen mode Exit fullscreen mode

Ortam seçmek için:

java -jar karate.jar -Dkarate.env=qa src/test/java/features
Enter fullscreen mode Exit fullscreen mode

Karate, çalıştırma sonunda HTML raporu üretir. Bu raporu CI artefaktı olarak saklayarak başarısız testleri pipeline üzerinden inceleyebilirsiniz.

CI/CD tarafını daha detaylı ele almak için CI/CD'de API testlerini nasıl otomatikleştireceğinizi inceleyebilirsiniz.

Karate'nin Güçlü Yönleri

Karate'nin öne çıktığı noktalar:

  • Testler düz metne yakın okunur.
  • HTTP adımları yerleşiktir.
  • JSON doğrulama için güçlü match söz dizimi vardır.
  • #string, #number, #uuid gibi esnek eşleştiriciler testleri daha dayanıklı yapar.
  • Testler Git altında tutulabilir.
  • Pull request incelemelerinde test değişiklikleri net görünür.
  • CI'de jar, Maven veya Gradle ile çalışabilir.
  • Mock, performans testi ve UI otomasyonu gibi ek modüllerle genişletilebilir.

Karate'nin Dezavantajları

Karate kod odaklı bir araçtır. Bu nedenle bazı maliyetleri vardır:

  • JVM gerektirir.
  • Java ekosistemine aşinalık faydalıdır.
  • DSL öğrenilmelidir.
  • Karmaşık yeniden kullanım senaryolarında JavaScript veya Java entegrasyonu gerekebilir.
  • Geliştirici olmayan ekip üyeleri test yazarken desteğe ihtiyaç duyabilir.
  • Testler kod olduğu için bakım disiplini gerekir.

Bu dezavantajlar Karate'yi kötü bir araç yapmaz. Sadece profilini netleştirir: Karate, testleri kod olarak yönetmek isteyen teknik ekipler için daha uygundur.

Karate ile Kodsuz Yaklaşım Karşılaştırması: Apidog

Karate kod tabanlı ve Git-yerlisidir. .feature dosyaları yazarsınız, commit edersiniz ve testleri CI'de çalıştırırsınız. Bu model, testleri uygulama kodunun yanında tutmak isteyen geliştirici ekipler için uygundur.

Apidog, aynı hedefe görsel ve kodsuz bir yoldan ulaşır. Test senaryolarını UI üzerinden oluşturur, istekleri zincirler ve doğrulamaları tıklayarak eklersiniz. API tasarımı, hata ayıklama, mocklama, dokümantasyon ve testler aynı çalışma alanında tutulabilir.

Bu yaklaşım özellikle şu ekipler için yararlıdır:

  • QA mühendisleri
  • Ürün ekipleri
  • API testlerini Java projesi kurmadan yönetmek isteyen ekipler
  • Testleri API dokümantasyonu ve tasarımıyla birlikte tutmak isteyen ekipler

Apidog'da oluşturulan testler CI'de de çalıştırılabilir. Bunun için Apidog CLI kullanılır.

Kurulum:

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

Kaydedilmiş bir senaryo veya paketi çalıştırma:

apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t <scenarioOrSuiteId> -e <environmentId> -r cli,html,junit
Enter fullscreen mode Exit fullscreen mode

Parametreler:

  • -t: senaryo, klasör veya paket kimliği
  • -e: ortam kimliği
  • -r: rapor formatları (cli, html, json, junit)
  • -d veya --iteration-data: veri odaklı çalıştırmalar için veri dosyası veya test verisi kimliği

Apidog CLI başsız çalışır ve Node çalıştırabilen herhangi bir CI ortamına eklenebilir. Etkileşimli bir istek gönderici veya yük testi aracı değildir; kaydedilmiş Apidog senaryolarını otomatik olarak çalıştırır.

Daha fazla detay için Apidog CLI'da tam incelemeyi ve Apidog CLI vs Newman karşılaştırmasını okuyabilirsiniz.

Özetle:

İhtiyaç Daha uygun yaklaşım
Testleri Git'te kod olarak tutmak Karate
JVM ve DSL ile çalışmak Karate
UI üzerinden test oluşturmak Apidog
QA ve ürün ekiplerinin katkı vermesi Apidog
CI'de başsız API testi çalıştırmak Her ikisi

Nasıl Seçilir?

Karate'yi şu durumlarda seçin:

  • Ekip geliştirici ağırlıklıysa
  • JVM ekosistemine alışkınsanız
  • Testleri uygulama kodunun yanında tutmak istiyorsanız
  • JSON assertion'larını kod benzeri bir DSL ile yazmak istiyorsanız
  • Pull request tabanlı test incelemesi sizin için önemliyse

Apidog gibi kodsuz bir aracı şu durumlarda seçin:

  • Testleri QA ve ürün ekipleri de yazacaksa
  • API tasarımı, dokümantasyon ve testleri tek yerde yönetmek istiyorsanız
  • Java projesi veya DSL bakımı istemiyorsanız
  • Görsel test akışı sizin için daha hızlıysa
  • CI'de yine de otomatik test çalıştırmak istiyorsanız

Bazı ekipler iki yaklaşımı birlikte kullanır: derin ve kod tabanlı regresyon testleri için Karate, daha geniş ekiplerin katkı verebildiği görsel API testleri için Apidog.

Hâlâ karar aşamasındaysanız bir API otomasyon test çerçevesini nasıl seçeceğinize dair genel bakış faydalı olabilir.

Sıkça Sorulan Sorular

Karate kullanmak için Java bilmem gerekiyor mu?

Temel API testleri yazmak için hayır. .feature dosyaları Gherkin DSL kullanır ve Karate HTTP adımlarını yerleşik olarak sağlar. Ancak testleri çalıştırmak için Java gerekir. Karmaşık yardımcı fonksiyonlar veya yeniden kullanım desenleri için JavaScript ya da Java bilgisi faydalı olur.

Karate'nin Cucumber'dan farkı nedir?

İkisi de Gherkin'in Given / When / Then söz dizimini kullanır. Cucumber'da adımlar için step definition kodu yazarsınız. Karate'de API testi adımları hazır gelir. Bu yüzden standart HTTP testleri için ek bağlantı kodu yazmanız gerekmez.

Karate Maven veya Gradle olmadan çalışabilir mi?

Evet. Bağımsız karate.jar dosyasını indirip şu şekilde çalıştırabilirsiniz:

java -jar karate.jar <yol>
Enter fullscreen mode Exit fullscreen mode

Etiket filtreleme, paralel çalıştırma ve özel çıktı dizini gibi seçenekler de desteklenir.

#string, #number ve #[10] ne anlama gelir?

Bunlar Karate'nin esnek eşleştiricileridir:

  • #string: alan string olmalı
  • #number: alan sayı olmalı
  • #boolean: alan boolean olmalı
  • #[10]: JSON dizisi 10 elemanlı olmalı

Bu yapı, dinamik değerleri sabitlemeden yanıtın şeklini doğrulamanızı sağlar.

Kodsuz API testleri CI'de çalışabilir mi?

Evet. Apidog gibi görsel araçlarda oluşturulan senaryolar Apidog CLI ile başsız şekilde çalıştırılabilir. Böylece testleri UI'de hazırlayıp CI pipeline içinde otomatik olarak çalıştırabilirsiniz.

Top comments (0)