Cara Migrasi dari Hoppscotch CLI ke Apidog CLI

Hoppscotch CLI adalah cara yang bersih dan gratis untuk menjalankan koleksi API di terminal atau *pipeline* CI. Perintah hopp test membaca file koleksi, mengeksekusi setiap permintaan, menjalankan skrip pra-permintaan dan pengujian Anda, dan keluar dengan kode bukan nol ketika sebuah asersi gagal. Bagi banyak tim, itu sudah cukup.

Namun, sebuah *runner* hanyalah satu bagian dari pekerjaan API. Pada titik tertentu, Anda akan mengelola alat desain terpisah, server *mock*, situs dokumentasi, dan *runner*, dan tidak ada satu pun dari mereka yang berbagi satu sumber kebenaran. Biasanya, saat itulah tim mulai mencari cara untuk bermigrasi dari Hoppscotch CLI ke Apidog CLI. Apidog menggabungkan desain, *debugging*, *mocking*, dokumentasi, dan pengujian ke dalam satu platform, dan CLI-nya menjalankan sisi pengujian di CI. *Runner* tetap dalam bentuk yang sudah Anda kenal. Yang berubah adalah segala sesuatu di sekelilingnya.

Kapan Anda Harus (dan Seharusnya Tidak) Bermigrasi

Jujurlah pada diri sendiri terlebih dahulu. Jika satu-satunya persyaratan Anda adalah "menjalankan koleksi di CI secara gratis, *self-host* jika saya mau," Hoppscotch CLI adalah alat yang benar-benar bagus. Ini sumber terbuka, *runner*-nya cepat, dan @hoppscotch/cli dikirim sebagai paket npm biasa. Tidak ada salahnya untuk tetap menggunakannya.

Bermigrasi saat salah satu dari ini mulai terasa menyulitkan:

• Anda mendesain API di satu alat, melakukan *mock* di alat lain, dan menulis dokumen di alat ketiga, dan menjaga agar semuanya sinkron adalah pekerjaan manual.
• Anda ingin *test run*, *mock server*, dan dokumentasi yang dipublikasikan berbagi definisi proyek tunggal.
• Anda membutuhkan pelaporan yang lebih kaya (laporan HTML untuk pemangku kepentingan, JSON untuk mesin) ditambah riwayat *run* yang dihosting di *cloud*.
• Anda ingin memperlakukan *endpoint*, skema, lingkungan, dan cabang sebagai kode yang dapat dikelola oleh CLI, bukan hanya dieksekusi.

Jika daftar tersebut menggambarkan minggu Anda, platform adalah alasan untuk pindah, bukan *runner*-nya. Berikut adalah cara melakukannya dengan bersih.

Langkah 1: Ekspor koleksi dan lingkungan Hoppscotch Anda

Segala sesuatu di Hoppscotch adalah JSON, yang membuat ekspor tanpa rasa sakit.

Dari aplikasi Hoppscotch (web atau desktop), buka koleksi yang Anda jalankan di CI. Gunakan menu koleksi dan pilih Export, yang akan memberikan Anda file .json. Lakukan hal yang sama untuk lingkungan yang Anda lewatkan dengan -e: buka panel lingkungan dan ekspor ke file JSON-nya sendiri.

Jika Anda sudah menjalankan CLI terhadap file lokal, Anda sudah memiliki ini di disk. Langkah CI Hoppscotch yang umum terlihat seperti ini:

npm i -g @hoppscotch/cli
hopp test ./collections/checkout-api.json -e ./environments/staging.json

Simpan kedua file. checkout-api.json adalah koleksi Anda, staging.json adalah lingkungan Anda. Keduanya adalah seluruh *payload* yang Anda bawa.

Satu catatan tentang versi Node selagi Anda di sini. Hoppscotch CLI saat ini membutuhkan Node.js v22 atau yang lebih baru; tim yang terpaku pada Node 20 tetap menggunakan CLI v0.26.0. Apidog CLI tidak mengikat Anda pada itu, jadi migrasi juga merupakan kesempatan untuk menghilangkan batasan versi.

Langkah 2: Impor koleksi ke Apidog

Buat proyek di Apidog (atau buka yang sudah ada), lalu impor ekspor Hoppscotch Anda. Apidog membaca format koleksi umum dan OpenAPI, sehingga Anda dapat langsung memasukkan koleksi tersebut. Jika API Anda juga memiliki spesifikasi OpenAPI, impor juga. Apidog memvalidasi spesifikasi saat impor, sehingga masalah struktural langsung muncul alih-alih gagal secara diam-diam di tengah *run*.

Petakan lingkungan Hoppscotch Anda ke lingkungan Apidog dengan nama variabel yang sama. Jika staging.json mendefinisikan base_url dan api_token, buat ulang kunci-kunci tersebut di bawah lingkungan Apidog yang sesuai. Menjaga nama-nama identik berarti skrip pengujian dan URL permintaan Anda tidak perlu diedit.

Ini juga saat platform mulai memberikan hasil. *Endpoint* yang Anda impor sekarang adalah artefak desain. Anda dapat melampirkan skema, membuat *mock server* dari mereka, dan mempublikasikan dokumen dari definisi yang sama yang Anda uji. Panduan lengkap Apidog CLI mencakup seluruh permukaan setelah Anda siap, dan panduan instalasi menangani biner *runner*.

Langkah 3: Petakan hopp test ke apidog run

Model mentalnya diteruskan secara langsung. Di mana Hoppscotch menjalankan file koleksi, Apidog menjalankan skenario pengujian atau koleksi dari proyek Anda. Pekerjaan yang sama, sumber kebenaran yang berbeda.

# Hoppscotch
hopp test ./collections/checkout-api.json -e ./environments/staging.json

# Apidog
apidog run --access-token $APIDOG_TOKEN -e "Staging"

Kedua perintah mengeksekusi setiap permintaan secara berurutan, menjalankan skrip pra-permintaan, menjalankan asersi pengujian Anda, dan mengembalikan kode keluar bukan nol jika ada yang gagal. Kontrak kode keluar itu adalah bagian yang diandalkan CI, dan itu dipertahankan, jadi logika lulus/gagal *pipeline* Anda tidak berubah.

Autentikasi berbeda secara berguna. Hoppscotch meneruskan token akses pribadi dengan --token untuk koleksi *cloud* atau *self-hosted*. Apidog mengautentikasi dengan *login* atau token akses, yang kemudian memungkinkan CLI menjangkau sumber daya di proyek Anda daripada file tunggal yang diekspor. Jika Anda pernah berjuang dengan penanganan token sebelumnya, panduan autentikasi menjelaskan opsi-opsinya.

Langkah 4: Konversi Eksekusi Berbasis Data

Kedua alat ini melakukan pengujian berbasis data (*data-driven testing*), sehingga iterasi melalui CSV masukan tetap berfungsi setelah migrasi.

Di Hoppscotch Anda meneruskan data iterasi dan hitungan:

hopp test ./collections/checkout-api.json \
  -e ./environments/staging.json \
  --iteration-count 50 \
  --iteration-data ./data/orders.csv

Di Apidog, *runner* mengambil *dataset* dengan -d. Ini menerima CSV dan JSON, sehingga orders.csv yang sama berfungsi setelah impor:

apidog run --access-token $APIDOG_TOKEN \
  -e "Staging" \
  -d ./data/orders.csv

Baris *header* CSV Anda menjadi nama variabel yang Anda referensikan di dalam permintaan dan asersi, pola yang sama yang digunakan Hoppscotch, sehingga badan pengujian tidak perlu ditulis ulang. Jika Anda baru mengenal gaya Apidog ini, panduan pengujian berbasis data menunjukkan cara mengikat kolom ke variabel dan menjalankan satu baris per iterasi.

Langkah 5: Konversi Pelapor Anda

Pelaporan adalah di mana platform unggul, dan konversinya mudah.

Hoppscotch mengeluarkan file JUnit XML dengan satu *flag*, yang sebagian besar sistem CI parsing untuk panel pengujian:

hopp test ./collections/checkout-api.json \
  -e ./environments/staging.json \
  --reporter-junit ./reports/results.xml

Apidog memberi Anda pilihan pelapor (*reporter*): ringkasan CLI yang mudah dibaca, laporan HTML yang dapat Anda berikan kepada pemangku kepentingan, dan laporan JSON untuk mesin. Anda juga dapat mengirimkan hasil ke *cloud* untuk riwayat *run* yang dapat dibagikan.

# Human-readable HTML report
apidog run --access-token $APIDOG_TOKEN \
  -e "Staging" \
  -r html \
  --upload-report

Jika dasbor CI Anda secara khusus mengharapkan JUnit XML, ingatlah integrasi itu selama pertukaran, karena Apidog lebih mengandalkan *reporter* CLI/HTML/JSON-nya ditambah laporan *cloud* daripada *flag* JUnit. Bagi sebagian besar tim, laporan HTML ditambah riwayat *cloud* yang diunggah adalah peningkatan dari file XML mentah yang tidak ada yang membukanya. Panduan laporan pengujian menguraikan setiap format dan kapan menggunakannya.

Sebelum dan Sesudah: Pemetaan Perintah

Perhatikan *flag* -d di tabel itu. Di Hoppscotch, -d adalah penundaan dalam milidetik; di Apidog, -d adalah *dataset* untuk eksekusi berbasis data. Huruf yang sama, tugas yang berbeda. Ini adalah satu-satunya jebakan yang membuat orang tersandung saat beralih dari Hopp ke Apidog.

Langkah 6: Integrasikan ke GitHub Actions

Langkah terakhir, dan tujuannya adalah *build* yang berhasil (hijau) sepanjang proses. Jalankan pekerjaan Apidog berdampingan dengan pekerjaan Hoppscotch yang lama terlebih dahulu, konfirmasi bahwa itu berhasil, lalu hapus langkah yang lama. Jangan pernah beralih secara membabi buta.

name: API tests
on: [push, pull_request]

jobs:
  apidog-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Apidog CLI
        run: npm install -g apidog-cli

      - name: Run API tests
        env:
          APIDOG_TOKEN: ${{ secrets.APIDOG_TOKEN }}
        run: |
          apidog run \
            --access-token "$APIDOG_TOKEN" \
            -e "Staging" \
            -d ./data/orders.csv \
            -r html \
            --upload-report

Simpan token akses Anda sebagai *secret* repositori, jangan pernah di YAML. Karena CLI mengembalikan kode keluar bukan nol pada setiap asersi yang gagal, pekerjaan akan gagal tepat ketika pengujian Anda gagal, yang merupakan perilaku yang sudah dipercaya tim Anda dari Hoppscotch. Panduan GitHub Actions mencakup *caching* dan *matrix runs*, dan panduan *pipeline* CI/CD yang lebih luas menangani GitLab, Jenkins, dan lainnya.

Setelah pekerjaan Apidog berhasil (hijau) untuk beberapa *run*, hapus langkah Hoppscotch dan instalasi npm-nya. Migrasi selesai, *build* tidak pernah merah.

Sebuah Catatan tentang Hoppscotch

Tidak ada satupun dari ini yang bermaksud merendahkan Hoppscotch. *Runner* CLI-nya cepat dan gratis, proyeknya sepenuhnya sumber terbuka, dan Anda dapat *self-host* seluruh *stack*. Jika Anda hanya menginginkan *runner* yang ramping dan tidak lebih, ia memiliki tempatnya. Alasan untuk beralih adalah cakupan: ketika desain, *mock*, dokumen, dan pengujian semuanya perlu berbagi satu definisi, *runner* mandiri tidak dapat memberikan itu kepada Anda, dan platform terintegrasi dapat. Bandingkan kedua *runner* secara langsung di Apidog CLI vs Hoppscotch CLI, dan jika Anda mempertimbangkan aplikasi daripada CLI, Postman vs Hoppscotch dan ringkasan alternatif Hoppscotch memberikan konteks tambahan.