Pengujian Beban Artillery: Panduan Praktis untuk API

Artillery adalah toolkit pengujian beban sumber terbuka berbasis Node.js yang mendorong lalu lintas konkurensi tinggi ke API Anda dari skrip YAML sederhana. Anda menentukan fase beban dan alur permintaan, menjalankan artillery run script.yml, dan membaca kembali persentil latensi, laju permintaan, dan jumlah kesalahan. Panduan ini akan memandu Anda menginstal Artillery v2, menulis skrip pengujian nyata, menjalankannya, menangkap hasilnya dengan cara v2 saat ini, dan menyambungkannya ke CI.

Apa itu Artillery dan Kapan Menggunakannya

Artillery menghasilkan pengguna virtual (VUs) yang mencapai titik akhir Anda dan mengukur seberapa baik sistem bertahan di bawah lalu lintas berkelanjutan. Pengguna virtual adalah klien simulasi yang menjalankan skenario, satu permintaan demi satu, seperti yang akan dilakukan oleh pemanggil nyata.

Anda menggunakan Artillery ketika Anda membutuhkan jawaban untuk pertanyaan skala. Bagaimana perilaku latensi p95 pada 50 permintaan per detik? Pada tingkat kedatangan berapa kesalahan mulai muncul? Apakah API tetap stabil selama lima menit beban berkelanjutan, ataukah kinerjanya menurun?

Artillery bagus dalam hal ini karena pengujiannya bersifat deklaratif. Anda menjelaskan bentuk beban dalam YAML, bukan mengodekan secara manual sebuah loop konkurensi. Ini berjalan di mana pun Node.js berjalan, jadi skrip yang sama berfungsi di laptop Anda dan di CI.

Artillery adalah salah satu dari beberapa opsi di bidang ini. Jika Anda masih membandingkan alat, rangkuman alat pengujian beban terbaik dan perbandingan perangkat lunak pengujian beban ini mencakup pertimbangan di antara k6, JMeter, Gatling, dan lainnya.

Instal Artillery (v2)

Nama paketnya persis artillery, dan versi utama saat ini adalah v2. Instal secara global dengan npm, lalu verifikasi versinya.

npm install -g artillery@latest
artillery version

Anda memerlukan rilis LTS Node.js terbaru. Artillery berjalan di Windows, macOS, dan Linux.

Jika Anda tidak ingin menginstal apa pun secara global, jalankan sesuai permintaan dengan npx.

npx artillery@latest run script.yml

Menulis Skrip Pengujian Artillery

Pengujian Artillery adalah file YAML dengan dua bagian tingkat atas. Bagian config mendefinisikan target dan profil beban. Bagian scenarios mendefinisikan apa yang dilakukan setiap pengguna virtual.

Berikut adalah skrip lengkap yang melakukan pemanasan, meningkat ke puncak, lalu menahan beban berkelanjutan.

config:
  target: "https://api.example.com"
  phases:
    - name: "Warm up"
      duration: 60
      arrivalRate: 5
    - name: "Ramp to peak"
      duration: 120
      arrivalRate: 5
      rampTo: 50
    - name: "Sustained load"
      duration: 300
      arrivalRate: 50
      maxVusers: 500
  # Inline variables (or use a CSV via config.payload)
  variables:
    productId:
      - "1001"
      - "1002"

scenarios:
  - name: "Browse and create order"
    flow:
      - get:
          url: "/v1/products/{{ productId }}"
      - post:
          url: "/v1/orders"
          json:
            productId: "{{ productId }}"
            quantity: 2

Memahami bagian config

config.target adalah host dasar tempat setiap permintaan dijalankan. Setiap langkah dalam skenario menambahkan url-nya ke dasar ini.

config.phases adalah larik fase beban yang berjalan secara berurutan. Kunci yang paling sering Anda gunakan:

duration: berapa lama fase berlangsung, dalam detik atau string yang mudah dibaca seperti "5m".
arrivalRate: berapa banyak pengguna virtual baru yang mulai setiap detik.
rampTo: meningkatkan laju kedatangan secara linier dari arrivalRate hingga nilai ini sepanjang fase.
arrivalCount: jumlah VU tetap yang tersebar di seluruh fase, bukan laju per detik.
maxVusers: batas berapa banyak pengguna virtual yang dapat berjalan secara bersamaan.
name: label yang muncul di output.

Satu detail yang sering membingungkan orang. duration suatu fase mengontrol berapa lama Artillery terus memunculkan pengguna virtual, bukan total waktu jam dinding pengujian. Jika VU dimulai mendekati akhir suatu fase dan skenarionya membutuhkan waktu cukup lama, eksekusi akan berlanjut sampai pengguna tersebut selesai.

Memahami bagian skenario

scenarios adalah larik. Setiap skenario memiliki flow, yaitu daftar langkah berurutan yang dijalankan oleh pengguna virtual. Kunci opsional meliputi name dan weight, di mana weight mengatur probabilitas relatif Artillery memilih skenario ini untuk VU tertentu.

Langkah-langkah flow menggunakan kunci kata kerja HTTP: get, post, put, delete, dan patch. Masing-masing mengambil url, dan badan permintaan berada di bawah json. Sintaks kurawal ganda, {{ productId }}, mengambil variabel.

Mendorong permintaan dari file CSV

Mengkodekan nilai secara langsung baik untuk pengujian asap (smoke test). Untuk beban realistis, masukkan data dari CSV dengan config.payload. Setiap pengguna virtual memilih satu baris, dan nama kolom menjadi variabel.

config:
  target: "https://api.example.com"
  payload:
    path: "./users.csv"
    fields:
      - "email"
      - "password"
  phases:
    - duration: 120
      arrivalRate: 20
scenarios:
  - flow:
      - post:
          url: "/login"
          json:
            email: "{{ email }}"
            password: "{{ password }}"

Menjalankan Pengujian

Perintah dasar mengarahkan Artillery ke skrip Anda.

artillery run script.yml

# Ganti target tanpa mengedit skrip:
artillery run --target https://staging.example.com script.yml

# Teruskan variabel sebagai JSON:
artillery run -v '{ "productId": ["1001","1002"] }' script.yml

Beberapa flag layak diketahui. --target (atau -t) mengganti config.target sehingga Anda dapat mengarahkan skrip yang sama ke staging atau produksi. --environment (atau -e) memilih blok bernama di bawah config.environments. --config (atau -c) memuat konfigurasi dari file terpisah. --insecure (atau -k) melewati verifikasi TLS untuk sertifikat yang ditandatangani sendiri di lingkungan pengujian.

Membaca Hasil

Selama pengujian berjalan, Artillery mencetak metrik agregat kira-kira setiap 10 detik. Setelah selesai, Anda akan mendapatkan laporan ringkasan. Angka-angka yang paling penting:

Laju permintaan: permintaan per detik yang sebenarnya dicapai oleh eksekusi.
Persentil latensi: p50 (median), p95, dan p99 waktu respons. p95 memberi tahu Anda pengalaman 5 persen permintaan paling lambat, yang biasanya merupakan tempat masalah pertama kali muncul.
Jumlah kesalahan: permintaan yang gagal, waktu habis (timeouts), dan respons non-2xx, dikelompokkan berdasarkan jenis.

Perhatikan latensi ekor, bukan hanya rata-ratanya. Rata-rata bisa terlihat sehat sementara p99 secara diam-diam naik ke wilayah multi-detik. Jika kesalahan muncul hanya selama fase berkelanjutan, Anda kemungkinan telah menemukan titik saturasi yang patut diselidiki. Untuk penjelasan yang lebih mendalam tentang metrik mana yang harus dilacak dan mengapa, lihat panduan pengujian kinerja API ini.

Membuat Laporan di Artillery v2

Pelaporan berubah di seluruh versi Artillery, jadi di sinilah tutorial usang akan menyesatkan Anda. Panduan lama memberitahu Anda untuk menjalankan artillery run --output report.json dan kemudian artillery report report.json untuk menghasilkan file HTML. Paruh pertama masih berfungsi. Paruh kedua tidak.

Flag --output masih menulis file hasil JSON yang dapat dibaca mesin.

# Tulis hasil JSON yang dapat dibaca mesin (masih didukung):
artillery run --output report.json script.yml

Perintah artillery report, generator JSON ke HTML, telah dihapus dari Artillery CLI. Dokumen resmi menyatakan bahwa itu "tidak lagi didukung dan telah dihapus dari Artillery CLI." Kode pelaporan HTML tidak terawat, didepresiasi, lalu dihapus, tanpa rencana untuk mengembalikannya. Jangan menulis artillery report report.json; itu tidak akan berfungsi pada v2 saat ini.

Anda memiliki tiga opsi saat ini sebagai gantinya.

Pertama, uraikan JSON sendiri. Ini ideal untuk CI, di mana Anda ingin menegaskan terhadap ambang batas. Ambil latensi p95 agregat dengan jq:

jq '.aggregate.summaries["http.response_time"].p95' report.json

Kedua, gunakan Artillery Cloud untuk dasbor yang di-host. Ini adalah pengganti resmi untuk laporan HTML lama. Berikan --record dengan kunci API Anda.

artillery run --record --key $ARTILLERY_CLOUD_API_KEY script.yml

Ketiga, dorong metrik ke tumpukan pemantauan Anda sendiri dengan plugin publish-metrics atau OpenTelemetry, sehingga latensi dan tingkat kesalahan muncul di dasbor yang sama yang sudah Anda gunakan untuk produksi.

Menjalankan Artillery di CI

Karena Artillery hanyalah CLI Node.js, ia dapat disisipkan ke dalam pipeline apa pun. Berikut adalah alur kerja GitHub Actions yang menginstal Artillery, menjalankan pengujian, dan mengunggah laporan JSON sebagai artefak build.

name: Load test
on: [workflow_dispatch]
jobs:
  artillery:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "lts/*"
      - run: npm install -g artillery@latest
      - run: artillery run --output report.json script.yml
      - uses: actions/upload-artifact@v4
        with:
          name: artillery-report
          path: report.json

Contoh ini berjalan berdasarkan pemicu manual. Uji beban berat biasanya dipicu sesuai permintaan atau sesuai jadwal daripada setiap commit, karena membutuhkan waktu beberapa menit dan mengonsumsi bandwidth nyata. Setelah laporan JSON ada, Anda dapat menambahkan langkah jq yang membuat job gagal jika p95 melebihi anggaran Anda.

Di Mana Apidog Cocok: Pengujian Fungsional dan Pintu Gerbang CI

Artillery menjawab "bisakah API bertahan dari lalu lintas sebanyak ini?" Itu adalah pengujian beban dan kinerja. Pertanyaan yang berbeda berjalan bersamanya: "apakah API masih mengembalikan respons yang benar setelah perubahan kode ini?" Itu adalah pengujian fungsional dan regresi, dan di sinilah Apidog cocok.

Apidog adalah platform API lengkap untuk desain, debugging, mocking, dokumentasi, dan pengujian otomatis. Skenario pengujiannya mengelompokkan titik akhir menjadi langkah-langkah logis dengan kondisi seperti if, for, dan foreach, sehingga Anda dapat memvalidasi badan respons, kode status, dan kontrak. Anda menjalankan skenario tersebut di CI dengan Apidog CLI untuk mencegah penggabungan setelah perubahan kode.

Jelaskan batasnya dengan jelas. Apidog memang menyertakan fitur pengujian kinerja, tetapi dibatasi hingga 100 pengguna virtual. Itu cukup untuk mendeteksi regresi yang jelas, dan itu bukan pengganti Artillery pada konkurensi tinggi. Untuk beban terdistribusi, dimodelkan kode dalam skala besar, Artillery adalah alat yang tepat. Pembingkaian jujur yang sama ini muncul dalam tulisan kami tentang pengujian beban API tanpa Python, dan mekanisme fitur 100-VU Apidog dibahas dalam pengujian kinerja API di Apidog.

Jadi gunakan keduanya. Uji beban dengan Artillery untuk skala. Jalankan pemeriksaan fungsional dan regresi di CI dengan Apidog CLI untuk menangkap perilaku yang rusak sebelum dirilis.

Apidog CLI diinstal dari npm, dan apidog run hanya menggunakan flag.

# Apidog CLI: menjalankan fungsional/regresi di CI (hanya flag, tidak ada file posisi)
npm install -g apidog-cli
apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t <TEST_SCENARIO_ID> \
  -e <ENVIRONMENT_ID> \
  -r cli,junit \
  --out-dir ./apidog-reports

Flag -t adalah ID skenario pengujian, -e adalah ID lingkungan yang diperlukan, dan -r cli,junit menghasilkan output konsol dan laporan XML JUnit yang dapat dibaca oleh sistem CI. Untuk panduan langkah demi langkah, lihat tutorial Apidog CLI, dan untuk pola desain pipeline, lihat praktik terbaik CI/CD untuk pengujian API ini.

Ingin pengujian fungsional dan kontrak menjadi pintu gerbang CI Anda bersama dengan pengujian beban Artillery Anda? Unduh Apidog secara gratis dan bangun skenario pengujian pertama Anda.

Pertanyaan yang Sering Diajukan

Apa itu pengujian beban Artillery?

Pengujian beban Artillery adalah praktik menggunakan toolkit Artillery sumber terbuka untuk mensimulasikan banyak pengguna virtual bersamaan yang mengakses API Anda. Anda menjelaskan bentuk beban dan alur permintaan dalam skrip YAML, menjalankannya, dan mengukur persentil latensi, laju permintaan, dan kesalahan untuk melihat bagaimana sistem Anda berperilaku di bawah tekanan.

Apakah Artillery gratis dan sumber terbuka?

Ya. Inti Artillery CLI gratis dan sumber terbuka, didistribusikan di npm sebagai paket artillery. Ada juga penawaran berbayar yang di-host, Artillery Cloud, yang menyediakan dasbor untuk hasil, tetapi Anda dapat menjalankan pengujian beban penuh secara lokal dan di CI tanpanya.

Bagaimana Anda menjalankan pengujian beban Artillery?

Instal dengan npm install -g artillery@latest, tulis skrip YAML dengan blok config (target dan fase) dan blok scenarios (alur permintaan), lalu jalankan artillery run script.yml. Artillery mencetak metrik langsung setiap 10 detik dan ringkasan di akhir.

Bagaimana Anda membuat laporan Artillery?

Jalankan artillery run --output report.json script.yml untuk menulis file hasil JSON. Perintah artillery report lama yang menghasilkan HTML telah dihapus dari CLI. Sebagai gantinya, uraikan JSON dengan alat seperti jq, gunakan Artillery Cloud melalui --record --key, atau dorong metrik keluar dengan plugin publish-metrics atau OpenTelemetry.

Artillery vs k6 atau JMeter: mana yang harus Anda gunakan?

Ketiganya menangani beban skala tinggi. Artillery menggunakan YAML deklaratif dan Node.js, yang cocok untuk tim yang sudah berada di ekosistem JavaScript. k6 menulis skrip dalam JavaScript dengan model code-first. JMeter didorong GUI dan berbasis Java dengan sejarah plugin yang panjang. Perbandingan Gatling vs JMeter mencakup pertimbangan lebih dalam. Pilih salah satu yang model scripting-nya cocok dengan tim Anda, lalu pasangkan dengan pengujian CI fungsional untuk cakupan penuh.