Bir GraphQL uç noktanız var ve çalıştığından emin olmanız gerekiyor. "Sunucu ayakta" değil, gerçek anlamda: user sorgusu uygulamanızın okuduğu alanları döndürüyor mu, bir createOrder mutasyonu gerçekten bir siparişi kalıcı kılıyor mu ve bir değişkeni değiştirdiğinizde şekiller bozulmuyor mu? Yalnızca yol ve fiil çağrılarını bilen bir REST aracı bunu zorlaştırır. GraphQL, her şeyi bir POST gövdesi olarak tek bir URL'ye gönderir, bu nedenle sorgu dilini anlayan, alan önerileri sunan ve geri dönen JSON üzerinde iddiada bulunmanıza olanak tanıyan bir istemciye ihtiyacınız var.
Apidog, HTTP, gRPC, WebSocket, SSE ve SOAP'ın yanı sıra GraphQL'ı birinci sınıf bir istek türü olarak ele alır. Bu kılavuz, sıfırdan bir GraphQL isteği oluşturmayı adım adım açıklar: sorgu yazma, kod tamamlama için şemayı getirme, değişkenleri iletme, bir mutasyon çalıştırma ve yanıta iddiada bulunma. Çalışan örnek, bir kullanıcıyı ve siparişlerini sorguladığınız, ardından yeni bir sipariş oluşturduğunuz bir e-ticaret API'sidir. GraphQL'in neden birçok uç nokta yerine tek, tip tanımlı bir sorgu gönderdiğine dair kavramsal arka planı öğrenmek isterseniz, resmi GraphQL belgeleri temel referanstır ve REST ile GraphQL karşılaştırmamız her birinin ne zaman uygun olduğunu ele alır.
Neyi test ediyorsunuz ve GraphQL neden farklı?
REST size her biri sabit bir şekil döndüren birçok uç nokta sunar. GraphQL ise size tek bir uç nokta sunar ve arayanın tam olarak istediği alanları istemesine olanak tanır. Bu esneklik işin püf noktasıdır ve testin neden farklı hissettirdiğini de açıklar.
İki şey değişir. Birincisi, istek gövdedeki bir sorgu belgesidir, değiştirdiğiniz bir URL değil. Bir GET /users/42 çağrısı, POST ile gönderilen bir user(id: 42) { ... } seçimine dönüşür. İkincisi, GraphQL iş hataları için neredeyse hiçbir zaman 200 olmayan bir durum kodu döndürmez. Başarısız bir sorgu bile JSON'da bir errors dizisiyle 200 OK olarak geri döner. Bu nedenle, durum kodunu kontrol etmek yeterli değildir. Gövdeyi okumanız gerekir. Bu tek gerçek, bu kılavuzda daha sonra nasıl iddiada bulunacağınızı şekillendirir.
Apidog size özel bir GraphQL gövde tipi, şema tabanlı kod tamamlama, tekrar kullanılabilir sorgular için değişkenler ve REST için kullanacağınız aynı doğrulama ve test senaryosu araçlarını sunar. İsteği uygulamada tasarlar ve çalıştırır, ardından yeniden çalıştırabileceğiniz bir senaryo olarak kaydedersiniz. Hadi bir tane oluşturalım.
Apidog'da bir GraphQL isteği oluşturma
İlk olarak, Apidog'u İndirin veya tarayıcınızda açın, ardından projenizi açın. Yeni başlıyorsanız, isteğin barınabileceği bir yer olması için bir proje oluşturun.
Adım 1: Yeni bir istek oluşturun ve gövdeyi GraphQL olarak değiştirin
+ düğmesine tıklayın ve New Request (Yeni İstek) seçeneğini belirleyin. Bu, bir REST çağrısı için kullanacağınız standart istek oluşturucuyu açar: metod, URL, parametreler ve Authorization (Yetkilendirme).
Metodu POST olarak ayarlayın ve GraphQL uç noktanızı URL çubuğuna yapıştırın. Tipik bir örnek şuna benzer:
https://api.yourstore.com/graphql
Şimdi Apidog'a bunun bir GraphQL isteği olduğunu bildirin. İstek gövdesi alanında Body (Gövde) öğesine tıklayın, ardından GraphQL'i seçin. Gövde düzenleyici, sorgu dilinin bulunduğu bir Query (Sorgu) kutusuyla GraphQL'e duyarlı bir görünüme dönüşür.
Uç noktanız bir belirteç gerektiriyorsa, Authorization (Yetkilendirme) bölümünü açın ve örneğin bir Taşıyıcı belirteci ekleyin. Bir GraphQL isteğindeki yetkilendirme, Apidog'daki diğer HTTP istekleriyle aynı şekilde çalışır, çünkü aslında hâlâ bir HTTP POST'tur.
Adım 2: İlk sorgunuzu yazın
Run (Çalıştır) sekmesinde, sorgunuzu Query (Sorgu) kutusuna yazın. Somut bir şeyle başlayın. Burada bir kullanıcı ve ona bağlı siparişleri istiyorsunuz:
query GetUserWithOrders {
user(id: "usr_1024") {
id
name
email
orders {
id
total
status
createdAt
}
}
}
Bu, bir kullanıcıyı ve iç içe geçmiş sipariş listesini ister. Alan adları sunucunuzun şemasıyla tam olarak eşleşmelidir. Şemanız email yerine emailAddress olarak adlandırıyorsa, bu sorgu başarısız olur. Bu, bir sonraki adımın önlemesi gereken bir durumdur.
Adım 3: Kod tamamlama için şemayı getirin
Alan adlarını tahmin etmek, GraphQL testinin yavaşladığı noktadır. Apidog şemanızı okuyabilir, böylece düzenleyici siz yazarken geçerli alanları ve tipleri önerir; başka bir sekmedeki bir belgeyi çapraz kontrol etmenize gerek kalmaz.
Bu manuel, isteğe bağlı bir eylemdir. Giriş kutusundaki Fetch Schema (Şemayı Getir) düğmesine tıklayın. Apidog, uç noktanıza karşı bir iç gözlem sorgusu çalıştırır ve tip sistemini çeker. Başarılı olduğunda, kod tamamlama açılır: bir seçimin içine bir alan yazmaya başladığınızda, o tipte gerçekten neyin mevcut olduğuna dair IntelliSense tarzı öneriler alırsınız.
Bilinmesi gereken iki şey var. Kod tamamlama otomatik değildir; yalnızca Fetch Schema (Şemayı Getir) düğmesine tıkladıktan sonra etkinleşir. Ve uç noktanızda iç gözlem devre dışıysa (bazı üretim sunucuları güvenlik nedeniyle yapar), getirme işlemi bir şema döndürmez, bu nedenle alanları kendi belgelerinize göre elle yazmanız gerekir. Getirme işlemi çalışıyorsa, önerilerin güncel kalması için herhangi bir şema değişikliğinden sonra tekrar getirin.
Adım 4: Çalıştırın ve yanıtı okuyun
Send (Gönder) düğmesine tıklayın. Yanıt arayüzün alt yarısında görünür. Başarılı bir sonuç şuna benzer:
{
"data": {
"user": {
"id": "usr_1024",
"name": "Dana Whitfield",
"email": "dana@example.com",
"orders": [
{ "id": "ord_5001", "total": 89.90, "status": "SHIPPED", "createdAt": "2026-07-01T09:14:00Z" },
{ "id": "ord_5002", "total": 12.50, "status": "PENDING", "createdAt": "2026-07-12T16:03:00Z" }
]
}
}
}
En üst düzey data anahtarına dikkat edin. Her GraphQL yanıtı, sonucunuzu data altında iç içe yerleştirir ve herhangi bir sorun kardeş bir errors dizisinde görünür. Bu yapıyı aklınızda bulundurun, çünkü iddialarınız köke değil, data.user... öğesine işaret edecektir.
İsteği yeniden kullanılabilir kılmak için değişkenleri geçirme
Sorguya "usr_1024"'ü sabit kodlamak bir kez işe yarar. Kullanıcılar ve ortamlar arasında yeniden çalıştıracağınız bir istek için, bu değeri bir değişkene taşıyın. GraphQL'in bunun için birinci sınıf bir değişken sözdizimi vardır ve Apidog bunu destekler. Sözdiziminin kendisi bir Apidog icadı yerine standart GraphQL'dir, bu nedenle değişkenler hakkındaki resmi GraphQL belgeleri doğruluk kaynağıdır.
Değişkeni sorgu imzasında bir $ öneki ve bir tür ile bildirin, ardından argümanlarda kullanın:
query GetUserWithOrders($userId: ID!) {
user(id: $userId) {
id
name
orders {
id
total
status
}
}
}
Ardından değeri küçük bir değişken JSON nesnesi olarak sağlayın:
{
"userId": "usr_1024"
}
Şimdi aynı sorgu, tek bir JSON değerini değiştirerek herhangi bir kullanıcı için çalışır. Bunu Apidog ortam değişkenleriyle eşleştirin ve sorguyu düzenlemeden aynı isteği hazırlık ve üretim ortamlarına yönlendirebilirsiniz. Tek seferlik bir çağrıyı kaydedebileceğiniz, paylaşabileceğiniz ve bir pakette çalıştırabileceğiniz bir şeye dönüştüren şey budur.
Sipariş oluşturmak için bir mutasyon yazın
Bir mutasyon veriyi değiştirir. GraphQL'de bunun için ayrı bir protokol veya kullanıcı arayüzü yoktur; bir mutasyon, query anahtar kelimesi yerine mutation anahtar kelimesiyle aynı Query kutusuna GraphQL olarak yazılır. Böylece zaten bildiğiniz iş akışı doğrudan devam eder.
Burada, daha önce sorguladığınız kullanıcı için bir sipariş oluşturursunuz:
mutation CreateOrder($input: CreateOrderInput!) {
createOrder(input: $input) {
id
total
status
createdAt
}
}
Değişkenler yükü taşır:
{
"input": {
"userId": "usr_1024",
"items": [
{ "sku": "TSHIRT-BLK-M", "quantity": 2 },
{ "sku": "MUG-CERAMIC", "quantity": 1 }
],
"currency": "USD"
}
}
Send (Gönder) düğmesine tıklayın. İyi bir yanıt oluşturulan siparişi yankılar:
{
"data": {
"createOrder": {
"id": "ord_5003",
"total": 42.30,
"status": "PENDING",
"createdAt": "2026-07-15T10:22:11Z"
}
}
}
Mutasyonlar gerçek veri yazdığı için, bunları üretim ortamı yerine bir test veya hazırlık ortamında çalıştırın. Yaygın bir desen, mutasyonu çalıştırmak, döndürülen id'yi yakalamak, ardından GetUserWithOrders sorgunuzu tekrar çalıştırmak ve yeni siparişin listede göründüğünü doğrulamaktır. Bu sorgu-mutasyon-sorgu döngüsü gerçekçi bir uçtan uca kontroldür ve tam da bir sonraki bölümde bir senaryo olarak kaydetmek isteyeceğiniz türden bir şeydir.
Yanıtı gözle kontrol etmek yerine doğrulayın
Keşfederken JSON'ı elle okumak iyidir. Otomatik olarak çalışan bir test için, kendi başlarına geçen veya başarısız olan doğrulayıcılara ihtiyacınız vardır. Apidog, bir isteğe doğrulayıcılar eklemenize olanak tanır, böylece bir çalıştırma otomatik olarak değerlendirilir; bu, API doğrulamalarında kurduğunuz şeydir.
GraphQL için, üç kontrol çoğu durumu kapsar:
- HTTP durumunun
200olduğunu doğrulayın. Gerekli ancak yeterli değil, çünkü GraphQL iş hatalarında bile 200 döndürür. errorsalanının bulunmadığını doğrulayın. Bu, gerçek GraphQL geçiş veya başarısızlık kapısıdır.errorsmevcutsa, durum ne olursa olsun işlem başarısız olmuştur.dataiçindeki belirli değerleri doğrulayın; örneğin$.data.createOrder.status'unPENDING'e eşit olduğunu veya$.data.user.orders'ın sıfırdan büyük bir uzunluğa sahip olduğunu bir JSONPath kullanarak doğrulayın.
Bu kombinasyon, yalnızca durum kontrolünün kaçırdığı hata modlarını yakalar: errors dizisiyle 200 döndüren bir sorgu veya başarılı olan ancak yanlış bir şekil döndüren bir sorgu. Değer doğrulayıcılarınızı, daha önce gördüğünüz yanıt yapısıyla eşleşen data altındaki iç içe yola yönlendirin.
Bir test senaryosuna kaydedin
Tek bir doğrulanmış istek iyi bir duman testidir. Asıl fayda, istekleri bir senaryo halinde zincirlemektir: kullanıcıyı sorgula, bir sipariş oluştur, ardından kalıcı olup olmadığını onaylamak için tekrar sorgula. Apidog test senaryoları, bu adımları sıralamanıza, aralarında veri aktarmanıza (mutasyondan id'yi yakalayıp onaylayıcı sorguya besleme) ve tüm akışı tek tıklamayla çalıştırmanıza olanak tanır. Tam ayrıntılı açıklama Apidog ile test senaryosu nasıl yazılır bölümünde bulunur.
Üst düzeyde: yeni bir test senaryosu oluşturun, GraphQL sorgunuzu ve mutasyonunuzu sırayla adımlar olarak ekleyin, mutasyon yanıtından sipariş id'sini bir değişkene çıkarın ve bu değişkeni son sorgu adımında referans alın. Önceki bölümdeki doğrulamaları her adıma ekleyin. Artık GraphQL API'niz için bir insan, bir zamanlayıcı veya bir işlem hattının çalıştırabileceği tekrarlanabilir bir regresyon testine sahipsiniz.
GraphQL'i diğer stillere karşı değerlendiren ekipler için, REST vs GraphQL vs gRPC karşılaştırmamız ve GraphQL test ve alay araçları özetimiz bu iş akışını bağlama oturtmanıza yardımcı olur. Ve yığın teknolojiniz SOAP da konuşuyorsa, Apidog'da SOAP API'leri nasıl test edilir bölümünde aynı istek ve doğrulama deseni uygulanır.
İş akışını Apidog CLI ile otomatikleştirme
GraphQL senaryolarınız projede yer aldığında, projenin kaydedilmiş test senaryolarını bir terminalden veya CI çalıştırıcısından Apidog CLI ile çalıştırabilirsiniz. Kurun ve oturum açın:
npm install -g apidog-cli
apidog login --with-token <your-token>
Ardından, bir ortamı hedefleyerek kimliğe göre kaydedilmiş bir senaryoyu çalıştırın:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Burada -t test senaryosu kimliği, -e ortam kimliği ve -r raporlayıcıdır (cli, html veya junit; birden fazla için virgülle ayırın, örneğin -r html,cli). CLI, bulut projenizdeki kaydedilmiş senaryoları ve test paketlerini çalıştırır ve geçme veya kalma durumunu raporlar; bu da Apidog'u bir yapıya bağlar. Dürüst bir uyarı: CLI belgeleri HTTP senaryo yürütmesini doğrular ve GraphQL adımlarını içeren senaryoların başsız çalışıp çalışmadığını belirtmez. CLI'yı HTTP regresyon çalıştırmaları için motorunuz ve import komutu (OpenAPI, HAR, Postman ve daha fazlası) aracılığıyla belirtimleri senkronize tutmak için kullanın ve GraphQL sorgu, mutasyon ve doğrulama çalışmalarınızı uygulamada yapın. Belirteç kurulumu için Apidog CLI kurulum kılavuzuna ve CI'ya bağlamak için GitHub Actions işlem hattındaki Apidog CLI'ye bakın.
Sıkça Sorulan Sorular
Apidog'da GraphQL test etmek için ücretli bir plana ihtiyacım var mı? GraphQL istek belgeleri bu özelliği bir plan kademesinin arkasına gizlemez ve bulut tabanlı veya kendi kendine barındırılan bir ayrım da yapmazlar. Ücretsiz katmanla başlayabilirsiniz: ücretsiz deneyin, kredi kartı gerekmez ve güncel plan detayları için Apidog'a bakın.
GraphQL isteğim neden 200 döndürmesine rağmen başarısız oluyor? Bu normal GraphQL davranışıdır. İletim başarılı olmuştur, bu nedenle HTTP durumu 200'dür, ancak işlem JSON gövdesindeki errors dizisine düşen bir iş veya doğrulama hatasıyla karşılaşmıştır. Durumu kontrol etmenin yanı sıra, API doğrulamalarında ele alındığı gibi, errors'ın bulunmadığını her zaman doğrulayın.
Sorgu yazarken alan önerilerini nasıl alabilirim? Giriş kutusundaki Fetch Schema (Şemayı Getir) düğmesine tıklayın. Apidog, uç noktanızı iç gözlemleyerek kod tamamlamayı etkinleştirir, böylece düzenleyici geçerli alanları ve türleri önerir. Bu otomatik olmayan manuel bir adımdır, bu nedenle uç nokta URL'niz ayarlandıktan sonra tıklayın ve herhangi bir şema değişikliğinden sonra yeniden getirin.
Mutasyonlar nereye gider? Ayrı bir mutasyon sekmesi görmüyorum. Böyle bir sekme yok. Bir mutasyon, query anahtar kelimesi yerine mutation anahtar kelimesi kullanılarak aynı Query kutusuna GraphQL olarak yazılır. Yükünü değişkenler aracılığıyla iletin, ardından bir sorguda olduğu gibi Send (Gönder) düğmesine tıklayın.
Sorguyu yeniden yazmadan farklı değerleri nasıl iletebilirim? GraphQL değişkenlerini kullanın. Bunları işlem imzasında bir $ önekiyle bildirin ve bir JSON değer nesnesi sağlayın. Sözdizimi standart GraphQL belirtimini takip eder ve Apidog'un değişken desteği ortam değişkenleriyle eşleşerek tek bir isteğin hazırlık ve üretim ortamlarında çalışmasını sağlar.
Özet
GraphQL testi birkaç dürüst alışkanlığa dayanır: sorguyu Query kutusuna yazmak, düzenleyicinin size yardımcı olması için şemayı getirmek, sabit değerleri değişkenlere taşımak ve durum koduna güvenmek yerine gövdeyi doğrulamak. Bir mutasyonu bir sorguyla aynı şekilde çalıştırın, ardından her ikisini de kaydedilmiş bir senaryo halinde zincirleyin, böylece kontrol kendini tekrar eder. Eşlik etmek için Apidog'u indirin, yukarıdaki kullanıcı ve siparişler akışını oluşturun ve şemanız her değiştiğinde yeniden çalıştırabileceğiniz bir GraphQL regresyon testiniz olacaktır.