Apa itu inso? Insomnia CLI

Jika Anda pernah menggunakan klien API Insomnia, Anda memiliki tempat bergrafis untuk mengirim permintaan, merancang spesifikasi OpenAPI, dan menulis tes. Namun, alat bergrafis berhenti di batas mesin Anda. Saat Anda ingin tes yang sama dijalankan di dalam pipeline CI, atau Anda ingin melinting spesifikasi pada setiap permintaan tarik, Anda memerlukan sesuatu yang berjalan di terminal. Sesuatu itu adalah inso.

Panduan ini menjelaskan apa itu inso, cara menginstalnya, perintah persis yang akan Anda gunakan sehari-hari, bagaimana ia menemukan spesifikasi dan koleksi Anda, serta di mana batasannya muncul. Pada akhirnya, Anda akan mengetahui apakah CLI inso sesuai dengan alur kerja Anda, dan apa yang harus Anda gunakan jika tidak.

Apa itu inso?

inso adalah pendamping baris perintah untuk Insomnia, klien API sumber terbuka yang kini dikelola oleh Kong. Ini mengambil tiga hal yang dilakukan Insomnia di UI-nya dan menjadikannya dapat discript: menjalankan tes, mengeksekusi koleksi permintaan, dan melinting spesifikasi API. Itu menjadikannya jembatan antara Insomnia di desktop Anda dan pemeriksaan otomatis yang Anda inginkan di CI/CD.

Versi singkat dari “apa itu inso”: ini adalah cara Anda menjalankan pekerjaan Insomnia Anda tanpa membuka Insomnia. Anda mengarahkannya ke dokumen desain atau koleksi berdasarkan nama, dan itu dieksekusi terhadap data yang sama yang sudah diketahui aplikasi Anda.

Menginstal CLI inso

Anda memiliki beberapa jalur yang didokumentasikan. Pilih yang sesuai dengan cara Anda mengirimkan.

Homebrew adalah yang paling sederhana di macOS dan Linux:

brew install inso

Docker adalah pilihan paling bersih untuk pelari CI, di mana Anda tidak ingin mengelola toolchain lokal:

docker pull kong/inso:latest

Anda juga bisa mendapatkan unduhan langsung. Kong mempublikasikan arsip zip Windows, Linux, dan macOS di situs dokumentasi CLI inso, yang berguna saat Anda menginginkan versi yang ditentukan dalam artefak build.

Secara historis, inso juga didistribusikan di npm sebagai `insomnia-inso`. Jalur itu masih ada, tetapi jalur yang didokumentasikan dan direkomendasikan sekarang adalah Homebrew, Docker, dan unduhan langsung. Jika Anda menyiapkan sesuatu yang baru, utamakan itu.

Konfirmasi instalasi berhasil:

inso --version

Perintah inti inso

inso memiliki antarmuka yang kecil dan terfokus. Berikut adalah perintah yang akan benar-benar Anda gunakan, dengan contoh nyata.

inso run test

Jalankan suite tes unit yang Anda buat di Insomnia, terhadap lingkungan bernama:

inso run test "Payments API tests" --env "Staging"

Suite dan lingkungan keduanya direferensikan berdasarkan nama, persis seperti yang muncul di data Insomnia Anda. Perintah inso run test akan keluar dengan kode non-nol jika ada asersi yang gagal, inilah yang membuatnya dapat digunakan sebagai gerbang CI.

inso run collection

Jalankan setiap permintaan dalam koleksi secara berurutan, sekali lagi terhadap lingkungan bernama:

inso run collection "Checkout flow" --env "Staging"

Ini adalah ekuivalen terdekat dengan “mainkan seluruh folder” di UI. Ini berguna untuk smoke test di mana Anda ingin mengonfirmasi bahwa urutan endpoint semuanya merespons seperti yang diharapkan.

inso lint spec

Validasi dokumen desain OpenAPI:

inso lint spec "Orders API"

Di balik layar, inso lint spec menggunakan Spectral, linter OpenAPI dan JSON sumber terbuka dari Stoplight. Ini adalah kekuatan sejati yang patut disebut secara jelas: Anda mendapatkan linting spesifikasi berbasis aturan yang nyata dengan kumpulan aturan yang matang, bukan pemeriksaan sintaksis dangkal. Jika tim Anda peduli dengan penegakan panduan gaya pada spesifikasi, perintah ini adalah alasan banyak orang tetap menggunakan inso.

inso export spec

Ambil dokumen desain ke dalam file di disk:

inso export spec "Orders API" --output orders.yaml

Berguna saat Anda ingin memasukkan spesifikasi ke generator lain, melakukan commit snapshot, atau menyerahkannya ke alat yang mengharapkan file YAML biasa.

inso script

Jalankan skrip bernama yang didefinisikan dalam data Insomnia Anda, meneruskan lingkungan berdasarkan ID:

inso script deploy-smoke --env env_9f2a

Ini adalah cara darurat untuk merangkai langkah-langkah kustom Anda sendiri.

Bagaimana inso menemukan spesifikasi dan koleksi Anda

Bagian ini sering membuat orang bingung, jadi penting untuk menjadi tepat. inso tidak menyimpan apa pun sendiri. Ia membaca dari salah satu dari dua tempat:

1. Direktori .insomnia di direktori kerja Anda. Ini adalah apa yang dihasilkan oleh Git Sync Insomnia, jadi ketika Anda melakukan commit proyek API Anda ke repositori, inso dapat membacanya langsung dari checkout. Ini adalah pola yang Anda inginkan untuk CI.
2. Direktori data aplikasi Insomnia, jika aplikasi diinstal di mesin. Ini nyaman secara lokal tetapi tidak berguna pada CI runner yang bersih yang belum pernah memiliki aplikasi tersebut.

Anda dapat menimpa sumber secara eksplisit:

inso lint spec "Orders API" --workingDir ./api-project
# atau menunjuk ke sumber yang tepat
inso run test "Payments API tests" --src ./api-project/.insomnia

Model mental kuncinya: inso mereferensikan semuanya berdasarkan nama (atau ID), dan nama-nama tersebut diselesaikan terhadap sumber data mana pun yang ditemukannya. Jika sebuah nama tidak ada di direktori .insomnia atau data aplikasi, inso tidak dapat menjalankannya. Tidak ada konsep mengarahkan inso ke file OpenAPI yang terpisah dan mengatakan “uji ini” kecuali file tersebut berada di dalam struktur proyek Insomnia.

Contoh CI minimal

Berikut adalah job GitHub Actions yang melakukan linting spesifikasi dan menjalankan suite tes pada setiap push, menggunakan direktori .insomnia yang disinkronkan Git yang di-commit ke repositori:

name: API checks
on: [push]

jobs:
  inso:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install inso
        run: |
          curl -sSL https://github.com/Kong/insomnia/releases/latest/download/inso-linux-x64.zip -o inso.zip
          unzip inso.zip && sudo mv inso /usr/local/bin/
      - name: Lint the spec
        run: inso lint spec "Orders API" --workingDir .
      - name: Run the test suite
        run: inso run test "Payments API tests" --env "CI" --workingDir .

Karena kedua perintah keluar dengan kode non-nol saat gagal, spesifikasi yang rusak atau asersi yang gagal akan menyebabkan job gagal. Itulah inti dari memindahkan pemeriksaan ini keluar dari GUI.

Batasan Jujur

inso bagus dalam apa yang dilakukannya, tetapi memiliki batasan nyata.

Ini terikat pada sumber data Insomnia. Spesifikasi, koleksi, dan suite Anda harus berada dalam proyek Insomnia, yang muncul baik melalui Git Sync atau aplikasi yang diinstal. Jika tim Anda tidak menggunakan Insomnia sebagai sumber kebenaran, inso tidak memiliki apa pun untuk dioperasikan.

Semuanya direferensikan berdasarkan nama. Itu mudah dibaca, tetapi rapuh. Ubah nama suite di UI dan job CI yang mengodekan nama lama akan rusak secara diam-diam hingga jalankan berikutnya. Nama juga harus cukup unik agar dapat diselesaikan dengan jelas.

Cakupan dirancang sempit. inso menjalankan tes, menjalankan koleksi, melinting spesifikasi, mengekspor, dan menjalankan skrip. Ini bukan platform desain-mock-dokumen-tes. Untuk apa pun di luar tindakan tersebut, Anda kembali ke GUI atau mencari alat lain.

inso vs alternatif terintegrasi

inso adalah pendamping terminal yang kuat jika Insomnia sudah menjadi klien Anda. Kekurangannya adalah Anda menyatukan berbagai bagian: Insomnia untuk desain dan debugging, inso untuk CI, aturan Spectral untuk linting, dan perkakas terpisah untuk mock dan dokumen.

Apidog mengambil sikap yang berlawanan. Ini menempatkan desain, mock, dokumentasi, dan pengujian dalam satu platform, dan Apidog CLI-nya menjalankan skenario tes dan koleksi Anda dari sumber kebenaran yang sama, dengan pengujian berbasis data, berbagai format pelapor, dan sumber daya-dan-cabang-sebagai-kode. Patut jujur di sini: Apidog CLI tidak menyediakan linter spesifikasi mandiri seperti yang dilakukan inso dengan Spectral, jadi jika penegakan panduan gaya ala Spectral adalah prioritas Anda, inso memiliki keunggulan nyata di sana. Di mana Apidog unggul adalah integrasi. Anda tidak menyatukan lima alat yang berbeda.

Jika Anda ingin membandingkan keduanya secara langsung, lihat Apidog CLI vs inso (Insomnia CLI), atau baca latar belakang yang lebih mendalam di apa itu inso (Insomnia CLI). Jika Anda telah memutuskan inso bukan pilihan yang tepat, rangkuman alternatif inso terbaik dan panduan migrasi dari inso ke Apidog CLI akan memandu Anda melalui langkah demi langkah. Untuk konteks yang lebih luas tentang klien GUI itu sendiri, Apidog vs Insomnia dan cara menggunakan Insomnia untuk menguji API adalah titik awal yang baik.

Anda dapat mengunduh Apidog secara gratis jika Anda ingin melihat pendekatan terintegrasi berdampingan dengan pengaturan inso Anda.