Cara Menjalankan Pengujian API di CI dengan apidog run

Anda menyalin perintah dari tab CI/CD, menempelkannya ke dalam pipeline, dan berhasil. Kemudian rekan tim bertanya mengapa build tetap hijau padahal ada tes yang jelas-jelas gagal, atau apakah Anda bisa mengarahkan eksekusi yang sama ke staging alih-alih produksi, atau bagaimana cara mendapatkan laporan yang benar-benar bisa diuraikan oleh dasbor CI Anda. Tiba-tiba satu baris perintah tidak cukup. Anda perlu tahu apa fungsi setiap bagiannya.

apidog run adalah satu-satunya perintah inti dari runner baris perintah Apidog. Perintah ini mengeksekusi skenario pengujian API yang Anda buat di Apidog secara headless, dari terminal, tanpa GUI dan tanpa manusia mengeklik tombol. Semua yang bisa dilakukan runner, dilakukan melalui flag pada satu perintah ini: skenario mana yang akan dijalankan, lingkungan mana yang akan dituju, berapa kali akan diulang, laporan apa yang akan dikeluarkan, dan apa yang dianggap sebagai kegagalan. Pelajari antarmuka flag sekali dan Anda berhenti menyalin-menempel secara membabi buta.

Apa itu apidog run

Apidog CLI dikirim sebagai paket npm bernama apidog-cli. Anda menginstalnya sekali dan Anda akan mendapatkan satu binary, apidog, dengan subperintah utamanya adalah run. Subperintah tersebut mengambil salah satu skenario pengujian Apidog Anda dan menjalankannya seperti aplikasi desktop, kemudian melaporkan kembali dengan kode keluar (exit code) dan file laporan apa pun yang Anda minta.

Instal secara global:

npm install -g apidog-cli

Konfirmasi telah teratasi:apidog -v

Hal yang perlu dipahami sebelum menggunakan flag adalah apa yang dioperasikan oleh apidog run. Perintah ini tidak mendefinisikan format pengujiannya sendiri. Pengujian adalah skenario yang Anda buat di aplikasi Apidog: permintaan berantai, pernyataan (assertions), nilai yang ditarik dari satu respons ke respons berikutnya, iterasi berbasis data opsional. CLI masuk ke proyek Anda, menemukan skenario berdasarkan ID, dan menjalankannya. Jadi, sebagian besar flag adalah tentang memberi tahu runner apa yang harus diambil dan bagaimana berperilaku saat berjalan, bukan tentang menulis pengujian secara inline.

Perintah minimal yang sebenarnya terlihat seperti ini:

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

Itu berarti: autentikasi dengan token ini, jalankan skenario pengujian 605067, terhadap lingkungan 1629989, sekali, dan hasilkan laporan HTML ditambah keluaran terminal yang dapat dibaca. Setiap flag dalam baris tersebut dijelaskan di bawah, beserta yang tidak disertakan dalam perintah tersebut.

Antarmuka opsi lengkap sekilas

Berikut adalah rangkaian lengkap opsi yang dikelompokkan berdasarkan tugas. Gunakan ini sebagai tabel pencarian; bagian-bagian setelahnya menjelaskan yang membutuhkan lebih dari satu kalimat.

Nama flag dan nilai default dapat berubah antar rilis CLI. Jika ragu, runner adalah sumber kebenarannya sendiri: jalankan apidog run --help pada versi yang Anda instal dan percayai itu daripada artikel apa pun, termasuk yang ini.

Memilih apa yang akan dijalankan

Tiga flag menentukan cakupan eksekusi, dan Anda memilih tepat satu dari mereka per perintah.

-t, --test-scenario <id> menjalankan satu skenario. Ini adalah kasus sehari-hari: satu smoke test terfokus, satu skenario regresi, satu hal yang ingin Anda batasi pada pull request.

-f, --test-scenario-folder <id> menjalankan setiap skenario di dalam folder. Gunakan ini saat Anda telah mengorganisir area fitur ke dalam folder dan ingin seluruh grup dijalankan sebagai satu tugas, seperti pemindaian regresi setiap malam.

--test-suite <id> menjalankan suite pengujian yang dikurasi, yaitu seperangkat skenario yang Anda rakit untuk dijalankan bersama sebagai satu unit logis. Suite adalah alat yang tepat ketika skenario yang Anda inginkan tidak semuanya dalam satu folder tetapi masih termasuk dalam pass pengujian yang sama.

Dua selektor lagi menyaring tempat runner mencari. --project <id> menamai proyek tempat skenario berada, berguna ketika token Anda memiliki akses ke lebih dari satu proyek. --branch <name> menjalankan skenario sebagaimana adanya pada branch tertentu alih-alih main, yang memungkinkan Anda memvalidasi perubahan pengujian pada feature branch sebelum digabungkan.

# satu skenario
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

# seluruh folder
apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit

# sebuah suite yang dikurasi
apidog run --access-token $APIDOG_ACCESS_TOKEN --test-suite 40231 -r junit

Mengautentikasi eksekusi

--access-token <token> adalah satu-satunya flag yang dibutuhkan setiap eksekusi online. Ini membuktikan bahwa eksekusi diizinkan untuk mengambil dan mengeksekusi skenario Anda. Anda membuat token di dalam tab CI/CD skenario pengujian di Apidog, tempat aplikasi juga membangun perintah apidog run lengkap untuk Anda dengan ID skenario dan ID lingkungan yang sudah terisi.

Perlakukan token seperti kata sandi. Jangan menempelkannya ke file pipeline yang di-commit atau skrip bersama. Simpan sebagai rahasia dalam sistem CI Anda dan teruskan melalui variabel lingkungan, itulah sebabnya setiap contoh di sini merujuk pada $APIDOG_ACCESS_TOKEN daripada string literal. Jika token bocor, buat ulang dari tab CI/CD yang sama dan token lama akan berhenti berfungsi.

Menargetkan lingkungan dan berulang

Flag lingkungan inilah yang memungkinkan satu skenario melayani banyak tujuan. -e, --environment <id> mengarahkan eksekusi ke lingkungan tertentu, sehingga skenario yang sama dapat memeriksa staging di gerbang pull request dan produksi dalam smoke test pasca-deploy tanpa Anda perlu menduplikasi apa pun. Jika Anda mengelola nilai di seluruh lingkungan, panduan tentang manajemen lingkungan dan rahasia untuk klien API mencakup bagaimana nilai-nilai tersebut mengalir.

-n, --iteration-count <n> menjalankan skenario n kali berturut-turut. Berguna untuk pemeriksaan stabilitas cepat atau untuk mengulang alur yang seharusnya bersifat idempoten.

-d, --iteration-data <path> adalah flag berbasis data. Arahkan ke file JSON atau CSV dan runner akan mengeksekusi skenario sekali per baris, memperlakukan setiap baris sebagai passnya sendiri dengan nilai inputnya sendiri. Begitulah cara Anda menjalankan satu skenario login di lima puluh akun, atau satu alur pembuatan pesanan di seluruh tabel payload. Pola yang lebih dalam ada di pengujian API berbasis data dengan CSV dan JSON.

Tiga flag menyuntikkan nilai tanpa mengedit skenario. --variables <path> memuat variabel dari file lokal. --global-var key=value mengatur variabel global secara inline. --env-var key=value menimpa satu variabel lingkungan hanya untuk eksekusi ini. Ini berguna dalam CI ketika suatu nilai (URL dasar, feature flag) berbeda per pipeline dan Anda tidak menginginkan lingkungan terpisah untuk masing-masingnya. Jika variabel di Apidog baru bagi Anda, menguasai variabel di Apidog menjelaskan cakupannya.

# jalankan skenario 50 kali di seluruh CSV input
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./accounts.csv -r junit

# timpa satu variabel lingkungan hanya untuk eksekusi ini
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 --env-var baseUrl=https://staging.internal -r cli

Pelapor: setiap format keluaran yang dapat dihasilkan oleh apidog run

Ini adalah grup yang paling banyak dicari orang, jadi berikut adalah setiap pelapor dan fungsinya. Anda memilihnya dengan -r, --reporters dan Anda dapat meneruskan beberapa sekaligus, dipisahkan koma. Defaultnya adalah cli.

cli mencetak ringkasan yang dapat dibaca ke terminal. Ini adalah apa yang manusia pindai dalam log build untuk melihat jumlah lulus/gagal dan pernyataan (assertions) mana yang rusak. Biarkan tetap aktif bahkan bersama format mesin agar log tetap berguna.

html menulis laporan HTML mandiri. Arsipkan sebagai artefak build dan buka di browser untuk melihat eksekusi penuh dengan detail permintaan dan respons. Ini adalah format yang Anda berikan kepada seseorang yang tidak memantau pipeline.

junit mengeluarkan XML dalam format JUnit standar. Hampir setiap dasbor CI tahu cara mengurai JUnit XML menjadi pohon lulus/gagal, menampilkan kegagalan di widget permintaan gabungan (merge-request), dan tren hasil seiring waktu. Jika Anda hanya memilih satu format mesin untuk CI, pilih yang ini.

json menghasilkan hasil terstruktur mentah. Gunakan ini ketika Anda ingin memproses hasil sendiri: berikan ke skrip, dorong metrik ke suatu tempat, atau bangun ringkasan kustom.

Kombinasi CI yang umum adalah HTML untuk manusia ditambah JUnit untuk dasbor:

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

Flag laporan yang tersisa mengontrol ke mana keluaran akan ditempatkan dan apa tambahan yang disertakannya:

• --out-dir <dir> mengatur direktori tempat laporan ditulis. Defaultnya adalah ./apidog-reports.
• --out-file <name> mengatur nama file laporan dan menerima placeholder {FOLDER_NAME}, {SCENARIO_NAME}, dan {GENERATE_TIME}, sehingga Anda dapat memberi stempel file dengan nama skenario dan stempel waktu alih-alih menimpa satu file setiap eksekusi.
• --out-json-failures-separated <value> memisahkan kegagalan ke file JSON-nya sendiri, yang memudahkan pembacaan perbedaan yang hanya berisi kegagalan.
• --upload-report [value] mengunggah ikhtisar laporan ke cloud Apidog sehingga eksekusi muncul di riwayat proyek Anda bersama dengan file lokal.

Mengontrol kegagalan: penanganan kesalahan dan kode keluar

Runner hanya berguna dalam pipeline jika memberi tahu pipeline apakah pengujian lulus. apidog run melakukan ini seperti alat baris perintah yang berfungsi dengan baik: ia keluar dengan kode 0 ketika setiap pernyataan (assertion) lulus dan kode bukan nol ketika ada yang gagal. Perilaku tunggal itu adalah seluruh gerbang kualitas. CI membaca kode keluar, menandai langkah gagal, dan memblokir penggabungan atau penyebaran. Anda tidak mengonfigurasi gerbang; kode keluar adalah gerbangnya.

--on-error <behavior> membentuk apa yang terjadi ketika sebuah langkah gagal di tengah skenario, dan ia memiliki tiga nilai:

• end menghentikan eksekusi pada langkah gagal pertama. Gunakan ini untuk smoke test yang cepat gagal di mana Anda menginginkan umpan balik saat ada sesuatu yang rusak.
• continue menjalankan setiap langkah yang tersisa sehingga Anda mengumpulkan semua kegagalan dalam satu laporan. Gunakan ini untuk pemindaian regresi di mana melihat setiap kegagalan sekaligus menghemat waktu.
• ignore memungkinkan eksekusi berlanjut melewati langkah yang diketahui tidak stabil tanpa memperlakukannya sebagai fatal. Gunakan dengan hemat; langkah yang diabaikan seharusnya tidak menyembunyikan regresi nyata.

Bagaimanapun, jika ada pernyataan (assertion) yang gagal, eksekusi masih berakhir dengan kode bukan nol, sehingga gerbang tetap berlaku terlepas dari perilaku yang Anda pilih. Satu hal yang diam-diam merusak gerbang: membungkus perintah dalam sesuatu yang menelan kode keluarnya, seperti menambahkan || true di shell. Jangan lakukan itu. Kode keluar bukan nol adalah intinya.

Empat flag menyetel perilaku permintaan selama eksekusi:

• --ignore-redirects menghentikan runner mengikuti pengalihan HTTP secara otomatis, sehingga Anda dapat membuat pernyataan (assert) pada respons pengalihan itu sendiri.
• --delay-request [n] menunggu n milidetik antar permintaan, yang membantu mengatasi batas laju (rate limit) atau endpoint yang sensitif terhadap beban.
• --timeout-request [n] membatasi berapa lama satu permintaan dapat memakan waktu, dalam milidetik.
• --timeout-script [n] membatasi berapa lama skrip pra- atau pasca-permintaan dapat berjalan, dalam milidetik.

# smoke test: berhenti pada kegagalan pertama
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli --on-error end

# regresi: jalankan semua, kumpulkan semua kegagalan
apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit --on-error continue --out-dir ./nightly-reports

TLS dan sertifikat

Saat Anda menguji endpoint di belakang TLS bersama atau otoritas sertifikat internal, grup ini adalah cara Anda membuat koneksi.

-k, --insecure menonaktifkan verifikasi sertifikat SSL sepenuhnya. Gunakan ini hanya untuk host internal tepercaya dengan sertifikat yang ditandatangani sendiri; jangan pernah mengarahkannya ke apa pun yang bersifat publik, karena ini mematikan pemeriksaan yang melindungi koneksi.

Untuk TLS bersama yang tepat, berikan kredensial klien sebagai gantinya: --ssl-client-cert <path> untuk sertifikat PEM, --ssl-client-key <path> untuk kunci privatnya, dan --ssl-client-passphrase <passphrase> jika kuncinya terenkripsi. Ketika host yang berbeda membutuhkan sertifikat yang berbeda, --ssl-client-cert-list <path> menunjuk ke file konfigurasi yang memetakannya. Dan --ssl-extra-ca-certs <path> menambahkan sertifikat CA tepercaya, yang merupakan perbaikan bersih untuk rantai CA internal yang tidak akan dikenali oleh runner, lebih baik daripada menggunakan -k.

Keluaran dan diagnostik

Grup terakhir mengontrol apa yang dicetak runner dan beberapa detail eksekusi.

--verbose mencetak permintaan dan respons lengkap untuk setiap langkah. Ini adalah langkah pertama Anda ketika skenario lulus secara lokal tetapi gagal di CI: ini menunjukkan byte persis yang dikirim dan diterima oleh runner, sehingga Anda dapat membandingkan dengan apa yang Anda kirim secara manual. --silent melakukan hal sebaliknya, menekan keluaran konsol untuk pekerjaan terjadwal yang bising di mana Anda hanya peduli tentang kode keluar dan laporan yang disimpan. --color <value> memaksa keluaran berwarna aktif atau nonaktif, berguna ketika penampil log CI merusak kode ANSI.

Sisanya adalah untuk fitur skenario tertentu:

• --external-program-path <path> menunjuk ke file program eksternal untuk logika kustom yang dipanggil oleh skenario.
• --database-connection <path> menyediakan konfigurasi basis data untuk skenario dengan langkah-langkah yang mengkueri basis data secara langsung.
• --preferred-http-version <version> mengatur versi protokol HTTP yang disukai oleh runner.
• -b, --bigint mengaktifkan penanganan BigInt agar nilai numerik besar tidak kehilangan presisi.
• --lang <language> mengatur bahasa tampilan CLI.
• -h, --help mencetak teks bantuan, yang merupakan daftar otoritatif untuk versi yang Anda instal.

Merekap: perintah yang benar-benar akan Anda jalankan

Smoke test terhadap produksi tepat setelah deploy, gagal cepat:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e $PROD_ENV_ID -r cli --on-error end

Regresi penuh setiap malam di seluruh folder, setiap kegagalan dalam satu laporan HTML dan JUnit:

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

Eksekusi berbasis data di seluruh CSV, keluaran yang dapat dibaca mesin untuk CI:

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

Validasi perubahan pengujian pada feature branch sebelum digabungkan:

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

Debug kegagalan khusus CI dengan membuang detail wire:

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

Jika Anda menjalankan CLI pada runner CI yang bersifat efemeral dan lebih memilih untuk tidak menginstal secara global, ganti instalasi dengan npx:

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

Itu mencakup antarmuka yang sama. Pilihan antara instalasi global dan npx adalah tentang kebersihan runner, bukan kapabilitas. Untuk menyiapkan skenario yang dijalankan CLI, Unduh Apidog, buat satu skenario di aplikasi, lalu salin perintah yang dihasilkan dari tab CI/CD-nya dan parameterkan tokennya.