DEV Community

Cover image for Cara Menguji API GraphQL di Apidog (Kueri, Mutasi, dan Otomatisasi)
Walse
Walse

Posted on • Originally published at apidog.com

Cara Menguji API GraphQL di Apidog (Kueri, Mutasi, dan Otomatisasi)

Anda memiliki endpoint GraphQL dan perlu memastikan endpoint tersebut benar-benar bekerja: kueri user mengembalikan bidang yang dipakai aplikasi, mutasi createOrder menyimpan pesanan, dan bentuk respons tetap konsisten saat variabel berubah. Alat REST yang berfokus pada URL dan HTTP method sering terasa kurang nyaman untuk GraphQL karena semua operasi biasanya dikirim ke satu endpoint melalui body POST. Anda memerlukan klien yang memahami sintaks kueri, dapat membaca skema, memberi saran bidang, dan memvalidasi respons JSON.

Coba Apidog hari ini

Apidog mendukung GraphQL sebagai tipe permintaan khusus, bersama HTTP, gRPC, WebSocket, SSE, dan SOAP. Dalam panduan ini, Anda akan membuat permintaan GraphQL dari nol: menulis kueri, mengambil skema untuk pelengkapan kode, memakai variabel, menjalankan mutasi, menambahkan assertion, lalu menyimpannya sebagai skenario pengujian. Contohnya menggunakan API e-commerce untuk mengambil pengguna dan pesanan, kemudian membuat pesanan baru. Untuk konsep dasar GraphQL, gunakan dokumentasi resmi GraphQL. Untuk memilih pendekatan API yang tepat, lihat perbandingan REST vs GraphQL.

Apa yang diuji dan mengapa GraphQL berbeda

REST biasanya memiliki banyak endpoint dengan struktur respons tetap. GraphQL biasanya menggunakan satu endpoint, tetapi pemanggil menentukan sendiri bidang yang ingin diambil.

Contoh REST:

GET /users/42
Enter fullscreen mode Exit fullscreen mode

Padanan GraphQL:

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

Dua perbedaan penting saat menguji GraphQL:

  1. Operasi dikirim sebagai dokumen kueri di body request, bukan sebagai variasi URL.
  2. HTTP 200 tidak selalu berarti operasi berhasil. GraphQL dapat mengembalikan 200 OK meskipun terjadi kesalahan validasi atau kesalahan bisnis. Kesalahan tersebut biasanya muncul dalam array errors.

Contoh respons yang gagal secara logika, tetapi tetap menggunakan HTTP 200:

{
  "errors": [
    {
      "message": "User tidak ditemukan"
    }
  ],
  "data": {
    "user": null
  }
}
Enter fullscreen mode Exit fullscreen mode

Karena itu, assertion GraphQL harus memeriksa body respons, bukan hanya status HTTP.

Buat permintaan GraphQL di Apidog

Mulai dengan mengunduh Apidog atau membukanya melalui browser. Buat atau buka proyek agar permintaan dapat disimpan dan digunakan ulang.

Langkah 1: buat request GraphQL

  1. Klik tombol +.
  2. Pilih New Request.
  3. Atur method menjadi POST.
  4. Masukkan URL endpoint GraphQL Anda.

Contoh:

https://api.yourstore.com/graphql
Enter fullscreen mode Exit fullscreen mode
  1. Buka tab Body.
  2. Pilih tipe body GraphQL.

Apidog akan menampilkan editor GraphQL dengan area Query. Jika endpoint memerlukan autentikasi, buka bagian Authorization dan tambahkan token, misalnya Bearer token.

Authorization: Bearer <your-token>
Enter fullscreen mode Exit fullscreen mode

GraphQL tetap berjalan melalui HTTP, sehingga konfigurasi autentikasinya sama seperti request HTTP lain.

Langkah 2: tulis kueri pertama

Di tab Run, masukkan kueri untuk mengambil pengguna beserta pesanan mereka:

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

Kueri ini meminta:

  • data pengguna;
  • daftar pesanan terkait;
  • detail setiap pesanan, termasuk status dan waktu pembuatan.

Nama bidang harus sesuai dengan skema server. Jika skema menggunakan emailAddress, bukan email, kueri akan gagal. Untuk menghindari menebak nama bidang, ambil skema endpoint pada langkah berikutnya.

Langkah 3: ambil skema untuk pelengkapan kode

Klik Fetch Schema pada editor GraphQL. Apidog akan menjalankan introspeksi terhadap endpoint dan mengambil informasi tipe, query, mutation, serta bidang yang tersedia.

Setelah skema berhasil diambil, editor dapat memberi saran bidang dan tipe saat Anda menulis kueri.

Gunakan alur berikut:

  1. Pastikan URL endpoint sudah benar.
  2. Konfigurasikan autentikasi bila diperlukan.
  3. Klik Fetch Schema.
  4. Mulai tulis kueri dan pilih bidang dari saran editor.
  5. Jalankan ulang Fetch Schema setelah ada perubahan skema.

Perlu diingat:

  • Pelengkapan kode tidak aktif otomatis; Anda harus memilih Fetch Schema.
  • Jika introspeksi dinonaktifkan di server produksi, skema tidak dapat diambil.
  • Dalam kasus tersebut, gunakan dokumentasi internal atau skema GraphQL yang disediakan tim backend.

Langkah 4: jalankan dan baca respons

Klik Send. Respons yang berhasil dapat terlihat seperti ini:

{
  "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

Perhatikan struktur respons:

  • hasil operasi berada di bawah data;
  • kesalahan GraphQL berada di bawah errors;
  • assertion nilai harus menggunakan jalur seperti $.data.user.orders, bukan $.user.orders.

Meneruskan variabel agar request dapat digunakan ulang

Jangan meng-hardcode nilai seperti "usr_1024" jika request akan dipakai ulang. Gunakan variabel GraphQL agar Anda dapat menjalankan kueri yang sama untuk pengguna, environment, atau data pengujian yang berbeda.

Referensi sintaksnya tersedia di dokumentasi GraphQL tentang variables.

Ubah kueri menjadi:

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

Kemudian masukkan nilai variabel sebagai JSON:

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

Dengan pola ini, Anda hanya perlu mengubah nilai di object variables tanpa mengedit dokumen kueri.

Untuk environment yang berbeda, gunakan kombinasi variabel GraphQL dan environment variables Apidog. Misalnya:

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

Dengan demikian, request yang sama dapat dijalankan terhadap staging dan produksi dengan konfigurasi environment yang berbeda.

Tulis mutasi untuk membuat pesanan

Mutasi digunakan untuk mengubah data. Di Apidog, mutasi ditulis pada editor Query yang sama; cukup gunakan keyword mutation.

Contoh mutasi untuk membuat pesanan:

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

Masukkan payload melalui variables:

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

Klik Send. Respons yang berhasil dapat berbentuk seperti ini:

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

Karena mutasi menulis data, jalankan mutasi pada environment testing atau staging, bukan produksi.

Pola pengujian end-to-end yang praktis:

  1. Jalankan query pengguna.
  2. Jalankan mutasi CreateOrder.
  3. Simpan id pesanan dari respons mutasi.
  4. Jalankan kembali query pengguna.
  5. Pastikan pesanan baru muncul pada daftar orders.

Tegaskan respons, jangan periksa JSON secara manual

Saat eksplorasi, memeriksa JSON secara manual masih cukup. Namun, pengujian regresi memerlukan assertion yang dapat menentukan lulus atau gagal secara otomatis.

Apidog memungkinkan Anda menambahkan assertion ke request, seperti yang dijelaskan pada panduan penegasan API.

Untuk request GraphQL, tambahkan minimal tiga pemeriksaan berikut:

  1. Status HTTP adalah 200

    Ini memastikan transport HTTP berhasil.

  2. Field errors tidak ada

    Ini adalah pemeriksaan utama GraphQL. Status 200 tetap dapat berisi kegagalan operasi.

  3. Nilai di bawah data sesuai harapan

    Gunakan JSONPath untuk memvalidasi struktur dan isi respons.

Contoh assertion yang berguna:

Status code equals 200
Enter fullscreen mode Exit fullscreen mode 
$.errors does not exist
Enter fullscreen mode Exit fullscreen mode 
$.data.createOrder.status equals PENDING
Enter fullscreen mode Exit fullscreen mode 
$.data.user.orders length is greater than 0
Enter fullscreen mode Exit fullscreen mode

Kombinasi tersebut menangkap masalah yang tidak terlihat jika hanya memeriksa status HTTP, seperti:

  • bidang GraphQL tidak valid;
  • user tidak ditemukan;
  • respons mengandung errors;
  • mutasi berhasil dipanggil tetapi mengembalikan status pesanan yang tidak sesuai;
  • struktur respons berubah setelah pembaruan skema.

Simpan alur ke dalam skenario pengujian

Satu request dengan assertion cocok untuk smoke test. Untuk pengujian alur bisnis, rangkai beberapa request menjadi skenario.

Contoh skenario:

  1. Query pengguna.
  2. Buat pesanan melalui mutasi.
  3. Ekstrak id pesanan dari respons mutasi.
  4. Query ulang pengguna atau pesanan.
  5. Pastikan pesanan yang dibuat benar-benar tersimpan.

Skenario pengujian Apidog dapat menjalankan langkah-langkkah tersebut secara berurutan, meneruskan data antar-step, dan menjalankan seluruh alur dengan satu aksi. Lihat panduan cara menulis skenario pengujian dengan Apidog.

Implementasikan skenario dengan langkah berikut:

  1. Buat test scenario baru.
  2. Tambahkan query GetUserWithOrders.
  3. Tambahkan mutasi CreateOrder.
  4. Ekstrak nilai berikut dari respons mutasi: 
   $.data.createOrder.id
Enter fullscreen mode Exit fullscreen mode
  1. Simpan hasil ekstraksi sebagai variabel skenario.
  2. Gunakan variabel tersebut pada query verifikasi.
  3. Tambahkan assertion pada setiap langkah.

Dengan pendekatan ini, Anda memiliki tes regresi yang dapat digunakan kembali saat skema, resolver, atau logika bisnis berubah.

Untuk membandingkan GraphQL dengan protokol lain, lihat REST vs GraphQL vs gRPC dan ringkasan alat pengujian dan mocking GraphQL. Jika stack Anda juga menggunakan SOAP, pola request dan assertion yang sama dapat diterapkan melalui panduan cara menguji API SOAP di Apidog.

Otomatiskan alur kerja dengan Apidog CLI

Setelah skenario berada dalam proyek, Anda dapat menjalankan skenario pengujian yang tersimpan dari terminal atau CI runner menggunakan Apidog CLI.

Instal CLI dan login:

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

Kemudian jalankan skenario berdasarkan ID dan environment:

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

Parameter yang digunakan:

  • -t: ID skenario pengujian;
  • -e: ID environment;
  • -r: reporter, misalnya cli, html, atau junit.

Untuk memakai lebih dari satu reporter:

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

CLI menjalankan skenario dan test suite yang disimpan di proyek cloud, lalu melaporkan hasil lulus atau gagal. Ini membuatnya sesuai untuk integrasi build dan pipeline.

Namun, dokumentasi CLI mengonfirmasi eksekusi skenario HTTP dan tidak secara eksplisit menyatakan apakah skenario dengan langkah GraphQL dapat berjalan tanpa kepala. Gunakan CLI untuk regresi HTTP dan sinkronisasi spesifikasi melalui perintah import untuk OpenAPI, HAR, Postman, dan format lainnya. Untuk pekerjaan query, mutation, dan assertion GraphQL, gunakan aplikasi Apidog.

Baca panduan instalasi Apidog CLI untuk setup token dan Apidog CLI dalam pipeline GitHub Actions untuk integrasi CI.

FAQ

Apakah saya memerlukan paket berbayar untuk menguji GraphQL di Apidog?

Dokumen request GraphQL tidak membatasi fitur ini pada paket tertentu dan tidak membedakan dukungan cloud maupun self-hosted. Anda dapat mulai dari paket gratis tanpa kartu kredit. Lihat Apidog untuk detail paket terbaru.

Mengapa request GraphQL mengembalikan 200 tetapi tetap gagal?

Itu adalah perilaku normal GraphQL. Transport HTTP berhasil sehingga server mengembalikan status 200, tetapi operasi dapat gagal karena validasi atau kesalahan bisnis. Selalu assert bahwa errors tidak ada, selain memeriksa status HTTP. Lihat panduan penegasan API.

Bagaimana cara mendapatkan saran bidang saat menulis kueri?

Klik Fetch Schema di editor GraphQL. Apidog akan mengintrospeksi endpoint dan mengaktifkan pelengkapan kode untuk bidang dan tipe yang valid. Jalankan kembali pengambilan skema setelah skema API berubah.

Di mana tab khusus untuk mutation?

Tidak ada tab terpisah. Tulis mutasi pada kotak Query yang sama menggunakan keyword mutation, lalu kirim payload melalui variables dan klik Send.

Bagaimana cara mengganti nilai tanpa menulis ulang kueri?

Gunakan variabel GraphQL. Deklarasikan variabel dengan prefiks $ pada signature operasi, lalu masukkan nilainya sebagai object JSON. Sintaks ini mengikuti spesifikasi variables GraphQL dan dapat dipadukan dengan environment variables Apidog.

Kesimpulan

Pengujian GraphQL yang efektif bergantung pada beberapa kebiasaan:

  • tulis operasi pada editor Query;
  • ambil skema agar editor dapat memberi saran bidang valid;
  • gunakan variables untuk data yang berubah;
  • periksa errors, bukan hanya status HTTP;
  • tambahkan assertion pada nilai di bawah data;
  • rangkai query dan mutation ke dalam skenario pengujian.

Mulai dengan mengunduh Apidog, buat alur query pengguna dan pembuatan pesanan, lalu simpan sebagai tes regresi yang dapat dijalankan kembali setiap kali skema berubah.

Top comments (0)