TL;DR
Menjalankan pengujian ReadyAPI di Jenkins dimungkinkan melalui alat baris perintah testrunner dan plugin SmartBear Jenkins, tetapi ini membutuhkan ReadyAPI untuk diinstal pada agen build dan seringkali melibatkan masalah konfigurasi. Integrasi CI/CD Apidog berfungsi melalui CLI sederhana yang diinstal npm tanpa persyaratan perangkat lunak agen dan tanpa lisensi per-eksekusi.
Pendahuluan
Mengintegrasikan pengujian API ke dalam pipeline CI/CD adalah salah satu hal paling berharga yang dapat dilakukan tim pengujian. Menemukan regresi pada setiap permintaan tarik (pull request), sebelum kode mencapai staging atau produksi, sepadan dengan upaya penyiapannya.
ReadyAPI mendukung integrasi Jenkins melalui dua mekanisme: alat baris perintah testrunner dan plugin resmi SmartBear Jenkins. Keduanya berfungsi, tetapi masing-masing memiliki kompleksitas. Panduan ini membahas cara mengatur ReadyAPI dengan Jenkins, masalah umum yang akan Anda temui, dan bagaimana Apidog menyediakan integrasi pipeline yang sama dengan overhead infrastruktur yang lebih rendah.
Menyiapkan ReadyAPI di Jenkins: pendekatan testrunner
Testrunner adalah mesin eksekusi baris perintah ReadyAPI. Ketika Jenkins perlu menjalankan pengujian ReadyAPI secara headless, ia memanggil testrunner dengan argumen yang menunjuk ke file proyek.
Prasyarat:
ReadyAPI harus diinstal pada setiap agen Jenkins yang menjalankan pengujian API. Ini adalah persyaratan operasional terbesar. Jika Anda memiliki lima agen build dan pengujian ReadyAPI berjalan di salah satu di antaranya, kelima agen tersebut memerlukan ReadyAPI terinstal. Hal ini menciptakan:
- Beban pemeliharaan instalasi saat ReadyAPI diperbarui.
- Pertanyaan lisensi: apakah setiap instalasi agen memerlukan lisensinya sendiri? Kebijakan lisensi CI/CD SmartBear bervariasi berdasarkan kontrak. Konfirmasikan dengan tim akun Anda.
- Ukuran gambar agen yang meningkat dan waktu startup yang lebih lama untuk agen berbasis cloud.
Perintah dasar testrunner:
Di Linux/macOS:
/path/to/ReadyAPI/testrunner.sh \
-r \
-f /path/to/results \
-s "TestSuiteName" \
-c "TestCaseName" \
/path/to/project.xml
Di Windows:
C:\ReadyAPI\testrunner.bat ^
-r ^
-f C:\results ^
-s "TestSuiteName" ^
-c "TestCaseName" ^
C:\projects\project.xml
Flag testrunner utama:
-r: menghasilkan laporan XML yang kompatibel dengan JUnit-f <direktori>: direktori output untuk hasil-s <nama>: jalankan suite pengujian tertentu (hilangkan untuk menjalankan semua)-c <nama>: jalankan kasus pengujian tertentu (hilangkan untuk menjalankan semua)-e <lingkungan>: tentukan lingkungan yang akan digunakan-P <nama>=<nilai>: timpa properti proyek
Langkah pipeline Jenkins:
Dalam Jenkinsfile:
stage('API Tests') {
steps {
sh '''
/opt/readyapi/testrunner.sh \
-r \
-f ${WORKSPACE}/test-results \
-e ${ENVIRONMENT} \
${WORKSPACE}/project.xml
'''
junit 'test-results/*.xml'
}
}
Langkah junit mempublikasikan hasil ke Jenkins sehingga kegagalan muncul di laporan build.
Menggunakan plugin SmartBear Jenkins
SmartBear memelihara plugin Jenkins untuk ReadyAPI yang tersedia dari direktori plugin Jenkins. Plugin ini menyediakan langkah build di UI Jenkins daripada mengharuskan Anda menulis perintah shell secara manual.
Untuk menginstalnya:
- Buka Jenkins > Kelola Jenkins > Manajer Plugin.
- Cari “SmartBear ReadyAPI Functional Testing”.
- Instal dan mulai ulang Jenkins.
Setelah instalasi, Anda mengkonfigurasi jalur instalasi ReadyAPI di pengaturan global Jenkins, lalu menambahkan langkah pengujian ReadyAPI ke tugas build Anda dengan memilih dari dropdown langkah build.
Plugin ini menangani konstruksi argumen untuk Anda dan mengintegrasikan hasil ke dalam pelaporan pengujian Jenkins. Untuk tim yang lebih memilih konfigurasi GUI daripada skrip pipeline Groovy, plugin ini mengurangi waktu penyiapan.
Batasan plugin: Plugin ini terikat pada versi Jenkins dan versi ReadyAPI tertentu. Pembaruan plugin tertinggal di belakang rilis ReadyAPI dan rilis Jenkins. Tim yang menjalankan ReadyAPI terbaru mungkin mengalami masalah kompatibilitas yang memerlukan menunggu pembaruan plugin.
Masalah umum Jenkins + ReadyAPI
Testrunner macet saat startup. ReadyAPI adalah aplikasi Java/Swing. Ketika diluncurkan secara headless di CI, terkadang ia mencoba menginisialisasi komponen GUI. Atur variabel lingkungan DISPLAY atau gunakan argumen JVM -Djava.awt.headless=true jika Anda mengalami hal ini.
Kegagalan validasi lisensi. ReadyAPI memvalidasi lisensinya saat startup. Jika agen CI tidak dapat mencapai server lisensi SmartBear (umum di jaringan perusahaan yang terkunci), pengujian gagal dengan kesalahan lisensi daripada kegagalan pengujian. Anda perlu mengkonfigurasi pengaturan server lisensi mengambang (floating license) atau lisensi offline.
Kesalahan kehabisan memori. Pengaturan heap JVM default di testrunner bersifat konservatif. Suite pengujian besar atau proyek dengan banyak file data mungkin perlu menyesuaikan pengaturan -Xmx. Edit file testrunner.sh atau testrunner.bat untuk meningkatkan heap:
-Xms128m -Xmx1024m
Masalah jalur dengan file proyek. Proyek ReadyAPI mereferensikan file eksternal (sumber data, skema, skrip) menggunakan jalur. Saat berjalan di CI, jalur relatif hanya berfungsi jika direktori kerja diatur dengan benar. Jalur absolut dalam file proyek menyebabkan masalah ketika proyek berpindah antar mesin. Gunakan properti proyek untuk jalur dan atur melalui flag -P saat runtime.
Pengujian berhasil secara lokal tetapi gagal di CI. Seringkali disebabkan oleh perbedaan lingkungan: data yang berbeda dalam file eksternal, nilai variabel lingkungan yang berbeda, atau jalur yang di-hardcode. Gunakan fitur Lingkungan ReadyAPI dengan pemilihan lingkungan eksplisit dalam argumen -e testrunner.
Integrasi Jenkins Apidog: pendekatan yang lebih sederhana
Runner CLI Apidog diinstal melalui npm dan tidak memerlukan aplikasi desktop pada agen build.
Instalasi pada agen Jenkins:
npm install -g apidog-cli
Atau dalam langkah pipeline:
npm ci
# apidog-cli is in devDependencies
Menjalankan pengujian dalam Jenkinsfile:
stage('API Tests') {
steps {
sh '''
apidog run \
--collection ${WORKSPACE}/apidog-collection.json \
--environment staging \
--reporter junit \
--reporter-junit-export ${WORKSPACE}/results/report.xml
'''
junit 'results/report.xml'
}
}
Perbedaan utama dari ReadyAPI:
Tidak ada aplikasi desktop pada agen. CLI Apidog adalah paket Node.js yang ringan. Instal dalam hitungan detik, bukan menit. Tidak ada masalah inisialisasi GUI, tidak ada persyaratan konektivitas server lisensi.
Tidak ada masalah lisensi per-eksekusi. Apidog tidak mengenakan biaya per eksekusi CI. Jalankan siklus pengujian sebanyak yang dibutuhkan pipeline Anda per hari.
Konfigurasi lingkungan melalui variabel lingkungan atau flag. Lewatkan kredensial dan URL dasar sebagai variabel lingkungan langsung dari penyimpanan kredensial Jenkins:
withCredentials([string(credentialsId: 'api-key', variable: 'API_KEY')]) {
sh 'apidog run collection.json -e production --env-var "apiKey=${API_KEY}"'
}
Perbandingan GitHub Actions:
Untuk tim yang juga menggunakan GitHub Actions, pendekatan Apidog sama bersihnya:
- name: Run API tests
run: |
npm install -g apidog-cli
apidog run collection.json --environment staging
env:
API_BASE_URL: ${{ vars.STAGING_URL }}
API_KEY: ${{ secrets.API_KEY }}
Ekuivalen ReadyAPI membutuhkan runner yang di-host sendiri dengan ReadyAPI terinstal atau pembuatan gambar Docker yang kompleks. Keduanya tidak sesederhana itu.
Memigrasi CI/CD dari ReadyAPI ke Apidog
Jika Anda memigrasi suite pengujian Anda dan perlu memperbarui konfigurasi CI/CD Anda secara bersamaan:
- Ekspor definisi API Anda dari ReadyAPI dan impor ke Apidog.
- Instal CLI Apidog pada agen Jenkins Anda.
- Tambahkan langkah pengujian Apidog ke pipeline Anda di samping langkah ReadyAPI yang sudah ada.
- Jalankan keduanya secara paralel. Bandingkan tingkat kegagalan dan cakupan pengujian.
- Hapus langkah ReadyAPI setelah Anda yakin dengan cakupan Apidog.
- Hapus ReadyAPI dari agen build selama penyegaran gambar agen berikutnya.
FAQ
Apakah testrunner ReadyAPI memerlukan lisensi CI terpisah?Kebijakan lisensi SmartBear untuk penggunaan CI/CD bervariasi berdasarkan kontrak. Beberapa perjanjian mencakup hak eksekusi CI/CD dalam lisensi standar; yang lain memerlukan perjanjian terpisah. Periksa kontrak Anda atau hubungi manajer akun SmartBear Anda sebelum berasumsi bahwa eksekusi CI tercakup.
Bisakah pengujian ReadyAPI berjalan di kontainer Docker?Ya, dengan usaha. Anda dapat membuat gambar Docker dengan ReadyAPI terinstal dan menggunakannya sebagai kontainer agen Jenkins. Gambar tersebut besar (ReadyAPI adalah aplikasi desktop) dan memerlukan konfigurasi headless. Ini berfungsi tetapi menambah kompleksitas dibandingkan dengan alat yang dibuat untuk lingkungan CI yang terkontainerisasi.
Apakah Apidog mendukung eksekusi pengujian paralel di Jenkins?Ya. Anda dapat menjalankan beberapa instance CLI Apidog secara paralel dalam tahapan Jenkins, masing-masing menjalankan koleksi atau lingkungan yang berbeda. Eksekusi paralel dikontrol melalui Jenkinsfile Anda, bukan CLI Apidog.
Format laporan pengujian apa yang dihasilkan Apidog untuk Jenkins?CLI Apidog dapat menghasilkan laporan XML JUnit, yang secara native diurai dan ditampilkan Jenkins di bagian hasil pengujian. Formatnya sama dengan yang dihasilkan oleh testrunner ReadyAPI.
Apakah skrip pengujian Apidog berjalan dalam proses yang sama dengan runner CLI?Ya. Skrip pengujian JavaScript dieksekusi dalam proses Node.js CLI Apidog. Tidak ada lingkungan eksekusi skrip terpisah yang perlu dikonfigurasi.
Apakah ada plugin Jenkins resmi Apidog?CLI Apidog berjalan sebagai langkah shell di Jenkins, yang tidak memerlukan plugin khusus. Pendekatan ini lebih sederhana untuk dipelihara daripada integrasi berbasis plugin yang memerlukan pembaruan ketika Jenkins atau Apidog merilis versi baru.
Integrasi Jenkins ReadyAPI berfungsi, tetapi memerlukan manajemen infrastruktur yang signifikan. Untuk tim yang ingin menyederhanakan penyiapan CI/CD mereka sambil mempertahankan cakupan pengujian API yang komprehensif, pendekatan CLI Apidog menghilangkan poin-poin masalah paling umum: persyaratan perangkat lunak agen, dependensi server lisensi, dan konfigurasi lingkungan yang kompleks.