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

Smart mock memberi Anda API palsu dalam hitungan detik. Ini membaca skema endpoint Anda dan mengembalikan data yang masuk akal: email yang terlihat nyata, stempel waktu yang masuk akal, nama yang bukan xJ8kQ. Untuk sebagian besar pekerjaan frontend, itu sudah cukup untuk mengatasi hambatan Anda.

Kemudian Anda menemui kasus yang tidak dapat dijangkau oleh Smart mock. Anda ingin /login mengembalikan 200 untuk pengguna yang dikenal dan 401 sebaliknya. Anda ingin /orders/{id} mengembalikan pesanan yang sudah dikirim untuk satu ID dan pesanan yang dibatalkan untuk ID lain. Anda ingin memaksa 500 sesuai permintaan agar penanganan kesalahan Anda dapat dilatih sebelum mencapai produksi. Smart mock mengembalikan satu bentuk per endpoint, jadi tidak dapat bercabang berdasarkan permintaan. Itulah celah yang ditutup oleh panduan ini.

Apidog mengatasinya dengan dua fitur: ekspektasi mock untuk respons kondisional berbasis aturan, dan skrip mock untuk logika yang tidak dapat diungkapkan oleh aturan. Panduan ini menunjukkan keduanya dengan contoh konkret, dan menjelaskan urutan prioritas agar aturan kustom Anda selalu mengalahkan Smart mock. Jika Anda baru mengenal dasar-dasarnya, gambaran umum mocking API adalah pemanasan yang baik, dan Apidog adalah alat yang akan kita gunakan sepanjang panduan ini. OpenAPI Initiative mendokumentasikan alur kerja contract-first yang memungkinkan semua ini.

button

Apa arti sebenarnya dari mocking kondisional

Mock kondisional adalah sebuah aturan: ketika permintaan yang masuk terlihat *seperti ini*, kembalikan *itu*. Apidog membangun aturan-aturan ini dari dua lapisan.

Lapisan pertama adalah kustomisasi tingkat bidang dalam skema endpoint. Anda mengunci bidang ke nilai tetap, atau Anda melampirkan ekspresi Faker.js dinamis sehingga bervariasi pada setiap panggilan. Itu mengontrol *apa yang terkandung dalam bidang*, tetapi masih mengembalikan satu bentuk respons untuk endpoint.

Lapisan kedua adalah ekspektasi mock respons penuh. Ekspektasi adalah aturan bernama dengan kondisi opsional dan body respons, kode status, serta header-nya sendiri. Ekspektasi tanpa kondisi mengembalikan data tetap tanpa syarat. Ekspektasi dengan kondisi mengembalikan datanya hanya ketika permintaan cocok. Tumpuk beberapa di antaranya dan Anda mendapatkan percabangan nyata: respons B ketika permintaan cocok dengan kondisi A, body kesalahan ketika header hilang, payload yang berbeda per parameter path.

Lapisan kedua itu memungkinkan status kesalahan sesuai permintaan dan body per-permintaan. Sisa dari panduan ini membahasnya.

Nilai dinamis tingkat bidang terlebih dahulu

Sebelum percabangan, ada baiknya melihat bagaimana satu bidang mendapatkan nilainya, karena respons kondisional Anda akan menggunakan kembali sintaks yang sama.

Di dalam skema endpoint, bidang string apa pun dapat menampung ekspresi Faker.js yang ditulis sebagai {{$category.method}}. Apidog menyelesaikannya baru pada setiap panggilan mock, menggunakan tipe bidang yang sudah dideklarasikan oleh definisi JSON Schema Anda.

{
  "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')}}"
}

Metode berparameter berfungsi, jadi {{$number.int(min=1000,max=9999)}} membatasi nilai dan {{$date.between(...)}} menetapkan rentang dan format. Anda dapat menggabungkan teks statis dan beberapa ekspresi dalam satu bidang, itulah cara alamat di atas dibangun. Jika Anda memerlukan data spesifik wilayah, Apidog mendukung lokal mock yang dapat disesuaikan sehingga nama, alamat, dan nomor telepon Anda cocok dengan bahasa atau negara tertentu. Referensi Faker.js di Apidog mencakup seluruh katalog metode.

Antarmuka Apidog yang menunjukkan bagaimana ekspresi Faker.js digunakan untuk nilai dinamis di bidang skema, seperti 'id', 'customer', 'email', 'product', 'shippingAddress', dan 'orderedAt'.

Ini adalah wilayah Smart mock. Ini dinamis, tetapi tidak kondisional. Untuk bercabang berdasarkan permintaan, Anda beralih ke ekspektasi.

Kasus kanonis: POST /login menerima body JSON dengan username dan password. Pengguna yang dikenal harus mendapatkan 200 dengan token. Semua yang lain harus mendapatkan 401.

Buka tab yang benar

Tempat Anda mengonfigurasi ini tergantung pada mode kerja Anda:

Dalam mode DEBUG (Request-first), buka endpoint dan klik tab Mock.

Tangkapan layar antarmuka Apidog yang menyoroti tab 'Mock' di mode DEBUG (Request-first) untuk mengkonfigurasi ekspektasi mock.

Dalam mode DESIGN (Design-first), buka endpoint dan klik tab Advanced mock.

Tangkapan layar antarmuka Apidog yang menyoroti tab 'Advanced mock' di mode DESIGN (Design-first) untuk mengkonfigurasi ekspektasi mock.

Keduanya mengarah ke daftar ekspektasi yang sama. Jika Anda ingin mengikuti dan belum memiliki aplikasi, Unduh Apidog dan impor atau buat endpoint /login terlebih dahulu.

Tambahkan ekspektasi sukses

Klik New expectation. Beri nama ekspektasi seperti login-success. Sekarang tambahkan kondisi. Karena username berada dalam body permintaan JSON, Anda mencocokkannya sebagai parameter body: masukkan jalur JSON dari properti target, username, di bidang nama, dan atur kondisi agar sama dengan alice@example.com.

Tangkapan layar Apidog yang menunjukkan konfigurasi ekspektasi mock, dengan bidang 'expectation name' diatur ke 'login-success' dan kondisi yang cocok dengan parameter body 'username' yang sama dengan 'alice@example.com'.

Kondisi parameter body hanya JSON, dan dicocokkan melalui jalur JSON di bidang nama, jadi properti bersarang menggunakan jalur titik seperti user.email. Isi Response data dengan payload sukses:

{
  "token": "mock-jwt-{{$string.uuid}}",
  "user": {
    "id": 4821,
    "username": "alice@example.com",
    "role": "member"
  }
}

Simpan. HTTP Status Code default adalah 200, jadi Anda tidak perlu menyentuh hal lain untuk jalur yang berhasil.

Tambahkan ekspektasi gagal

Klik New expectation lagi. Beri nama login-failure dan biarkan kondisinya kosong agar berfungsi sebagai penangkap semua. Atur Response data ke body error:

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

Yang ini membutuhkan status non-default. Buka tab More dari ekspektasi dan atur HTTP Status Code menjadi 401. Saat Anda di sana, perhatikan bahwa tab More juga tempat Anda mengatur Response Delay dalam milidetik (default 0) dan header respons kustom apa pun. Penundaan 400ms adalah cara murah untuk memastikan spinner loading Anda benar-benar muncul.

Urutan penting

Ekspektasi dievaluasi dari atas ke bawah, dan kecocokan pertama menang. Jadi login-success harus berada *di atas* login-failure. Permintaan dengan username sama dengan alice@example.com akan cocok dengan aturan pertama dan mengembalikan token. Yang lainnya akan jatuh ke aturan kegagalan tanpa syarat dan mendapatkan 401. Jika Anda membalik urutannya, aturan kondisi kosong akan cocok dengan semuanya dan kasus sukses Anda tidak akan pernah terpicu.

Salin mock URL dari endpoint dan uji kedua jalur:

# pengguna dikenal -> 200 dengan token
curl -X POST https://<host-mock-Anda>/login \
  -H "Content-Type: application/json" \
  -d '{"username":"alice@example.com","password":"whatever"}'

# orang lain -> 401
curl -X POST https://<host-mock-Anda>/login \
  -H "Content-Type: application/json" \
  -d '{"username":"stranger@example.com","password":"whatever"}'

Panduan: body yang berbeda untuk /orders/{id} berdasarkan status

Kasus umum kedua bercabang pada parameter path. Anda ingin /orders/{id} mengembalikan pesanan yang sudah dikirim untuk satu ID dan pesanan yang dibatalkan untuk ID lain, sehingga UI Anda dapat merender setiap status tanpa backend langsung.

Buat satu ekspektasi per status. Untuk masing-masing, tambahkan kondisi pada parameter path id, lalu isi Response data yang cocok.

Ekspektasi order-shipped, kondisi: parameter path id sama dengan 5001.

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

Ekspektasi order-cancelled, kondisi: parameter path id sama dengan 5002.

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

Tambahkan ekspektasi terakhir tanpa kondisi yang mengembalikan pesanan tertunda generik, sehingga ID lainnya tetap mendapatkan respons yang valid alih-alih tidak cocok. Urutkan aturan spesifik di atas aturan penangkap semua, simpan, dan Anda memiliki mock yang merender setiap status pesanan sesuai permintaan. Pencampuran kondisi juga berfungsi: tambahkan kondisi header bersamaan dengan kondisi path dan keduanya harus terpenuhi, karena Apidog menggabungkan beberapa kondisi dengan logika AND (persimpangan kondisi, dalam istilah dokumen).

Kondisi tidak terbatas pada body dan path. Anda dapat mencocokkan parameter kueri, parameter header, parameter cookie, dan bahkan alamat IP, yang memungkinkan Anda membatasi respons untuk klien tertentu selama pengujian.

Memaksa status kesalahan sesuai permintaan

Anda tidak memerlukan backend yang rusak untuk menguji respons yang rusak. Ekspektasi ditambah tab More memberi Anda status apa pun yang Anda inginkan.

Untuk memaksa 500, tambahkan ekspektasi yang kondisinya adalah sesuatu yang Anda kendalikan dari klien, misalnya header X-Mock-Scenario sama dengan server-error. Atur Response data-nya ke body error yang realistis dan HTTP Status Code-nya ke 500 di tab More.

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

Sekarang endpoint yang sama menyajikan 200 normal secara default dan 500 kapan pun Anda mengirim header tersebut. Lakukan hal yang sama untuk 404, 429 (dengan header Retry-After yang diatur di tab More), atau 503. Penanganan kesalahan frontend Anda akhirnya memiliki sesuatu untuk ditangkap. Jika Anda menegaskan respons ini dalam pemeriksaan otomatis, panduan penegasan API cocok dengan pengaturan ini.

Satu detail untuk proyek bersama: setiap ekspektasi dapat diaktifkan atau dinonaktifkan secara independen untuk lingkungan mock lokal dan cloud dari daftar ekspektasi. Jadi, Anda dapat menjaga aturan 500 tetap aktif secara lokal sambil mematikannya di mock cloud yang digunakan rekan tim Anda.

Ketika aturan tidak cukup: skrip mock

Ekspektasi bersifat deklaratif. Mereka mencocokkan dan mengembalikan, tetapi tidak dapat menghitung. Ketika Anda membutuhkan bidang yang berasal dari permintaan, total yang dijumlahkan dari item baris, atau body yang berubah bentuk berdasarkan beberapa input sekaligus, Anda membutuhkan skrip mock.

Skrip mock adalah JavaScript yang berjalan terhadap respons mock. Ini berada di bagian Mock Script di bagian bawah tab Mock dan diaktifkan dengan sakelar. Skrip ini mengekspos dua global:

$$.mockRequest: membaca permintaan masuk melalui getParam(key), ditambah headers, cookies, body, formdata, dan urlencoded.
$$.mockResponse: membentuk respons keluar melalui setBody(), setCode(), setDelay(), json(), dan properti headers dan code.

Berikut adalah skrip yang menghitung total pesanan dari item baris yang diposting dan menggemakan kembali header mata uang pemanggil:

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))
});

Alur kerjanya adalah: Smart mock menghasilkan respons awal, skrip Anda membaca $$.mockRequest dan $$.mockResponse saat ini, menerapkan logikanya, memanggil $$.mockResponse.setBody() (dan setCode, setDelay, atau headers sesuai kebutuhan), dan mesin mengembalikan hasil akhir. Referensi JavaScript MDN adalah teman yang solid jika Anda ingin mendorong logika lebih jauh dengan metode array atau perhitungan tanggal.

Satu aturan yang sering membingungkan orang

Skrip mock hanya berfungsi dengan Smart mock. Mereka tidak berlaku untuk ekspektasi mock atau contoh respons. Ini adalah hal terpenting yang perlu dipahami: Anda tidak dapat menggabungkan skrip mock dengan respons berbasis ekspektasi. Jika sebuah ekspektasi cocok dengan permintaan, skrip tidak akan pernah berjalan. Jadi, pilih satu jalur per endpoint. Gunakan ekspektasi ketika Anda bercabang pada kondisi tetap dan mengembalikan body yang sudah ditentukan. Gunakan skrip mock ketika Anda membutuhkan output terhitung dari basis yang dihasilkan oleh Smart mock.

Bagaimana urutan prioritas diselesaikan

Gabungkan semuanya dan inilah urutan yang dilewati Apidog untuk setiap permintaan mock:

Ini memeriksa ekspektasi Anda, dari atas ke bawah. Ekspektasi pertama yang semua kondisinya cocok akan menang, dan responsnya dikembalikan. Inilah mengapa aturan kustom mengalahkan Smart mock: ekspektasi yang cocok akan memotong semua yang ada di bawahnya.
Jika tidak ada ekspektasi yang cocok, Apidog akan kembali ke Mock method priority yang Anda atur di Project Settings - Feature Settings - Mock Settings. Itu adalah tingkat di mana Smart mock (dan skrip mock apa pun yang melekat padanya) menghasilkan respons.

Model mentalnya sederhana: aturan spesifik terlebih dahulu, data yang dihasilkan kedua. Urutkan ekspektasi Anda dari yang paling spesifik hingga paling tidak spesifik, simpan aturan penangkap semua kondisi kosong di bagian bawah jika Anda menginginkan kecocokan yang dijamin, dan biarkan Smart mock menangani yang lainnya. Untuk tinjauan lebih dalam tentang kapan harus mengandalkan setiap lapisan, panduan kasus penggunaan mocking API memetakan skenario umum ke fitur.

Hal-hal penting yang perlu diketahui sebelum Anda merilis

Beberapa batasan akan menyelamatkan Anda dari sesi debug yang membingungkan:

Kondisi parameter tidak mendukung {{variables}}. Variabel proyek dan lingkungan Apidog tidak tersedia di dalam ekspektasi mock, jadi masukkan nilai literal dalam kondisi Anda.
Kondisi parameter body hanya JSON, bukan XML, dan harus dicocokkan melalui jalur JSON di bidang nama.
Format body permintaan dalam kondisi harus cocok dengan spesifikasi API. Endpoint form-data harus di-mock dengan penempatan form-data, bukan JSON.
Di dalam skrip mock tidak ada fungsi logging, objek pm tidak tersedia (ini adalah lingkungan eksekusi yang berbeda dari skrip pengujian), dan variabel Apidog tidak dapat digunakan. Jaga agar logika skrip tetap mandiri.

Tidak ada fitur ini yang dikenakan pembatasan rencana dalam dokumen. Satu-satunya perbedaan lokal-versus-cloud adalah fungsional: tombol on/off independen per lingkungan yang dijelaskan sebelumnya, bukan paywall.

Otomatiskan alur kerja dengan Apidog CLI

Mocking di Apidog adalah kemampuan GUI dan cloud. Mesin mock menyajikan endpoint Anda dari URL mock lokal dan cloud, dan tidak ada perintah CLI yang menyiapkan server mock yang berjalan. Yang ditambahkan oleh Apidog CLI adalah kontrol atas sumber daya tempat mock tersebut dibangun.

Respons mock dihasilkan dari skema endpoint, sehingga keakuratan mock Anda melacak keakuratan spesifikasi Anda. CLI, dan agen kode AI yang menggerakannya (Cursor, Claude Code, Trae, Codex), dapat membuat dan memperbarui endpoint dan skema dalam proyek Anda. Ubah kontrak dalam kode, sinkronkan, dan output mock tetap benar tanpa ada yang perlu membuka kembali aplikasi.

Setelah mock berhasil mengatasi pekerjaan frontend, skenario pengujian proyek yang sama berjalan tanpa kepala di CI untuk memvalidasi backend yang sebenarnya terhadap kontrak yang dijelaskan oleh mock:

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

Perintah tunggal itu mengeksekusi skenario pengujian Anda dan melaporkan hasilnya, sehingga mock dan verifikasi berbagi satu sumber kebenaran. Panduan instalasi Apidog CLI mencakup pengaturan, dan panduan Apidog CLI di GitHub Actions menyambungkannya ke pipeline.

FAQ

Mengapa ekspektasi saya diabaikan meskipun kondisinya terlihat benar? Hampir selalu karena urutan atau ketidakcocokan format. Ekspektasi dievaluasi dari atas ke bawah dan kecocokan pertama yang menang, jadi aturan kondisi kosong yang luas yang berada di atas aturan spesifik akan menelan permintaan. Juga konfirmasi format body cocok dengan spesifikasi (jalur JSON untuk body JSON, penempatan form-data untuk endpoint form). Gambaran umum mocking API mencakup dasar-dasar pengaturan jika Anda ingin memeriksa ulang.

Dapatkah saya menggunakan skrip mock dan ekspektasi mock pada respons yang sama? Tidak. Skrip mock hanya berjalan dengan Smart mock. Mereka diabaikan oleh ekspektasi mock dan contoh respons. Jika sebuah ekspektasi cocok, skrip tidak akan pernah dieksekusi, jadi pilih satu pendekatan per endpoint: ekspektasi untuk percabangan berbasis aturan, skrip untuk output yang dihitung.

Bagaimana cara mengembalikan 401 atau 500 tanpa merusak default 200? Tambahkan ekspektasi khusus dengan kondisi yang Anda kendalikan dari klien (header berfungsi dengan baik), lalu buka tab More-nya dan atur Kode Status HTTP. Respons default tetap 200; kesalahan hanya akan terpicu ketika kondisi cocok.

Dapatkah kondisi menggunakan variabel lingkungan saya? Tidak. Nilai {{variable}} Apidog tidak tersedia di dalam ekspektasi mock, dan kondisi parameter tidak mendukung {{variables}}. Gunakan nilai literal dalam kondisi.

Apa yang terjadi jika tidak ada ekspektasi yang cocok sama sekali? Apidog kembali ke Prioritas Metode Mock di Pengaturan Proyek - Pengaturan Fitur - Pengaturan Mock, di mana Smart mock menghasilkan respons dari skema Anda. Menambahkan ekspektasi penangkap semua kondisi kosong adalah cara untuk menjamin fallback spesifik sebagai gantinya.

Ringkasan

Smart mock menangani kasus umum, dan ekspektasi mock menangani semuanya dengan *jika* di dalamnya: 200 untuk pengguna yang dikenal dan 401 sebaliknya, body pesanan yang berbeda per status, 500 sesuai permintaan. Gunakan skrip mock hanya ketika Anda membutuhkan output yang dihitung yang tidak dapat diungkapkan oleh aturan, dan ingat bahwa itu hanya berjalan terhadap Smart mock. Ingat urutan prioritas (ekspektasi spesifik terlebih dahulu, data yang dihasilkan kedua) dan mock Anda akan bercabang persis seperti yang dilakukan API sungguhan. Unduh Apidog untuk membangun mock kondisional pertama Anda, gratis, tanpa kartu kredit.