Suite pengujian API Anda hanya berguna jika berjalan sesuai jadwal yang dapat Anda percayai. Koleksi yang Anda picu secara manual hanya akan menangkap bug saat Anda ingat untuk mengklik. Eksekusi setiap malam di mesin yang Anda kendalikan akan menangkapnya pada pukul 2 pagi, sebelum pengguna Anda menyadarinya. Itulah tugas Apidog runner: sebuah layanan yang di-deploy sendiri, diinstal dengan Docker di server Anda sendiri, yang mengeksekusi skenario pengujian terjadwal yang Anda buat di Apidog dan mengirimkan laporannya kembali ke proyek Anda.
Kami telah membahas tiga cara menjadwalkan pengujian di Apidog dalam panduan kami untuk menjadwalkan pengujian API otomatis. Postingan tersebut membandingkan eksekusi cloud, runner, dan CLI pada tingkat tinggi. Postingan ini adalah pembahasan mendalam tentang jalur runner: kapan Anda membutuhkannya, cara mendeploy-nya, cara mengarahkan tugas terjadwal kepadanya, dan bagaimana perbandingannya dengan alternatif lain.
Kapan Anda membutuhkan test runner yang di-host sendiri
Eksekusi cloud memang nyaman, tetapi tiga situasi mendorong tim menuju test runner yang di-host sendiri.
API Anda berada di jaringan pribadi. Lingkungan staging di https://orders.staging.internal:8443 tidak dapat dijangkau dari internet publik. Tidak ada layanan cloud yang bisa mencapainya. Runner yang di-deploy di dalam VPC atau jaringan kantor Anda bisa, karena ia membuat permintaan dari tempat ia berada. Ini adalah alasan yang sama di balik menjalankan server mock yang di-host sendiri di intranet Anda: beban kerja harus berada di tempat akses jaringan tersedia.
Kepatuhan menjaga lalu lintas tetap di dalam perusahaan. Jika tim keamanan Anda melarang payload pengujian dengan data pelanggan realistis keluar dari infrastruktur Anda, eksekusi cloud tidak dapat dilakukan. Dengan runner, permintaan berasal dari server Anda dan langsung mengenai API Anda. Hanya laporan pengujian yang kembali ke Apidog.
Anda menginginkan jadwal yang stabil tanpa tergantung pada laptop mana pun. Pengujian yang dijadwalkan di dalam aplikasi desktop berhenti saat aplikasi ditutup. Pengujian yang terhubung ke CI berjalan saat seseorang mendorong kode. Keduanya tidak memberikan Anda "setiap 6 jam, selamanya, apa pun yang terjadi." Runner di server yang selalu menyala melakukan hal ini.
Jika tidak ada di atas yang berlaku, Anda mungkin tidak memerlukan runner. Eksekusi manual di aplikasi atau CLI di CI akan mencukupi.
Apa itu Apidog runner
Runner yang di-host sendiri adalah layanan otomatisasi yang Anda deploy di server independen. Setelah terhubung ke tim Anda, ia dapat:
- Menjalankan tugas pengujian otomatis terjadwal yang dibuat dari skenario pengujian Apidog Anda
- Mengimpor dokumentasi API sesuai jadwal berulang
- Melayani respons mock yang di-host sendiri
Ini tersedia dalam dua cakupan. Runner umum tingkat tim milik satu tim. Runner tingkat organisasi dapat dibagikan di semua proyek dalam tim organisasi Anda. Deployment bekerja dengan cara yang sama untuk keduanya.
Model mental kuncinya: runner adalah pekerja, bukan salinan proyek Anda. Skenario pengujian, lingkungan, dan assertions Anda tetap ada di Apidog. Runner menerima tugas, mengeksekusinya terhadap jaringan apa pun yang dapat dijangkaunya, dan mengunggah hasilnya. Anggota tim tidak pernah SSH ke dalamnya untuk melihat apa yang terjadi; mereka membuka riwayat eksekusi di aplikasi.
Prasyarat
Periksa ini sebelum Anda melakukan deployment. Mereka berasal langsung dari dokumen lingkungan deployment runner.
Perangkat keras. Minimum 2 inti CPU dan RAM 4 GB; 4+ inti dan 8 GB direkomendasikan jika Anda akan menjalankan tugas secara bersamaan atau memiliki tim yang lebih besar. Sediakan setidaknya 30 GB disk untuk log dan artefak pengujian, 50 GB agar lebih nyaman.
Docker. Host membutuhkan Docker versi 20.10.0 atau yang lebih baru, dengan 20.10.13 direkomendasikan. Jika server baru, ikuti panduan instalasi Docker Engine resmi untuk distribusi Anda terlebih dahulu.
Jaringan. Runner berkomunikasi dengan server Apidog melalui HTTPS di port 443 dan menjaga koneksi WebSocket (WSS) tetap terbuka untuk pengiriman tugas real-time. Ia juga membutuhkan akses keluar ke domain AWS yang digunakan untuk upload laporan, ditambah, tentu saja, jangkauan jaringan ke setiap API yang menjadi target pengujian Anda. Perhatikan arahnya di sini: runner melakukan panggilan keluar. Anda tidak perlu membuka port masuk agar Apidog dapat mencapainya, yang membuat percakapan firewall dengan tim operasi Anda singkat.
Izin dan rencana. Mendeploy runner adalah tindakan sumber daya tim, jadi Anda memerlukan peran tim yang sesuai. Berapa banyak eksekusi tugas terjadwal yang Anda dapatkan tergantung pada tingkatan langganan Anda; periksa halaman harga Apidog untuk batas saat ini per paket.
Langkah 1: dapatkan perintah deployment dari Apidog
Apidog menghasilkan perintah deployment Docker untuk Anda, dengan token autentikasi yang sudah terpasang. Jangan menyalinnya dari postingan blog, termasuk yang ini; token tersebutlah yang mengikat kontainer ke tim Anda.
- Buka Apidog dan buka halaman Beranda Apidog. Jika Anda belum memiliki akun, unduh Apidog secara gratis untuk mengikuti.
- Pilih tim tempat runner seharusnya berada.
- Klik Resources di sisi kanan.
- Klik Deploy General Runner.
Sebuah pop-up menampilkan perintah deployment lengkap. Segera salin: ini berisi token sensitif dan hanya ditampilkan sekali. Perlakukan seperti rahasia CI, bukan cuplikan untuk wiki tim Anda.
Sebelum menyalin, dialog memungkinkan Anda menyesuaikan perintah:
- Sistem Operasi Server: Linux, macOS, atau Windows.
- Varian Gambar: General dilengkapi dengan Node.js 18, Java 21, Python 3, dan PHP 8, sehingga skrip pra/pasca-pemrosesan dalam bahasa-bahasa tersebut berfungsi tanpa pengaturan tambahan. Slim hanya menyertakan Node.js 18 dan menarik lebih cepat. Custom memungkinkan Anda menyediakan Dockerfile Anda sendiri ketika pengujian bergantung pada sertifikat CA internal atau pustaka yang tidak biasa.
- Port Terpapar: petakan satu dengan
-p(misalnya-p 80:4524) jika Anda juga akan menggunakan runner untuk mock yang di-host sendiri. - Direktori Data yang Dipasang: tambahkan pemasangan volume
-vjika skenario pengujian Anda membaca file data lokal, seperti kumpulan data CSV untuk eksekusi berbasis data.
Dokumen runner umum mencakup setiap opsi secara detail.
Langkah 2: jalankan kontainer dan konfirmasi bahwa ia terhubung
SSH ke server target, tempel perintahnya, dan biarkan Docker menarik gambar dan memulai kontainer. Dua catatan operasional yang perlu diatur pada hari pertama:
- Lewatkan
TZsebagai variabel lingkungan (misalnyaTZ=Asia/Singapore) agar "setiap hari jam 02:00" berarti jam 02:00 Anda, bukan default kontainer. - Dari runner versi 2.2.5, gambar menyertakan pengguna `runner` non-root (UID/GID 10001). Jika platform Anda memberlakukan `runAsNonRoot`, atur konteks keamanan sesuai dan konfigurasikan izin volume terlebih dahulu, karena entrypoint tidak dapat chown direktori dalam mode non-root.
Kembali ke Apidog, runner muncul di bawah Resources tim Anda setelah handshake WebSocket selesai, dan anggota tim dapat memilihnya saat membuat tugas. Jika tidak muncul dalam satu menit, periksa log kontainer dengan docker logs dan konfirmasi bahwa host dapat menjangkau server Apidog di port 443; koneksi WSS yang terblokir adalah penyebab umum di jaringan perusahaan yang terkunci.
Anda dapat mendeploy beberapa runner dalam satu tim. Tim sering menyimpan satu di dalam VPC staging dan satu lagi dengan akses baca produksi, lalu memilih per tugas.
Langkah 3: buat tugas terjadwal yang menargetkan runner
Dengan runner daring, penjadwalan adalah formulir, bukan skrip.
- Di proyek Anda, buka modul Tests dan klik Scheduled Tasks. Tugas berada dalam struktur folder, jadi kelompokkan berdasarkan layanan atau lingkungan saat daftar bertambah.
- Buat tugas dan berikan nama yang akan dipahami oleh rekan satu tim dalam enam bulan: "Orders service smoke, staging, every 6h" lebih baik daripada "test1".
- Pilih satu atau lebih skenario pengujian. Per skenario Anda dapat mengatur lingkungan, data pengujian, jumlah iterasi, penundaan antar permintaan, dan apakah akan menyimpan badan permintaan/respons.
- Atur lingkungan dan cakupan variabel. Menerapkan variabel ke semua skenario dalam tugas adalah jalan tengah yang direkomendasikan; cakupan seluruh folder kuat tetapi mudah tersandung.
- Atur Run Cycle: setiap Minggu jam 11 malam, setiap 6 jam, apa pun yang sesuai dengan seberapa cepat Anda perlu tahu ada sesuatu yang rusak.
- Di bawah Runs on, pilih runner yang di-host sendiri berdasarkan nama.
- Konfigurasi notifikasi. Anda dapat memberi peringatan setelah setiap eksekusi atau hanya pada kegagalan. Hanya kegagalan adalah default yang masuk akal; saluran yang penuh dengan tanda centang hijau melatih semua orang untuk mengabaikannya.
Simpan. Dari titik ini, jadwal akan dieksekusi di server Anda terlepas dari apakah ada orang yang membuka aplikasi Apidog atau tidak.
Langkah 4: baca laporan eksekusi di Apidog
Setelah setiap eksekusi, runner secara otomatis mengunggah hasil ke server Apidog. Buka Scheduled Tasks → Run History di aplikasi untuk melihat setiap eksekusi: status berhasil/gagal, hasil per skenario, kegagalan assertion, dan waktu.
Ini adalah keunggulan tersembunyi dari runner dibandingkan dengan pengaturan cron-plus-skrip buatan sendiri. Eksekusi terjadi di infrastruktur Anda, tetapi pelaporan tiba di ruang kerja bersama yang sama tempat pengujian didefinisikan. Ketika eksekusi hari Selasa pukul 02:00 gagal, insinyur QA yang menyelidiki melihat assertion mana yang gagal pada langkah mana, dalam konteks, tanpa perlu mencari file log di server.
Pasangkan notifikasi kegagalan dengan riwayat eksekusi dan Anda memiliki lingkaran pemantauan: peringatan berbunyi, buka laporan, reproduksi langkah yang gagal secara manual di aplikasi terhadap lingkungan yang sama, perbaiki, dan tunggu eksekusi hijau berikutnya.
Runner vs CLI vs cloud: memilih jalur eksekusi
Apidog memberi Anda tiga cara untuk mengeksekusi pengujian di luar klik manual di aplikasi, dan ketiganya memecahkan masalah yang berbeda. Kami telah menulis panduan lengkap jalur CI dalam panduan Aksi GitHub CLI Apidog kami, dan perbandingan di bawah menunjukkan di mana masing-masing cocok.
| Runner yang di-host sendiri | Apidog CLI di CI | Eksekusi cloud | |
|---|---|---|---|
| Pemicu | Jadwal berbasis waktu | Dorongan kode, PR, atau jadwal pipeline | Jalankan dari aplikasi |
| Berjalan di | Server Anda (Docker) | Worker CI Anda | Infrastruktur Apidog |
| Mencapai API intranet | Ya | Ya, jika runner CI berada di dalam jaringan | Tidak |
| Data tetap di dalam perusahaan | Ya, hanya laporan yang keluar | Ya | Tidak |
| Upaya pengaturan | Satu deployment Docker per tim | YAML per pipeline | Tidak ada |
| Laporan | Riwayat eksekusi di Apidog | Output CLI/HTML/JSON, dapat diunggah | Di Apidog |
| Terbaik untuk | Pemeriksaan kesehatan berulang pada API pribadi | Membatasi deployment berdasarkan hasil pengujian | Eksekusi cepat pada API publik |
Jalur-jalur ini saling melengkapi daripada bersaing. Pengaturan umum: CLI membatasi setiap deployment dalam pipeline, sementara runner mengeksekusi suite smoke setiap jam terhadap staging dan regresi penuh setiap malam, menangkap kegagalan yang disebabkan oleh *infrastructure drift* dan kredensial yang kedaluwarsa daripada perubahan kode.
Satu peringatan tentang waktu: sesuai dokumen tugas terjadwal, tugas terjadwal dirancang untuk berjalan pada runner yang di-host sendiri, dengan Apidog Cloud dapat dipilih seiring ketersediaan yang diluncurkan. Jika Anda membutuhkan eksekusi terjadwal hari ini dan tidak bisa menunggu ketersediaan cloud untuk paket Anda, runner adalah jalur yang dapat diandalkan.
FAQ
Apakah saya membutuhkan runner jika saya sudah menggunakan Apidog CLI di CI?
Mereka menjawab pertanyaan yang berbeda. CI memberi tahu Anda "apakah perubahan ini merusak API?" pada waktu push. Runner memberi tahu Anda "apakah API sehat saat ini?" pada siklus tetap, menangkap kegagalan yang disebabkan oleh token kedaluwarsa, dependensi mati, atau *infrastructure drift* tanpa ada komit yang terlampir. Banyak tim menjalankan keduanya; lihat panduan pengaturan pengujian API malam kami untuk setengah bagian pola yang dijadwalkan CI.
Bisakah runner mencapai API intranet?
Ya, dan ini adalah alasan utama keberadaannya. Runner membuat permintaan dari mesin tempat ia di-deploy. Letakkan di dalam VPC atau jaringan kantor Anda dan ia dapat menguji host *.internal yang tidak dapat dipecahkan oleh layanan cloud mana pun. Ia hanya membutuhkan akses HTTPS dan WebSocket keluar ke server Apidog untuk menerima tugas dan mengunggah laporan.
Apa spesifikasi server minimum?
Dua inti CPU, RAM 4 GB, disk 30 GB, dan Docker 20.10.0 atau yang lebih baru. Untuk tim yang menjalankan tugas terjadwal secara bersamaan, pindah ke 4+ inti dan 8 GB. VM kecil atau kotak cadangan di rak kantor keduanya berfungsi; kendalanya adalah uptime, bukan tenaga kuda.
Paket apa yang saya butuhkan untuk tugas terjadwal di runner yang di-host sendiri?
Kuota eksekusi tugas terjadwal bervariasi berdasarkan tingkatan langganan, jadi periksa batas saat ini di halaman harga Apidog sebelum Anda merencanakan jadwal frekuensi tinggi. Jika Anda mengevaluasi opsi eksekusi di berbagai alat, perbandingan Apidog CLI vs Postman CLI kami melihat apa yang disertakan oleh sisi test-runner dari setiap platform.