Cara Otomatisasi Pengujian API di Travis CI Menggunakan Apidog CLI

API Anda berfungsi di mesin Anda. Unit test berwarna hijau. Anda melakukan merge, deploy, dan satu jam kemudian seorang rekan tim menghubungi Anda: endpoint /checkout mengembalikan kode 500 untuk siapa saja dengan keranjang kosong. Bug tersebut tidak pernah ada di kode yang Anda ubah; itu ada dalam kontrak dua layanan yang tidak ada yang mengujinya kembali. Inilah celah yang diisi oleh tes API tingkat integrasi, dan ini persis jenis pemeriksaan yang Anda inginkan berjalan secara otomatis pada setiap commit, bukan hanya ada di benak seseorang.

Travis CI adalah salah satu layanan integrasi berkelanjutan yang dihosting tertua, dan masih melakukan satu hal dengan baik: ia memantau repositori Git Anda, menyiapkan lingkungan bersih untuk setiap push dan pull request, dan menjalankan perintah apa pun yang Anda masukkan dalam file .travis.yml. Kebanyakan tim menggunakannya untuk siklus kompilasi dan unit test. Jauh lebih sedikit yang menggunakannya untuk menjalankan tes HTTP nyata terhadap API yang sedang berjalan, meskipun di situlah bug-bug mahal bersembunyi. Alasannya adalah gesekan. Menyambungkan test runner API ke dalam kotak CI, meneruskan rahasia dengan aman, dan mendapatkan sinyal lulus/gagal kembali cukup rumit sehingga orang melewatkannya.

Panduan ini membahas cara menutup celah tersebut dengan runner baris perintah Apidog. Anda mendesain dan men-debug tes API Anda di aplikasi desktop Apidog, tempat Anda dapat melihat permintaan dan pernyataan secara visual, lalu menjalankan tes yang persis sama tanpa antarmuka grafis di dalam Travis CI dengan satu perintah. Tidak ada penulisan ulang logika tes sebagai kode, tidak ada pemeliharaan harness tes terpisah. Artikel ini mencakup jalur lengkap: file .travis.yml minimal, menginstal runner, meneruskan token akses Anda dengan aman, memilih apa yang akan dijalankan, menghasilkan laporan, dan membuat build gagal secara jelas ketika sebuah endpoint rusak. Unduh Apidog jika Anda ingin mengikuti.

Mengapa menjalankan tes API di CI sama sekali

Unit test mengkonfirmasi bahwa sebuah fungsi mengembalikan nilai yang benar. Tes API mengkonfirmasi bahwa seluruh siklus permintaan-respons berfungsi: rute ada, otentikasi diberlakukan, kode status benar, skema JSON cocok, dan nilai-nilai di dalam body masuk akal. Ini adalah mode kegagalan yang berbeda, dan jenis kedua adalah yang sebenarnya dialami pengguna Anda.

Menjalankannya secara lokal baik-baik saja sampai tidak. Jalankan lokal bergantung pada Anda mengingat untuk menjalankannya, pada mesin Anda yang cocok dengan konfigurasi produksi, dan pada Anda yang tidak sedang minum kopi ketika sebuah regresi lolos. Integrasi berkelanjutan menghilangkan ketiga alasan tersebut. Setiap push memicu rangkaian yang sama di lingkungan yang sama, dan hasilnya dilampirkan pada commit dan pull request untuk dilihat semua orang.

Ada manfaat yang lebih dalam khusus untuk tim API. Ketika tes Anda hidup berdampingan dengan desain API Anda, perubahan yang merusak muncul sebagai pernyataan yang gagal saat didorong, bukan sebagai tiket dukungan. Jika Anda ingin latar belakang konseptual tentang di mana ini cocok dalam pipeline pengiriman, penjelasan apa itu CI/CD adalah bacaan pelengkap yang bagus; artikel ini tetap berfokus pada build Travis CI yang praktis.

Apa yang Anda butuhkan sebelum memulai

Tiga hal, dan Anda mungkin sudah memiliki dua di antaranya.

• Repositori Git yang terhubung ke Travis CI. Tingkat gratis di travis-ci.com berfungsi untuk repositori publik dan pribadi dalam batas penggunaan.

• Proyek Apidog dengan setidaknya satu skenario pengujian yang sudah Anda buat dan jalankan dengan sukses di aplikasi desktop. Skenario pengujian di Apidog adalah serangkaian permintaan API yang berurutan dengan pernyataan (assertions); anggap saja sebagai satu alur end-to-end, seperti "masuk, buat pesanan, ambil pesanan, hapus."
• Node.js. Apidog CLI berjalan di Node, dan membutuhkan versi 16 atau yang lebih baru. Travis menyediakan Node secara default di lingkungan bahasa node_js, jadi ini sebagian besar adalah deklarasi satu baris.

Jika Anda belum membangun skenario pengujian, lakukan itu terlebih dahulu di aplikasi. Inti dari alur kerja ini adalah Anda men-debug secara visual sekali, lalu mengotomatiskan selamanya. Mencoba membuat pengujian secara "buta" di dalam log CI adalah jalan yang lambat. Untuk dasar-dasar menulis pemeriksaan yang baik, Pernyataan API: panduan praktis mencakup cara memvalidasi kode status, body respons, dan skema JSON sebelum Anda melakukan push.

Langkah 1: Dapatkan token akses dan ID skenario Anda

Apidog CLI menjalankan tes yang disimpan di cloud Anda tanpa antarmuka grafis, jadi dibutuhkan dua bagian identitas:

1. Token akses yang membuktikan runner diizinkan untuk membaca proyek Anda. Buat itu dari pengaturan akun Apidog Anda di bawah token akses. Perlakukan seperti kata sandi; itu memberikan akses API ke data proyek Anda.
2. ID skenario pengujian. Buka skenario di aplikasi desktop dan salin ID-nya, atau gunakan opsi "Jalankan di CI/CD", yang menghasilkan perintah siap pakai dengan ID yang sudah terisi.

Cara termudah untuk mendapatkan perintah pertama yang benar adalah dengan membiarkan Apidog menuliskannya untuk Anda. Di dalam skenario pengujian, opsi jalankan CI/CD menghasilkan sesuatu seperti ini:

apidog run --access-token <your-access-token> -t 5564321 -e 4417023 -r cli

Itulah bentuk lengkapnya: otentikasi, tunjuk skenario (-t), tunjuk lingkungan (-e), dan pilih reporter (-r). Salin itu, konfirmasikan berjalan di laptop Anda sendiri terlebih dahulu, dan baru kemudian pindahkan ke Travis. Memverifikasi secara lokal menghemat Anda belasan build merah yang dihabiskan untuk men-debug kesalahan penulisan dalam token.

Langkah 2: Simpan token sebagai variabel Travis terenkripsi

Jangan pernah menempelkan token akses Anda ke .travis.yml. File tersebut di-commit ke Git, dan token yang bocor memberikan akses baca kepada siapa pun ke proyek API Anda. Travis memiliki dua opsi aman.

Cara yang bersih adalah variabel lingkungan repositori yang diatur di UI web Travis. Buka pengaturan repositori Anda di Travis, temukan variabel lingkungan, dan tambahkan:

• APIDOG_ACCESS_TOKEN dengan nilai token Anda
• APIDOG_ENV_ID dengan ID lingkungan yang ingin Anda uji

Biarkan toggle "tampilkan nilai di log build" mati agar token tidak pernah tercetak. Travis menyuntikkan ini ke setiap build sebagai variabel lingkungan nyata, dan konfigurasi Anda merujuknya berdasarkan nama. Ini menjaga rahasia sepenuhnya keluar dari repositori, yang merupakan perilaku yang Anda inginkan; jika kontributor mem-fork repo, token Anda tidak ikut serta.

Jika Anda lebih suka semuanya ada di dalam file, Travis juga mendukung variabel terenkripsi melalui CLI-nya:

travis encrypt APIDOG_ACCESS_TOKEN="your-token-here" --add env.global

Ini menulis blob terenkripsi ke dalam .travis.yml yang hanya dapat didekripsi oleh build repositori Anda. Kedua pendekatan berhasil. Jalur UI lebih sederhana untuk kebanyakan tim dan lebih mudah untuk dirotasi ketika token kedaluwarsa.

Langkah 3: Tulis .travis.yml

Berikut adalah konfigurasi lengkap dan minimal yang menginstal Apidog CLI dan menjalankan satu skenario pada setiap push dan pull request:

language: node_js
node_js:
  - "18"

cache:
  npm: true

install:
  - npm install -g apidog-cli

script:
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -r cli

Tiga blok melakukan pekerjaan. language: node_js dengan versi memberi Anda runtime Node yang cukup baru untuk CLI. Langkah install menginstal apidog-cli secara global sehingga perintah apidog ada di path. Langkah script menjalankan tes Anda. Reporter -r cli mencetak ringkasan lulus/gagal yang mudah dibaca langsung ke log Travis, yang akan Anda perhatikan ketika ada sesuatu yang rusak.

Perhatikan ID skenario di-hardcode tetapi rahasia berasal dari variabel lingkungan. Itu pemisahan yang benar: ID tidak sensitif, token sensitif. Commit file ini, push, dan Travis menjalankan tes API Anda secara otomatis. Build hijau pertama adalah saat API Anda mendapatkan jaring pengaman.

Jika Anda memelihara beberapa layanan dan menginginkan model mental bersama di antara para runner, panduan mengotomatiskan tes API di CI/CD menunjukkan pola yang sama yang diterapkan pada platform lain, dan versi GitHub Actions hampir identik dalam semangat jika Anda pernah bermigrasi.

Langkah 4: Buat build gagal ketika sebuah tes gagal

Ini adalah bagian yang dilupakan tim, dan itu diam-diam menggagalkan seluruh latihan. Sebuah pekerjaan CI hanya berguna jika tes yang gagal membuat build menjadi merah. Jika runner keluar dengan nol tidak peduli apa pun, Anda telah membangun printer log yang sangat mahal.

Kabar baik: Apidog CLI sudah melakukan hal yang benar. Ketika sebuah pernyataan (assertion) gagal, proses apidog run keluar dengan kode status bukan nol, dan Travis memperlakukan setiap keluar bukan nol dalam fase script sebagai kegagalan build. Jadi konfigurasi minimal di atas sudah gagal dengan benar secara default. Anda tidak memerlukan tambahan apa pun.

Yang bisa Anda sesuaikan adalah bagaimana jalannya skenario ketika satu permintaan mengalami kesalahan. Flag --on-error mengontrol ini:

• --on-error end menghentikan skenario pada kegagalan pertama. Umpan balik tercepat, output lebih sedikit.
• --on-error continue menjalankan langkah-langkah yang tersisa sehingga Anda melihat setiap kegagalan dalam satu kali jalan.
• --on-error ignore terus berjalan dan tidak membiarkan kesalahan menghentikan eksekusi.

Untuk CI, continue biasanya adalah titik manisnya: Anda ingin gambaran lengkap tentang apa yang rusak tanpa pekerjaan berhenti setelah pernyataan merah pertama, sambil tetap berakhir dengan keluar bukan nol sehingga build gagal. Baris skrip yang masuk akal terlihat seperti ini:

script:
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -r cli --on-error continue

Hindari godaan untuk menambahkan || true ke perintah untuk "membuat build berhasil". Itu menelan kode keluar dan memperkenalkan kembali titik buta yang persis ingin Anda hilangkan.

Langkah 5: Hasilkan dan simpan laporan HTML

Reporter cli baik untuk melihat sekilas, tetapi ketika sebuah build gagal, Anda sering kali menginginkan artefak yang lebih kaya: permintaan mana, pernyataan mana, bagaimana body respons sebenarnya. CLI menghasilkan laporan HTML dengan reporter html, dan Anda dapat menumpuk reporter dalam satu kali jalankan.

script:
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -r cli,html --out-dir ./apidog-reports

-r cli,html mencetak ke log dan menulis file HTML mandiri. --out-dir mengatur di mana laporan disimpan, defaultnya adalah ./apidog-reports. Agar laporan tersebut tetap ada setelah build selesai, deploy ke tempat yang dapat dipublikasikan oleh Travis, seperti bucket S3 atau GitHub Pages, dalam blok deploy. Pola umum:

deploy:
  provider: pages
  skip_cleanup: true
  github_token: $GITHUB_TOKEN
  local_dir: apidog-reports
  on:
    branch: main

Jika Anda lebih memilih untuk tidak mengelola penyimpanan artefak sama sekali, CLI dapat mendorong laporan ke cloud Apidog dengan --upload-report, di mana tim Anda dapat membukanya dari tautan tanpa hosting tambahan. Itu adalah opsi dengan pemeliharaan terendah untuk tim yang terdistribusi.

Langkah 6: Tambahkan lingkungan, data, dan eksekusi matriks

Satu skenario terhadap satu lingkungan adalah awal yang baik. Pipeline nyata tumbuh dalam tiga arah, dan flag CLI memetakan dengan bersih ke masing-masing arah.

• Beberapa lingkungan. Flag -e memilih URL dasar dan variabel lingkungan mana yang akan digunakan. Jalankan skenario yang sama terhadap staging pada setiap push dan terhadap produksi pada build cron malam hari dengan menukar ID lingkungan. Pekerjaan cron Travis dikonfigurasi per repositori di UI pengaturan.
• Eksekusi berbasis data. Flag -d (bentuk panjang --iteration-data) memasukkan file CSV atau JSON ke dalam skenario Anda sehingga berjalan sekali per baris. Beginilah cara Anda mencakup kasus-kasus khusus: input valid, bidang yang hilang, payload berukuran besar, karakter khusus, semuanya dari satu definisi skenario. Pasangkan dengan -n (--iteration-count) ketika Anda menginginkan jumlah pengulangan yang tetap, bukan iterasi berbasis file.

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -d ./test-data.csv -r cli

• Skenario paralel. Matriks build Travis memungkinkan Anda menjalankan beberapa skenario sekaligus di seluruh pekerjaan paralel. Definisikan matriks variabel lingkungan di mana setiap entri membawa ID skenario yang berbeda, dan setiap pekerjaan matriks menjalankan satu skenario. Build hanya akan berwarna hijau ketika semuanya lulus.

env:
  - SCENARIO_ID=5564321   # checkout flow
  - SCENARIO_ID=5564322   # auth flow
  - SCENARIO_ID=5564323   # search flow

script:
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t $SCENARIO_ID -e $APIDOG_ENV_ID -r cli

Seiring bertambahnya rangkaian, mengorganisir skenario ke dalam rangkaian pengujian untuk pengujian API otomatis menjaga matriks tetap mudah dikelola alih-alih menjadi "dinding" ID.

Mengapa ini lebih baik daripada menulis tes secara manual dalam skrip CI Anda

Anda bisa menulis tes API langsung di skrip Travis dengan curl dan jq, atau sebagai eksekusi Newman dari koleksi yang diekspor. Keduanya berfungsi, dan keduanya memburuk seiring waktu.

Pendekatan curl-plus-shell mengubah setiap pernyataan (assertion) menjadi perbandingan string yang rapuh. Memeriksa bidang JSON bersarang menjadi mantra jq; memeriksa skema pada dasarnya tidak mungkin; dan saat API Anda menambahkan bidang, separuh grep Anda perlu ditulis ulang. Anda akhirnya memelihara salinan kedua, yang lebih buruk, dari pengetahuan API Anda di Bash.

Pendekatan collection-runner lebih baik tetapi mengaitkan CI Anda dengan ritual ekspor dan sinkronisasi: edit tes di satu alat, ekspor, commit JSON, berharap tidak menyimpang dari kenyataan. Penyimpangan itu nyata, dan itu adalah sumber keluhan "tes lulus tetapi API rusak". Kami telah menulis tentang mode kegagalan yang tepat ini di mengapa koleksi Postman Anda bukan sumber kebenaran, dan jika Anda menjalankan koleksi di CI hari ini, cara menjalankan koleksi Postman di CI tanpa Newman mencakup jalur migrasi.

Model Apidog menyatukan seluruh siklus. Tes Anda, desain API Anda, lingkungan Anda, dan server mock Anda berada di satu tempat. CLI menjalankan versi langsung dan terkini dari tes tersebut; tidak ada yang perlu diekspor dan tidak ada yang menyimpang. Anda men-debug pernyataan yang tidak stabil secara visual di aplikasi, menyimpan, dan eksekusi CI berikutnya mengambil perubahan. Sumber kebenaran tunggal itu adalah seluruh alasan untuk menggunakan runner yang dibangun khusus daripada tumpukan skrip shell. Jika Anda mengevaluasinya terhadap pengaturan Anda saat ini, rangkuman alternatif Postman terbaik untuk pengujian API menyajikan opsi-opsi tersebut secara berdampingan.

Catatan khusus tentang Travis CI

Travis adalah CI open-source default selama bertahun-tahun, dan banyak repositori lama masih berjalan di atasnya. Jika Anda memulai dari awal pada tahun 2026, perlu diketahui bahwa bidang ini telah bergeser; GitHub Actions, GitLab CI, dan CircleCI sekarang menangani sebagian besar proyek baru, dan perbandingan alat CI/CD terbaik kami merinci di mana setiap alat cocok. Kabar baiknya adalah Apidog CLI dirancang agnostik terhadap platform. Perintah apidog run yang persis sama yang berfungsi di .travis.yml Anda juga berfungsi di langkah GitHub Actions, file .gitlab-ci.yml GitLab, atau tahap Jenkins. Jika Anda beralih dari Travis, tes API Anda ikut serta tanpa perubahan; hanya kunci YAML di sekitarnya yang berbeda. Portabilitas itu adalah manfaat yang senyap namun nyata dari menjaga logika pengujian di luar sintaks khusus CI.

Pertanyaan yang sering diajukan

Apakah saya perlu menginstal aplikasi desktop Apidog di kotak CI? Tidak. Aplikasi desktop adalah untuk mendesain dan men-debug tes. Travis hanya membutuhkan paket npm apidog-cli dan runtime Node 16+, yang sudah disediakan oleh lingkungan bahasa node_js. CLI mengambil dan menjalankan skenario yang disimpan di cloud Anda secara headless.

Di mana saya menemukan token akses dan ID skenario saya? Buat token akses di pengaturan akun Apidog Anda di bawah token akses. ID skenario terlihat di aplikasi desktop pada setiap skenario pengujian; opsi bawaan "Jalankan di CI/CD" juga menghasilkan perintah lengkap dengan ID yang sudah terisi, yang merupakan cara tercepat untuk mendapatkan dasar kerja.

Bagaimana cara menjaga token agar tidak masuk ke repositori saya? Atur sebagai variabel lingkungan repositori di UI web Travis dengan tampilan log build dimatikan, lalu rujuk sebagai $APIDOG_ACCESS_TOKEN dalam konfigurasi Anda. Atau, gunakan travis encrypt untuk menyimpan nilai terenkripsi di .travis.yml. Jangan pernah melakukan commit token mentah.

Apakah build akan benar-benar gagal jika sebuah tes gagal? Ya. Perintah apidog run keluar non-nol ketika sebuah pernyataan (assertion) gagal, dan Travis memperlakukan setiap keluar non-nol dalam fase script sebagai build yang gagal. Jangan hanya menekan kode keluar dengan || true. Gunakan --on-error continue jika Anda ingin setiap kegagalan dilaporkan dalam satu kali eksekusi sambil tetap menggagalkan build.

Bisakah saya menjalankan tes terhadap beberapa lingkungan atau dengan beberapa set data? Ya. Gunakan -e untuk beralih lingkungan (staging pada push, produksi pada cron malam), -d untuk memasukkan file data CSV atau JSON untuk iterasi berbasis data, dan matriks build Travis untuk menjalankan beberapa skenario dalam pekerjaan paralel.

Bisakah saya menggunakan ini jika saya tidak menggunakan Travis CI? Ya. Perintah CLI identik di seluruh platform. Tukar YAML di sekitarnya untuk GitHub Actions, GitLab CI, atau Jenkins dan baris apidog run tetap sama.

Meringkas

Mengintegrasikan tes API ke Travis CI boils down to empat langkah: simpan token akses Anda sebagai variabel terenkripsi, instal apidog-cli di langkah instalasi, jalankan skenario Anda dengan apidog run di langkah skrip, dan biarkan kode keluar non-nol menggagalkan build. Dari sana Anda menambahkan laporan HTML, beberapa lingkungan, iterasi berbasis data, dan matriks paralel seiring pertumbuhan suite Anda.

Alasan untuk melakukannya dengan runner khusus daripada tumpukan panggilan curl adalah sumber kebenaran tunggal. Anda mendesain dan men-debug secara visual, lalu menjalankan versi langsung dari tes yang persis sama pada setiap commit, tanpa langkah ekspor yang dapat menyebabkan ketidaksesuaian. Regresi /checkout Anda tertangkap pada pull request, bukan di produksi.

Bangun skenario pengujian pertama Anda, lalu unduh Apidog dan sambungkan ke push Anda berikutnya. Setelah build pertama berhasil (hijau), setiap commit setelahnya dikirim dengan jaring pengaman.