Cara Menggunakan Apidog CLI di Windsurf

Agen Cascade di Windsurf bekerja dalam loop: mengedit file, menjalankan perintah terminal, membaca output, lalu menentukan langkah berikutnya. Agar pengujian API ikut masuk ke loop ini, jalankan skenario Apidog melalui CLI, bukan hanya dari GUI. Paket npm apidog-cli memungkinkan Cascade menjalankan tes, memeriksa kode keluar, lalu memperbaiki kode saat hasilnya gagal.

Coba Apidog hari ini

Sebelum melanjutkan, pastikan CLI sudah tersedia dan akun Anda sudah diautentikasi:

apidog --version

Jika CLI belum terinstal, ikuti panduan instalasi Apidog CLI dengan agen pengkodean AI. Panduan tersebut mencakup instalasi npm, autentikasi, dan eksekusi pertama.

Windsurf yang Dibahas

Windsurf adalah IDE beragen dari Codeium. Agen bawaannya, Cascade, berjalan secara lokal dan dapat:

• membaca file di repositori;
• mengedit kode;
• menjalankan perintah shell di terminal terintegrasi;
• membaca output perintah;
• meminta persetujuan berdasarkan pengaturan eksekusi otomatis.

Panduan ini membahas Windsurf IDE dan Cascade, bukan ekstensi browser atau plugin autocomplete.

Jika belum menggunakannya, mulai dari cara mengunduh dan menginstal Windsurf. Setelah Cascade terbuka di proyek, tambahkan aturan proyek agar ia tahu cara menjalankan Apidog CLI.

Langkah 1: Tambahkan aturan Apidog ke .windsurf/rules

Cascade membaca aturan proyek dari file Markdown sebelum mulai bekerja. Buat direktori berikut di root repositori:

.windsurf/rules/

Kemudian buat file .windsurf/rules/apidog.md.

Windsurf juga mendukung .windsurfrules di root workspace dan ~/.codeium/windsurf/memories/global_rules.md untuk aturan global. Namun, gunakan .windsurf/rules/ untuk instruksi khusus repositori.

Referensi lengkap tersedia di dokumentasi aturan dan memori Windsurf.

Isi file apidog.md dengan aturan seperti berikut:

# 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 mengubah kode yang menyentuh API, jalankan skenario dan tindak lanjuti hasilnya.

Aturan dalam file lebih andal daripada instruksi sekali pakai di chat karena:

• tetap tersedia di setiap sesi Cascade;
• dibagikan kepada tim melalui Git;
• dimuat otomatis saat Cascade memulai konteks proyek;
• memastikan ID skenario dan perintah tes konsisten.

Langkah 2: Salin perintah yang benar dari Apidog

Jangan menebak nilai <scenario_id> dan <env_id>. Apidog menyediakan perintah yang sudah berisi ID dan konfigurasi yang tepat.

1. Buka skenario pengujian di Apidog.
2. Buka tab CI/CD.
3. Salin perintah apidog run yang tersedia.
4. Ganti baris contoh dalam .windsurf/rules/apidog.md dengan perintah tersebut.

Contoh hasil akhirnya:

apidog run -t <scenario_id> -e <env_id> -r cli

Dengan cara ini, Cascade menjalankan skenario dan environment yang benar untuk proyek Anda.

Untuk detail setiap flag, lihat referensi perintah apidog run.

Langkah 3: Minta Cascade menjalankan tes API

Setelah aturan tersedia, buka Cascade di repositori Anda. Cascade akan memuat .windsurf/rules/apidog.md saat dimulai.

Setelah membuat perubahan API, gunakan prompt seperti ini:

Jalankan skenario Apidog dan beritahu saya kode keluar.

Cascade seharusnya menjalankan perintah apidog run dari file aturan.

Apakah perintah dapat berjalan tanpa persetujuan bergantung pada konfigurasi eksekusi otomatis Windsurf:

• Dinonaktifkan — setiap perintah memerlukan persetujuan.
• Hanya Daftar Putih — hanya perintah pada allow list yang berjalan otomatis.
• Otomatis — menggunakan pertimbangan model premium.
• Turbo — menjalankan semua perintah kecuali yang diblokir deny list.

Untuk mengizinkan apidog run tanpa melonggarkan aturan lain, tambahkan apidog ke pengaturan:

windsurf.cascadeCommandsAllowList

Pengaturan blokirnya adalah:

windsurf.cascadeCommandsDenyList

Jika sebuah perintah cocok dengan allow list dan deny list, deny list yang berlaku. Lihat dokumentasi terminal Windsurf untuk konfigurasi lengkap.

Langkah 4: Baca hasil tes di terminal Cascade

Reporter cli menampilkan hasil eksekusi langsung di terminal Cascade, termasuk:

• request yang dijalankan;
• asersi yang diperiksa;
• status lulus atau gagal;
• nilai yang diharapkan dan nilai aktual;
• ringkasan eksekusi.

Saat tes gagal, gunakan output tersebut untuk mengarahkan perbaikan. Misalnya, Cascade dapat menemukan apakah kegagalan disebabkan oleh status HTTP yang salah, field respons yang hilang, atau nilai respons yang tidak sesuai.

Untuk membuat laporan HTML, gunakan reporter tambahan:

apidog run -t <scenario_id> -e <env_id> -r cli,html

Reporter html menulis laporan mandiri ke:

./apidog-reports

Tetap sertakan cli agar Cascade dapat membaca output inline dan menentukan langkah berikutnya.

Untuk format reporter lain, termasuk JUnit untuk CI, lihat panduan lengkap Apidog CLI dan cara membaca laporan tes Apidog CLI.

Jadikan Tes API Bagian dari Loop Cascade

Tujuannya bukan hanya menjalankan perintah secara manual. Tujuannya adalah memasukkan pengujian API ke loop edit-test-fix Cascade.

Contoh alurnya:

1. Cascade mengubah handler respons checkout.
2. Cascade menjalankan skenario Apidog terhadap staging.
3. Cascade membaca kode keluar.
4. Jika kode keluar 0, Cascade melanjutkan pekerjaan.
5. Jika kode keluar bukan 0, Cascade membaca asersi yang gagal.
6. Cascade memperbaiki kode dan menjalankan skenario lagi.

Dengan aturan proyek yang jelas, tes API diperlakukan seperti unit test: perubahan kode diikuti validasi, lalu perbaikan bila diperlukan.

Tetap gunakan Apidog untuk membuat dan memelihara skenario secara visual. Cascade bertugas menjalankan perintah dan membaca hasilnya. Untuk pola yang lebih luas, lihat cara menggunakan agen AI untuk pengujian API dan alat uji AI Apidog.

Verifikasi Cascade Benar-Benar Menjalankan CLI

Jangan hanya mengandalkan ringkasan agen. Verifikasi eksekusi dengan tiga pemeriksaan berikut.

1. Pastikan perintah benar-benar dijalankan

Cari perintah literal berikut di terminal Cascade:

apidog run ...

Pastikan outputnya muncul setelah perintah tersebut. Jika Cascade menyatakan tes sudah dijalankan tetapi tidak ada perintah atau output terminal, minta ia menjalankan ulang dan menampilkan output mentah.

2. Periksa kode keluar

Tanyakan secara langsung:

Berapa kode keluar dari perintah apidog run itu?

Aturannya sederhana:

• kode keluar 0: semua asersi lulus;
• kode keluar bukan 0: setidaknya satu asersi gagal.

Jika narasi Cascade mengatakan tes lulus tetapi kode keluarnya bukan nol, percayai kode keluar.

3. Pastikan ID skenario dan environment benar

Jika muncul error seperti scenario not found, Cascade mungkin menggunakan ID yang salah.

Periksa kembali:

• nilai setelah -t;
• nilai setelah -e;
• perintah pada tab CI/CD Apidog;
• isi .windsurf/rules/apidog.md.

File aturan harus menjadi sumber kebenaran untuk perintah yang digunakan Cascade.

Opsional: Hubungkan Server Apidog MCP

Apidog CLI cukup untuk menjalankan pengujian. Jika Anda ingin Cascade juga membaca spesifikasi API saat menulis kode, hubungkan server MCP.

Cascade mendukung Model Context Protocol dan membaca konfigurasi server dari:

~/.codeium/windsurf/mcp_config.json

Anda dapat mengedit file tersebut langsung atau mengelolanya melalui panel MCP di Cascade. Lihat referensi MCP Windsurf dan cara mengatur server MCP di Windsurf.

Server MCP Apidog mengekspos spesifikasi API melalui MCP. Pembagian tugasnya:

• Apidog CLI: menjalankan skenario dan menghasilkan hasil tes.
• Apidog MCP: memberi agen akses ke skema dan spesifikasi API.

Troubleshooting

Cascade mengabaikan aturan

Periksa hal berikut:

• file berada di .windsurf/rules/ pada root repositori;
• file menggunakan ekstensi .md;
• isi file tidak melebihi batas 12.000 karakter;
• Cascade sudah dimulai ulang setelah perubahan aturan.

Cascade mencoba menambahkan token akses

Jangan simpan token akses di file aturan yang dikomit. Mesin seharusnya sudah diautentikasi melalui:

apidog login

Perkuat instruksi dalam aturan:

Jangan pernah menambahkan token akses ke perintah.

Untuk detail autentikasi, lihat panduan autentikasi Apidog CLI.

Cascade mengarang flag CLI

Jika muncul error unknown option, minta Cascade menjalankan:

apidog run --help

Gunakan flag yang ditampilkan oleh versi CLI yang benar-benar terinstal di mesin Anda.

Cascade melaporkan lulus saat tes gagal

Kembalilah ke kode keluar. Jika kode keluar bukan nol, eksekusi gagal, meskipun ringkasan Cascade menyatakan sebaliknya.

Dari Agen Harian ke Loop yang Diuji

Konfigurasinya sederhana:

1. Instal apidog-cli mengikuti panduan instalasi.
2. Buat .windsurf/rules/apidog.md.
3. Tempel perintah apidog run dari tab CI/CD Apidog.
4. Instruksikan Cascade untuk menjalankan skenario setelah perubahan API.
5. Gunakan kode keluar sebagai sumber status yang benar.

Dengan setup ini, endpoint rusak dapat terdeteksi saat Cascade masih mengerjakan perubahan, bukan setelah kode dikirim.

Anda tetap membuat skenario secara visual di Apidog, sementara Cascade menjalankannya sebagai bagian dari loop pengembangan. Setelah alur lokal berfungsi, gunakan perintah yang sama di pipeline melalui Apidog CLI di GitHub Actions.

Unduh Apidog, buat satu skenario, salin perintah apidog run ke aturan Windsurf, lalu biarkan Cascade menjalankannya pada perubahan API berikutnya.