DEV Community

Cover image for Apidog'da Koşullu Mock Veri Nasıl Döndürülür (Özel Kurallar ve Mock Scriptleri)
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

Apidog'da Koşullu Mock Veri Nasıl Döndürülür (Özel Kurallar ve Mock Scriptleri)

Akıllı mock, saniyeler içinde sahte bir API oluşturur. Uç nokta şemanızı okuyarak gerçekçi görünen e-posta adresleri, zaman damgaları ve adlar gibi mantıklı veriler döndürür. Çoğu ön uç geliştirme senaryosunda, bağımlı olduğunuz arka uç hazır olmadan ilerlemeniz için yeterlidir.

Apidog'u bugün deneyin

Ancak bazı test senaryolarında tek bir yanıt şekli yeterli olmaz. Örneğin, bilinen bir kullanıcı için /login uç noktasının 200, diğer kullanıcılar için 401 döndürmesini isteyebilirsiniz. /orders/{id} çağrısında bir siparişin sevk edilmiş, diğerinin iptal edilmiş görünmesi gerekebilir. Ya da hata yönetimini test etmek için isteğe bağlı olarak 500 hatası üretmeniz gerekebilir.

Apidog bu ihtiyacı iki özellikle karşılar:

  • Mock beklentileri: Kural tabanlı ve koşullu yanıtlar için.
  • Mock komut dosyaları: Kurallarla ifade edemediğiniz hesaplama veya dönüşüm mantığı için.

Bu yazıda her iki yöntemi de uygulamalı örneklerle ele alacak, ayrıca özel kuralların Akıllı mock'a neden ve nasıl öncelik verdiğini göstereceğiz. Başlangıç için API mock'lama genel bakışına bakabilirsiniz. Bu rehber boyunca Apidog kullanacağız. Sözleşme öncelikli yaklaşımın temelleri için OpenAPI Girişimi kaynaklarını da inceleyebilirsiniz.

Koşullu mock'lama nedir?

Koşullu mock, basitçe şu mantığı uygular:

İstek belirli bir koşulla eşleşirse belirli bir yanıt döndür.

Apidog'da bunu iki katmanda uygulayabilirsiniz.

  1. Alan düzeyinde değer özelleştirme

    Bir alanı sabit bir değere ayarlayabilir veya her çağrıda yeni değer üretmek için Faker.js ifadeleri kullanabilirsiniz. Bu yaklaşım alan içeriğini değiştirir; ancak uç noktanın genel yanıt yapısı aynı kalır.

  2. Mock beklentileri

    Her beklenti; isteğe bağlı koşullar, yanıt gövdesi, HTTP durum kodu ve yanıt başlıkları içeren adlandırılmış bir kuraldır. Birden fazla beklenti tanımlayarak gerçek dallanma davranışı oluşturabilirsiniz.

Örneğin:

  • Belirli bir kullanıcı adı için 200
  • Eksik başlık için hata gövdesi
  • Farklı yol parametreleri için farklı sipariş durumları
  • Belirli bir başlık gönderildiğinde 500

Bu rehberin odağı ikinci katmandır: isteğe göre farklı yanıt döndüren mock beklentileri.

Alan düzeyinde dinamik değerler

Koşullu kurallara geçmeden önce, tekil alanlarda dinamik veri üretimini gözden geçirelim.

Uç nokta şemanızda bir dize alanına şu biçimde Faker.js ifadesi ekleyebilirsiniz:

{{$category.method}}
Enter fullscreen mode Exit fullscreen mode

Apidog, her mock çağrısında bu ifadeleri çözer ve JSON Şema tanımınızdaki alan türlerine uygun yeni değerler üretir.

{
  "id": "{{$number.int(min=1000,max=9999)}}",
  "customer": "{{$person.fullName}}",
  "email": "{{$internet.email}}",
  "product": "{{$commerce.productName}}",
  "shippingAddress": "{{$location.streetAddress}}, {{$location.city}}",
  "orderedAt": "{{$date.between(from='2024-01-01',to='2024-12-31',format='yyyy-MM-dd')}}"
}
Enter fullscreen mode Exit fullscreen mode

Parametre alan yöntemleriyle üretilen veriyi sınırlandırabilirsiniz:

  • {{$number.int(min=1000,max=9999)}}: Belirtilen aralıkta sayı üretir.
  • {{$date.between(...)}}: Tarih aralığı ve çıktı formatı belirler.
  • Birden fazla ifadeyi veya statik metni aynı alanda birleştirebilirsiniz.

Bölgeye özgü isim, adres ve telefon verileri gerekiyorsa Apidog mock yerel ayarlarını özelleştirebilirsiniz. Tüm kullanılabilir yöntemler için Apidog'daki Faker.js referansına bakın.

Faker.js ile dinamik mock değerleri

Bu yaklaşım dinamiktir ancak koşullu değildir. İsteğe göre yanıt değiştirmek için mock beklentilerini kullanmanız gerekir.

Uygulamalı örnek: /login için 200 veya 401 döndürmek

Senaryo:

  • POST /login, kullanıcı adı ve parola içeren JSON gövdesi alır.
  • alice@example.com için 200 ve token döndürür.
  • Diğer tüm kullanıcılar için 401 döndürür.

Doğru sekmeyi açın

Yapılandırma ekranı çalışma modunuza göre değişir:

  • Hata Ayıklama (İstek öncelikli) modunda uç noktayı açın ve Mock sekmesine geçin.

Hata Ayıklama modunda Mock sekmesi

  • Tasarım (Tasarım öncelikli) modunda uç noktayı açın ve Gelişmiş mock sekmesine geçin.

Tasarım modunda Gelişmiş mock sekmesi

Her iki ekran da aynı beklenti listesine ulaşır. Henüz bir projeniz yoksa Apidog'u indirin ve bir /login uç noktası oluşturun veya içe aktarın.

1. Başarı beklentisini ekleyin

Yeni beklenti seçeneğine tıklayın ve beklenti adına login-success yazın.

Ardından JSON gövdesindeki username alanı için koşul ekleyin:

Alan Değer
Gövde parametresi username
Operatör Eşittir
Değer alice@example.com

İç içe alanlarda nokta gösterimini kullanın. Örneğin:

user.email
Enter fullscreen mode Exit fullscreen mode

Başarılı yanıt gövdesini şu şekilde ayarlayın:

{
  "token": "mock-jwt-{{$string.uuid}}",
  "user": {
    "id": 4821,
    "username": "alice@example.com",
    "role": "member"
  }
}
Enter fullscreen mode Exit fullscreen mode

Varsayılan HTTP durum kodu 200 olduğu için başarı senaryosunda ek ayar yapmanız gerekmez.

2. Hata beklentisini ekleyin

Tekrar Yeni beklenti seçeneğine tıklayın ve adına login-failure yazın.

Bu kez koşulları boş bırakın. Böylece bu beklenti, üstteki özel kurallarla eşleşmeyen tüm istekleri yakalayan varsayılan durum olur.

Yanıt gövdesi:

{
  "error": "invalid_credentials",
  "message": "Username or password is incorrect."
}
Enter fullscreen mode Exit fullscreen mode

Ardından beklentinin Daha Fazla sekmesinden HTTP durum kodunu 401 olarak ayarlayın.

Aynı ekrandan şunları da yapılandırabilirsiniz:

  • Yanıt gecikmesi: Milisaniye cinsinden gecikme.
  • Özel yanıt başlıkları
  • HTTP durum kodu

Örneğin, yükleme durumlarını test etmek için 400 ms gecikme ekleyebilirsiniz.

3. Beklenti sırasını kontrol edin

Beklentiler yukarıdan aşağıya değerlendirilir ve ilk eşleşen kural kazanır.

Doğru sıralama:

  1. login-success
  2. login-failure

Bu sıralamada:

  • alice@example.com için ilk kural eşleşir ve 200 döner.
  • Diğer tüm kullanıcılar ikinci, koşulsuz kurala düşer ve 401 alır.

Ters sıralama yaparsanız boş koşullu login-failure kuralı her isteği yakalar. Bu durumda başarı kuralı hiç çalışmaz.

Mock URL'nizi kullanarak iki durumu test edin:

# Bilinen kullanıcı -> 200 ve token
curl -X POST https://<your-mock-host>/login \
  -H "Content-Type: application/json" \
  -d '{"username":"alice@example.com","password":"whatever"}'

# Diğer kullanıcılar -> 401
curl -X POST https://<your-mock-host>/login \
  -H "Content-Type: application/json" \
  -d '{"username":"stranger@example.com","password":"whatever"}'
Enter fullscreen mode Exit fullscreen mode

Uygulamalı örnek: /orders/{id} için farklı gövdeler

Bir diğer yaygın ihtiyaç, yol parametresine göre farklı yanıtlar döndürmektir.

Örneğin kullanıcı arayüzünüzün farklı sipariş durumlarını gerçek arka uç olmadan işlemesini isteyebilirsiniz:

  • /orders/5001: Sevk edilmiş sipariş
  • /orders/5002: İptal edilmiş sipariş
  • Diğer kimlikler: Genel bekleyen sipariş

Her durum için ayrı bir mock beklentisi oluşturun.

order-shipped beklentisi

Koşul:

Alan Değer
Yol parametresi id
Operatör Eşittir
Değer 5001

Yanıt gövdesi:

{
  "id": 5001,
  "status": "shipped",
  "total": 129.9,
  "trackingNumber": "1Z{{$string.alphanumeric(length=16)}}",
  "shippedAt": "{{$date.recent(days=3,format='yyyy-MM-dd')}}"
}
Enter fullscreen mode Exit fullscreen mode

order-cancelled beklentisi

Koşul:

Alan Değer
Yol parametresi id
Operatör Eşittir
Değer 5002

Yanıt gövdesi:

{
  "id": 5002,
  "status": "cancelled",
  "total": 0,
  "cancelledAt": "{{$date.recent(days=1,format='yyyy-MM-dd')}}",
  "refundIssued": true
}
Enter fullscreen mode Exit fullscreen mode

Varsayılan beklentiyi ekleyin

Son olarak, koşulsuz bir beklenti ekleyerek diğer tüm sipariş kimlikleri için genel bir bekleyen sipariş yanıtı döndürebilirsiniz.

Önemli sıralama:

  1. order-shipped
  2. order-cancelled
  3. Genel, koşulsuz beklenti

Bir beklentiye birden fazla koşul ekleyebilirsiniz. Örneğin hem yol parametresi hem de başlık koşulu tanımlarsanız, Apidog bunları AND mantığıyla birleştirir. Yani yanıtın dönmesi için tüm koşulların eşleşmesi gerekir.

Koşulları şu kaynaklara göre tanımlayabilirsiniz:

  • Yol parametreleri
  • Sorgu parametreleri
  • Başlıklar
  • Çerezler
  • IP adresleri
  • JSON gövdesi alanları

İsteğe bağlı hata durumlarını zorlama

Hata senaryolarını test etmek için bozuk bir arka uca ihtiyacınız yoktur.

Örneğin, istemcinin gönderdiği bir başlığa göre 500 döndüren bir beklenti oluşturabilirsiniz.

Koşul:

Alan Değer
Başlık X-Mock-Scenario
Operatör Eşittir
Değer server-error

Yanıt gövdesi:

{
  "error": "internal_error",
  "requestId": "{{$string.uuid}}",
  "message": "Something went wrong on our end. Please retry."
}
Enter fullscreen mode Exit fullscreen mode

Beklentinin Daha Fazla sekmesinde HTTP durum kodunu 500 olarak ayarlayın.

Artık aynı uç nokta:

  • Normalde 200
  • X-Mock-Scenario: server-error başlığı gönderildiğinde 500

döndürebilir.

Aynı yaklaşımı şu durumlar için de kullanabilirsiniz:

  • 404
  • 429
  • 503

429 testi yapıyorsanız Daha Fazla sekmesinden Retry-After yanıt başlığını da ekleyebilirsiniz.

Bu hata senaryolarını otomatik testlerde doğrulamak için API iddiaları rehberini kullanabilirsiniz.

Paylaşılan projelerde her beklentiyi yerel ve bulut mock ortamları için bağımsız olarak açıp kapatabilirsiniz. Örneğin, yerelde 500 kuralını etkin bırakırken ekip arkadaşlarınızın kullandığı bulut mock ortamında kapalı tutabilirsiniz.

Kurallar yeterli olmadığında: Mock komut dosyaları

Mock beklentileri deklaratiftir: isteği eşleştirir ve önceden tanımlanmış bir yanıt döndürür.

Ancak şu ihtiyaçlarınız varsa mock komut dosyası kullanmanız gerekir:

  • İstek gövdesinden toplam hesaplamak
  • Birden fazla girdiye göre yanıt biçimini değiştirmek
  • İstekten türetilen alanlar üretmek
  • Dizi işlemleri veya tarih hesaplamaları yapmak

Mock komut dosyaları JavaScript ile çalışır ve Mock sekmesinin altındaki Mock Komut Dosyası bölümünden etkinleştirilir.

Kullanabileceğiniz iki global nesne vardır:

  • $$.mockRequest: Gelen isteği okur.
  • $$.mockResponse: Giden yanıtı düzenler.

Kullanılabilir API'ler

$$.mockRequest ile:

  • getParam(key)
  • headers
  • cookies
  • body
  • formdata
  • urlencoded

$$.mockResponse ile:

  • setBody()
  • setCode()
  • setDelay()
  • json()
  • headers
  • code

Aşağıdaki örnek, istek gövdesindeki satır öğelerinden sipariş toplamını hesaplar ve x-currency başlığını yanıta yansıtır:

const body = $$.mockRequest.body;
const items = body.items || [];

const subtotal = items.reduce((sum, item) => {
  return sum + item.price * item.quantity;
}, 0);

const currency = $$.mockRequest.headers["x-currency"] || "USD";

$$.mockResponse.setCode(201);
$$.mockResponse.setBody({
  orderId: Math.floor(Math.random() * 90000) + 10000,
  currency: currency,
  subtotal: subtotal,
  tax: Number((subtotal * 0.08).toFixed(2)),
  total: Number((subtotal * 1.08).toFixed(2))
});
Enter fullscreen mode Exit fullscreen mode

İşleyiş sırası şöyledir:

  1. Akıllı mock başlangıç yanıtını üretir.
  2. Komut dosyası $$.mockRequest üzerinden isteği okur.
  3. Komut dosyası mevcut $$.mockResponse nesnesini değiştirir.
  4. setBody(), setCode(), setDelay() veya headers ile nihai yanıt oluşturulur.
  5. Mock motoru sonucu döndürür.

JavaScript dizi işlemleri, tarih hesaplamaları ve veri dönüşümleri için MDN JavaScript referansı yararlı bir kaynaktır.

Dikkat: Mock komut dosyaları beklentilerle birlikte çalışmaz

Mock komut dosyaları yalnızca Akıllı mock ile çalışır.

Bir mock beklentisi eşleşirse:

  • Mock komut dosyası çalışmaz.
  • Beklentinin yanıtı doğrudan döndürülür.

Bu nedenle uç nokta başına yaklaşımınızı seçin:

İhtiyaç Kullanılacak özellik
Sabit koşullara göre dallanma Mock beklentileri
Önceden hazırlanmış hata veya başarı gövdeleri Mock beklentileri
Hesaplanan toplamlar Mock komut dosyaları
İstekten türetilen dinamik yanıt Mock komut dosyaları
Karmaşık JavaScript mantığı Mock komut dosyaları

Öncelik sırası nasıl çalışır?

Apidog, bir mock isteğini şu sırayla işler:

  1. Mock beklentilerini yukarıdan aşağıya kontrol eder.

    Tüm koşulları eşleşen ilk beklenti kazanır ve yanıt doğrudan döndürülür.

  2. Hiçbir beklenti eşleşmezse Mock yöntem önceliğine döner.

    Bu ayarı şu konumdan yapılandırabilirsiniz:

   Proje Ayarları > Özellik Ayarları > Mock Ayarları > Mock yöntem önceliği
Enter fullscreen mode Exit fullscreen mode

Bu katmanda Akıllı mock ve varsa ona bağlı mock komut dosyası yanıtı üretir.

Pratik sıralama kuralı:

  1. En spesifik beklentileri en üste koyun.
  2. Daha genel kuralları alta koyun.
  3. Gerekiyorsa en alta koşulsuz bir her şeyi yakalayan kural ekleyin.
  4. Eşleşmeyen istekleri Akıllı mock'a bırakın.

Bu yaklaşım hakkında daha fazla örnek için API mock'lama kullanım senaryoları rehberine bakabilirsiniz.

Yayınlamadan önce bilmeniz gereken tuzaklar

Koşullu mock'ları yapılandırırken şu sınırlamaları göz önünde bulundurun:

  • Parametre koşulları {{değişken}} kullanımını desteklemez. Proje ve ortam değişkenleri mock beklentilerinde kullanılamaz.
  • Gövde parametresi koşulları yalnızca JSON içindir; XML gövdeleriyle eşleşmez.
  • İç içe JSON alanları için nokta gösterimi kullanmalısınız: user.email.
  • İstek gövdesi biçimi API belirtiminizle eşleşmelidir. Form-data uç noktasını JSON gövdesi gibi mock etmeyin.
  • Mock komut dosyalarında günlük kaydı işlevi yoktur.
  • Mock komut dosyalarında pm nesnesi kullanılamaz.
  • Mock komut dosyalarında Apidog değişkenleri kullanılamaz.

Bu özellikler için dokümanlarda plan sınırlaması belirtilmemektedir. Yerel ve bulut mock ortamlarındaki fark, daha önce anlatıldığı gibi beklentilerin ortam başına bağımsız olarak açılıp kapatılabilmesidir.

İş akışını Apidog CLI ile otomatikleştirin

Apidog'da mock sunucusu GUI ve bulut üzerinden çalışır. CLI ile doğrudan çalışan bir mock sunucusu başlatan komut bulunmaz.

Bunun yerine Apidog CLI, mock'ların dayandığı uç nokta ve şema tanımlarını yönetmenize yardımcı olur.

Mock yanıtları şemadan üretildiği için mock doğruluğu doğrudan API sözleşmenizin doğruluğuna bağlıdır. CLI ve onu kullanan kodlama ajanları; proje uç noktalarını ve şemalarını oluşturabilir veya güncelleyebilir.

İş akışı:

  1. API sözleşmesini kodda güncelleyin.
  2. Değişiklikleri projeyle senkronize edin.
  3. Mock çıktısının güncel şemayı takip etmesini sağlayın.
  4. Test senaryolarını CI ortamında gerçek arka uca karşı çalıştırın.

Örnek CLI komutu:

apidog run -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

Bu komut test senaryolarını çalıştırır ve sonuçları raporlar. Böylece mock ve doğrulama süreçleri aynı API sözleşmesini kullanır.

Kurulum için Apidog CLI kurulum kılavuzuna, CI entegrasyonu için GitHub Actions'taki Apidog CLI rehberine bakabilirsiniz.

Sıkça Sorulan Sorular

Koşul doğru görünse bile beklentim neden göz ardı ediliyor?

Genellikle iki neden vardır:

  1. Sıralama hatası: Daha yukarıdaki geniş veya koşulsuz bir kural isteği önce yakalıyordur.
  2. Format uyumsuzluğu: JSON gövdesi, form-data veya JSON yolu API belirtimiyle eşleşmiyordur.

Beklentilerin yukarıdan aşağıya işlendiğini unutmayın. Temel kurulum için API mock'lama genel bakışına tekrar bakabilirsiniz.

Aynı yanıt üzerinde mock komut dosyası ve mock beklentisi kullanabilir miyim?

Hayır.

Mock komut dosyaları yalnızca Akıllı mock ile çalışır. Bir beklenti eşleştiğinde komut dosyası çalıştırılmaz.

  • Kural tabanlı dallanma için mock beklentilerini kullanın.
  • Hesaplanmış veya dönüştürülmüş veri için mock komut dosyalarını kullanın.

Varsayılan 200 yanıtını bozmadan nasıl 401 veya 500 döndürebilirim?

İstemcinin kontrol edebileceği bir koşula sahip özel beklenti ekleyin. Başlık kullanmak pratik bir yöntemdir.

Örneğin:

X-Mock-Scenario: server-error
Enter fullscreen mode Exit fullscreen mode

Ardından beklentinin Daha Fazla sekmesinden HTTP durum kodunu 500 olarak ayarlayın. Koşul eşleşmediğinde varsayılan 200 yanıtı döner.

Koşullar ortam değişkenlerini kullanabilir mi?

Hayır.

Apidog'da {{değişken}} değerleri mock beklentilerinde ve parametre koşullarında kullanılamaz. Koşullar için sabit değerler kullanmalısınız.

Hiçbir beklenti eşleşmezse ne olur?

Apidog, şu ayardaki Mock yöntem önceliğine döner:

Proje Ayarları > Özellik Ayarları > Mock Ayarları
Enter fullscreen mode Exit fullscreen mode

Bu aşamada Akıllı mock şemanızdan yanıt üretir. Belirli bir geri dönüşü garanti etmek istiyorsanız, en alta koşulsuz bir her şeyi yakalayan beklenti ekleyin.

Özet

Akıllı mock, şemanızdan hızlı ve gerçekçi varsayılan yanıtlar üretir. Mock beklentileri ise koşullu davranış ekler:

  • Bilinen kullanıcı için 200, diğerleri için 401
  • Sipariş kimliğine göre farklı gövdeler
  • Başlıkla tetiklenen 500, 429 veya 503 hataları
  • Belirli istemciler veya parametreler için özel yanıtlar

Hesaplanmış çıktı gerektiğinde mock komut dosyalarını kullanın. Ancak mock komut dosyalarının yalnızca Akıllı mock ile çalıştığını ve eşleşen mock beklentilerinden sonra çalışmadığını unutmayın.

Temel öncelik kuralı şöyledir:

Önce spesifik beklentiler, sonra üretilen Akıllı mock verileri.

İlk koşullu mock'unuzu oluşturmak için Apidog'u ücretsiz indirin.

Top comments (0)