Asersi API: Panduan Praktis Memvalidasi Respons

Permintaan API yang mengembalikan respons bukanlah pengujian yang berhasil. Itu hanya sebuah respons. Pengujian hanya ada ketika sesuatu memeriksa bahwa respons tersebut benar. Pemeriksaan itu adalah pernyataan (assertion), dan kualitas pernyataan Anda menentukan apakah rangkaian pengujian Anda menangkap *bug* nyata atau hanya mengonfirmasi bahwa *server* hidup.

Panduan ini menjelaskan apa itu pernyataan API, jenis-jenis yang layak ditulis, di mana tim sering keliru, dan bagaimana membangun pernyataan secara visual di Apidog tanpa skrip.

Apa itu pernyataan API

Pernyataan adalah sebuah statemen mengenai respons yang harus benar agar pengujian berhasil. Anda mengirim permintaan, API membalas, dan pernyataan membandingkan sebagian dari balasan itu dengan nilai yang diharapkan. Jika cocok, berhasil. Jika tidak, gagal.

Tanpa pernyataan, pengujian otomatis hanya membuktikan bahwa *endpoint* dapat dijangkau. Dengan pernyataan, ia membuktikan bahwa *endpoint* tersebut *benar*. Kesenjangan antara keduanya adalah tempat sebagian besar insiden produksi terjadi: API aktif, mengembalikan 200, tetapi *body* salah.

Pernyataan yang berguna bersifat spesifik dan independen. Spesifik, sehingga kegagalan menunjuk pada satu hal. Independen, sehingga tidak secara diam-diam bergantung pada pernyataan lain yang berhasil terlebih dahulu. Satu langkah pengujian biasanya memuat beberapa pernyataan, masing-masing memeriksa aspek berbeda dari respons yang sama.

Pernyataan kode status, dan mengapa itu tidak cukup

Pernyataan paling umum memeriksa kode status HTTP: harapkan 200 untuk pembacaan yang berhasil, 201 untuk sumber daya yang dibuat, 400 untuk masukan yang buruk, 401 untuk otentikasi yang hilang. Ini diperlukan. Memahami kode status dengan benar adalah disiplin tersendiri; kode status HTTP apa yang harus digunakan API REST layak dibaca jika API Anda tidak konsisten di sini.

Namun, pernyataan kode status saja lemah. Sebuah API dapat mengembalikan 200 OK dengan *body* kosong, nilai kadaluwarsa, nilai *null* di mana seharusnya ada objek, atau pesan kesalahan yang disamarkan sebagai keberhasilan. Status menunjukkan bahwa permintaan telah ditangani. Ini tidak mengatakan apa pun tentang apakah datanya benar.

Perlakukan pernyataan status sebagai baris pertama dari langkah pengujian, jangan pernah sebagai satu-satunya baris.

Jenis-jenis pernyataan yang layak ditulis

Pernyataan konten *body*. Periksa nilai aktual dalam respons. Bidang id ada dan tidak kosong. email cocok dengan yang Anda kirim. total sama dengan jumlah item baris. Ini menangkap *bug* logika yang terlewatkan oleh kode status.

Pernyataan skema. Validasi *bentuk* respons terhadap Skema JSON atau definisi OpenAPI: bidang yang diperlukan ada, jenisnya benar, tidak ada bidang tak terduga yang muncul. Pernyataan skema menangkap *contract drift*, di mana *backend* diam-diam mengubah bidang dari *string* menjadi objek dan merusak setiap klien. Ini tumpang tindih dengan pengujian kontrak API, yang memformalkan gagasan tersebut di antara produsen dan konsumen.

Pernyataan *header*. Konfirmasi Content-Type adalah application/json, bahwa *header* *caching* diatur sesuai tujuan, bahwa *header* CORS ada, dan bahwa *header* keamanan seperti Strict-Transport-Security juga ada.

Pernyataan waktu respons. Tetapkan anggaran latensi, misalnya 800 ms, dan gagal pengujian ketika respons lebih lambat. Regresi kinerja tidak terlihat oleh jenis pernyataan lain, jadi ini adalah satu-satunya yang menangkapnya dalam rangkaian fungsional.

Pernyataan bentuk kesalahan. Untuk kasus negatif, nyatakan *body* kesalahan, bukan hanya kode 4xx. Bidang error sama dengan validation_error, *array* details menyebutkan bidang yang bermasalah, dan tidak ada data sensitif yang bocor dalam pesan.

Pernyataan keamanan. Konfirmasi *endpoint* menolak permintaan tanpa token, menolak token yang kadaluwarsa, menegakkan otorisasi antar pengguna, dan tidak mengembalikan *payload* injeksi tanpa *escape*.

Langkah pengujian yang menegaskan status, dua atau tiga bidang *body*, skema, dan anggaran waktu respons sedang melakukan pekerjaan nyata. Langkah yang hanya menegaskan status bersifat dekoratif.

Di mana logika pernyataan keliru

Terlalu banyak pernyataan pada data yang *volatile*. Menegaskan *timestamp* created_at yang tepat atau UUID yang dihasilkan membuat pengujian gagal setiap kali dijalankan tanpa alasan. Nyatakan bahwa bidang tersebut ada dan memiliki jenis yang benar, bukan nilai pastinya.

Kurangnya pernyataan pada *happy path*. Pengujian *happy path* adalah yang paling mungkin hanya menegaskan kode status. Ini juga yang paling sering diakses pengguna. Berikan pernyataan paling menyeluruh padanya, bukan yang paling sedikit.

Pernyataan yang bergantung pada urutan. Jika pernyataan B hanya masuk akal ketika pernyataan A berhasil, tetapi keduanya berjalan secara buta, kegagalan di A menghasilkan kegagalan kedua yang membingungkan di B. Susun langkah-langkah sehingga ketergantungan bersifat eksplisit.

Satu pernyataan melakukan dua pekerjaan. “Respons benar” bukanlah sebuah pernyataan. Pisahkan: status adalah 200, token ada, expires_in sama dengan 3600. Tiga pemeriksaan, tiga pesan kegagalan yang jelas.

Mengabaikan kasus negatif. Tim banyak menegaskan pada keberhasilan dan hampir tidak sama sekali pada kegagalan. Kasus negatif tanpa pernyataan *body* hanya membuktikan bahwa API mengatakan “tidak,” bukan bahwa ia mengatakan tidak *dengan benar*.

Membangun pernyataan di Apidog

Di Apidog, pernyataan adalah bagian dari pembangun pengujian visual, jadi Anda menentukannya dengan mengklik daripada membuat skrip.

Untuk permintaan apa pun dalam skenario pengujian, buka panel pernyataan dan tambahkan pemeriksaan:

1. Pernyataan status. Pilih “status respons” dan atur agar sama dengan 200.
2. Pernyataan bidang *body*. Gunakan ekspresi JSONPath seperti $.token dan nyatakan bahwa ia ada dan merupakan *string* yang tidak kosong; nyatakan $.expires_in sama dengan 3600. Apidog membaca struktur respons, jadi Anda memilih bidang daripada mengetik *path* secara buta.
3. Pernyataan skema. Validasi respons terhadap skema yang ditentukan oleh *endpoint*. Karena Apidog menjaga desain API dan pengujian dalam satu *workspace*, skema yang digunakan pernyataan Anda adalah skema yang sama dengan yang diterbitkan dokumentasi Anda; tidak ada salinan kedua yang menyimpang.
4. Pernyataan waktu respons. Tambahkan pemeriksaan bahwa waktu respons di bawah anggaran Anda.
5. Skrip kustom, hanya jika diperlukan. Untuk logika yang tidak dapat diekspresikan oleh pemeriksaan visual, masukkan ke dalam *post-processor* JavaScript. Sebagian besar pernyataan tidak pernah membutuhkannya.

Kelompokkan pernyataan di seluruh skenario dan Apidog menjalankannya secara bersamaan. Untuk cakupan yang dapat diskalakan, lampirkan file data agar satu set pernyataan berjalan terhadap setiap baris masukan pengujian berbasis data. Saat skenario berjalan, laporan yang dihasilkan menunjukkan dengan tepat pernyataan mana yang gagal, pada permintaan mana, dengan nilai yang diharapkan dan aktual ditampilkan secara berdampingan.

Skenario yang sama berjalan tidak berubah di CI, sehingga setiap *commit* memeriksa ulang setiap pernyataan; mengotomatiskan pengujian API di CI/CD membahas *wiring* tersebut. Unduh Apidog untuk membangun satu set pernyataan terhadap *endpoint* Anda sendiri.

Satu set pernyataan yang telah diterapkan

Ambil GET /users/{id} yang mengembalikan objek pengguna. Satu set pernyataan yang kuat untuk *happy path*:

• Status sama dengan 200
• *Header* Content-Type berisi application/json
• $.id sama dengan *id* yang diminta
• $.email ada dan cocok dengan pola *email*
• $.role adalah salah satu dari admin, member, viewer
• *Body* respons sesuai dengan skema User
• Waktu respons di bawah 600 ms

Dan untuk GET /users/{id} dengan *id* yang tidak dikenal:

• Status sama dengan 404
• $.error sama dengan not_found
• *Body* respons tidak berisi email, id, atau bidang pengguna lainnya

Dua permintaan, sebelas pernyataan, dan Anda telah memverifikasi kontrak, data, *header*, kinerja, dan perilaku kesalahan. Itulah yang memisahkan rangkaian pengujian yang melindungi rilis dari rangkaian pengujian yang hanya melakukan *ping* ke server.

Pernyataan dalam *pipeline* CI

Pernyataan mendapatkan nilai penuhnya ketika dijalankan secara otomatis. Rangkaian yang dijalankan seseorang secara manual seminggu sekali akan menangkap *bug* seminggu terlambat. Rangkaian yang sama yang terhubung ke CI akan menangkapnya pada *pull request*.

Ketika pernyataan berjalan dalam *pipeline*, dua pilihan desain menjadi penting. Pertama, kegagalan harus tidak ambigu. Log CI yang mengatakan “pengujian gagal” memaksa pengembang untuk mereproduksi jalannya secara lokal; log yang mengatakan “diharapkan $.expires_in sama dengan 3600, tetapi mendapatkan 7200 pada POST /auth/login” langsung memberitahu mereka di mana harus mencari. Pernyataan yang kuat dan spesifik inilah yang menghasilkan kegagalan yang mudah dibaca.

Kedua, pernyataan perlu stabil di seluruh lingkungan. Pernyataan yang meng-*hard-code* ID pengguna produksi akan gagal di *staging* karena alasan yang tidak ada hubungannya dengan kode. Simpan nilai-nilai spesifik lingkungan dalam variabel, dan nyatakan struktur dan jenis di mana nilai pastinya bergantung pada lingkungan. Pernyataan skema berfungsi baik antar lingkungan; pernyataan pada ID yang dihasilkan secara spesifik tidak.

Pola praktis: nyatakan status dan skema pada setiap *endpoint* sebagai *baseline* yang berjalan di mana-mana, kemudian lapisi dengan pernyataan nilai yang peka lingkungan. *Baseline* menangkap *contract drift* di lingkungan mana pun; pernyataan nilai menangkap *bug* logika di mana Anda memiliki data stabil. Jalankan keduanya pada setiap *commit* dan rangkaian pengujian menjadi gerbang daripada laporan.

Pertanyaan yang sering diajukan

Apa perbedaan antara pernyataan dan kasus pengujian? Kasus pengujian adalah pemeriksaan keseluruhan: permintaan ditambah hasil yang diharapkan. Pernyataan adalah perbandingan individual di dalamnya yang memutuskan berhasil atau gagal. Lihat cara menulis kasus pengujian API.

Berapa banyak pernyataan yang seharusnya dimiliki satu permintaan? Cukup untuk mencakup status, bidang *body* utama, skema, dan anggaran latensi. Untuk sebagian besar *endpoint*, itu adalah empat hingga delapan. Lebih banyak tidak masalah jika masing-masing memeriksa sesuatu yang berbeda.

Haruskah saya menegaskan *body* respons yang persis? Nyatakan bidang stabil secara persis dan bidang *volatile* berdasarkan jenis atau keberadaannya. Menegaskan *body* lengkap termasuk *timestamp* dan ID yang dihasilkan menciptakan pengujian yang gagal setiap kali dijalankan.

Bisakah saya menegaskan kinerja API dalam pengujian fungsional? Ya. Pernyataan waktu respons menangkap regresi latensi selama pengujian fungsional normal, tidak diperlukan pengujian beban terpisah untuk pemeriksaan anggaran dasar.

Haruskah kasus pengujian negatif juga memiliki pernyataan? Tentu saja, dan ini adalah kasus yang paling sering dibiarkan kosong. Kasus negatif dengan hanya pemeriksaan kode status membuktikan bahwa API mengatakan tidak, bukan bahwa ia mengatakan tidak dengan benar. Nyatakan bidang kesalahan, detail bidang yang bermasalah, dan tidak adanya data sensitif dalam pesan.

Di mana skrip pernyataan kustom harus digunakan? Cadangkan skrip untuk logika yang tidak dapat diekspresikan oleh pembangun visual: perbandingan antar-permintaan, nilai turunan, atau pemeriksaan kondisional yang bergantung pada respons sebelumnya. Sebagian besar pernyataan, status, skema, bidang *body*, dan waktu, lebih bersih dan lebih mudah ditinjau sebagai pemeriksaan visual.