Anda menulis tes API. Tes tersebut berhasil di mesin Anda. Dan di situlah tes tersebut berada, karena menjalankannya adalah sesuatu yang harus diingat oleh seseorang. Seorang rekan satu tim mengirimkan perubahan pada Jumat sore, endpoint autentikasi diam-diam mulai mengembalikan 500 pada salah satu jalur kode, dan orang pertama yang mengetahuinya adalah pengguna pada hari Senin. Cakupannya ada sepanjang waktu. Tidak ada yang menjalankannya pada saat yang seharusnya dapat menangkap regresi tersebut.
Solusinya adalah memindahkan tes dari editor Anda dan ke dalam pipeline, sehingga tes berjalan pada setiap push tanpa campur tangan manusia. Itu berarti Anda memerlukan perintah yang menjalankan tes API Anda secara headless, mengembalikan status berhasil atau gagal yang jelas, dan masuk ke sistem CI apa pun yang sudah Anda gunakan. Apidog CLI melakukannya. Anda membangun skenario tes secara visual di Apidog, kemudian menjalankannya dari satu perintah terminal yang dapat dieksekusi oleh runner CI apa pun dengan Node.js. Tanpa GUI, tanpa menulis ulang tes sebagai kode, tanpa layanan tambahan untuk di-hosting.
Ini adalah panduan salin-tempel. Di bawah ini Anda akan menemukan file pipeline siap pakai untuk GitHub Actions, GitLab CI, Jenkins, CircleCI, dan Azure Pipelines, ditambah beberapa pola yang menjaga build tetap jujur. Ambil blok untuk platform Anda, ganti ID dan rahasia Anda, dan Anda akan memiliki tes API yang menjaga setiap penggabungan pada akhir hari. Jika Anda menginginkan referensi flag yang lengkap, topik yang lebih luas tentang cara mengotomatiskan tes API di CI/CD mencakup strateginya; halaman ini adalah tentang cara membuat pipeline yang berfungsi.
Apa yang Anda sambungkan
Apidog CLI adalah paket npm, apidog-cli. Ini menjalankan skenario tes yang Anda buat di aplikasi Apidog: permintaan berantai, pernyataan, nilai yang diambil dari satu respons ke yang berikutnya, iterasi berbasis data. CLI tidak membuat format tesnya sendiri. Ia menjangkau proyek Anda, menemukan skenario berdasarkan ID, menjalankannya dengan cara yang sama seperti aplikasi, dan melaporkan hasilnya dengan kode keluar.
Kode keluar itulah intinya. Ketika setiap pernyataan berhasil, eksekusi keluar dengan `0`. Ketika ada yang gagal, eksekusi keluar dengan nilai bukan nol. Sistem CI membaca kode keluar itu, menandai langkah gagal, dan memblokir penggabungan atau penyebaran. Anda tidak mengkonfigurasi gerbang; gerbangnya adalah kode keluar. Selama langkah `apidog run` ada di pipeline Anda, pernyataan yang rusak akan menghentikan baris.
Tiga hal membuat eksekusi berjalan, dan Anda akan melihatnya di setiap blok di bawah ini:
- Token akses, yang membuktikan bahwa eksekusi diizinkan untuk menjalankan skenario Anda. Perlakukan seperti kata sandi. Simpan sebagai rahasia CI, jangan pernah dalam file yang dikomit.
- ID skenario (atau ID folder, atau ID rangkaian tes), yang menyatakan apa yang harus dijalankan.
- ID lingkungan, yang menyatakan di mana harus menjalankannya: dev, staging, atau produksi.
Anda tidak mengetik ID tersebut secara manual. Buka skenario tes di Apidog, beralih ke tab CI/CD, pilih opsi baris perintah, dan hasilkan token akses. Apidog memberikan Anda perintah apidog run lengkap dengan ID skenario dan ID lingkungan yang sudah terisi. Salin sekali, lalu pindahkan token ke rahasia. Jika Anda belum membangun skenario, mulailah dengan cara menulis skenario tes dengan Apidog dan kembali lagi setelah Anda memiliki satu skenario yang berhasil.
Satu perintah yang menjadi dasar segalanya
Inilah jalannya kanonis. Setiap file pipeline adalah pembungkus di sekitar baris ini:
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t 605067 \
-e 1629989 \
-n 1 \
-r html,junit \
--out-dir ./apidog-reports
Fungsi setiap bagian:
--access-tokenmengautentikasi eksekusi. Ini membaca dari variabel lingkungan$APIDOG_ACCESS_TOKEN, yang Anda isi dari rahasia.-t 605067menjalankan skenario tes dengan ID tersebut. Ganti-tdengan-f <folderId>untuk menjalankan seluruh folder, atau--test-suite <id>untuk menjalankan rangkaian tes yang telah dikurasi.-e 1629989menargetkan suatu lingkungan. Ini adalah cara skenario yang sama menyerang staging dalam pemeriksaan PR dan produksi dalam pengujian smoke pasca-deploy.-n 1menjalankan skenario sekali. Tingkatkan untuk mengulang, atau pasangkan dengan-d <file>untuk mendorong iterasi dari file data CSV atau JSON.-r html,junitmemilih format laporan.junitmengeluarkan XML yang dianalisis oleh dasbor CI Anda menjadi pohon berhasil/gagal;htmladalah laporan yang dapat dijelajahi yang Anda simpan sebagai artefak build. Tambahkanclijika Anda juga menginginkan output yang mudah dibaca di log.--out-dir ./apidog-reportsadalah tempat laporan disimpan.
Pelapor adalah perbedaan antara “build menjadi merah” dan “ini adalah pernyataan yang gagal dan respons yang memecahkannya.” JUnit XML adalah salah satu yang dipahami secara native oleh hampir setiap platform, jadi itu muncul di semua lima blok di bawah ini.
GitHub Actions
Masukkan ini di .github/workflows/api-tests.yml. Ini menjalankan skenario Anda pada setiap permintaan pull terhadap main, mengunggah laporan sebagai artefak, dan menggagalkan pemeriksaan jika ada pernyataan yang gagal.
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
Dua detail penting. Token berada di Settings → Secrets and variables → Actions sebagai APIDOG_ACCESS_TOKEN dan mencapai langkah melalui env:. Dan if: always() pada langkah upload berarti Anda masih mendapatkan laporan saat tes gagal, yang merupakan satu-satunya saat Anda benar-benar perlu membacanya. Jika skenario rusak, langkah apidog run keluar non-nol, pekerjaan menjadi merah, dan PR menunjukkan pemeriksaan yang gagal. Untuk panduan lebih lanjut tentang platform ini secara spesifik, lihat cara mengotomatiskan tes API di GitHub Actions.
GitLab CI
Ide yang sama di .gitlab-ci.yml. Image node:20 sudah memiliki runtime, jadi satu-satunya pengaturan adalah instalasi.
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
Simpan APIDOG_ACCESS_TOKEN di bawah Settings → CI/CD → Variables sebagai variabel yang disamarkan dan dilindungi agar tidak pernah tercetak di log. Blok reports: junit: adalah bagian yang cenderung dilewatkan oleh pengguna GitLab: ini memberi tahu GitLab untuk mengurai XML dan menampilkan hasil langsung di widget permintaan penggabungan. Peninjau melihat pernyataan mana yang gagal tanpa mengunduh apa pun.
Jenkins
Untuk pipeline deklaratif, simpan token sebagai kredensial Jenkins dan tarik ke dalam lingkungan, lalu panggil CLI dalam sebuah tahap. Blok post memasukkan JUnit XML ke dalam grafik tren tes Jenkins dan menyimpan laporan HTML pada build.
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 yang di-cache, hapus baris npm install dan panggil apidog run secara langsung. Apidog juga menyediakan panduan integrasi khusus Jenkins jika Anda menginginkan rute plugin daripada langkah shell: integrasikan pengujian otomatis Apidog dengan Jenkins untuk CI/CD.
CircleCI
Dalam .circleci/config.yml, gunakan image Node convenience dan simpan token sebagai variabel lingkungan proyek di bawah Project Settings → Environment Variables.
version: 2.1
jobs:
api-tests:
docker:
- image: cimg/node:20.11
steps:
- checkout
- run:
name: Install Apidog CLI
command: npm install -g apidog-cli
- run:
name: Run API test scenario
command: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067 \
-e 1629989 \
-r junit,cli \
--out-dir ./apidog-reports
- store_test_results:
path: ./apidog-reports
- store_artifacts:
path: ./apidog-reports
destination: apidog-reports
workflows:
test:
jobs:
- api-tests
store_test_results adalah setara CircleCI dengan blok JUnit GitLab; arahkan ke direktori laporan dan CircleCI akan menampilkan pernyataan yang gagal di tab Tes-nya. store_artifacts menyimpan laporan HTML yang terlampir sehingga Anda dapat membukanya dari halaman build.
Azure Pipelines
Dalam azure-pipelines.yml, instal Node dengan task, jalankan CLI, dan publikasikan hasil JUnit. Tambahkan APIDOG_ACCESS_TOKEN sebagai variabel rahasia di pipeline (atau tarik dari grup variabel Azure Key Vault), lalu petakan ke env langkah skrip.
trigger:
- main
pool:
vmImage: ubuntu-latest
steps:
- task: NodeTool@0
inputs:
versionSpec: '20.x'
displayName: 'Install Node.js'
- script: npm install -g apidog-cli
displayName: 'Install Apidog CLI'
- script: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067 \
-e 1629989 \
-r junit,html \
--out-dir ./apidog-reports
displayName: 'Run API test scenario'
env:
APIDOG_ACCESS_TOKEN: $(APIDOG_ACCESS_TOKEN)
- task: PublishTestResults@2
condition: always()
inputs:
testResultsFormat: 'JUnit'
testResultsFiles: 'apidog-reports/*.xml'
testRunTitle: 'Apidog API tests'
Makro $(APIDOG_ACCESS_TOKEN) membaca variabel pipeline rahasia; memetakannya melalui env menjauhkannya dari baris perintah yang terlihat. PublishTestResults@2 dengan condition: always() membuat hasil muncul di tab Tes apakah eksekusi berhasil atau gagal. Untuk perlakuan yang lebih lengkap tentang platform ini, Apidog memiliki panduan khusus tentang pengujian API pipeline Azure DevOps.
Pola yang menjaga gerbang tetap jujur
Pipeline yang menjalankan tes Anda adalah dasar. Resep-resep ini adalah yang membuatnya berguna sehari-hari.
Uji smoke segera setelah deploy. Jalankan satu skenario cepat terhadap produksi saat rilis mendarat, arahkan ke lingkungan produksi, dan berhenti pada kegagalan pertama:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e <prodEnvId> -r cli --on-error end
Regresi penuh semalaman. Jalankan seluruh folder skenario sesuai jadwal dan kumpulkan setiap kegagalan ke dalam satu laporan alih-alih berhenti pada yang pertama:
apidog run --access-token $APIDOG_ACCESS_TOKEN -f <folderId> -r html,junit --on-error continue --out-dir ./nightly-reports
--on-error adalah kenop di sini. end gagal dengan cepat, yang Anda inginkan untuk gerbang deploy. continue menjalankan setiap langkah sehingga laporan malam menunjukkan semua kerusakan sekaligus. Bagaimanapun, eksekusi masih keluar non-nol jika ada yang gagal, jadi gerbang tetap berlaku.
Jalankan satu skenario dengan banyak input. Dorong iterasi dari file data dan perlakukan setiap baris sebagai pass-nya sendiri:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./test-data.csv -r junit
Uji branch fitur, bukan main. Jalankan skenario persis seperti yang ada di branch:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 --branch feature-payments -e 1629989 -r cli
Debug kegagalan khusus CI. Ketika skenario berhasil secara lokal tetapi gagal di pipeline, tambahkan --verbose. Ini mencetak permintaan yang persis dikirim oleh runner dan respons yang persis diterimanya, yang hampir selalu menjadi cara Anda menemukan perbedaan lingkungan yang menyebabkan celah tersebut.
Ketika build berbohong kepada Anda
Beberapa mode kegagalan cukup sering muncul untuk disebutkan, karena masing-masing diam-diam mengalahkan gerbang.
Build tetap hijau padahal tes seharusnya gagal. Ini adalah yang berbahaya. Hampir selalu berarti kode keluar ditelan. Jika Anda membungkus perintah dalam pipeline shell, atau menambahkan || true untuk "menghentikannya agar tidak merusak build", Anda juga menghentikannya untuk tidak menangkap apa pun. Hapus apa pun yang menyamarkan exit non-nol. Langkah apidog run harus menjadi hal yang dibaca oleh langkah CI.
Kesalahan autentikasi. Token salah, kedaluwarsa, atau tidak mencapai perintah. Pastikan rahasia CI benar-benar terisi (echo yang disamarkan dari panjangnya, bukan nilainya), dan hasilkan kembali dari tab CI/CD skenario jika perlu.
"Skenario tidak ditemukan." ID skenario, ID proyek, atau branch tidak sesuai. Salin ulang perintah dari tab CI/CD sehingga ID terjamin terkini, dan periksa kembali --branch menunjuk ke tempat yang Anda kira.
Berhasil secara lokal, gagal di CI. Hampir selalu ada perbedaan lingkungan. Runner mungkin menargetkan lingkungan -e yang berbeda, berada di balik firewall yang tidak dapat menjangkau host Anda, atau tidak memiliki variabel yang dibutuhkan skenario. Jalankan dengan --verbose dan bedakan permintaan yang dihasilkan runner dengan yang Anda kirim secara lokal.
Kegagalan TLS terhadap host internal. Jika endpoint Anda menggunakan CA internal, berikan sertifikat CA tambahan daripada menonaktifkan verifikasi. Gunakan -k (lewati verifikasi SSL) hanya sebagai upaya terakhir pada host internal tepercaya dengan sertifikat yang ditandatangani sendiri, jangan pernah terhadap apa pun yang bersifat publik.
Mengapa membangun secara visual dan menjalankan secara headless
Ada pilihan desain nyata di balik semua ini, dan itu patut mendapat satu paragraf. Dengan runner yang berbasis skrip, tes dan eksekusinya adalah file yang sama, sehingga skrip yang rapuh adalah tes sekaligus hambatan Anda. Dengan Apidog, skenario dalam proyek Anda adalah tes, dan CLI hanya menjalankannya di tempat yang tidak dapat dilakukan oleh manusia. Tidak ada yang mempertahankan dua representasi dari pemeriksaan yang sama. Anda menulis dengan cepat di pembangun visual, Anda menjalankannya secara otomatis di pipeline, dan keduanya tetap sinkron karena merupakan artefak yang sama. Itu adalah bagian besar mengapa tim memperlakukan Apidog sebagai alternatif Postman untuk pengujian API setelah CI masuk, dan mengapa pernyataan API yang solid lebih penting daripada runner yang membungkusnya.
Siklusnya sederhana setelah berjalan. Rancang dan debug permintaan dalam aplikasi. Rantai mereka menjadi skenario dengan pernyataan. Dorong kode Anda, dan CLI menjalankan skenario itu di CI pada setiap perubahan. Ketika ada yang rusak, laporan menyebutkan pernyataan dan kode keluar menghentikan deploy. Anda memperbaikinya, dorong lagi, dan gerbang yang sama mengkonfirmasi perbaikan.
Jika tes Anda masih ada di editor seseorang, itulah celah yang harus ditutup minggu ini. Unduh Apidog, buat satu skenario berhasil, salin perintah apidog run dari tab CI/CD-nya, dan tempelkan blok di atas untuk platform Anda. Anda akan memiliki tes API yang menjaga setiap penggabungan pada sore hari yang sama.
Pertanyaan yang Sering Diajukan
Apakah Apidog CLI gratis digunakan di CI? CLI adalah paket npm gratis: npm install -g apidog-cli. Ini menjalankan skenario dari proyek Apidog Anda, jadi apa yang dapat Anda jalankan tergantung pada paket Apidog Anda, tetapi runner baris perintah itu sendiri bukan produk berbayar terpisah.
Apakah saya harus menulis ulang tes saya sebagai kode? Tidak. Anda membuat skenario secara visual di Apidog dan CLI menjalankannya berdasarkan ID. Skenario adalah tesnya; CLI hanyalah pelaksana. Itulah hal utama yang membedakannya dari runner yang berbasis skrip.
Bagaimana tes yang gagal benar-benar menggagalkan build saya? Melalui kode keluar. Ketika ada pernyataan yang gagal, apidog run keluar dengan nilai bukan nol. Sistem CI Anda membaca itu, menandai langkah gagal, dan memblokir penggabungan atau deploy. Anda tidak menambahkan konfigurasi tambahan agar gerbang berfungsi.
Format laporan mana yang harus saya gunakan? Gunakan junit untuk XML yang dapat dibaca mesin yang diuraikan oleh dasbor CI Anda menjadi hasil berhasil/gagal, dan tambahkan html jika Anda menginginkan laporan yang dapat dijelajahi yang disimpan sebagai artefak build. Pasangan yang umum adalah -r junit,html. Tetap aktifkan cli juga jika Anda menginginkan output yang mudah dibaca di log build.
Apakah saya perlu menginstal Apidog di server CI? Tidak. Runner CI hanya membutuhkan Node.js (v16 atau lebih baru) dan paket apidog-cli. Tidak ada aplikasi desktop, tidak ada GUI, tidak ada file lisensi di server. Paket ditambah token akses sudah cukup.
Bisakah saya menjalankannya tanpa instalasi global? Ya. Gunakan npx apidog-cli run ... untuk mengeksekusinya tanpa instalasi global yang persisten, yang lebih bersih pada runner sementara yang dihilangkan setelah setiap pekerjaan.
Apa bedanya dengan Newman? Newman menjalankan koleksi Postman dari baris perintah. Apidog CLI menjalankan skenario tes Apidog. Peran-peran ini paralel, tetapi runner Apidog mengeksekusi skenario yang Anda buat di aplikasi dan dikirim sebagai satu paket apidog-cli. Lihat Postman CLI vs Newman untuk sisi Postman dari perbandingan itu.
Dari mana saya mendapatkan token akses dan ID? Semuanya dari tab CI/CD skenario tes di Apidog. Pilih opsi baris perintah, hasilkan token akses, dan salin perintah apidog run lengkap yang dibuat Apidog dengan ID skenario dan lingkungan yang sudah terisi. Kemudian pindahkan token ke rahasia CI dan referensikan sebagai $APIDOG_ACCESS_TOKEN.