Anda memiliki endpoint GraphQL dan Anda perlu tahu apakah itu berfungsi. Bukan "server sudah berjalan," tetapi yang sebenarnya: apakah kueri user mengembalikan bidang yang dibaca aplikasi Anda, apakah mutasi createOrder benar-benar menyimpan pesanan, dan apakah bentuknya tetap sama saat Anda mengubah variabel. Alat REST yang hanya mengetahui panggilan jalur-dan-kata kerja membuatnya canggung. GraphQL mengirimkan semuanya ke satu URL sebagai badan POST, jadi Anda memerlukan klien yang memahami bahasa kueri itu sendiri, memberi Anda saran bidang, dan memungkinkan Anda menegaskan JSON yang kembali.
Apidog menangani GraphQL sebagai tipe permintaan kelas satu, di samping HTTP, gRPC, WebSocket, SSE, dan SOAP. Panduan ini akan memandu Anda membangun permintaan GraphQL dari awal: menulis kueri, mengambil skema untuk pelengkapan kode, meneruskan variabel, menjalankan mutasi, dan menegaskan respons. Contoh yang berjalan adalah API e-commerce tempat Anda mengkueri pengguna dan pesanan mereka, lalu membuat pesanan baru. Jika Anda menginginkan latar belakang konseptual mengapa GraphQL mengirimkan satu kueri bertipe alih-alih banyak endpoint, dokumentasi resmi GraphQL adalah referensi kanonis, dan perbandingan kami REST vs GraphQL mencakup kapan masing-masing cocok.
Apa yang Anda uji dan mengapa GraphQL berbeda
REST memberi Anda banyak endpoint, masing-masing mengembalikan bentuk yang tetap. GraphQL memberi Anda satu endpoint dan memungkinkan pemanggil meminta persis bidang yang diinginkannya. Fleksibilitas itulah intinya, dan itu juga yang membuat pengujian terasa berbeda.
Dua hal berubah. Pertama, permintaan adalah dokumen kueri di badan, bukan URL yang Anda variasikan. Sebuah GET /users/42 menjadi pemilihan user(id: 42) { ... } yang dikirim oleh POST. Kedua, GraphQL hampir tidak pernah mengembalikan status non-200 untuk kesalahan bisnis. Kueri yang gagal masih kembali 200 OK dengan array errors di JSON. Jadi memeriksa kode status saja tidak cukup. Anda harus membaca badan. Fakta tunggal ini membentuk bagaimana Anda menegaskan nanti dalam panduan ini.
Apidog memberi Anda tipe badan GraphQL khusus, pelengkapan kode yang peka skema, variabel untuk kueri yang dapat digunakan kembali, dan alat penegasan dan skenario pengujian yang sama yang akan Anda gunakan untuk REST. Anda merancang dan menjalankan permintaan di aplikasi, lalu menyimpannya ke dalam skenario yang dapat Anda jalankan kembali.
Buat permintaan GraphQL di Apidog
Pertama, Unduh Apidog atau buka di browser Anda, lalu buka proyek Anda. Jika Anda memulai dari awal, buat proyek agar permintaan memiliki tempat untuk tinggal.
Langkah 1: buat permintaan baru dan alihkan badan ke GraphQL
Klik tombol + dan pilih New Request. Ini membuka pembangun permintaan standar, yang sama yang akan Anda gunakan untuk panggilan REST: metode, URL, parameter, dan Authorization.
Atur metode ke POST dan tempel endpoint GraphQL Anda ke bilah URL. Yang khas terlihat seperti ini:
https://api.yourstore.com/graphql
Sekarang beritahu Apidog bahwa ini adalah permintaan GraphQL. Di area badan permintaan, klik Body, lalu pilih GraphQL. Editor badan berubah ke tampilan yang peka GraphQL dengan kotak Query, di mana bahasa kueri berada.
Jika endpoint Anda memerlukan token, buka bagian Authorization dan tambahkan di sana, misalnya token Bearer. Otentikasi pada permintaan GraphQL berfungsi sama seperti permintaan HTTP lainnya di Apidog, karena pada dasarnya itu masih HTTP POST.
Langkah 2: tulis kueri pertama Anda
Pada tab Run, ketik kueri Anda ke dalam kotak Query. Mulailah dengan sesuatu yang konkret. Di sini Anda menginginkan pengguna dan pesanan yang terkait dengannya:
query GetUserWithOrders {
user(id: "usr_1024") {
id
name
email
orders {
id
total
status
createdAt
}
}
}
Ini meminta satu pengguna dan daftar pesanan mereka yang bersarang. Nama bidang harus sama persis dengan skema server Anda. Jika skema Anda menyebutnya emailAddress alih-alih email, kueri ini akan gagal. Itu adalah tugas langkah selanjutnya untuk mencegahnya.
Langkah 3: ambil skema untuk pelengkapan kode
Menebak nama bidang adalah bagian di mana pengujian GraphQL berjalan lambat. Apidog dapat membaca skema Anda sehingga editor menyarankan bidang dan tipe yang valid saat Anda mengetik, alih-alih Anda memeriksa silang dokumen di tab lain.
Ini adalah tindakan manual, sesuai permintaan. Klik tombol Fetch Schema di kotak input. Apidog menjalankan kueri introspeksi terhadap endpoint Anda dan menarik sistem tipe. Setelah berhasil, pelengkapan kode aktif: mulai ketik bidang di dalam pilihan dan Anda akan mendapatkan saran gaya IntelliSense untuk apa yang sebenarnya tersedia pada tipe tersebut.
Dua hal yang perlu diketahui. Pelengkapan kode tidak otomatis; itu hanya aktif setelah Anda mengklik Fetch Schema. Dan jika endpoint Anda memiliki introspeksi yang dinonaktifkan (beberapa server produksi melakukannya demi keamanan), pengambilan tidak akan mengembalikan skema, jadi Anda harus menulis bidang secara manual sesuai dokumentasi Anda sendiri. Jika pengambilan berhasil, ulangi pengambilan setelah perubahan skema agar saran tetap mutakhir.
Langkah 4: jalankan dan baca responsnya
Klik Send. Respons muncul di bagian bawah antarmuka. Hasil yang sehat terlihat seperti ini:
{
"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" }
]
}
}
}
Perhatikan kunci data tingkat atas. Setiap respons GraphQL menyarangkan hasil Anda di bawah data, dan masalah apa pun muncul dalam array errors yang sejajar. Ingatlah struktur itu, karena pernyataan Anda akan menunjuk ke data.user..., bukan ke root.
Meneruskan variabel untuk membuat permintaan dapat digunakan kembali
Mengkodekan "usr_1024" ke dalam kueri hanya berfungsi sekali. Untuk permintaan yang akan Anda jalankan berulang kali di seluruh pengguna dan lingkungan, pindahkan nilai itu ke dalam variabel. GraphQL memiliki sintaks variabel kelas satu untuk ini, dan Apidog mendukungnya. Sintaks itu sendiri adalah GraphQL standar daripada penemuan Apidog, jadi dokumen resmi GraphQL tentang variabel adalah sumber kebenaran.
Deklarasikan variabel dalam tanda tangan kueri dengan prefiks $ dan tipe, lalu gunakan dalam argumen:
query GetUserWithOrders($userId: ID!) {
user(id: $userId) {
id
name
orders {
id
total
status
}
}
}
Kemudian berikan nilainya sebagai objek JSON kecil dari variabel:
{
"userId": "usr_1024"
}
Sekarang kueri yang sama berjalan untuk pengguna mana pun dengan mengubah satu nilai JSON. Pasangkan ini dengan variabel lingkungan Apidog dan Anda dapat mengarahkan permintaan yang identik ke staging dan produksi tanpa mengedit kueri. Inilah yang mengubah panggilan sekali pakai menjadi sesuatu yang dapat Anda simpan, bagikan, dan jalankan dalam suite.
Tulis mutasi untuk membuat pesanan
Mutasi mengubah data. Di GraphQL tidak ada protokol atau UI terpisah untuk itu; mutasi ditulis sebagai GraphQL dalam kotak Query yang sama, dengan kata kunci mutation alih-alih query. Jadi alur kerja yang sudah Anda ketahui langsung berlaku.
Di sini Anda membuat pesanan untuk pengguna yang Anda kueri sebelumnya:
mutation CreateOrder($input: CreateOrderInput!) {
createOrder(input: $input) {
id
total
status
createdAt
}
}
Variabel membawa payload:
{
"input": {
"userId": "usr_1024",
"items": [
{ "sku": "TSHIRT-BLK-M", "quantity": 2 },
{ "sku": "MUG-CERAMIC", "quantity": 1 }
],
"currency": "USD"
}
}
Klik Send. Respons yang baik menggemakan pesanan yang dibuat:
{
"data": {
"createOrder": {
"id": "ord_5003",
"total": 42.30,
"status": "PENDING",
"createdAt": "2026-07-15T10:22:11Z"
}
}
}
Karena mutasi menulis data nyata, jalankan terhadap lingkungan pengujian atau staging, bukan produksi. Pola umum adalah menjalankan mutasi, menangkap id yang dikembalikan, lalu menjalankan kueri GetUserWithOrders Anda lagi dan mengkonfirmasi pesanan baru muncul dalam daftar. Loop kueri-mutasi-kueri itu adalah pemeriksaan end-to-end yang realistis, dan itu persis jenis hal yang ingin Anda simpan sebagai skenario di bagian berikutnya.
Tegaskan respons alih-alih memeriksanya secara manual
Membaca JSON secara manual baik-baik saja saat Anda menjelajah. Untuk pengujian yang berjalan tanpa pengawasan, Anda memerlukan pernyataan yang lulus atau gagal dengan sendirinya. Apidog memungkinkan Anda menambahkan pernyataan ke permintaan sehingga eksekusi dinilai secara otomatis, seperti yang Anda siapkan di penegasan API.
Untuk GraphQL, tiga pemeriksaan mencakup sebagian besar kasus:
- Tegaskan status HTTP adalah
200. Diperlukan tetapi tidak cukup, karena GraphQL mengembalikan 200 bahkan pada kesalahan bisnis. - Tegaskan bahwa bidang
errorstidak ada. Ini adalah gerbang lulus atau gagal GraphQL yang sebenarnya. Jikaerrorsada, operasi gagal tidak peduli apa yang dikatakan status. - Tegaskan pada nilai-nilai spesifik di dalam
data, menggunakan JSONPath seperti$.data.createOrder.statussama denganPENDING, atau$.data.user.ordersmemiliki panjang lebih besar dari nol.
Kombinasi itu menangkap mode kegagalan yang tidak terdeteksi oleh pemeriksaan status-saja: kueri yang mengembalikan 200 dengan array errors, atau yang berhasil tetapi mengembalikan bentuk yang salah. Arahkan pernyataan nilai Anda ke jalur bersarang di bawah data, cocok dengan struktur respons yang Anda lihat sebelumnya.
Simpan ke dalam skenario pengujian
Satu permintaan yang ditegaskan adalah tes asap yang baik. Keuntungan sebenarnya adalah merangkai permintaan menjadi skenario: kueri pengguna, buat pesanan, lalu kueri lagi untuk mengkonfirmasi bahwa itu disimpan. Skenario pengujian Apidog memungkinkan Anda mengurutkan langkah-langkah ini, meneruskan data di antara mereka (menangkap id dari mutasi, memasukkannya ke dalam kueri konfirmasi), dan menjalankan seluruh alur dengan satu klik. Penjelasan lengkapnya ada di cara menulis skenario pengujian dengan Apidog.
Pada tingkat tinggi: buat skenario pengujian baru, tambahkan kueri dan mutasi GraphQL Anda sebagai langkah-langkah secara berurutan, ekstrak id pesanan dari respons mutasi ke dalam variabel, dan referensikan variabel itu di langkah kueri terakhir. Lampirkan pernyataan dari bagian sebelumnya ke setiap langkah. Sekarang Anda memiliki tes regresi yang dapat diulang untuk API GraphQL Anda yang dapat dijalankan oleh manusia, jadwal, atau pipeline.
Untuk tim yang mempertimbangkan GraphQL dibandingkan gaya lain sebelum berkomitmen, perincian kami tentang REST vs GraphQL vs gRPC dan ringkasan alat pengujian dan mocking GraphQL keduanya membantu Anda menempatkan alur kerja ini dalam konteks. Dan jika stack Anda juga menggunakan SOAP, pola permintaan-dan-penegasan yang sama berlaku di cara menguji API SOAP di Apidog.
Otomatiskan alur kerja dengan Apidog CLI
Setelah skenario GraphQL Anda berada di proyek, Anda dapat menjalankan skenario pengujian yang tersimpan di proyek dari terminal atau CI runner dengan Apidog CLI. Instal dan masuk:
npm install -g apidog-cli
apidog login --with-token <your-token>
Kemudian jalankan skenario yang disimpan berdasarkan id, diarahkan ke lingkungan:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Di sini -t adalah id skenario pengujian, -e adalah id lingkungan, dan -r adalah reporter (cli, html, atau junit; pisahkan dengan koma, seperti -r html,cli, untuk lebih dari satu). CLI menjalankan skenario yang disimpan dan suite pengujian dari proyek cloud Anda dan melaporkan lulus atau gagal, yang merupakan cara Apidog terhubung ke build. Satu peringatan jujur: dokumentasi CLI mengkonfirmasi eksekusi skenario HTTP, dan tidak menyatakan apakah skenario yang berisi langkah-langkah GraphQL berjalan tanpa kepala. Perlakukan CLI sebagai mesin Anda untuk menjalankan regresi HTTP dan untuk menjaga spesifikasi tetap sinkron melalui perintah import-nya (OpenAPI, HAR, Postman, dan lainnya), dan lakukan pekerjaan kueri, mutasi, dan penegasan GraphQL Anda di aplikasi. Lihat panduan instalasi Apidog CLI untuk penyiapan token dan Apidog CLI dalam pipeline GitHub Actions untuk menghubungkannya ke CI.
FAQ
Apakah saya memerlukan paket berbayar untuk menguji GraphQL di Apidog? Dokumen permintaan GraphQL tidak membatasi fitur ini di balik tingkat paket, dan mereka juga tidak menarik garis antara cloud-versus-self-hosted. Anda dapat memulai dengan tingkat gratis: coba gratis, tidak perlu kartu kredit, dan lihat Apidog untuk detail paket saat ini.
Mengapa permintaan GraphQL saya mengembalikan 200 tetapi masih gagal? Itu adalah perilaku GraphQL yang normal. Transportasi berhasil, jadi status HTTP adalah 200, tetapi operasi menemui kesalahan bisnis atau validasi yang masuk ke array errors dari badan JSON. Selalu tegaskan bahwa errors tidak ada selain memeriksa status, seperti yang dibahas dalam penegasan API.
Bagaimana saya mendapatkan saran bidang saat menulis kueri? Klik tombol Fetch Schema di kotak input. Apidog mengintrospeksi endpoint Anda dan mengaktifkan pelengkapan kode sehingga editor menyarankan bidang dan tipe yang valid. Ini adalah langkah manual, bukan otomatis, jadi klik setelah URL endpoint Anda diatur, dan ambil ulang setelah perubahan skema apa pun.
Di mana mutasi pergi? Saya tidak melihat tab mutasi terpisah. Tidak ada. Mutasi ditulis sebagai GraphQL di kotak Query yang sama, menggunakan kata kunci mutation alih-alih query. Teruskan payload-nya melalui variabel, lalu klik Send, sama seperti kueri.
Bagaimana cara meneruskan nilai yang berbeda tanpa menulis ulang kueri? Gunakan variabel GraphQL. Deklarasikan di tanda tangan operasi dengan prefiks $ dan berikan objek JSON nilai. Sintaks mengikuti spesifikasi GraphQL standar, dan dukungan variabel Apidog berpasangan dengan variabel lingkungan sehingga satu permintaan berjalan di seluruh staging dan produksi.
Kesimpulan
Menguji GraphQL bermuara pada beberapa kebiasaan jujur: tulis kueri di kotak Query, ambil skema sehingga editor membantu Anda, pindahkan nilai tetap ke variabel, dan tegaskan pada badan daripada mempercayai kode status. Jalankan mutasi dengan cara yang sama Anda menjalankan kueri, lalu rangkai keduanya ke dalam skenario yang disimpan sehingga pemeriksaan berulang dengan sendirinya. Unduh Apidog untuk mengikuti, bangun alur pengguna-dan-pesanan di atas, dan Anda akan memiliki tes regresi GraphQL yang dapat Anda jalankan kembali kapan pun skema Anda berubah.