DEV Community

Cover image for Apidog'da GraphQL API'lerini Test Etme (Sorgular, Mutasyonlar ve Otomasyon)
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

Apidog'da GraphQL API'lerini Test Etme (Sorgular, Mutasyonlar ve Otomasyon)

Bir GraphQL uç noktasının gerçekten çalıştığını doğrulamak için yalnızca HTTP durum koduna bakmak yeterli değildir. user sorgusunun uygulamanızın beklediği alanları döndürdüğünü, createOrder mutasyonunun veriyi kalıcı olarak yazdığını ve değişkenler değiştiğinde yanıt şemasının bozulmadığını kontrol etmeniz gerekir. GraphQL istekleri genellikle tek bir URL’ye POST gövdesiyle gönderildiği için, sorgu dilini destekleyen, şema önerileri sunan ve JSON yanıtları üzerinde doğrulama yapabilen bir istemci kullanmak önemlidir.

Apidog'u bugün deneyin

Apidog, HTTP, gRPC, WebSocket, SSE ve SOAP yanında GraphQL’i de ayrı bir istek türü olarak destekler. Bu rehberde sıfırdan bir GraphQL isteği oluşturacak, şemayı getirerek kod tamamlama etkinleştirecek, değişken kullanacak, mutasyon çalıştıracak ve yanıtı doğrulayacaksınız.

Örnek olarak bir e-ticaret API’sinde kullanıcı ve siparişlerini sorgulayıp ardından yeni bir sipariş oluşturacağız. GraphQL’in temel kavramları için resmî GraphQL belgelerine bakabilirsiniz. REST ve GraphQL arasındaki kullanım farkları için de REST ile GraphQL karşılaştırmasını inceleyin.

Neyi test ediyorsunuz ve GraphQL neden farklı?

REST API’lerde genellikle her kaynak için ayrı bir uç nokta bulunur ve her uç nokta sabit bir yanıt şekli döndürür. GraphQL ise tek bir uç nokta üzerinden istemcinin ihtiyaç duyduğu alanları seçmesine izin verir.

Örneğin REST çağrısı şöyle olabilir:

GET /users/42
Enter fullscreen mode Exit fullscreen mode

GraphQL’de aynı veri isteği çoğunlukla tek bir POST isteğinin gövdesindeki sorgu belgesiyle gönderilir:

user(id: 42) {
  id
  name
}
Enter fullscreen mode Exit fullscreen mode

GraphQL testinde dikkat edilmesi gereken kritik nokta hata davranışıdır. İş veya doğrulama hataları oluştuğunda GraphQL çoğu zaman HTTP seviyesinde 200 OK döndürür. Hata bilgisi ise JSON gövdesindeki errors dizisinde yer alır.

Bu nedenle her GraphQL testi en az şunları doğrulamalıdır:

  1. HTTP durum kodu 200 mü?
  2. Yanıtta errors alanı var mı?
  3. data altındaki alanlar beklenen değer ve yapıda mı?

Apidog; GraphQL gövde türü, şema tabanlı kod tamamlama, değişken desteği ve API doğrulama araçlarıyla bu kontrolleri tek bir akışta yapmanızı sağlar.

Apidog’da GraphQL isteği oluşturma

İlk olarak Apidog’u indirin veya tarayıcıdan açın. Ardından mevcut projenizi seçin ya da yeni bir proje oluşturun.

Adım 1: Yeni istek oluşturun ve gövdeyi GraphQL yapın

+ düğmesine tıklayın ve New Request seçeneğini seçin.

İstek metodunu POST olarak ayarlayın ve GraphQL uç noktanızı URL alanına girin:

https://api.yourstore.com/graphql
Enter fullscreen mode Exit fullscreen mode

Ardından:

  1. Body sekmesini açın.
  2. Gövde türü olarak GraphQL seçin.
  3. Açılan Query alanına GraphQL sorgunuzu yazın.

Uç noktanız kimlik doğrulama gerektiriyorsa Authorization bölümünden örneğin Bearer Token ekleyin. GraphQL istekleri de HTTP üzerinden çalıştığı için yetkilendirme süreci diğer POST istekleriyle aynıdır.

Adım 2: İlk sorgunuzu yazın

Run sekmesindeki Query alanına aşağıdaki sorguyu ekleyin:

query GetUserWithOrders {
  user(id: "usr_1024") {
    id
    name
    email
    orders {
      id
      total
      status
      createdAt
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Bu sorgu bir kullanıcıyı ve kullanıcının siparişlerini getirir.

Alan adları sunucunuzun GraphQL şemasıyla birebir eşleşmelidir. Örneğin şemada email yerine emailAddress tanımlıysa, email alanını istemek hata üretir.

Adım 3: Kod tamamlama için şemayı getirin

Alan adlarını tahmin etmek yerine şemayı Apidog’a getirin.

  1. GraphQL istek ekranında Fetch Schema düğmesine tıklayın.
  2. Apidog, GraphQL introspection sorgusu ile şema bilgisini çeker.
  3. Sorgu editöründe alan veya tip yazmaya başladığınızda geçerli önerileri kullanın.

Örneğin user { yazdıktan sonra editör, User tipinde kullanılabilen alanları önerebilir.

Dikkat edilmesi gerekenler:

  • Kod tamamlama otomatik olarak açılmaz; Fetch Schema işlemini manuel çalıştırmanız gerekir.
  • Üretim uç noktanızda introspection kapalıysa şema getirilemez.
  • Şema değiştiğinde güncel öneriler için tekrar Fetch Schema çalıştırın.

Adım 4: İsteği çalıştırın ve yanıtı inceleyin

Send düğmesine tıklayın. Başarılı bir yanıt şu yapıda olur:

{
  "data": {
    "user": {
      "id": "usr_1024",
      "name": "Dana Whitfield",
      "email": "dana@example.com",
      "orders": [
        {
          "id": "ord_5001",
          "total": 89.9,
          "status": "SHIPPED",
          "createdAt": "2026-07-01T09:14:00Z"
        },
        {
          "id": "ord_5002",
          "total": 12.5,
          "status": "PENDING",
          "createdAt": "2026-07-12T16:03:00Z"
        }
      ]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

GraphQL yanıtlarında asıl veri data altında bulunur. Hata varsa aynı seviyede errors dizisi görünür:

{
  "data": null,
  "errors": [
    {
      "message": "User not found"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Bu nedenle doğrulama yollarınızı kökten değil, data.user gibi iç içe alanlardan kurun.

İsteği yeniden kullanılabilir yapmak için değişken kullanın

Sorguya "usr_1024" değerini sabit yazmak hızlı bir deneme için uygundur. Ancak aynı isteği farklı kullanıcılar, test verileri veya ortamlar için çalıştıracaksanız GraphQL değişkenlerini kullanın.

GraphQL değişken sözdizimi standarttır; ayrıntılar için resmî GraphQL değişken belgelerine bakabilirsiniz.

Sorguyu şu şekilde güncelleyin:

query GetUserWithOrders($userId: ID!) {
  user(id: $userId) {
    id
    name
    orders {
      id
      total
      status
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Ardından değişken değerini JSON olarak iletin:

{
  "userId": "usr_1024"
}
Enter fullscreen mode Exit fullscreen mode

Bu yaklaşımla sorgu metnini değiştirmeden farklı kullanıcılar için test çalıştırabilirsiniz.

Pratik kullanım deseni:

  • Sorguda $userId kullanın.
  • Değeri GraphQL Variables alanından verin.
  • Ortama göre farklı değerler için Apidog ortam değişkenlerini kullanın.
  • Aynı isteği hazırlık ve üretim ortamlarında sorguyu değiştirmeden çalıştırın.

Sipariş oluşturmak için mutasyon yazın

GraphQL’de veri değiştiren işlemler mutation ile tanımlanır. Ayrı bir mutasyon sekmesi kullanmanız gerekmez; sorgularla aynı Query alanına yazılır.

Aşağıdaki mutasyon, kullanıcı için sipariş oluşturur:

mutation CreateOrder($input: CreateOrderInput!) {
  createOrder(input: $input) {
    id
    total
    status
    createdAt
  }
}
Enter fullscreen mode Exit fullscreen mode

Girdi verisini değişkenler alanında sağlayın:

{
  "input": {
    "userId": "usr_1024",
    "items": [
      {
        "sku": "TSHIRT-BLK-M",
        "quantity": 2
      },
      {
        "sku": "MUG-CERAMIC",
        "quantity": 1
      }
    ],
    "currency": "USD"
  }
}
Enter fullscreen mode Exit fullscreen mode

Send düğmesine tıkladığınızda başarılı bir yanıt şu şekilde olabilir:

{
  "data": {
    "createOrder": {
      "id": "ord_5003",
      "total": 42.3,
      "status": "PENDING",
      "createdAt": "2026-07-15T10:22:11Z"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Mutasyonlar gerçek veri yazabildiği için bunları öncelikle test veya hazırlık ortamında çalıştırın.

Uçtan uca test için şu akışı kullanın:

  1. Kullanıcıyı ve mevcut siparişlerini sorgulayın.
  2. createOrder mutasyonunu çalıştırın.
  3. Dönen sipariş id değerini kaydedin.
  4. Kullanıcı sorgusunu tekrar çalıştırın.
  5. Yeni siparişin sipariş listesinde yer aldığını doğrulayın.

Yanıtı gözle kontrol etmek yerine doğrulayın

JSON yanıtını elle okumak keşif aşamasında yeterli olabilir. Regresyon testlerinde ise doğrulama kuralları kullanmanız gerekir.

Apidog’da bir isteğe doğrulayıcı ekleyerek çalıştırmanın otomatik olarak başarılı veya başarısız sayılmasını sağlayabilirsiniz. Ayrıntılar için API doğrulamalarını inceleyin.

GraphQL için temel doğrulama seti şudur:

  • HTTP durum kodunun 200 olduğunu doğrulayın.
  • errors alanının mevcut olmadığını doğrulayın.
  • data altındaki kritik değerleri JSONPath ile kontrol edin.

Örnek doğrulamalar:

Kontrol Örnek yol Beklenen sonuç
HTTP durumu HTTP status 200
GraphQL hatası $.errors Alan bulunmamalı
Mutasyon durumu $.data.createOrder.status PENDING
Sipariş sayısı $.data.user.orders Uzunluk 0 değerinden büyük
Oluşturulan sipariş $.data.createOrder.id Boş olmamalı

Yalnızca 200 kontrolü yapmak yetersizdir. Aşağıdaki yanıt HTTP seviyesinde başarılı görünür, ancak GraphQL işlemi başarısızdır:

{
  "errors": [
    {
      "message": "Invalid input"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Bu nedenle errors alanının olmadığını doğrulamak GraphQL testlerinin temel kontrolüdür.

Bir test senaryosuna kaydedin

Tek bir doğrulanmış istek duman testi için faydalıdır. Daha güçlü bir kontrol için sorgu ve mutasyonları tek bir test senaryosunda zincirleyin.

Örnek senaryo:

  1. GetUserWithOrders sorgusunu çalıştırın.
  2. CreateOrder mutasyonunu çalıştırın.
  3. Mutasyon yanıtındaki $.data.createOrder.id değerini değişkene kaydedin.
  4. Kullanıcı veya sipariş sorgusunu tekrar çalıştırın.
  5. Kaydedilen sipariş kimliğinin döndüğünü doğrulayın.

Apidog test senaryoları adımları sıralamanıza, adımlar arasında veri aktarmanıza ve tüm akışı tek çalıştırmada doğrulamanıza imkân verir. Uygulama adımları için Apidog ile test senaryosu nasıl yazılır rehberine bakın.

GraphQL’i diğer API stilleriyle değerlendiriyorsanız şu kaynaklar da yardımcı olabilir:

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

GraphQL senaryolarınız projeye kaydedildikten sonra, kayıtlı test senaryolarını terminalden veya CI çalıştırıcısından Apidog CLI ile çalıştırabilirsiniz.

CLI’yi kurun ve oturum açın:

npm install -g apidog-cli
apidog login --with-token <your-token>
Enter fullscreen mode Exit fullscreen mode

Ardından belirli bir ortamda kaydedilmiş senaryoyu çalıştırın:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

Parametrelerin anlamı:

  • -t: Test senaryosu kimliği
  • -e: Ortam kimliği
  • -r: Raporlayıcı türü

Raporlayıcı olarak cli, html veya junit kullanabilirsiniz. Birden fazla raporlayıcı için virgülle ayırın:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t <scenario_id> \
  -e <env_id> \
  -r html,cli
Enter fullscreen mode Exit fullscreen mode

CLI; kaydedilmiş senaryoları ve test paketlerini çalıştırıp sonucu raporlayabilir. Ancak CLI belgeleri GraphQL adımları içeren senaryoların başsız çalıştırılmasını açıkça belirtmez. Bu nedenle GraphQL sorgu, mutasyon ve doğrulama akışlarınızı uygulamada doğrulamak; CLI’yi ise HTTP regresyon çalıştırmaları ve belirtim senkronizasyonu için kullanmak daha güvenli bir yaklaşımdır.

Kurulum ve CI entegrasyonu için:

Sıkça Sorulan Sorular

Apidog’da GraphQL test etmek için ücretli plana ihtiyacım var mı?

GraphQL istek belgeleri bu özelliğin belirli bir plan kademesine veya bulut/kendi kendine barındırılan ayrımına bağlı olduğunu belirtmez. Ücretsiz katmanla başlayabilir, güncel plan bilgileri için Apidog sayfasını kontrol edebilirsiniz.

GraphQL isteğim neden 200 dönmesine rağmen başarısız oluyor?

Bu normal GraphQL davranışıdır. HTTP isteği başarıyla ulaşmış olabilir, ancak iş veya doğrulama hatası JSON gövdesindeki errors dizisinde döner. Bu yüzden HTTP durumuna ek olarak errors alanının bulunmadığını doğrulamalısınız.

Sorgu yazarken alan önerilerini nasıl alabilirim?

GraphQL istek ekranındaki Fetch Schema düğmesine tıklayın. Apidog introspection ile şemayı çeker ve editörde geçerli alanlar ile tipler için kod tamamlama önerileri sunar.

Mutasyonlar için ayrı bir sekme var mı?

Hayır. Mutasyonları sorgularla aynı Query alanına yazarsınız. Tek fark, query yerine mutation anahtar kelimesini kullanmanızdır.

Sorguyu değiştirmeden farklı değerleri nasıl iletebilirim?

GraphQL değişkenlerini kullanın. Değişkeni işlem imzasında $ önekiyle tanımlayın ve değeri JSON değişken nesnesi olarak iletin:

query GetUser($userId: ID!) {
  user(id: $userId) {
    id
    name
  }
}
Enter fullscreen mode Exit fullscreen mode 
{
  "userId": "usr_1024"
}
Enter fullscreen mode Exit fullscreen mode

Özet

GraphQL testinde güvenilir bir iş akışı için:

  1. GraphQL gövde türünü seçin.
  2. Sorgu veya mutasyonu Query alanına yazın.
  3. Kod tamamlama için şemayı getirin.
  4. Sabit değerleri GraphQL değişkenlerine taşıyın.
  5. HTTP 200 kontrolüne ek olarak errors alanını doğrulayın.
  6. data altındaki kritik alanları JSONPath ile test edin.
  7. Sorgu ve mutasyonları tekrar çalıştırılabilir bir senaryoda zincirleyin.

Bu akışla kullanıcı sorgusu, sipariş oluşturma ve oluşturulan veriyi yeniden okuma işlemlerini aynı regresyon testi içinde doğrulayabilirsiniz.

Top comments (0)