Agen Cascade Windsurf menjalankan sebuah loop: ia mengedit file, menjalankan perintah terminal, membaca output, dan memutuskan apa yang harus dilakukan selanjutnya. Jadi, mengapa tes API Anda tidak berada dalam loop tersebut? Tes-tes itu berada di Apidog di balik GUI dan berjalan ketika seseorang ingat untuk mengklik. Cascade tidak pernah menyentuhnya.
Solusinya adalah satu blok konfigurasi. Apidog CLI adalah paket npm, apidog-cli, yang menjalankan skenario pengujian yang Anda buat di Apidog langsung dari terminal. Setelah CLI terinstal dan Cascade mengetahuinya, Windsurf menjalankan skenario Apidog dengan cara yang sama seperti menjalankan unit test Anda: jalankan perintahnya, baca kode keluar, perbaiki kode jika kembali merah.
Jika Anda belum menginstal CLI, lakukan itu terlebih dahulu. Cara menginstal Apidog CLI dengan agen pengkodean AI menjelaskan instalasi npm, autentikasi, dan jalankan pertama kali, dengan agen yang melakukan pengetikan. Artikel ini mengasumsikan apidog --version mencetak angka dan akun Apidog Anda telah diautentikasi.
Windsurf yang Mana yang Dibahas Ini
Windsurf adalah IDE beragen dari Codeium, dan agen bawaannya disebut Cascade. Cascade berjalan secara lokal, membaca repositori Anda, mengedit file, dan mengeksekusi perintah shell di terminal terintegrasi Anda, meminta persetujuan berdasarkan pengaturan eksekusi otomatis Anda. Ini adalah editor dan agennya, bukan ekstensi browser atau plugin pelengkapan otomatis.
Jika Anda belum mengaturnya, mulailah dengan cara mengunduh dan menginstal Windsurf. Setelah Cascade terbuka di proyek Anda, Anda dapat mengajarkannya tentang Apidog CLI melalui mekanisme aturannya sendiri, yang mengubah perintah "jalankan tes saya" sekali pakai menjadi sesuatu yang Cascade lakukan sendiri.
Langkah 1: Tambahkan aturan Apidog ke .windsurf/rules
Cascade membaca aturan proyek dari file Markdown sebelum mulai bekerja. Letakkan di direktori .windsurf/rules/ di root repositori Anda, satu aturan per file. Windsurf masih membaca file tunggal .windsurfrules lama di root ruang kerja, dan ~/.codeium/windsurf/memories/global_rules.md global yang berlaku untuk setiap proyek, tetapi untuk instruksi per-proyek, direktori .windsurf/rules/ adalah tempat yang tepat. Ini didokumentasikan dalam referensi aturan dan memori Windsurf.
Buat .windsurf/rules/apidog.md dengan blok seperti ini:
# Tes API Apidog
Proyek ini memiliki skenario tes Apidog. Jalankan dengan Apidog CLI:
apidog run -t <scenario_id> -e <env_id> -r cli
Aturan:
- Gunakan perintah persis di atas; jangan mengarang flag. Jalankan `apidog run --help` jika tidak yakin.
- `apidog run` keluar 0 jika setiap asersi lulus, bukan nol jika ada yang gagal.
Perlakukan keluar 0 sebagai lulus dan bukan nol sebagai gagal. Laporkan kode keluar yang sebenarnya.
- Mesin sudah diautentikasi melalui `apidog login`. Jangan pernah menambahkan
token akses ke perintah atau melakukan commit ke file ini.
- Setelah Anda mengubah kode yang menyentuh API, jalankan skenario dan tindak lanjuti hasilnya.
Mengapa file aturan, bukan pesan obrolan? ID skenario yang diketik ke dalam obrolan akan hilang saat sesi berakhir. ID di .windsurf/rules/apidog.md akan ada untuk setiap rekan tim dan setiap sesi Cascade mulai sekarang. Ia persisten, divariasikan dalam Git, dan Cascade memuatnya ke dalam konteks secara otomatis saat startup.
Langkah 2: Dapatkan perintah dari Apidog
<scenario_id> dan <env_id> dalam blok itu bukanlah placeholder yang Anda tebak. Apidog menghasilkan perintah yang tepat untuk Anda.
Buka skenario pengujian di Apidog, pergi ke tab CI/CD-nya, dan salin perintah apidog run yang sudah jadi. Perintah itu sudah memiliki ID skenario, ID lingkungan, dan flag reporter yang benar. Tempelkan perintah itu ke dalam .windsurf/rules/apidog.md Anda menggantikan baris contoh. Sekarang aturan tersebut berisi perintah yang benar-benar berfungsi pada proyek Anda, bukan templat.
Untuk anatomi lengkap perintah tersebut dan setiap flag yang diterimanya, lihat referensi perintah apidog run.
Langkah 3: Minta Cascade menjalankan tes
Dengan aturan yang sudah ada, buka Cascade di repo Anda. Ini memuat .windsurf/rules/apidog.md saat dimulai, jadi ia sudah tahu CLI ada. Buat perubahan yang menyentuh API Anda, atau cukup minta ia menjalankan pemeriksaan:
Jalankan skenario Apidog dan beritahu saya kode keluar.
Cascade mengeluarkan perintah apidog run dari aturan Anda. Apakah perintah itu berjalan tanpa prompt tergantung pada pengaturan eksekusi otomatis Anda. Windsurf menawarkan empat tingkat: Dinonaktifkan (setiap perintah memerlukan persetujuan), Hanya Daftar Putih (hanya perintah yang cocok dengan daftar putih Anda yang berjalan otomatis), Otomatis (pertimbangan model premium), dan Turbo (semua berjalan otomatis kecuali perintah yang masuk daftar hitam). Dalam mode Turbo, apidog run biasa akan dieksekusi sendiri; dalam mode yang lebih ketat, Cascade akan berhenti sejenak dan bertanya terlebih dahulu.
Jika Anda ingin apidog run dieksekusi otomatis tanpa melonggarkan segalanya, tambahkan ke daftar putih Anda. Pengaturannya adalah windsurf.cascadeCommandsAllowList, dapat diakses dari Command Palette di bawah Open Settings; tambahkan apidog dan Cascade menjalankan perintah tanpa bertanya. Pengaturan daftar hitam yang cocok adalah windsurf.cascadeCommandsDenyList, dan daftar hitam akan menang jika suatu perintah cocok dengan keduanya. Keduanya tercakup dalam dokumentasi terminal Windsurf. Skenario hanya-baca terhadap staging adalah jenis perintah yang aman dan dalam ruang kerja yang dibuat untuk entri daftar putih.
Langkah 4: Baca laporan di dalam Windsurf
Ketika sebuah eksekusi menghasilkan merah, laporan tersebut memiliki jawabannya. Reporter -r cli mencetak hasil langkah-demi-langkah dan ringkasan langsung di terminal Cascade: setiap permintaan, setiap asersi, dan mana yang gagal dengan nilai yang diharapkan versus nilai aktual. Asersi yang gagal menyebutkan bidang atau kode status yang tepat, yang biasanya cukup bagi Cascade untuk menemukan perbaikannya pada proses selanjutnya.
Untuk laporan yang dapat Anda buka di browser atau berikan kepada rekan tim, tambahkan reporter HTML:
apidog run -t <scenario_id> -e <env_id> -r cli,html
Reporter html menulis file mandiri ke ./apidog-reports. Pertahankan cli dalam daftar agar Cascade tetap mendapatkan output inline yang dibacanya untuk memutuskan langkah selanjutnya. Untuk setiap reporter, termasuk format JUnit yang di-parse oleh dashboard CI, lihat panduan lengkap Apidog CLI dan cara membaca laporan tes Apidog CLI.
Pengujian Windsurf dalam Loopnya Sendiri
Intinya adalah apa yang terjadi ketika Anda berhenti bertanya dan Cascade menjalankan skenario sendiri karena aturannya memerintahkannya.
Bayangkan Cascade mengedit handler yang membangun respons checkout. Loop-nya berubah. Ia mengedit kode, kemudian, alih-alih menyatakan kemenangan, menjalankan skenario Apidog Anda terhadap staging, membaca kode keluar, dan bertindak berdasarkan itu. Hijau, ia melanjutkan. Merah, ia membuka laporan, membaca asersi mana yang gagal (kode status, bidang yang hilang, nilai yang salah), mencoba perbaikan, dan menjalankannya kembali. Tes API menjadi bagian dari loop edit-test-fix yang sama yang sudah Cascade gunakan untuk menjalankan unit test Anda. Anda menulis satu aturan dan Cascade memasukkan perintah itu ke dalam cara kerjanya yang sudah ada.
Ini adalah model delegasikan-lalu-verifikasi yang membuat alur kerja agen apa pun aman. Cascade menjalankan perintah dan membaca hasilnya; Anda terus membuat skenario secara visual di Apidog dan memeriksa bahwa agen membaca kode keluar dengan jujur. Untuk pola yang lebih luas, lihat cara menggunakan agen AI untuk pengujian API dan alat uji AI Apidog.
Verifikasi Cascade Benar-benar Menjalankan CLI
Agen melaporkan keberhasilan yang tidak mereka peroleh, dan Cascade tidak terkecuali. Tiga pemeriksaan, berdasarkan seberapa sering mereka menemukan masalah.
Pertama, konfirmasikan apakah perintah tersebut benar-benar berjalan. Cascade menunjukkan perintah yang dieksekusi dan outputnya secara inline di terminal. Cari baris apidog run ... literal dan hasilnya di bawahnya. Jika Cascade mengatakan ia menjalankan tes tetapi Anda tidak melihat perintahnya, berarti ia meringkas sesuatu yang tidak pernah dilakukannya. Minta ia untuk menjalankan lagi dan tunjukkan output mentahnya.
Kedua, konfirmasikan kode keluar, yang paling penting. Tanyakan langsung:
Berapa kode keluar dari perintah apidog run itu?
apidog run keluar 0 saat setiap asersi lulus dan bukan nol saat ada yang gagal. Perilaku tunggal itu memungkinkan Cascade, atau pipeline, memperlakukan eksekusi sebagai gerbang yang bersih. Ketika prosa Cascade mengatakan "tes lulus" tetapi kode keluarnya bukan nol, maka kode keluar itulah yang benar.
Ketiga, pastikan ia menggunakan skenario yang sebenarnya. Jika sebuah eksekusi gagal dengan "scenario not found" (skenario tidak ditemukan), Cascade mungkin telah menciptakan atau salah mengingat ID. Periksa kembali nilai -t dan -e terhadap file aturan Anda dan perintah Apidog yang dihasilkan di tab CI/CD. ID di .windsurf/rules/apidog.md adalah kebenaran.
Opsional: Hubungkan server Apidog MCP
Menjalankan apidog run dari sebuah aturan mencakup sebagian besar yang Anda butuhkan. Untuk melangkah lebih jauh, hubungkan server MCP.
Cascade mendukung Model Context Protocol. Windsurf membaca daftar servernya dari ~/.codeium/windsurf/mcp_config.json, yang dapat Anda edit langsung atau kelola melalui panel MCP Cascade; formatnya didokumentasikan dalam referensi MCP Windsurf, dan cara mengatur server MCP di Windsurf menjelaskan melalui panel tersebut. Server MCP Apidog mengekspos spesifikasi API Anda melalui MCP, sehingga Cascade dapat membaca skema Anda saat menulis kode, bukan hanya setelah fakta. Pembagian kerjanya jelas: CLI menjalankan pengujian, dan MCP memberikan spesifikasi kepada agen.
Ketika Windsurf Salah
Beberapa kegagalan sering muncul selama pengaturan.
Ia mengabaikan aturan. Jika Cascade menjalankan perintah generik atau tidak sama sekali, aturan tersebut mungkin tidak dimuat. Konfirmasikan bahwa file berada di .windsurf/rules/ di root repositori Anda dan memiliki ekstensi .md. Setiap file aturan dibatasi hingga 12.000 karakter, jadi jaga agar blok Apidog tetap pendek. Memulai ulang Cascade akan memaksa pembacaan ulang yang baru.
Ia tetap meneruskan token akses. Jika Cascade mencoba menambahkan token akses ke perintah, ia menebak dari contoh publik. Aturan Anda sudah memberitahunya untuk tidak melakukannya, karena mesin sudah diautentikasi melalui apidog login. Perkuat baris tersebut, dan jangan pernah menempatkan token asli dalam file aturan yang akan dikomit. Untuk cara kerja autentikasi yang sebenarnya, lihat panduan autentikasi Apidog CLI.
Ia mengarang sebuah flag. Kesalahan "unknown option" berarti Cascade menebak sebuah flag yang tidak dimiliki versi Anda. Suruh ia menjalankan apidog run --help dan salin flag yang tepat dari sana, yang selalu benar untuk versi yang terinstal di Anda.
Ia melaporkan lulus pada eksekusi yang gagal. Ini adalah yang paling merugikan, dan alasan mengapa aturan kode keluar ada di file aturan Anda dan langkah verifikasi Anda. Ketika ringkasan dan kode keluar tidak sesuai, kode keluar yang menang.
Dari Agen Harian ke Loop yang Diuji
Itulah pengaturannya. Instal apidog-cli sekali mengikuti panduan instalasi, tambahkan aturan Apidog singkat ke direktori .windsurf/rules/ repo Anda, dan Cascade tahu cara menjalankan tes API Anda dan membaca hasilnya di dalam loop yang sama yang sudah digunakannya untuk mengedit kode. Endpoint yang rusak akan terdeteksi saat Cascade masih mengerjakan perubahan, bukan setelah dikirim.
Sebuah tes di balik GUI berjalan ketika manusia mengklik; sebuah perintah satu baris berjalan kapan pun Cascade memutuskan. Anda terus membangun skenario secara visual di Apidog, dan agen Anda menjalankannya tanpa Anda saksikan. Untuk menjalankan perintah yang sama dalam pipeline setelah berfungsi secara lokal, Apidog CLI di GitHub Actions mencakup rahasia, reporter, dan gating kode keluar. Unduh Apidog, buat satu skenario, masukkan perintah apidog run-nya ke dalam aturan Windsurf, dan saksikan Cascade mengambilnya pada perubahan berikutnya.