Cara Menjalankan Tes API Berparameter dari CSV dan JSON

Anda menulis tes login. Ini lulus. Kemudian seorang rekan tim menanyakan pertanyaan yang jelas: apakah ini lulus untuk akun yang terkunci, email yang belum diverifikasi, kata sandi dengan spasi di akhir, string injeksi SQL yang pada akhirnya akan ditempelkan seseorang ke dalam kolom? Sekarang Anda punya pilihan. Salin tes itu lima kali dan ubah satu nilai di setiap salinan, atau temukan cara untuk memberi makan tes yang sama dengan banyak baris input dan biarkan semua itu berjalan.

Rute salin-tempel adalah bagaimana sebagian besar suite pengujian membusuk. Lima tes yang hampir identik terpisah selama setahun. Satu mendapatkan pernyataan baru, yang lain tidak. Pengubahan nama bidang merusak empat di antaranya secara diam-diam. Anda akhirnya memelihara lima hal yang seharusnya menjadi satu. Pengujian berparameter memperbaiki ini pada akarnya: Anda menulis tes sekali, lalu mengarahkannya ke tabel input dan output yang diharapkan. Satu skenario, ratusan kasus, satu tempat untuk mengedit.

button

Apa sebenarnya arti pengujian berparameter

Pengujian berparameter, kadang-kadang disebut pengujian berbasis data, memisahkan logika pengujian dari data yang dijalankannya. Logikanya adalah urutan langkah-langkah: kirim permintaan, periksa kode status, validasi bidang dalam respons. Data adalah kumpulan input dan ekspektasi yang ingin Anda jalankan logika tersebut.

Bayangkan satu skenario pengujian untuk endpoint kode diskon. Logikanya selalu sama. Kirim POST /api/orders dengan kode, lalu verifikasi responsnya. Data berubah per kasus:

code	order_total	expected_status	expected_discount
WELCOME10	100	200	10
WELCOME10	5	422	0
EXPIRED	100	410	0
(empty)	100	400	0
FAKE123	100	404	0

Lima baris, lima perilaku berbeda, satu tes. Runner mengulang baris-baris tersebut. Pada setiap putaran, ia mengikat nilai kolom ke variabel, memicu permintaan, dan memeriksa pernyataan terhadap ekspektasi baris tersebut. Ketika baris 3 gagal karena kode yang kedaluwarsa mengembalikan 200 bukannya 410, Anda mendapatkan satu kegagalan yang jelas menunjuk ke satu baris. Anda tidak perlu mencari-cari di lima file tes terpisah untuk mencari tahu salinan mana yang rusak.

Pola ini paling penting di batas-batasnya. Cakupan jalur positif (happy-path) mudah ditulis dan jarang menangkap bug yang membuat Anda terjaga pada jam 2 pagi. Bug-bug tersebut hidup dalam kasus-kasus batas: string kosong, angka negatif, nama unicode, token kedaluwarsa, nilai yang satu sen melebihi batas. Parametrisasi membuat penambahan kasus batas semurah menambahkan baris ke spreadsheet.

Mengapa file data terpisah mengalahkan nilai-nilai yang dikodekan secara langsung (hardcoded)

Anda bisa mengkodekan setiap kasus secara langsung dalam tes. Kebanyakan orang memulai dari sana. Masalahnya muncul nanti.

Ketika data berada dalam tes, non-insinyur tidak dapat menyumbangkan kasus. Pemimpin QA Anda tahu lima belas input rumit yang telah merusak endpoint ini sebelumnya, tetapi mereka tidak dapat menambahkannya tanpa mengedit kode dan membuka permintaan tarik (pull request). Ketika data berada dalam CSV, mereka mengedit spreadsheet dan mengkomitnya. Hambatan turun mendekati nol.

File terpisah juga menjaga skenario tes Anda tetap terbaca. Tes yang mengulang file eksternal pendek: satu permintaan, beberapa pernyataan, selesai. Tes dengan tiga puluh kasus inline adalah tembok pengulangan yang tidak ingin disentuh siapa pun. Dan ketika Anda perlu menghasilkan kasus secara terprogram, katakan seribu baris yang ditarik dari log produksi, file adalah satu-satunya pilihan yang masuk akal. Anda tidak bisa menempelkan seribu kasus ke dalam badan tes.

Format yang Anda pilih tergantung pada bentuk data Anda. Kasus datar dan tabular cocok untuk CSV. Payload bertingkat atau terstruktur cocok untuk JSON. Keduanya adalah input kelas satu di runner Apidog, jadi pilihannya adalah tentang data Anda, bukan tentang batasan alat.

Menyiapkan file data Anda

Mulailah dengan CSV untuk kasus tabular. Baris header menamai variabel Anda; setiap baris di bawahnya adalah satu iterasi. Berikut adalah tabel kode diskon sebagai file nyata, discount-cases.csv:

code,order_total,expected_status,expected_discount
WELCOME10,100,200,10
WELCOME10,5,422,0
EXPIRED,100,410,0
,100,400,0
FAKE123,100,404,0

Setiap header kolom menjadi variabel yang Anda rujuk di dalam tes. Dalam badan permintaan Anda menulis {{code}} dan {{order_total}}; dalam pernyataan Anda membandingkan dengan {{expected_status}} dan {{expected_discount}}. Runner melakukan pengikatan baris demi baris.

Ketika input Anda bertingkat, gunakan JSON. Array objek, satu objek per iterasi, memungkinkan setiap kasus membawa data terstruktur yang akan canggung untuk diratakan menjadi kolom. Berikut adalah user-cases.json untuk endpoint pembuatan pengguna di mana payload memiliki bidang bertingkat:

[
  {
    "scenario": "valid full profile",
    "user": {
      "email": "ada@example.com",
      "roles": ["admin", "billing"],
      "profile": { "country": "US", "timezone": "America/New_York" }
    },
    "expected_status": 201
  },
  {
    "scenario": "missing email",
    "user": {
      "email": "",
      "roles": ["viewer"],
      "profile": { "country": "GB", "timezone": "Europe/London" }
    },
    "expected_status": 400
  },
  {
    "scenario": "unknown role",
    "user": {
      "email": "grace@example.com",
      "roles": ["wizard"],
      "profile": { "country": "CA", "timezone": "America/Toronto" }
    },
    "expected_status": 422
  }
]

Di dalam tes Anda mereferensikan nilai-nilai terstruktur dengan sintaks {{user}}, {{expected_status}} yang sama, dan Apidog menyerahkan bidang-bidang setiap objek ke iterasi. Kolom scenario adalah label untuk diri Anda sendiri; itu muncul di laporan sehingga iterasi yang gagal terbaca “unknown role” daripada “iteration 3.”

Beberapa aturan untuk menjaga file data agar tidak menyulitkan Anda:

Jaga satu perhatian per file. File kode diskon dan file pembuatan pengguna adalah dua file, bukan satu dengan kolom campuran.
Letakkan hasil yang diharapkan dalam data, bukan tes. Intinya adalah baris 2 mengharapkan 422 sedangkan baris 1 mengharapkan 200. Jika ekspektasi dikodekan secara langsung, Anda kembali ke satu tes per kasus.
Kutip apa pun yang mengandung koma dalam CSV, atau alihkan file itu ke JSON. Bidang teks bebas dengan koma di dalamnya adalah masalah klasik CSV.
Simpan file-file ini di repo Anda di samping sisa konfigurasi tes Anda sehingga mereka memiliki versi yang sama dengan kode yang mereka jalankan.

Membangun skenario berparameter di Apidog

Di aplikasi Apidog, bangun skenario tes sekali seperti biasa. Tambahkan permintaan ke endpoint Anda. Di dalam body, tukar nilai literal dengan referensi variabel: {{code}}, {{order_total}}, dan seterusnya. Ini adalah kolom-kolom dari file data Anda.

Kemudian tambahkan pernyataan yang membaca dari file yang sama. Untuk contoh diskon, Anda akan menyatakan bahwa status respons sama dengan {{expected_status}} dan bahwa bidang diskon di badan JSON sama dengan {{expected_discount}}. Karena baik input maupun output yang diharapkan berasal dari baris, logika pernyataan yang sama memvalidasi setiap kasus dengan benar. Jika Anda belum pernah menulis pernyataan di Apidog sebelumnya, API assertions: a practical guide mencakup pola-pola tersebut, dan how to set assertions and extract variables from a JSON response menunjukkan sisi JSONPath secara detail.

Untuk mengaitkan data, buka pengaturan jalankan skenario tes dan lampirkan file CSV atau JSON Anda sebagai sumber data iterasi. Apidog membaca file, menghitung baris, dan menjalankan skenario satu kali per baris, mengikat kolom setiap baris ke variabel yang cocok. Jalankan di dalam aplikasi dan Anda akan mendapatkan rincian per-iterasi: baris mana yang lulus, mana yang gagal, dan nilai aktual versus yang diharapkan untuk setiap pernyataan yang gagal.

Di sinilah parameterisasi juga menyatu dengan bagian lain dari suite Anda. Skenario berparameter masih merupakan skenario, jadi Anda dapat mengelompokkan beberapa di antaranya ke dalam test suite dan menjalankan seluruh set sebagai satu pekerjaan. Loop berbasis data menangani cakupan dalam satu endpoint; suite tes menangani cakupan di seluruh endpoint.

Menjalankannya dari baris perintah

Aplikasi adalah tempat Anda membangun dan melakukan debug. CI adalah tempat tes menghasilkan nilainya, berjalan pada setiap permintaan tarik (pull request) tanpa perlu ada yang mengklik tombol. Penyerahan itulah gunanya Apidog CLI. Ia mengambil skenario yang Anda bangun di aplikasi dan menjalankannya tanpa antarmuka dari terminal, dengan data iterasi yang sama.

CLI dikirimkan sebagai paket npm. Instal secara global:

npm install -g apidog-cli

Binernya adalah apidog, jadi setiap perintah dimulai dengan apidog run. Jalankan dasar menunjuk ke skenario berdasarkan ID dan lingkungan berdasarkan ID:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

Untuk menjalankan skenario itu dari file data, tambahkan flag iterasi-data. Ini menerima jalur ke file JSON atau CSV:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 \
  -d ./discount-cases.csv -r cli,junit --out-dir ./test-reports

Flag -d (bentuk panjang --iteration-data) adalah inti dari eksekusi berparameter dari baris perintah. Apidog membaca file, menjalankan skenario sekali per baris, dan melaporkan setiap iterasi. Tukar discount-cases.csv dengan user-cases.json dan flag yang sama menangani array JSON; runner mengambil format dari file. Perlakukan token akses seperti kata sandi dan simpan sebagai rahasia CI, jangan pernah dalam file yang dikomit. Itulah mengapa setiap contoh merujuk pada $APIDOG_ACCESS_TOKEN daripada nilai literal.

Beberapa flag yang cocok secara alami dengan eksekusi berparameter:

-d, --iteration-data <path> mengarahkan eksekusi ke file CSV atau JSON Anda. Ini adalah yang mengubah eksekusi satu kali menjadi berbasis data.
-n, --iteration-count <n> menjalankan skenario sebanyak jumlah tetap. Ketika Anda menyediakan file data, jumlah baris biasanya mendorong iterasi, jadi Anda menggunakan -n terutama untuk kasus pengulangan tanpa data seperti uji rendaman (soak tests).
-r, --reporters <list> memilih format output. Gunakan cli untuk output log build yang mudah dibaca dan junit untuk mengeluarkan XML yang diurai dasbor CI menjadi pohon lulus/gagal per iterasi.
--out-dir <path> menetapkan di mana laporan disimpan sehingga Anda dapat mengarsipkannya sebagai artefak build.

Jika Anda ingin daftar flag yang otoritatif dan terkini untuk versi yang Anda instal, jalankan apidog run --help. CLI mencetak setiap opsi dengan bentuk pendek dan panjangnya.

Mengintegrasikan eksekusi berparameter ke CI

Alasan untuk berinvestasi dalam pengujian berparameter adalah karena mereka memberikan keuntungan secara otomatis. Berikut adalah pekerjaan GitHub Actions yang menginstal CLI dan menjalankan skenario berbasis CSV pada setiap permintaan tarik (pull request):

name: API tests
on: [pull_request]

jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Install Apidog CLI
        run: npm install -g apidog-cli
      - name: Run parameterized API tests
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
        run: |
          apidog run --access-token $APIDOG_ACCESS_TOKEN \
            -t 605067 -e 1629989 \
            -d ./tests/discount-cases.csv \
            -r cli,junit --out-dir ./test-reports
      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: api-test-report
          path: ./test-reports

Token berasal dari secrets.APIDOG_ACCESS_TOKEN, yang diatur sekali di pengaturan repo Anda. Reporter junit menulis XML yang sebagian besar dasbor CI ubah menjadi pohon hasil per-iterasi, sehingga baris yang gagal muncul sebagai tes yang gagal dengan nama daripada kumpulan teks log. if: always() pada langkah unggah berarti Anda tetap menyimpan laporan meskipun eksekusi gagal, yang merupakan saat Anda sangat menginginkannya. Untuk panduan yang lebih mendalam tentang sisi Actions, lihat how to automate API tests in GitHub Actions.

Skenario yang sama dan file data yang sama berjalan di sistem CI mana pun. GitLab CI, Jenkins, CircleCI, dan lainnya semuanya bermuara pada tiga langkah yang sama: instal Node dan CLI, ekspos token sebagai variabel lingkungan, panggil apidog run dengan -d. Tidak ada penulisan ulang tes Anda per platform.

Membandingkan Pendekatan Pengujian Berparameter

Apidog bukan satu-satunya cara untuk menjalankan tes API berbasis data. Penting untuk mengetahui lanskapnya agar Anda memilih yang paling sesuai.

Postman dan runner-nya juga mendukung file data. Dengan Postman’s Collection Runner atau alat baris perintah Newman, Anda melampirkan file CSV atau JSON dan mereferensikan variabel {{column}} dalam permintaan, mirip dengan pola di sini. Ini adalah pendekatan yang mampu dan terdokumentasi dengan baik. Kekurangannya adalah logika tes Anda berada dalam skrip JavaScript pre-request dan test, jadi seiring bertambahnya pernyataan Anda, Anda akan memelihara lebih banyak kode. Jika Anda mempertimbangkan runner baris perintah secara spesifik, Postman CLI vs Newman menguraikan perbedaannya.

Framework yang mengutamakan kode seperti pytest dengan @pytest.mark.parametrize, @ParameterizedTest dari JUnit, atau REST Assured memberi Anda kontrol bahasa pemrograman penuh. Ini adalah pilihan yang tepat ketika logika tes Anda benar-benar membutuhkan kode: penyiapan yang kompleks, pembuatan data khusus, keterkaitan erat dengan basis kode tes yang ada. Biayanya adalah setiap kasus berada dalam kode, sehingga non-insinyur tidak dapat berkontribusi, dan Anda harus memelihara perpipaan HTTP sendiri.

Sudut pandang Apidog adalah bahwa skenarionya visual dan datanya eksternal, sehingga logikanya tetap mudah dibaca dan kasus-kasus tetap terbuka untuk siapa saja yang dapat mengedit spreadsheet, sementara skenario yang sama masih berjalan tanpa antarmuka di CI. Jika Anda secara khusus memilih alat untuk eksekusi berbasis data CSV dan JSON, perbandingan di which tool for data-driven API testing with CSV or JSON membahas lebih dalam tentang komprominya. Tidak ada yang salah. Sesuaikan pendekatan dengan siapa yang menulis kasus dan berapa banyak logika kustom yang dibutuhkan setiap kasus.

Alur Kerja Praktis yang Skalabel

Begini tampilannya setelah menjadi bagian dari rutinitas tim Anda.

Mulailah secara sempit. Pilih satu endpoint yang pernah membuat Anda kesulitan sebelumnya. Tulis skenario tunggal di Apidog dengan referensi variabel dalam permintaan dan hasil yang diharapkan dalam pernyataan. Buat CSV dengan tiga baris: satu jalur positif (happy path), satu kegagalan yang diketahui, satu kasus batas. Jalankan di aplikasi sampai ketiga iterasi berperilaku seperti yang diharapkan.

Kemudian kembangkan datanya, bukan tesnya. Setiap kali laporan bug masuk, tambahkan input yang menyebabkannya sebagai baris baru dengan output yang diharapkan yang benar. Bug tersebut menjadi kasus regresi permanen dan Anda tidak pernah menulis tes baru, Anda menambahkan baris ke file. Selama beberapa bulan, file tersebut mengumpulkan "kejelekan" dunia nyata yang sebenarnya dihadapi endpoint Anda.

Akhirnya, otomatiskan itu. Masukkan perintah apidog run -d ke CI sehingga seluruh tabel berjalan pada setiap permintaan tarik (pull request). Sekarang perubahan yang merusak jalur kode yang kedaluwarsa akan menyebabkan build gagal segera setelah didorong, dengan iterasi bernama yang menunjuk langsung ke baris yang rusak.

Kemenangan berlipat ganda adalah pemeliharaan. Ketika bentuk respons endpoint berubah, Anda memperbaiki pernyataan sekali dan setiap kasus mendapatkan perbaikan tersebut. Ketika Anda membutuhkan lima puluh kasus lagi, Anda menambahkan lima puluh baris. Logika tes tetap menjadi satu hal yang kecil, mudah dibaca, tidak peduli seberapa luas cakupan Anda.

Pertanyaan yang sering diajukan

Apa perbedaan antara pengujian berparameter dan pengujian berbasis data? Keduanya menggambarkan ide yang sama dan orang menggunakan istilah tersebut secara bergantian. Keduanya berarti menjalankan satu tes berulang kali dengan input dan output yang diharapkan berbeda yang disediakan dari luar tes. "Berparameter" mengacu pada mekanisme pengikatan parameter; "berbasis data" mengacu pada sumber data eksternal. Dalam praktiknya, perlakukan keduanya sebagai sinonim.

Haruskah saya menggunakan CSV atau JSON untuk file data saya? Sesuaikan format dengan bentuk data Anda. Kasus datar dan tabular di mana setiap baris memiliki kolom sederhana yang sama cocok untuk CSV, dan CSV lebih mudah diedit oleh non-insinyur di spreadsheet. Payload bertingkat atau terstruktur, seperti badan permintaan dengan array dan sub-objek, cocok untuk JSON. Apidog membaca keduanya sebagai data iterasi, jadi pilih mana saja yang mewakili kasus Anda tanpa pemelintiran.

Akankah ratusan iterasi memperlambat pipeline saya? Setiap baris adalah satu eksekusi skenario, jadi total waktu akan diskalakan dengan jumlah baris dikalikan latensi per-permintaan. Untuk sebagian besar tes API, itu adalah detik, bukan menit. Jika kumpulan data yang besar meregangkan build Anda, pisahkan: jalankan subset smoke test yang cepat pada setiap pull request dan tabel lengkap pada pekerjaan malam atau pra-rilis. Skenario dan file yang sama menggerakkan keduanya; hanya subset data yang berubah.

Bagaimana cara menjauhkan rahasia dari file data dan konfigurasi tes saya? Jauhkan kredensial dari file data sepenuhnya. Token dan kata sandi termasuk dalam variabel lingkungan atau penyimpanan rahasia sistem CI Anda, dirujuk sebagai $APIDOG_ACCESS_TOKEN dan sejenisnya. File data seharusnya hanya berisi input tes dan hasil yang diharapkan, bukan materi otentikasi. Siapa pun yang dapat membaca repo dapat membaca CSV, jadi perlakukan demikian.

Bisakah saya menjalankan skenario berparameter yang sama terhadap staging dan production? Ya. Pertahankan skenario dan file data tetap, dan ganti lingkungan dengan flag -e. Arahkan pemeriksaan permintaan tarik (pull request) ke staging dan smoke test pasca-deploy ke production menggunakan ID skenario yang sama dan data yang sama, hanya dengan ID lingkungan yang berbeda. Itulah alasan mengapa lingkungan dan data adalah input terpisah.

Penutup

Pengujian API berparameter mengubah cakupan dari tugas salin-tempel menjadi tugas entri data. Anda menulis tes sekali, menjelaskan setiap kasus sebagai baris dalam file CSV atau JSON, dan biarkan runner melakukan sisanya. Logikanya tetap kecil dan mudah dibaca, kasus-kasus tetap terbuka untuk siapa saja di tim, dan CI menjalankan seluruh tabel pada setiap perubahan.

Apidog memberi Anda pembangun skenario visual untuk penulisan, file CSV dan JSON eksternal untuk data, dan perintah apidog run -d untuk eksekusi tanpa antarmuka di sistem CI mana pun. Bangun satu skenario, arahkan ke tabel kasus yang berkembang, dan cakupan tes Anda meluas setiap kali seseorang menambahkan baris. Unduh Apidog dan ubah tes sekali jalan Anda yang tidak stabil berikutnya menjadi skenario berparameter yang skalabel.

button