Insomnia adalah klien API yang dibangun oleh Kong untuk mengirim permintaan dan memeriksa respons. Aplikasi ini dikenal karena antarmukanya yang bersih, bebas gangguan, dan dukungan untuk HTTP, REST, GraphQL, gRPC, SOAP, dan WebSocket di satu tempat. Para pengembang menggunakannya ketika mereka menginginkan sesuatu yang lebih ringan daripada alat bergaya IDE yang berat tetapi tetap mampu melakukan pekerjaan pengujian yang sesungguhnya.
Panduan ini menunjukkan cara menguji API di Insomnia dari awal hingga akhir. Anda akan membuat koleksi permintaan, mengirim dan memeriksa respons, menyiapkan lingkungan sehingga Anda dapat mengganti URL dasar dan token, serta menggunakan fitur rangkaian uji (test suites) untuk menulis pernyataan (assertions) yang berjalan secara otomatis. Contoh-contohnya menggunakan API publik sehingga Anda dapat langsung mengikutinya.
Instal Insomnia dan buat permintaan
Unduh Insomnia dari situs resmi Kong dan instal untuk platform Anda. Saat pertama kali diluncurkan, Insomnia akan menanyakan apakah Anda ingin masuk. Anda dapat memilih untuk bekerja secara lokal tanpa akun jika Anda mau, dan Insomnia menyimpan data Anda di mesin Anda sendiri. Sinkronisasi cloud bersifat opsional dan merupakan hal yang berubah pada versi 8, yang akan kami bahas di bawah.
Insomnia mengatur pekerjaan ke dalam koleksi dan dokumen. Klik Buat di dasbor dan pilih Koleksi Permintaan. Beri nama yang jelas seperti “Pengujian API Pengguna.” Di dalam koleksi, klik tombol + dan pilih Permintaan HTTP.
Sebuah permintaan membutuhkan metode dan URL. Pilih GET dan masukkan endpoint yang nyata. Layanan JSONPlaceholder berfungsi dengan baik untuk latihan:
GET https://jsonplaceholder.typicode.com/users/1
Klik Kirim. Panel kanan menunjukkan badan respons, kode status, waktu respons, dan ukuran. Insomnia secara otomatis mencetak JSON dengan rapi dan memungkinkan Anda menyaring badan respons dengan kueri JSONPath atau XPath, yang berguna saat respons berukuran besar.
Konfigurasi metode, parameter, dan autentikasi
Untuk apa pun di luar pembacaan sederhana, Anda akan mengatur lebih banyak pada permintaan. Insomnia mengelompokkannya di bawah tab di bawah bilah URL.
Tab Body menangani payload permintaan. Untuk POST, pilih JSON dan masukkan data:
{
"name": "Daniel Okafor",
"email": "daniel.okafor@example.com"
}
Insomnia mengatur header Content-Type untuk Anda saat Anda memilih jenis badan (body). Tab Kueri memungkinkan Anda menambahkan parameter string kueri tanpa mengedit URL secara manual, yang menjaga URL panjang tetap mudah dibaca dan memungkinkan Anda mengaktifkan serta menonaktifkan parameter individual. Tab Headers adalah untuk hal lain yang diharapkan API, seperti X-Request-Id khusus atau header Accept untuk menegosiasikan format respons.
Tab Auth menangani kredensial. Insomnia mendukung daftar skema yang panjang: Bearer Token, Basic Auth, API Key, OAuth 1.0 dan 2.0, AWS IAM, dan lainnya. Pilih skema yang digunakan API Anda dan isi bidang-bidangnya. Untuk API yang dilindungi token, pilih Bearer Token dan tempelkan tokennya, atau lebih baik, rujuk variabel lingkungan agar token tidak di-hardcode. Jika Anda tidak yakin kode status apa yang harus diharapkan kembali, referensi tentang kode status HTTP yang harus digunakan oleh API REST adalah pendamping yang baik.
Siapkan lingkungan dan variabel
Lingkungan memungkinkan Anda menghindari pengulangan nilai dan mempermudah pengalihan target. Di Insomnia, lingkungan adalah objek JSON berisi variabel yang melekat pada suatu koleksi.
Klik dropdown lingkungan di dekat bagian atas bilah sisi dan buka Kelola Lingkungan. Lingkungan Dasar menyimpan nilai-nilai bersama. Tambahkan sub-lingkungan untuk setiap target:
{
"base_url": "https://jsonplaceholder.typicode.com",
"auth_token": "your-token-here"
}
Buat sub-lingkungan kedua untuk produksi dengan nilai yang berbeda. Referensikan variabel dalam permintaan apa pun dengan sintaks templat {{ _.base_url }}, sehingga URL menjadi:
GET {{ _.base_url }}/users/1
Ganti lingkungan aktif dari dropdown dan setiap permintaan yang menggunakan variabel akan diperbarui. Insomnia juga mendukung tag templat, fungsi kecil yang dapat Anda masukkan ke dalam bidang untuk menghasilkan stempel waktu, UUID, atau untuk mengambil nilai dari respons sebelumnya. Yang terakhir ini memungkinkan Anda merangkai permintaan, misalnya menangkap token dari respons login dan memasukkannya ke permintaan selanjutnya.
Tag templat respons patut diperhatikan lebih dekat karena inilah cara Insomnia menangani dependensi permintaan tanpa scripting. Anda menambahkan tag yang mengatakan “gunakan badan permintaan login, di JSONPath $.token,” dan masukkan ke header Authorization dari setiap permintaan yang dilindungi. Ketika Anda menjalankan permintaan yang dilindungi, Insomnia menjalankan permintaan login terlebih dahulu jika diperlukan, mengekstrak token, dan menggantinya. Rantai ini tetap deklaratif, sehingga tidak ada kode penghubung (glue code) yang perlu dipertahankan. Untuk gagasan yang lebih luas tentang pengelompokan pemeriksaan terkait, lihat panduan contoh kasus uji API.
Tulis rangkaian uji dengan pernyataan
Mengirim permintaan akan menunjukkan respons. Untuk memeriksa apakah respons sudah benar secara otomatis, Anda menggunakan fitur rangkaian uji (test suites) Insomnia, terkadang ditampilkan sebagai tab Unit Tests pada sebuah koleksi.
Buka koleksi Anda dan beralih ke tampilan Tes. Buat rangkaian uji, lalu tambahkan tes individual di dalamnya. Setiap tes adalah sepotong kecil JavaScript. Insomnia menggunakan pustaka pernyataan Chai dan memberi Anda pembantu untuk mengirim permintaan dan mengambil responsnya. Sebuah tes terlihat seperti ini:
const response = await insomnia.send();
expect(response.status).to.equal(200);
Anda bisa lebih spesifik dengan mengurai badan (body) dan memeriksa bidang-bidangnya:
const response = await insomnia.send();
const body = JSON.parse(response.data);
expect(response.status).to.equal(200);
expect(body.email).to.equal("daniel.okafor@example.com");
expect(body).to.have.property("id");
Setiap tes dalam rangkaian menargetkan permintaan dari koleksi Anda, yang dipilih dari dropdown, sehingga tes mengetahui apa yang harus dikirim. Klik Jalankan Tes dan Insomnia akan mengeksekusi setiap tes dalam rangkaian, menunjukkan setiap tes sebagai lulus atau gagal beserta waktu yang dibutuhkan. Ini adalah pemeriksaan regresi Anda: jalankan rangkaian setelah perubahan dan Anda akan segera melihat apakah API masih berfungsi dengan baik.
Cara Anda mengatur rangkaian uji sangat penting seiring bertambahnya jumlahnya. Pola umum adalah satu rangkaian per sumber daya, sehingga semua tes artikel berada bersamaan dan semua tes pengguna juga berada bersamaan. Di dalam sebuah rangkaian, fokuskan setiap tes pada satu perilaku tunggal: satu tes untuk "happy path", tes terpisah untuk kasus "not-found" dan kasus kesalahan validasi. Ketika sebuah tes gagal, namanya dan cakupannya yang sempit seharusnya memberi tahu Anda apa yang rusak tanpa Anda harus membaca kode pernyataan. Untuk melihat lebih dalam tentang menulis pemeriksaan yang baik, panduan tentang pernyataan API menjelaskan apa yang harus ditegaskan dan apa yang harus dilewati, dan artikel rangkaian uji untuk otomatisasi pengujian API membahas struktur rangkaian seiring pertumbuhannya.
Jalankan dari baris perintah dengan Inso
GUI bagus untuk pengembangan, tetapi otomatisasi membutuhkan sesuatu yang tanpa kepala (headless). Insomnia menyertakan pendamping baris perintah yang disebut Inso. Setelah mengekspor atau menyinkronkan koleksi Anda, Anda menjalankan rangkaian uji Anda dari terminal:
inso run test "User API tests"
Inso keluar dengan kode status bukan nol jika ada tes yang gagal, yang persis seperti yang dibutuhkan pipeline CI untuk menandai sebuah build sebagai rusak. Anda dapat menyambungkan ini ke GitHub Actions atau runner lainnya sehingga tes Insomnia Anda dieksekusi pada setiap push, menangkap endpoint yang rusak sebelum mencapai rekan tim atau produksi. Inso juga dapat melint spesifikasi API Anda dan menghasilkan laporan tes dalam format standar, yang membuatnya berguna lebih dari sekadar menjalankan rangkaian. Artikel tentang mengotomatiskan tes API di CI/CD menunjukkan pola umum, yang berlaku dengan bersih untuk Inso.
Perubahan cloud versi 8, dan alternatifnya
Insomnia 8 bergerak menuju model cloud-first. Secara default, ia mendorong pengguna untuk membuat akun Kong dan menyimpan proyek di cloud. Keputusan itu membuat frustrasi sebagian komunitas, karena versi sebelumnya sepenuhnya lokal dan ramah offline. Rilis selanjutnya mengembalikan opsi lokal-saja atau “Scratch Pad” yang lebih jelas, tetapi episode tersebut membuat beberapa tim mencari alternatif, terutama di lingkungan di mana data tidak dapat keluar dari gedung.
Jika itu menggambarkan Anda, Apidog patut dicoba. Ini adalah platform API all-in-one yang mencakup desain, debugging, mocking, pengujian, dan dokumentasi, dan ia mengimpor ekspor Insomnia sehingga Anda tidak perlu memulai dari awal. Apidog memungkinkan Anda membangun pernyataan secara visual tanpa menulis JavaScript, sambil tetap mendukung skrip jika Anda menginginkannya. Karena spesifikasi API, data uji, dan server mock berbagi satu proyek, tes Anda tetap selaras dengan kontrak yang sebenarnya alih-alih menyimpang. Anda dapat mengunduh Apidog dan mengimpor koleksi Insomnia untuk membandingkan secara berdampingan. Untuk survei yang lebih luas, daftar alat pengujian API online gratis mencakup beberapa opsi.
Insomnia masih merupakan klien yang kuat dan terfokus, terutama untuk pengembang tunggal dan tim kecil yang menghargai antarmukanya yang minimalis, bebas gangguan, dan startup yang cepat. Pilihan yang tepat bergantung pada cara kerja tim Anda dan seberapa banyak siklus hidup API yang ingin Anda tangani di satu tempat daripada menyebar ke berbagai alat terpisah.
Pertanyaan yang sering diajukan
Apakah Insomnia gratis untuk digunakan?
Insomnia memiliki tingkatan gratis yang mencakup penggunaan individu, termasuk mengirim permintaan dan menjalankan rangkaian uji secara lokal. Paket berbayar menambahkan kolaborasi tim dan batas sinkronisasi cloud yang lebih besar. Anda dapat menggunakan klien inti tanpa membayar, dan versi terbaru memungkinkan Anda bekerja sepenuhnya secara lokal jika Anda memilih untuk tidak menggunakan sinkronisasi cloud.
Protokol apa saja yang didukung Insomnia?
Insomnia menangani HTTP, REST, GraphQL, gRPC, SOAP, dan WebSocket. Penyiapan permintaan berbeda per protokol, tetapi pemeriksaan respons dan, untuk permintaan berbasis HTTP, pernyataan rangkaian uji berfungsi secara konsisten di antara semuanya.
Bagaimana cara menulis pernyataan di Insomnia?
Gunakan fitur rangkaian uji. Buka tampilan Tes pada sebuah koleksi, buat rangkaian, dan tambahkan tes. Setiap tes adalah JavaScript yang memanggil insomnia.send() untuk menjalankan permintaan, lalu menggunakan pernyataan expect bergaya Chai pada status, header, atau badan yang diurai. Jalankan seluruh rangkaian dengan tombol Jalankan Tes.
Apa yang berubah di Insomnia 8?
Insomnia 8 beralih ke default cloud-first, mendorong pengguna untuk masuk ke akun Kong dan menyinkronkan proyek ke cloud. Beberapa pengguna tidak menyukai alur akun yang wajib dan pergeseran dari aplikasi yang murni lokal. Pembaruan selanjutnya menambahkan opsi lokal-saja yang lebih jelas, tetapi perubahan tersebut mendorong beberapa tim untuk mengevaluasi alternatif.
Bisakah saya menjalankan tes Insomnia di pipeline CI?
Ya. Gunakan Inso, pendamping baris perintah. Ekspor atau sinkronkan koleksi Anda, lalu jalankan inso run test "<nama rangkaian>" di pipeline Anda. Inso mengembalikan kode keluar bukan nol saat kegagalan, sehingga CI dapat secara otomatis menggagalkan build ketika tes API rusak.