Cara Tes API Upload File (multipart/form-data) di Apidog

Anda membuat endpoint yang menerima file. Pengguna mengunggah gambar profil ke POST /avatars, atau aplikasi Anda mengirim PDF yang ditandatangani ke POST /documents. Rute tersebut mungkin sudah jelas, tetapi Anda tetap perlu membuktikannya melalui HTTP: pilih file nyata, lampirkan ke field formulir, kirim permintaan, lalu periksa responsnya.

Coba Apidog hari ini

Unggahan file menggunakan multipart/form-data, bukan JSON. Karena itu, Anda tidak bisa sekadar menempel body JSON lalu mengirimnya. Anda memerlukan pembuat request yang memahami field file, serta test runner yang dapat menemukan file saat pengujian berjalan. Apidog menangani keduanya.

Panduan ini membahas cara:

• Mengirim satu file.
• Mengirim file bersama JSON.
• Menambahkan assertion pada respons.
• Menjalankan upload di Runner atau CLI tanpa gagal karena file tidak ditemukan.

Jika Anda ingin memahami format multipart lebih dulu, baca panduan unggah file di API. Untuk sisi browser, gunakan referensi MDN tentang FormData.

Apa itu multipart/form-data dan mengapa unggahan memerlukannya

Body request API dapat memiliki beberapa format. Di bagian Body Apidog, Anda dapat memilih form-data, x-www-form-urlencoded, JSON, XML, raw, atau binary.

Sebagian besar endpoint menggunakan JSON. Upload file adalah pengecualian.

Tipe body form-data memetakan ke header berikut:

Content-Type: multipart/form-data

Format ini dibuat untuk mengirim file bersama data lain dalam satu request. Body dibagi menjadi beberapa bagian:

• Satu bagian dapat berisi string, misalnya title.
• Bagian lain dapat berisi byte mentah file, misalnya gambar PNG atau PDF.

Karena itu, Anda dapat mengirim foto dan metadata dalam request yang sama.

x-www-form-urlencoded terlihat mirip karena sama-sama menggunakan pasangan key-value. Namun, format itu hanya cocok untuk field skalar sederhana dan tidak membawa byte file.

Jika endpoint menerima file, gunakan form-data.

Di Apidog, setiap parameter form-data memiliki tipe, misalnya string, integer, atau file. Atur tipe parameter menjadi file agar Apidog melampirkan file, bukan mengirim path-nya sebagai teks.

Kirim unggahan file tunggal dan tambahkan assertion respons

Misalnya Anda menguji POST /avatars. Endpoint menerima satu field bernama avatar dan mengembalikan JSON berisi URL file yang tersimpan.

1. Pilih body form-data

Buat atau buka endpoint Anda, lalu atur:

• Method: POST
• URL: endpoint avatar Anda, misalnya /avatars
• Body type: form-data

Apidog akan mengatur Content-Type: multipart/form-data secara otomatis.

2. Tambahkan parameter file

Tambahkan parameter dengan konfigurasi berikut:

Key	Type
avatar	file

Ubah tipe parameter dari string menjadi file. Kolom nilai akan berubah menjadi pemilih file.

3. Pilih file lokal

Klik Upload pada baris avatar, lalu pilih file lokal, misalnya:

jane-profile.png

Apidog menyimpan path file tersebut untuk digunakan saat request dikirim.

4. Kirim request

Klik Send. Apidog membaca file dari path lokal, membangun body multipart, lalu mengirim request.

Perlu diperhatikan: Apidog mengirim file dalam request, tetapi tidak menyimpan byte file di cloud. Yang disimpan adalah path lokal file tersebut. Detail ini penting saat Anda menjalankan request di Runner, CLI, atau mesin lain.

Respons yang berhasil dapat terlihat seperti ini:

{
  "id": "usr_8842",
  "avatarUrl": "https://cdn.example.com/avatars/usr_8842.png",
  "sizeBytes": 48210,
  "contentType": "image/png"
}

5. Tambahkan assertion

Status 200 saja belum cukup untuk menyatakan pengujian berhasil. Tambahkan assertion pasca-request untuk memvalidasi respons.

Contoh assertion:

status code == 200
$.avatarUrl exists
$.contentType == "image/png"

Assertion tersebut memeriksa:

1. Respons memiliki status 200.
2. Field avatarUrl ada.
3. Field contentType bernilai image/png.

Di Apidog, tambahkan assertion ini pada endpoint atau langkah scenario. Untuk daftar operator dan penggunaan JSONPath, lihat panduan assertion API.

Sebagai pembanding, request yang sama dengan curl terlihat seperti ini:

curl -X POST https://api.example.com/avatars \
  -F "avatar=@jane-profile.png"

Flag -F membuat bagian multipart, sedangkan @ memberi tahu curl untuk membaca isi file. Field form-data bertipe file di Apidog menjalankan fungsi yang sama melalui UI.

Kirim file dan JSON bersamaan

Endpoint nyata biasanya menerima file dan metadata. Misalnya, POST /documents dapat menerima PDF, judul, kategori, serta daftar tag.

Ada dua pola umum.

Tambahkan field skalar untuk metadata sederhana

Untuk metadata sederhana, tambahkan parameter form-data di samping field file:

Key	Type	Contoh nilai
file	file	q3-invoice.pdf
title	string	Q3 Invoice
category	string	billing

Semua field dikirim dalam request multipart yang sama.

Kirim metadata terstruktur sebagai string JSON

Jika metadata berisi objek bersarang atau array, tambahkan field metadata bertipe string, lalu isi nilainya dengan JSON:

{
  "title": "Q3 Invoice",
  "category": "billing",
  "tags": ["invoice", "2026", "paid"]
}

Struktur request menjadi:

Key	Type	Isi
file	file	q3-invoice.pdf
metadata	string	JSON metadata

Server membaca file dari satu bagian multipart dan mengurai JSON dari bagian lainnya.

Pola ini umum pada API publik. Contohnya dapat dilihat pada dokumentasi unggahan file Stripe. Jika Anda bermigrasi dari Postman, panduan mengunggah file dan data JSON di Postman menjelaskan pemetaannya ke field form-data Apidog.

Kirim lebih dari satu file

Tambahkan satu parameter file untuk setiap file yang diharapkan endpoint.

Contoh untuk endpoint yang menerima dokumen utama dan thumbnail:

Key	Type
file	file
thumbnail	file

Tidak ada mode multi-file khusus. Tambahkan saja parameter bertipe file hingga seluruh bagian yang diharapkan endpoint tercakup.

Ubah request menjadi scenario pengujian yang dapat diulang

Mengirim request sekali hanya membuktikan endpoint berfungsi pada saat itu. Untuk mendeteksi regresi, simpan upload sebagai scenario pengujian.

Contoh alur scenario:

1. Kirim POST /avatars.
2. Simpan id dari respons.
3. Kirim GET /users/{id}.
4. Pastikan URL avatar masih ada pada respons.

Bangun langkah upload seperti request biasa, lalu simpan sebagai langkah scenario. Panduan cara menulis scenario pengujian dengan Apidog membahas perangkaian langkah dan pengiriman nilai antar-langkah.

Setelah upload masuk ke scenario, Anda dapat:

• Menjalankannya terhadap staging setiap deployment.
• Menambahkan cabang dengan logika bersyarat dalam scenario pengujian API.
• Menjalankannya secara berkala dengan pengujian API terjadwal.

Namun, ada satu hal yang perlu Anda siapkan saat scenario dijalankan di luar laptop Anda: file upload harus tersedia di mesin eksekusi.

Kesalahan umum: unggahan berjalan di mesin lain

Apidog menyimpan path file, bukan file itu sendiri.

Di laptop Anda, hal ini biasanya tidak terlihat karena path tersebut menunjuk ke file yang benar. Tetapi ketika request atau scenario dijalankan di mesin lain, path yang sama mungkin tidak ada.

Anda akan menemukannya dalam dua situasi.

Kolaborasi tim

Misalnya Anda memilih file berikut:

/Users/jane/pics/jane-profile.png

Rekan tim dapat melihat parameter file dan path tersebut, tetapi tidak dapat mengirim request jika file hanya ada di laptop Anda.

Solusinya: setiap anggota tim harus menyediakan salinan file di mesin mereka sendiri dan mengganti path file sesuai lokasi lokal mereka.

Eksekusi Runner dan CLI

Masalah yang sama terjadi dalam otomatisasi.

Scenario berhasil saat dijalankan lokal, tetapi gagal di Runner atau CLI karena host tersebut tidak memiliki file pada path yang tersimpan dari laptop Anda.

Penyebabnya bukan assertion atau endpoint. Runner atau CLI hanya tidak dapat menemukan file.

Perbaikannya sederhana:

1. Pastikan file tersedia di mesin yang menjalankan scenario.
2. Ubah path pada langkah upload agar menunjuk ke lokasi file di mesin tersebut.

Konfigurasi file untuk Runner

Runner membaca file dari direktori host yang dipasang sebagai volume saat deployment menggunakan flag -v.

Langkahnya:

1. Salin file upload ke direktori host yang dipasang ke Runner.
2. Buka detail langkah upload pada scenario.
3. Klik Batch Edit.
4. Ganti nilai field file dengan path yang tersedia di Runner.

Contoh:

/opt/runner/jane-profile.png

Konfigurasi file untuk CLI

Untuk CLI, gunakan pola yang sama:

1. Letakkan file di mesin yang menjalankan CLI.
2. Buka langkah upload.
3. Gunakan Batch Edit untuk mengganti path file.

Contoh:

/opt/apidog/runner/jane-profile.png

Gunakan variabel agar path tidak di-hardcode

Jangan simpan path literal langsung pada langkah scenario jika Anda menjalankan scenario di banyak environment.

Gunakan variabel, misalnya:

{{upload_file_path}}

Lalu atur nilai variabel sesuai environment:

# Lokal
/Users/jane/pics/jane-profile.png

# Runner
/opt/runner/jane-profile.png

Dengan pendekatan ini, langkah scenario tidak perlu diubah setiap kali dijalankan di laptop, Runner, atau CI.

Runner hanya dapat membaca file yang berada di bawah direktori host yang dipasang menggunakan -v. Jika file berada di luar direktori tersebut, path apa pun tidak akan dapat mengaksesnya.

Untuk langkah deployment dan pengeditan massal, lihat dokumentasi Apidog tentang request unggahan file.

Otomatiskan alur kerja dengan Apidog CLI

Setelah scenario upload disimpan, jalankan scenario tersebut di CI tanpa UI.

Instal CLI dan autentikasi:

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>

Kemudian jalankan scenario berdasarkan ID dan environment:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli

Parameter yang digunakan:

• -t: ID scenario pengujian.
• -e: ID environment.
• -r: reporter.

Reporter yang tersedia meliputi cli, html, dan junit. Gunakan beberapa reporter dengan pemisah koma.

CLI menjalankan scenario tersimpan dari proyek cloud dan mengembalikan status berhasil atau gagal melalui exit code. Karena itu, perintah ini dapat digunakan untuk mengontrol pipeline CI.

Lihat panduan instalasi Apidog CLI untuk konfigurasi lebih lanjut.

Satu hal tetap berlaku: file upload harus tersedia di mesin CLI, dan path pada langkah scenario harus menunjuk ke file tersebut. Gunakan Batch Edit atau variabel environment sebelum menjalankan scenario.

Untuk pengujian CI yang menggunakan input per baris, lihat pengujian berbasis data dengan Apidog CLI.

FAQ

Mengapa rekan tim saya tidak dapat mengirim request upload file saya?

Apidog menyimpan path file lokal, bukan file itu sendiri. Rekan tim dapat melihat request dan path yang Anda pilih, tetapi path tersebut mengarah ke disk Anda, bukan ke disk mereka.

Minta mereka menyalin file ke mesin mereka dan memilih path lokal mereka sendiri. Hal yang sama berlaku untuk pengujian terjadwal dan tugas Runner.

Bagaimana cara mengirim JSON bersama file dalam request yang sama?

Gunakan body form-data.

1. Tambahkan field file dengan tipe file.
2. Tambahkan field lain dengan tipe string.
3. Tempel JSON pada nilai field string tersebut.

Server akan menerima file dan string JSON sebagai dua bagian dalam satu request multipart.

Path apa yang harus digunakan untuk file di Runner?

Gunakan path di dalam direktori yang dipasang ke volume Runner dengan flag -v.

Contoh:

/opt/runner/yourfile.jpg

Salin file ke direktori tersebut, buka langkah upload, klik Batch Edit, lalu set nilai field ke path tersebut.

Untuk CLI, path dapat terlihat seperti ini:

/opt/apidog/runner/yourfile.jpg

Apakah ada batas ukuran file atau tipe file yang diizinkan?

Apidog membangun request dan membaca file dari path yang Anda pilih. Batas ukuran serta tipe file ditentukan oleh API yang Anda uji.

Periksa aturan validasi pada server Anda, lalu tambahkan assertion terhadap respons untuk kasus file terlalu besar atau tipe file yang ditolak.

Haruskah menggunakan form-data atau x-www-form-urlencoded untuk upload?

Gunakan form-data.

form-data memetakan ke multipart/form-data dan mendukung file. x-www-form-urlencoded hanya cocok untuk form sederhana yang berisi field skalar tanpa file.

Ringkasan

Pengujian upload file memiliki dua bagian utama:

1. Bangun request multipart dengan benar.
2. Pastikan file tersedia di setiap mesin tempat pengujian dijalankan.

Di Apidog, pilih Body form-data, ubah tipe field menjadi file, pilih file melalui Upload, tambahkan metadata JSON sebagai field string, lalu kirim request dan tambahkan assertion.

Saat menjalankan scenario di Runner atau CLI, siapkan file pada mesin eksekusi dan arahkan path menggunakan Batch Edit atau variabel environment.

Ingin mencobanya pada endpoint Anda sendiri? Unduh Apidog, buat request form-data ke endpoint upload Anda, lalu periksa responsnya.