Cara Mengembalikan Data Mock Kondisional di Apidog (Aturan Kustom dan Skrip Mock)

Smart mock memberi API palsu dalam hitungan detik. Fitur ini membaca skema endpoint dan mengembalikan data yang masuk akal, seperti email realistis, stempel waktu valid, dan nama yang dapat digunakan untuk pengembangan frontend.

Coba Apidog hari ini

Namun, Smart mock hanya mengembalikan satu bentuk respons per endpoint. Saat Anda perlu mengembalikan 200 untuk pengguna tertentu, 401 untuk pengguna lain, atau memicu 500 sesuai permintaan, gunakan mock kondisional.

Apidog menyediakan dua pendekatan:

1. Mock expectation untuk respons kondisional berbasis aturan.
2. Mock script untuk logika JavaScript yang tidak dapat dinyatakan dengan aturan.

Jika Anda belum familiar dengan konsep dasarnya, baca gambaran umum mocking API. Panduan ini menggunakan Apidog dan mengikuti pendekatan contract-first yang didokumentasikan oleh OpenAPI Initiative.

Apa itu mocking kondisional?

Mock kondisional adalah aturan sederhana:

Jika permintaan masuk cocok dengan kondisi tertentu, kembalikan respons tertentu.

Apidog mendukung dua lapisan mocking:

• Nilai dinamis tingkat bidang pada skema endpoint.
• Mock expectation untuk menentukan status, header, dan body respons berdasarkan kondisi permintaan.

Nilai dinamis membuat data berubah di setiap pemanggilan, tetapi tidak membuat percabangan. Untuk percabangan berdasarkan body, header, parameter path, atau query, gunakan expectation.

Mulai dari nilai dinamis tingkat bidang

Di dalam skema endpoint, bidang string dapat menggunakan ekspresi Faker.js dengan format:

{{$category.method}}

Contoh payload:

{
  "id": "{{$number.int(min=1000,max=9999)}}",
  "customer": "{{$person.fullName}}",
  "email": "{{$internet.email}}",
  "product": "{{$commerce.productName}}",
  "shippingAddress": "{{$location.streetAddress}}, {{$location.city}}",
  "orderedAt": "{{$date.between(from='2024-01-01',to='2024-12-31',format='yyyy-MM-dd')}}"
}

Ekspresi dapat menerima parameter. Misalnya:

• {{$number.int(min=1000,max=9999)}} membatasi rentang angka.
• {{$date.between(...)}} menghasilkan tanggal dalam rentang tertentu.
• Anda dapat menggabungkan teks statis dan beberapa ekspresi dalam satu nilai.

Untuk data spesifik wilayah, gunakan locale mock agar nama, alamat, dan nomor telepon sesuai bahasa atau negara target. Lihat referensi Faker.js di Apidog untuk daftar metode lengkap.

Smart mock bersifat dinamis, tetapi belum kondisional. Untuk merespons berdasarkan isi permintaan, buat expectation.

Panduan: POST /login mengembalikan 200 atau 401

Misalnya endpoint POST /login menerima body berikut:

{
  "username": "[e-mail]",
  "password": "whatever"
}

Target perilakunya:

• [e-mail] menerima 200 dan token.
• Pengguna lain menerima 401.

1. Buka tab konfigurasi mock

Lokasinya bergantung pada mode kerja:

• Dalam mode DEBUG (Request-first), buka endpoint lalu pilih tab Mock.

• Dalam mode DESIGN (Design-first), buka endpoint lalu pilih tab Advanced mock.

Kedua tab tersebut membuka daftar expectation yang sama. Jika belum memiliki proyek, unduh Apidog, lalu buat atau impor endpoint /login.

2. Tambahkan expectation sukses

Klik New expectation, lalu:

1. Beri nama login-success.
2. Tambahkan kondisi parameter body.
3. Isi nama properti dengan username.
4. Atur operator menjadi sama dengan.
5. Isi nilainya dengan [e-mail].

Untuk properti body bersarang, gunakan jalur titik. Contohnya:

user.email

Masukkan payload sukses ke Response data:

{
  "token": "mock-jwt-{{$string.uuid}}",
  "user": {
    "id": 4821,
    "username": "[e-mail]",
    "role": "member"
  }
}

Simpan expectation. Status HTTP default adalah 200, sehingga tidak perlu diubah.

3. Tambahkan expectation gagal

Klik New expectation lagi, lalu:

1. Beri nama login-failure.
2. Biarkan kondisi kosong agar menjadi fallback.
3. Masukkan body error berikut:

{
  "error": "invalid_credentials",
  "message": "Username or password is incorrect."
}

Buka tab More, kemudian ubah HTTP Status Code menjadi 401.

Di tab More, Anda juga dapat mengatur:

• Response Delay dalam milidetik.
• Header respons kustom.
• Status HTTP untuk skenario error.

Misalnya, tambahkan delay 400ms untuk memastikan loading spinner frontend terlihat saat pengujian.

4. Pastikan urutan expectation benar

Expectation dievaluasi dari atas ke bawah. Kecocokan pertama akan digunakan.

Urutan yang benar:

1. login-success — kondisi username = [e-mail]
2. login-failure — tanpa kondisi

Jika login-failure diletakkan di atas, aturan tanpa kondisi akan menangkap semua permintaan. Akibatnya, login-success tidak pernah dijalankan.

Uji mock URL endpoint Anda:

# pengguna dikenal -> 200 dengan token
curl -X POST https://<host-mock-Anda>/login \
  -H "Content-Type: application/json" \
  -d '{"username":"[e-mail]","password":"whatever"}'

# pengguna lain -> 401
curl -X POST https://<host-mock-Anda>/login \
  -H "Content-Type: application/json" \
  -d '{"username":"[e-mail]","password":"whatever"}'

Panduan: respons berbeda untuk /orders/{id}

Anda juga dapat membuat respons berbeda berdasarkan parameter path. Misalnya:

• /orders/5001 mengembalikan pesanan berstatus shipped.
• /orders/5002 mengembalikan pesanan berstatus cancelled.
• ID lain mengembalikan pesanan generik berstatus pending.

Buat satu expectation untuk setiap status.

Expectation order-shipped

Kondisi:

path parameter id = 5001

Response data:

{
  "id": 5001,
  "status": "shipped",
  "total": 129.9,
  "trackingNumber": "1Z{{$string.alphanumeric(length=16)}}",
  "shippedAt": "{{$date.recent(days=3,format='yyyy-MM-dd')}}"
}

Expectation order-cancelled

Kondisi:

path parameter id = 5002

Response data:

{
  "id": 5002,
  "status": "cancelled",
  "total": 0,
  "cancelledAt": "{{$date.recent(days=1,format='yyyy-MM-dd')}}",
  "refundIssued": true
}

Tambahkan expectation terakhir tanpa kondisi untuk menjadi fallback, misalnya respons pesanan pending.

Urutkan expectation seperti ini:

1. order-shipped
2. order-cancelled
3. order-pending tanpa kondisi

Anda juga dapat menggabungkan beberapa kondisi. Misalnya, cocokkan parameter path id sekaligus header tertentu. Semua kondisi harus cocok karena Apidog menggabungkannya dengan logika AND.

Kondisi dapat menggunakan:

• Parameter body JSON
• Parameter path
• Parameter query
• Header
• Cookie
• Alamat IP

Memaksa status error sesuai permintaan

Anda tidak memerlukan backend yang rusak untuk menguji UI error. Buat expectation yang dipicu oleh header yang Anda kendalikan dari klien.

Contoh: paksa respons 500 saat header berikut dikirim:

X-Mock-Scenario: server-error

Buat expectation dengan kondisi header tersebut, lalu gunakan response body berikut:

{
  "error": "internal_error",
  "requestId": "{{$string.uuid}}",
  "message": "Something went wrong on our end. Please retry."
}

Di tab More, atur HTTP Status Code menjadi 500.

Sekarang endpoint yang sama dapat:

• Mengembalikan 200 secara normal.
• Mengembalikan 500 ketika klien mengirim header skenario.

Pola ini juga dapat digunakan untuk:

• 404
• 429, dengan header Retry-After
• 503

Jika Anda ingin memvalidasi respons error ini secara otomatis, gunakan penegasan API.

Untuk proyek tim, expectation dapat diaktifkan atau dinonaktifkan secara terpisah pada lingkungan mock lokal dan cloud. Contohnya, simpan aturan 500 aktif secara lokal, tetapi nonaktifkan di cloud mock yang digunakan tim.

Ketika aturan tidak cukup: gunakan mock script

Expectation cocok untuk aturan tetap. Namun, gunakan Mock Script jika Anda perlu:

• Menghitung total dari item pesanan.
• Menghasilkan output berdasarkan beberapa input.
• Mengubah bentuk respons secara dinamis.
• Membaca nilai dari body atau header permintaan.

Mock script adalah JavaScript yang berjalan pada respons Smart mock. Aktifkan bagian Mock Script di bagian bawah tab Mock.

Dua global utama tersedia:

• $$.mockRequest untuk membaca permintaan masuk.
• $$.mockResponse untuk membentuk respons keluar.

Contoh script untuk menghitung total pesanan dan menggunakan header mata uang:

const body = $$.mockRequest.body;
const items = body.items || [];

const subtotal = items.reduce((sum, item) => {
  return sum + item.price * item.quantity;
}, 0);

const currency = $$.mockRequest.headers["x-currency"] || "USD";

$$.mockResponse.setCode(201);
$$.mockResponse.setBody({
  orderId: Math.floor(Math.random() * 90000) + 10000,
  currency: currency,
  subtotal: subtotal,
  tax: Number((subtotal * 0.08).toFixed(2)),
  total: Number((subtotal * 1.08).toFixed(2))
});

API yang umum digunakan:

// Membaca request
$$.mockRequest.getParam("key");
$$.mockRequest.headers;
$$.mockRequest.cookies;
$$.mockRequest.body;
$$.mockRequest.formdata;
$$.mockRequest.urlencoded;

// Membentuk response
$$.mockResponse.setBody({});
$$.mockResponse.setCode(200);
$$.mockResponse.setDelay(500);
$$.mockResponse.json();
$$.mockResponse.headers;
$$.mockResponse.code;

Untuk operasi JavaScript yang lebih kompleks, lihat referensi JavaScript MDN.

Batasan penting mock script

Mock script hanya berjalan dengan Smart mock.

Mock script tidak diterapkan pada:

• Mock expectation
• Contoh respons
• Respons expectation yang cocok

Jika sebuah expectation cocok, script tidak akan berjalan. Karena itu, pilih pendekatan per endpoint:

Kebutuhan	Gunakan
Respons berbeda berdasarkan kondisi tetap	Mock expectation
Status 200, 401, 404, 500, atau 429 berdasarkan header/path/body	Mock expectation
Perhitungan dari body permintaan	Mock script
Respons yang bergantung pada banyak input	Mock script

Urutan prioritas mock

Untuk setiap permintaan mock, Apidog menggunakan urutan berikut:

1. Memeriksa semua expectation dari atas ke bawah.
2. Mengembalikan respons dari expectation pertama yang seluruh kondisinya cocok.
3. Jika tidak ada expectation yang cocok, menggunakan Mock method priority pada: Project Settings → Feature Settings → Mock Settings.
4. Smart mock menghasilkan respons berdasarkan skema endpoint. Mock script, jika aktif, berjalan pada jalur Smart mock ini.

Model mentalnya:

Expectation spesifik
  ↓
Expectation fallback tanpa kondisi
  ↓
Smart mock
  ↓
Mock script

Urutkan aturan dari paling spesifik ke paling umum. Letakkan expectation tanpa kondisi di bagian bawah jika Anda ingin fallback yang eksplisit.

Untuk memilih strategi mocking berdasarkan kebutuhan, baca kasus penggunaan mocking API.

Hal penting sebelum merilis

Perhatikan batasan berikut agar tidak membuang waktu saat debugging:

• Kondisi parameter tidak mendukung {{variables}}.
• Variabel proyek dan lingkungan Apidog tidak tersedia di dalam mock expectation.
• Kondisi body hanya mendukung JSON, bukan XML.
• Properti body JSON harus dicocokkan dengan jalur JSON, seperti user.email.
• Format body kondisi harus mengikuti spesifikasi endpoint.
• Endpoint form-data harus menggunakan kondisi form-data, bukan JSON.
• Mock script tidak menyediakan fungsi logging.
• Objek pm tidak tersedia di mock script.
• Variabel Apidog tidak dapat digunakan di mock script.
• Simpan logika script agar mandiri dan tidak bergantung pada runtime test script.

Otomatiskan alur kerja dengan Apidog CLI

Mock server tetap dijalankan melalui GUI dan cloud Apidog. Apidog CLI tidak menyediakan perintah untuk menjalankan server mock lokal.

Namun, CLI membantu menjaga kontrak API tetap sinkron. Karena respons mock dibuat dari skema endpoint, perubahan spesifikasi akan langsung memengaruhi respons mock.

Anda dapat menggunakan CLI dan agen kode AI seperti Cursor, Claude Code, Trae, atau Codex untuk membuat dan memperbarui endpoint serta skema proyek.

Setelah frontend menggunakan mock, jalankan skenario pengujian terhadap backend nyata di CI:

apidog run -t <id_skenario> -e <id_lingkungan> -r cli

Perintah tersebut menjalankan skenario pengujian dan melaporkan hasilnya, sehingga mock dan pengujian backend menggunakan sumber kebenaran kontrak yang sama.

Lihat panduan instalasi Apidog CLI dan panduan Apidog CLI di GitHub Actions untuk integrasi pipeline.

FAQ

Mengapa expectation saya diabaikan?

Biasanya karena urutan atau format kondisi.

Periksa hal berikut:

1. Expectation spesifik harus berada di atas expectation tanpa kondisi.
2. Body JSON harus menggunakan jalur JSON yang benar.
3. Format kondisi harus sesuai spesifikasi endpoint.
4. Endpoint form-data tidak boleh menggunakan kondisi JSON.

Baca kembali gambaran umum mocking API jika perlu memeriksa konfigurasi dasar.

Dapatkah mock script dan mock expectation digunakan pada respons yang sama?

Tidak. Mock script hanya berjalan pada Smart mock. Jika expectation cocok, script tidak dieksekusi.

Bagaimana mengembalikan 401 atau 500 tanpa mengubah default 200?

Buat expectation khusus dengan kondisi yang Anda kontrol dari klien, misalnya header. Lalu atur status HTTP di tab More. Respons default tetap 200; respons error hanya muncul ketika kondisi cocok.

Dapatkah kondisi menggunakan variabel lingkungan?

Tidak. Nilai {{variable}} Apidog tidak tersedia dalam mock expectation. Gunakan nilai literal pada kondisi.

Apa yang terjadi jika tidak ada expectation yang cocok?

Apidog menggunakan Mock method priority pada pengaturan proyek. Smart mock kemudian menghasilkan respons berdasarkan skema endpoint. Jika Anda ingin fallback tertentu, tambahkan expectation tanpa kondisi di bagian bawah.

Ringkasan

Gunakan Smart mock untuk data dinamis dari skema. Gunakan mock expectation untuk percabangan berbasis aturan:

• 200 untuk pengguna dikenal, 401 untuk pengguna lain.
• Body pesanan berbeda berdasarkan ID atau status.
• 500, 404, 429, atau 503 sesuai skenario pengujian.

Gunakan mock script hanya ketika respons perlu dihitung dari permintaan. Ingat bahwa mock script hanya berjalan dengan Smart mock, bukan expectation.

Prinsip utamanya sederhana: letakkan expectation paling spesifik di atas, fallback di bawah, lalu biarkan Smart mock menangani sisanya. Unduh Apidog untuk membuat mock kondisional pertama Anda.