Cara Menulis Test Case API: Template dan Contoh

API yang mudah rusak jarang gagal karena seseorang lupa mengujinya. Ini gagal karena pengujian yang dijalankan memeriksa hal yang salah, atau tidak memeriksa apa pun selain kode status 200. Kasus uji API yang ditulis dengan baik adalah perbedaan antara menangkap kontrak yang rusak sebelum rilis dan menjelaskan pemadaman sesudahnya.

Panduan ini akan menjelaskan apa itu kasus uji API, bidang-bidang yang dibutuhkan oleh kasus uji yang baik, dan cara menulisnya dari awal. Anda akan melihat contoh lengkap yang telah dikerjakan untuk titik akhir login, lalu membangun pengujian yang sama di Apidog tanpa menulis skrip.

Apa sebenarnya kasus uji API itu

Kasus uji API adalah seperangkat input, tindakan, dan hasil yang diharapkan yang ditentukan untuk mengonfirmasi bahwa satu titik akhir berfungsi dengan benar dalam satu kondisi spesifik. Ini lebih sempit daripada skenario uji. Skenario mengatakan "verifikasi login pengguna." Kasus uji mengatakan "POST kredensial yang valid ke /auth/login dan konfirmasi respons 200 dengan JWT di body dalam 800 ms."

Setiap kasus menargetkan satu perilaku. Fokus itu penting. Ketika pengujian yang luas dan serbaguna gagal, Anda masih harus menyelidiki bagian mana yang rusak. Ketika kasus yang terfokus gagal, nama kegagalan memberi tahu Anda jawabannya. Jika Anda masih memetakan bagaimana kasus berhubungan dengan skenario dan skrip, skenario uji vs kasus uji dan kasus uji vs skrip uji menjelaskan batas-batasnya dengan jelas.

Pengujian API biasanya mencakup lima sudut pandang, dan kasus Anda harus tersebar di semuanya:

• Fungsional: apakah titik akhir mengembalikan data yang benar untuk input yang valid?
• Negatif: apakah itu menolak input yang buruk dengan kesalahan dan kode status yang benar?
• Kinerja: apakah itu merespons dalam batas waktu yang dapat diterima?
• Keamanan: apakah itu menerapkan otentikasi, otorisasi, dan batas input?
• Kontrak: apakah respons cocok dengan skema yang didokumentasikan?

Rangkaian pengujian yang hanya memeriksa jalur yang berhasil akan lolos sampai pengguna nyata mengirimkan bidang kata sandi kosong.

Mengapa Anda membutuhkan templat kasus uji

Menulis setiap kasus dari halaman kosong menghasilkan cakupan yang tidak konsisten. Satu insinyur mencatat kode status yang diharapkan; yang lain mencatat body respons; yang ketiga menulis "seharusnya berfungsi." Templat memperbaikinya dengan memaksakan struktur yang sama setiap saat.

Templat bersama memberi Anda empat keuntungan nyata. Cakupan menjadi dapat diaudit, karena setiap kasus memiliki bidang yang sama dan celah terlihat. Orientasi menjadi lebih cepat, karena penguji baru membaca satu format daripada lima. Kasus menjadi dapat digunakan kembali di seluruh rilis, karena kasus terstruktur mudah dikloning dan disesuaikan. Dan ketertelusuran tetap terjaga, karena setiap kasus terhubung kembali ke persyaratan atau titik akhir.

Templat juga membuat otomatisasi menjadi realistis. Kasus terstruktur memetakan dengan bersih ke langkah pengujian otomatis; kasus yang samar harus ditulis ulang sebelum mesin dapat menjalankannya.

Anatomi kasus uji API yang kuat

Templat kasus uji API yang lengkap mencakup bidang-bidang ini. Anda tidak memerlukan semuanya untuk setiap kasus, tetapi set inti tidak dapat dinegosiasikan.

Bidang yang paling sering dilewati tim adalah waktu respons yang diharapkan dan body respons yang diharapkan. Melewatkannya adalah cara pengujian "berhasil" sambil mengembalikan 200 dengan payload kosong, atau payload yang benar tiga detik terlalu lambat.

Cara menulis kasus uji API langkah demi langkah

Baca dokumentasi API terlebih dahulu. Catat parameter yang diperlukan, metode otentikasi, kode status yang didokumentasikan, dan skema respons. Setiap kasus uji adalah klaim tentang perilaku yang didokumentasikan, jadi dokumen adalah sumber kebenaran Anda. Alat yang membaca spesifikasi OpenAPI untuk menghasilkan koleksi pengujian dapat memberi Anda kerangka awal.

Daftar kondisi yang layak diuji. Untuk satu titik akhir, itu biasanya berarti: input yang valid, setiap bidang yang diperlukan hilang, setiap bidang yang salah format, permintaan yang tidak sah, token yang kedaluwarsa, dan payload yang terlalu besar. Setiap kondisi menjadi satu kasus.

Siapkan data uji yang berbeda. Kasus negatif membutuhkan data yang salah dalam satu cara yang tepat. Menggunakan kembali payload yang sama di seluruh kasus menyembunyikan bug, karena Anda hanya pernah menggunakan satu jalur.

Tulis hasil yang diharapkan dengan tepat. "Mengembalikan keberhasilan" bukanlah sebuah pernyataan. "Mengembalikan 200, body berisi string token non-kosong, expires_in sama dengan 3600" adalah. Presisi di sini adalah yang membuat kasus layak dijalankan.

Tambahkan kasus ke rangkaian yang dapat dijalankan. Kasus dalam spreadsheet mendokumentasikan maksud. Kasus dalam alat pengujian menghasilkan lulus atau gagal. Kelompokkan kasus terkait sehingga seluruh titik akhir berjalan dalam satu klik; rangkaian pengujian ada untuk tujuan ini.

Pertahankan kasus tetap terbaru. Ketika API berubah, kasus juga berubah bersamanya. Kasus usang yang menegaskan skema lama lebih buruk daripada tidak ada kasus, karena gagal untuk alasan yang salah dan melatih tim untuk mengabaikan build merah.

Contoh yang dikerjakan: menguji titik akhir login

Ambil titik akhir otentikasi standar: POST /auth/login, yang menerima email dan kata sandi dan mengembalikan JWT. Berikut adalah empat kasus yang mencakupnya dengan benar.

AUTH-LOGIN-001: kredensial valid (fungsional, kritis)

• Titik akhir: POST /auth/login
• Pra-kondisi: pengguna ada dengan email dana@example.com
• Body: {"email": "dana@example.com", "password": "Correct-Horse-9"}
• Status yang diharapkan: 200
• Respons yang diharapkan: body berisi token non-kosong (string), token_type sama dengan Bearer, expires_in sama dengan 3600
• Waktu respons yang diharapkan: di bawah 800 ms

AUTH-LOGIN-002: kata sandi salah (negatif, kritis)

• Body: {"email": "dana@example.com", "password": "wrong"}
• Status yang diharapkan: 401
• Respons yang diharapkan: error sama dengan invalid_credentials; tidak ada bidang token
• Catatan: pesan tidak boleh mengungkapkan apakah email ada

AUTH-LOGIN-003: bidang kata sandi hilang (negatif, tinggi)

• Body: {"email": "dana@example.com"}
• Status yang diharapkan: 400
• Respons yang diharapkan: error sama dengan validation_error; details menyebutkan bidang password

AUTH-LOGIN-004: email salah format (negatif, sedang)

• Body: {"email": "not-an-email", "password": "Correct-Horse-9"}
• Status yang diharapkan: 400
• Respons yang diharapkan: error sama dengan validation_error

Empat kasus, satu titik akhir, dan Anda sudah memeriksa kontrak, bentuk kesalahan, kode status, dan anggaran latensi. Tambahkan kasus keamanan untuk string injeksi SQL di bidang email dan Anda memiliki rangkaian yang layak dijalankan di setiap commit.

Menulis kasus uji yang sama di Apidog

Anda dapat menjalankan keempat kasus di atas tanpa menulis satu baris skrip pun. Di Apidog, kasus uji API dibuat secara visual.

1. Impor atau definisikan titik akhir. Ambil POST /auth/login dari file OpenAPI, koleksi Postman, atau definisikan langsung. Skema permintaan menjadi dasar untuk setiap penegasan.
2. Tambahkan data permintaan. Masukkan body untuk kasus AUTH-LOGIN-001. Untuk cakupan berbasis data, lampirkan file CSV atau JSON sehingga satu kasus berjalan melawan setiap baris kredensial; ini adalah bagaimana pengujian API berbasis data menggantikan empat kasus yang hampir identik dengan satu.
3. Atur penegasan secara visual. Klik untuk menegaskan bahwa status sama dengan 200, bahwa token ada dan merupakan string non-kosong, bahwa expires_in sama dengan 3600, dan bahwa waktu respons tetap di bawah 800 ms. Tidak diperlukan skrip.
4. Kelompokkan kasus ke dalam skenario uji. Tambahkan keempat kasus login ke satu skenario sehingga titik akhir sepenuhnya diuji dalam satu kali jalankan.
5. Jalankan dan baca laporannya. Apidog mengeksekusi skenario, menghasilkan laporan lulus/gagal per kasus, dan menampilkan penegasan yang tepat yang rusak. Anda dapat menjalankan skenario secara lokal, terjadwal, atau di dalam CI.

Intinya bukan bahwa skrip itu salah; tetapi kasus visual terstruktur lebih cepat ditulis, lebih mudah ditinjau, dan lebih sulit untuk salah secara halus. Ketika Anda memang membutuhkan kode, Apidog masih memungkinkan Anda untuk masuk ke skrip kustom. Untuk alur kerja yang sepenuhnya bebas skrip, pengujian API tanpa Postman mencakup pendekatan yang lebih luas.

Kesalahan umum yang harus dihindari

Menegaskan hanya kode status. 200 berarti permintaan telah ditangani, bukan bahwa responsnya benar. Selalu tegaskan bidang body.

Satu kasus raksasa per titik akhir. Ketika gagal, Anda tidak belajar apa-apa. Bagi berdasarkan kondisi.

Data uji yang digunakan kembali. Jika setiap kasus negatif mengirimkan payload yang sama, Anda hanya menguji satu mode kegagalan.

Tidak ada penegasan latensi. Regresi kinerja menyelinap tanpa disadari ketika tidak ada yang mengukur waktu respons.

Kasus yang tidak pernah diotomatiskan. Kasus yang didokumentasikan yang tidak dijalankan oleh pelari adalah komentar, bukan pengujian. Pindahkan kasus ke dalam rangkaian yang berjalan di setiap build; menghasilkan skrip uji dari spesifikasi OpenAPI adalah cara cepat untuk memulai rangkaian itu.

Unduh Apidog jika Anda ingin mengikuti contoh dan membangun sendiri empat kasus login.

Pertanyaan yang sering diajukan

Berapa banyak kasus uji yang dibutuhkan satu titik akhir? Cukup untuk mencakup jalur yang berhasil, setiap kegagalan bidang yang diperlukan, satu kegagalan otentikasi, dan satu probe keamanan. Untuk titik akhir sederhana itu empat hingga enam kasus; untuk yang kompleks bisa lebih banyak.

Haruskah saya menulis kasus sebelum API dibangun? Ya. Menulis kasus terhadap desain, mendahulukan desain, menangkap celah kontrak lebih awal. Pasangkan ini dengan pembuatan kasus uji yang dibantu AI untuk menyusun set pertama dengan cepat, lalu perbaiki secara manual.

Spreadsheet atau alat uji untuk menyimpan kasus? Spreadsheet mendokumentasikan maksud tetapi tidak dapat dijalankan. Simpan kasus dalam alat yang mengeksekusinya dan melaporkan hasilnya, sehingga suatu kasus selalu hijau atau merah.

Apa perbedaan antara kasus uji dan skenario uji? Skenario adalah tujuan tingkat tinggi ("verifikasi login"); kasus adalah satu pemeriksaan konkret yang dapat dijalankan di dalamnya. Lihat skenario uji vs kasus uji.