Cara Menjalankan Tes API dari Apidog CLI

Uji coba API Anda berhasil di laptop Anda. Kemudian seseorang menggabungkan perubahan pada pukul 2 pagi, *endpoint* staging mulai mengembalikan *payload* yang salah bentuk, dan tidak ada yang menyadarinya sampai seorang pelanggan mengajukan tiket keesokan paginya. Uji coba itu ada. Hanya saja, uji coba tersebut tidak pernah berjalan di tempat yang seharusnya: di dalam *pipeline*, pada setiap *push*, tanpa ada manusia yang mengeklik tombol.

Kesenjangan antara "uji coba yang ada" dan "uji coba yang berjalan secara otomatis" inilah yang ditutup oleh *runner* baris perintah. Apidog CLI mengambil skenario uji coba yang telah Anda buat di aplikasi desktop atau web Apidog dan menjalankannya tanpa antarmuka grafis dari terminal. Tanpa GUI, tanpa klik manual. Anda menginstalnya dengan satu perintah npm, mengarahkannya ke skenario uji coba, dan ia keluar dengan kode status bersih serta laporan yang dapat Anda publikasikan di sistem CI apa pun. Ini menjadikannya jembatan antara pembangun uji coba visual dan platform CI/CD Anda.

TL;DR

• Apidog CLI adalah paket npm bernama apidog-cli. Instal secara global dengan npm install -g apidog-cli, lalu jalankan skenario dengan perintah apidog run.
• Ini menjalankan skenario uji coba yang Anda rancang di Apidog. Anda tidak perlu menulis ulang uji coba sebagai kode; CLI mengeksekusi skenario yang sama berdasarkan ID, menggunakan *access token* untuk autentikasi.
• Eksekusi inti: apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenarioId> -e <environmentId> -n 1 -r html,cli.
• *Reporter* mencakup cli, html, json, dan junit. JUnit XML adalah yang langsung terhubung ke *dashboard* uji coba CI.
• Kode keluar (exit code) bukan nol saat uji coba gagal adalah yang membuat CLI menjadi *quality gate* sejati. Uji coba yang gagal akan menggagalkan *build* secara *default*.
• Ini berfungsi di *runner* CI mana pun yang memiliki Node.js: GitHub Actions, GitLab CI, Jenkins, CircleCI, Azure Pipelines, dan lainnya.

Apa Sebenarnya Apidog CLI Itu

Apidog adalah platform API *all-in-one*: Anda merancang skema, men-debug permintaan, membangun skenario uji coba otomatis, mem-mock *endpoint*, dan menerbitkan dokumentasi dalam satu *workspace*. Sebagian besar pekerjaan itu terjadi di antarmuka visual. Anda merangkai permintaan ke dalam skenario uji coba, menambahkan *assertion*, menarik nilai dari satu respons ke yang berikutnya, dan melakukan *loop* atas file data.

CLI adalah *executor* tanpa antarmuka grafis untuk skenario-skenario tersebut. Ia tidak memiliki format uji cobanya sendiri. Ia masuk ke dalam proyek Apidog Anda, menemukan skenario yang Anda sebutkan berdasarkan ID, dan menjalankannya persis seperti yang akan dilakukan aplikasi, lalu melaporkannya kembali. Bayangkan ini sebagai hubungan antara alat *build* dan kode sumber Anda: sumber kebenaran ada di proyek, dan CLI adalah hal yang menjalankannya tanpa kehadiran seseorang.

Ini penting karena menghilangkan alasan paling umum uji coba API membusuk. Ketika uji coba hanya ada sebagai langkah-langkah yang dapat diklik di aplikasi desktop, uji coba tersebut dijalankan ketika seseorang mengingatnya. Ketika uji coba tersebut dijalankan dari perintah satu baris, Anda dapat menyambungkannya ke *pipeline* dan uji coba tersebut berjalan pada setiap *commit*, setiap *merge*, setiap jadwal malam. Pembangun visual memberi Anda penulisan yang cepat; CLI memberi Anda otomatisasi. Anda mendapatkan keduanya tanpa harus memilih.

Jika Anda berasal dari dunia Postman, model mentalnya cocok dengan bersih. Apidog CLI memainkan peran yang dimainkan Postman CLI atau Newman untuk koleksi Postman, kecuali ia menjalankan skenario uji coba Apidog dan dikirim sebagai satu paket. Kami telah membahas perbandingan tersebut secara mendalam di Postman CLI vs Newman, dan pertanyaan yang lebih luas tentang menjalankan koleksi di CI tanpa Newman jika Anda bermigrasi.

Prasyarat

Sebelum Anda menjalankan satu perintah pun, Anda memerlukan tiga hal:

1. Node.js v16 atau yang lebih baru. CLI dikirimkan sebagai paket npm, jadi *runtime* Node adalah satu-satunya dependensi sistem. Periksa milik Anda dengan node -v. Gambar CI mana pun dengan Node 16+ sudah memenuhi syarat.
2. Skenario uji coba Apidog. CLI menjalankan skenario, bukan permintaan lepas. Buat satu di aplikasi Apidog terlebih dahulu: rangkai permintaan Anda, tambahkan *assertion*, siapkan iterasi berbasis data yang Anda butuhkan. Jika Anda baru dalam membuat *assertion*, API assertions: panduan praktis membahas validasi respons.
3. *Access token*. Ini mengautentikasi CLI ke akun Apidog Anda sehingga dapat mengambil dan menjalankan skenario. Anda membuatnya di tab CI/CD skenario uji coba; lebih lanjut tentang itu di bawah.

Itu saja. Tidak ada instalasi Apidog terpisah di *box* CI, tidak ada GUI, tidak ada file lisensi. Paket dan *token* sudah cukup.

Menginstal Apidog CLI

Instal secara global dengan npm:

npm install -g apidog-cli

Kemudian konfirmasi semuanya teratasi dengan benar:

node -v && apidog -v && which node && which npm && which apidog

Jika itu mencetak nomor versi dan jalur, Anda selesai. Biner tersebut adalah apidog, jadi setiap perintah dimulai dengan apidog run.

Pada mesin pengembang, instalasi global tidak masalah. Di CI, Anda memiliki dua pola yang masuk akal. Yang pertama adalah menginstalnya baru di setiap *pipeline run*, yang menjamin Anda menggunakan versi terbaru:

npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

Yang kedua adalah menjalankannya tanpa instalasi global persisten melalui npx, yang menghindari memodifikasi paket global *runner*:

npx apidog-cli run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

Keduanya berfungsi. Pendekatan npx lebih bersih untuk *runner* CI sementara; instalasi global sedikit lebih cepat jika Anda menyimpannya dalam *cache* antar *run*.

Mendapatkan *Access Token* dan ID Skenario Anda

CLI perlu mengetahui dua hal: skenario mana yang akan dijalankan, dan bahwa ia diizinkan untuk menjalankannya. Apidog menghasilkan keduanya untuk Anda sehingga Anda tidak perlu mencari-cari di UI.

Buka skenario uji coba yang ingin Anda otomatisasi. Beralih ke tab CI/CD-nya. Pilih opsi baris perintah, lalu klik Tambahkan *access token* dan Buat *token*. Apidog akan membuat perintah apidog run lengkap untuk Anda, dengan *access token*, ID skenario, dan ID lingkungan sudah terisi. Klik perintah tersebut untuk menyalinnya.

Perintah yang dihasilkan itu adalah titik awal kanonik. Bentuknya seperti ini:

apidog run --access-token YOUR_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r html,cli

Angka-angka tersebut adalah ID asli dari proyek Anda. 605067 adalah ID skenario uji coba. 1629989 adalah ID lingkungan. Anda hampir tidak akan pernah mengetik ini secara manual; Anda menyalinnya dari tab CI/CD sekali lalu memparameterisasi *token*.

Satu aturan yang patut disebutkan sejak awal: perlakukan *access token* seperti kata sandi. Jangan menempelkannya ke file konfigurasi yang di-*commit* atau definisi *pipeline* publik. Simpan sebagai rahasia di sistem CI Anda dan referensikan sebagai variabel lingkungan. Setiap contoh di bawah menggunakan $APIDOG_ACCESS_TOKEN justru karena alasan ini.

Perintah apidog run, *flag* demi *flag*

Seluruh CLI berputar pada satu perintah. Berikut adalah semua opsi yang tersedia, dikelompokkan berdasarkan apa yang dikendalikan oleh setiap kelompok.

Memilih Apa yang Akan Dijalankan

Anda memilih salah satu dari `-t`, `-f`, atau `--test-suite` tergantung pada cakupannya. Satu skenario untuk *smoke test* terfokus, folder untuk area fitur, *test suite* ketika Anda menginginkan serangkaian skenario terpilih dijalankan bersama sebagai satu pekerjaan logis.

Autentikasi

Ini adalah satu-satunya *flag* yang dibutuhkan setiap perintah CI. Sampaikan dari rahasia, jangan pernah secara langsung.

Lingkungan dan Iterasi

*Flag* lingkungan adalah cara Anda mengarahkan skenario yang sama ke *staging* dalam pemeriksaan *pull-request* dan ke produksi dalam *smoke test* pasca-deploy, tanpa menduplikasi skenario. Data iterasi adalah cara Anda menjalankan satu skenario di lima puluh baris input dan memperlakukan setiap baris sebagai *pass* terpisah. Kami membahas pola berbasis data lebih lengkap dalam panduan tentang menskalakan uji coba API otomatis dengan *test suite*.

Laporan

Di sinilah CLI mendapatkan tempatnya dalam *pipeline*. Lewati beberapa format sekaligus, dipisahkan koma:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -r html,junit --out-dir ./test-reports

cli memberi Anda *output* terminal yang dapat dibaca oleh manusia yang membaca *log build*. html menghasilkan laporan mandiri yang dapat Anda arsipkan sebagai artefak *build* dan membukanya di browser. junit mengeluarkan XML dalam format JUnit standar, yang hampir setiap *dashboard* CI tahu cara mem-*parse* menjadi pohon lulus/gagal. json memberi Anda hasil terstruktur mentah jika Anda ingin memprosesnya lebih lanjut.

Penanganan Kesalahan dan Perilaku Keluar

--on-error mengontrol apa yang terjadi di tengah skenario. end menghentikan *run* pada kegagalan pertama, yang biasanya Anda inginkan untuk *smoke test* yang cepat gagal. continue menjalankan setiap langkah sehingga Anda melihat semua kegagalan dalam satu laporan. ignore adalah untuk kasus langka di mana suatu langkah diketahui *flaky* dan Anda tidak ingin itu menggagalkan *run*.

TLS dan Sertifikat

Gunakan ini saat Anda menguji *endpoint* di belakang TLS mutual atau dengan rantai CA internal. Gunakan `-k` hanya sebagai upaya terakhir pada *host* internal tepercaya di mana sertifikat ditandatangani sendiri; jangan pernah terhadap apa pun yang bersifat publik.

Output dan Diagnostik

--verbose adalah langkah pertama Anda ketika uji coba berhasil secara lokal tetapi gagal di CI; ini menunjukkan kepada Anda permintaan persis yang dikirim *runner* dan respons persis yang diterimanya kembali. --silent adalah untuk pekerjaan malam yang bising di mana Anda hanya peduli dengan kode keluar dan laporan yang disimpan.

Kode Keluar: Bagian yang Membuat CI Berfungsi

*Test runner* hanya berguna dalam *pipeline* jika ia memberi tahu *pipeline* apakah uji coba berhasil. Apidog CLI melakukan ini dengan cara yang sama seperti setiap alat baris perintah yang berfungsi dengan baik: ia keluar dengan kode 0 ketika setiap *assertion* berhasil dan kode bukan nol ketika ada sesuatu yang gagal.

Perilaku tunggal itu yang mengubah apidog run menjadi *quality gate*. Sistem CI membaca kode keluar dari setiap langkah. Kode keluar bukan nol menandai langkah tersebut sebagai gagal, yang menggagalkan pekerjaan, yang memblokir *merge* atau *deploy*. Anda tidak mengonfigurasi apa pun tambahan. Selama langkah apidog run ada di *pipeline* Anda, uji coba yang gagal akan menghentikan baris.

Anda dapat membentuk ini dengan --on-error. Perilaku *default* adalah gagal pada *assertion* pertama yang rusak, yang menjaga *feedback* cepat. Beralih ke --on-error continue ketika Anda lebih suka melihat setiap kegagalan dalam satu laporan sebelum *build* menjadi merah. Bagaimanapun, *run* masih berakhir dengan kode keluar bukan nol jika ada yang gagal, sehingga gerbang tetap bertahan.

Menjalankan di GitHub Actions

*workflow* lengkap yang menjalankan skenario Apidog pada setiap *pull request* dan menerbitkan laporan sebagai artefak.

name: API tests

on:
 pull_request:
 branches: [main]

jobs:
 api-tests:
 runs-on: ubuntu-latest
 steps:
 - name: Checkout
 uses: actions/checkout@v4

 - name: Set up Node.js
 uses: actions/setup-node@v4
 with:
 node-version: '20'

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

 - name: Run API test scenario
 run: |
 apidog run \
 --access-token "$APIDOG_ACCESS_TOKEN" \
 -t 605067 \
 -e 1629989 \
 -n 1 \
 -r html,junit \
 --out-dir ./apidog-reports
 env:
 APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

 - name: Upload report
 if: always()
 uses: actions/upload-artifact@v4
 with:
 name: apidog-report
 path: ./apidog-reports

*Token* tersebut berada di rahasia repositori dan mencapai langkah sebagai variabel lingkungan. if: always() pada langkah unggah berarti Anda tetap mendapatkan laporan meskipun uji coba gagal, yang merupakan saat yang tepat untuk membacanya. Jika uji coba rusak, langkah apidog run keluar dengan kode bukan nol, pekerjaan menjadi merah, dan PR menunjukkan pemeriksaan yang gagal.

Menjalankan di GitLab CI

Pola yang sama dalam .gitlab-ci.yml:

stages:
 - test

api-tests:
 stage: test
 image: node:20
 script:
 - npm install -g apidog-cli
 - >
 apidog run
 --access-token "$APIDOG_ACCESS_TOKEN"
 -t 605067
 -e 1629989
 -r junit,cli
 --out-dir ./apidog-reports
 artifacts:
 when: always
 paths:
 - apidog-reports/
 reports:
 junit: apidog-reports/*.xml

Dua hal yang perlu diperhatikan. Simpan APIDOG_ACCESS_TOKEN sebagai variabel CI/CD yang tersembunyi dan dilindungi di bawah Pengaturan, bukan di dalam file. Dan blok reports: junit: memberi tahu GitLab untuk mengurai XML JUnit dan menampilkan hasilnya di *widget merge request*, sehingga peninjau melihat *assertion* mana yang gagal tanpa perlu mengunduh apa pun.

Menjalankan di Jenkins

Dalam *pipeline* deklaratif, simpan *token* sebagai kredensial Jenkins atau variabel lingkungan global, lalu panggil CLI dalam suatu *stage*:

pipeline {
 agent any
 environment {
 APIDOG_ACCESS_TOKEN = credentials('apidog-access-token')
 }
 stages {
 stage('API tests') {
 steps {
 sh 'npm install -g apidog-cli'
 sh 'apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r html,junit --out-dir apidog-reports'
 }
 }
 }
 post {
 always {
 junit 'apidog-reports/*.xml'
 archiveArtifacts artifacts: 'apidog-reports/', allowEmptyArchive: true
 }
 }
}

Jika agen *build* Anda sudah memiliki CLI terinstal dan di-*cache*, hapus baris npm install dan panggil apidog run secara langsung. Langkah junit di blok post memasukkan XML ke grafik tren uji coba Jenkins; archiveArtifacts menyimpan laporan HTML yang terlampir pada *build*. Jika Anda membandingkan Jenkins dengan *runner* lain, perbandingan di pengaturan CI ReadyAPI Jenkins, dan alternatif yang lebih sederhana mencakup kompromi-komprominya.

Pola dan Resep Umum

*Smoke test* setelah *deploy*. Jalankan satu skenario cepat terhadap produksi tepat setelah rilis, menargetkan lingkungan produksi:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e <prodEnvId> -r cli --on-error end

Regresi penuh setiap malam. Jalankan seluruh folder skenario sesuai jadwal, dengan semua kegagalan dikumpulkan menjadi satu laporan:

apidog run --access-token $APIDOG_ACCESS_TOKEN -f <folderId> -r html,junit --on-error continue --out-dir ./nightly-reports

*Run* berbasis data. Lakukan *loop* satu skenario di atas CSV kasus uji coba:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./test-data.csv -r junit

Pemeriksaan spesifik *branch*. Jalankan skenario sebagaimana adanya pada *feature branch*, bukan main:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 --branch feature-payments -e 1629989 -r cli

Mendebug kegagalan hanya CI. Ketika skenario berhasil secara lokal tetapi gagal di *pipeline*, tambahkan --verbose untuk melihat permintaan dan respons tingkat *wire* persis yang dihasilkan oleh *runner*.

Pemecahan Masalah

Kesalahan autentikasi. Jika *run* gagal dengan kesalahan autentikasi, *token* salah, kedaluwarsa, atau tidak mencapai perintah. Lakukan *echo* pemeriksaan yang di-*mask* (jangan pernah *token* penuh) dan konfirmasi bahwa rahasia CI Anda benar-benar terisi. Buat ulang *token* dari tab CI/CD skenario jika diperlukan.

"Skenario tidak ditemukan." ID skenario, ID proyek, atau *branch* tidak cocok. Salin ulang perintah dari tab CI/CD agar ID dijamin terbaru, dan konfirmasi bahwa --branch menunjuk ke tempat yang Anda harapkan.

Uji coba berhasil secara lokal tetapi gagal di CI. Hampir selalu perbedaan lingkungan. *Runner* CI mungkin menargetkan lingkungan -e yang berbeda, mencapai *host* yang tidak dapat dijangkau, atau tidak memiliki variabel yang diandalkan oleh skenario Anda. Jalankan dengan --verbose dan bandingkan permintaan yang dikirim oleh *runner* CI dengan yang Anda kirim secara lokal.

Kegagalan jaringan atau TLS terhadap *host* internal. Jika *endpoint* Anda menggunakan CA internal, teruskan --ssl-extra-ca-certs. Gunakan -k hanya sebagai upaya terakhir pada *host* internal tepercaya di mana sertifikat ditandatangani sendiri.

*Build* tetap hijau meskipun seharusnya uji coba gagal. Konfirmasi bahwa kode keluar langkah apidog run benar-benar mencapai CI. Jika Anda membungkusnya dalam *shell pipeline* atau menambahkan || true, kode keluar bukan nol akan tertelan dan *gate* berhenti berfungsi. Hapus apa pun yang menyembunyikan kode keluar.

Bagaimana Apidog CLI Cocok dalam Alur Kerja Nyata

CLI adalah salah satu bagian dari sebuah *loop*. Anda merancang dan men-debug permintaan di aplikasi Apidog. Anda merangkainya menjadi skenario dengan *assertion*. Anda melakukan *commit* pekerjaan Anda dan CLI menjalankan skenario tersebut di CI pada setiap perubahan. Ketika ada sesuatu yang rusak, laporan memberi tahu Anda *assertion* mana yang gagal dan kode keluar menghentikan *deploy*. Anda memperbaikinya, melakukan *push* lagi, dan *gate* yang sama mengkonfirmasi perbaikan tersebut.

Keuntungan membangun uji coba secara visual dan menjalankannya tanpa antarmuka grafis adalah tidak ada yang perlu memelihara dua representasi dari uji coba yang sama. Skenario dalam proyek adalah uji cobanya. CLI hanya menjalankannya di mana manusia tidak dapat melakukannya. Itu adalah model yang berbeda dari *runner* yang mengutamakan skrip, di mana uji coba dan eksekusinya adalah file rapuh yang sama, dan itu adalah bagian besar mengapa tim beralih ke Apidog sebagai alternatif Postman untuk pengujian API.

Jika Anda belum membuat uji coba, mulailah di aplikasi, dapatkan satu skenario yang berhasil, lalu sambungkan perintah CLI dari tab CI/CD-nya. Unduh Apidog untuk menyiapkan skenario otomatis pertama Anda, dan Anda akan memiliki *gate* untuk *pipeline* Anda pada sore yang sama.

Pertanyaan yang Sering Diajukan

Apakah Apidog CLI gratis? CLI itu sendiri adalah paket npm gratis. Anda menginstalnya dengan npm install -g apidog-cli. Ini menjalankan skenario uji coba dari proyek Apidog Anda, jadi apa yang dapat Anda jalankan tergantung pada paket Apidog Anda, tetapi *runner* baris perintah bukanlah produk berbayar terpisah.

Apakah saya harus menulis ulang uji coba saya sebagai kode untuk menggunakan CLI? Tidak. Itulah perbedaan utama dari *runner* yang mengutamakan skrip. Anda membangun skenario secara visual di Apidog, dan CLI menjalankannya berdasarkan ID. Skenario adalah uji cobanya; CLI hanyalah *executor*.

Apa perbedaan antara Apidog CLI dan Newman? Newman menjalankan koleksi Postman dari baris perintah. Apidog CLI menjalankan skenario uji coba Apidog. Peran-peran ini paralel, tetapi *runner* Apidog mengeksekusi skenario yang Anda buat di aplikasi Apidog dan dikirim sebagai paket apidog-cli tunggal. Lihat Postman CLI vs Newman untuk sisi Postman dari perbandingan itu.

Format laporan mana yang harus saya gunakan di CI? Gunakan junit untuk hasil yang dapat dibaca mesin yang diurai oleh *dashboard* CI Anda menjadi pohon lulus/gagal, dan tambahkan html jika Anda ingin laporan yang dapat dijelajahi disimpan sebagai artefak *build*. Pilihan umum adalah -r html,junit. Tetap aktifkan cli juga jika Anda ingin *output* yang dapat dibaca di *log build*.

Bagaimana CLI membuat *build* gagal? Melalui kode keluarnya. Ketika ada *assertion* yang gagal, apidog run keluar dengan kode bukan nol. Sistem CI membaca kode keluar tersebut, menandai langkah tersebut sebagai gagal, dan memblokir *merge* atau *deploy*. Anda tidak perlu mengonfigurasi apa pun tambahan agar ini berfungsi.

Bisakah saya menjalankan CLI tanpa menginstalnya secara global? Ya. Gunakan npx apidog-cli run ... untuk mengeksekusinya tanpa instalasi global persisten, yang nyaman pada *runner* CI sementara.

Versi Node.js berapa yang saya butuhkan? Node.js v16 atau yang lebih baru. Gambar CI modern mana pun dengan Node 16+ sudah memenuhi persyaratan tersebut.

Di mana saya mendapatkan *access token* dan ID skenario? Keduanya berasal dari tab CI/CD skenario uji coba di Apidog. Pilih opsi baris perintah, buat *access token*, dan salin perintah apidog run lengkap yang dibuat Apidog untuk Anda dengan ID yang sudah terisi. Kemudian pindahkan *token* tersebut ke rahasia CI.