Cara Menggunakan Apidog CLI di Trae

Trae bekerja dalam sebuah perulangan: agen Builder membaca repositori, mengedit file, menjalankan perintah terminal, lalu membaca output untuk menentukan langkah berikutnya. Agar pengujian API ikut berada dalam perulangan tersebut, jalankan skenario Apidog dari terminal menggunakan apidog-cli, bukan hanya dari GUI. Dengan begitu, Builder dapat menjalankan tes, memeriksa kode keluar, lalu memperbaiki kode saat tes gagal.

Coba Apidog hari ini

Apidog CLI adalah paket npm bernama apidog-cli yang menjalankan skenario pengujian Apidog langsung dari terminal. Setelah CLI terinstal dan Trae mengetahui perintahnya, Builder dapat memperlakukannya seperti unit test: jalankan perintah, baca kode keluar, lalu tindak lanjuti hasilnya.

Sebelum melanjutkan, pastikan CLI sudah terinstal dan terautentikasi:

apidog --version

Jika Anda belum menyiapkannya, ikuti cara menginstal Apidog CLI dengan agen pengkodean AI. Panduan tersebut mencakup instalasi npm, autentikasi, dan eksekusi pertama.

Trae yang dimaksud

Artikel ini membahas Trae desktop IDE dari ByteDance, yang dibangun di atas VS Code dan memiliki mode agen bernama Builder. Builder dapat mengedit file dan menjalankan perintah terminal dengan persetujuan Anda.

Lihat detail produknya di situs resmi Trae. Artikel ini bukan tentang proyek GitHub trae-agent. Jika Anda dapat membuka Trae, melihat panel chat di samping editor, lalu memilih agen Builder, Anda berada di tempat yang tepat.

Agar Builder selalu mengetahui cara menjalankan tes API, simpan instruksinya sebagai aturan proyek. Jika Anda ingin memahami CLI secara terpisah dari Trae, baca panduan lengkap Apidog CLI.

Langkah 1: Tambahkan aturan proyek Trae

Trae membaca aturan proyek sebelum Builder mulai bekerja. Berdasarkan dokumentasi aturan Trae, buat file berikut di root repositori:

.trae/rules/project_rules.md

Tambahkan instruksi yang eksplisit: kapan tes harus dijalankan, perintah yang digunakan, dan bagaimana Builder harus memperlakukan kegagalan.

## Pengujian API dengan Apidog CLI

Ketika Anda mengubah kode yang menyentuh endpoint API, verifikasi dengan menjalankan
skenario pengujian Apidog, bukan hanya unit test.

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

Aturan:
- `apidog run` keluar dengan kode 0 ketika semua assertion lulus, dan non-nol jika ada kegagalan.
  Perlakukan kode keluar non-nol sebagai tes gagal, meskipun ringkasan terlihat berhasil.
- Mesin ini sudah diautentikasi melalui `apidog login`. Jangan pernah menambahkan flag
  `--access-token` dan jangan pernah menyimpan token di file ini.
- Jika sebuah flag tidak dikenal, jalankan `apidog run --help` dan gunakan flag yang tersedia.

Menyimpan instruksi dalam project_rules.md lebih andal daripada menuliskannya di chat. Instruksi chat dapat hilang saat sesi berakhir, sedangkan aturan proyek tetap tersedia untuk setiap anggota tim dan setiap sesi Builder berikutnya.

Untuk monorepo, Anda juga dapat menambahkan folder .trae/rules/ di dalam subdirektori layanan agar setiap layanan memiliki aturan pengujiannya sendiri.

Langkah 2: Salin perintah dari Apidog

Jangan menebak ID skenario atau ID environment secara manual.

1. Buka skenario pengujian di Apidog.
2. Buka tab CI/CD.
3. Salin perintah apidog run yang dihasilkan.
4. Tempelkan ID sebenarnya ke project_rules.md.

Contohnya:

apidog run -t 123456 -e 987654 -r cli

Ganti placeholder berikut pada aturan proyek Anda:

<scenario_id>
<env_id>

dengan nilai dari perintah yang dihasilkan Apidog. Untuk detail semua flag yang tersedia, lihat referensi perintah apidog run.

Langkah 3: Minta Builder menjalankan pengujian

Setelah aturan proyek tersedia, pilih mode Builder di Trae. Builder akan memuat project_rules.md saat inisialisasi.

Anda dapat meminta pemeriksaan secara langsung:

Jalankan skenario pengujian Apidog dan beri tahu saya kode keluarnya.

Atau lakukan perubahan pada handler, controller, service, atau endpoint API. Berdasarkan aturan proyek, Builder seharusnya menjalankan skenario Apidog setelah perubahan yang memengaruhi API.

Trae menggunakan model persetujuan untuk perintah shell:

1. Builder merekomendasikan perintah.
2. Trae menampilkan tombol Run.
3. Anda menyetujui eksekusi.
4. Builder membaca output terminal dan melanjutkan analisis.

Dengan reporter -r cli, hasil pengujian ditampilkan langsung di terminal. Builder dapat membaca permintaan yang dijalankan, assertion yang gagal, ringkasan, dan kode keluar.

Langkah 4: Baca laporan pengujian di Trae

Saat eksekusi gagal, output CLI memberikan informasi yang dibutuhkan untuk perbaikan, seperti:

• request yang gagal;
• assertion yang gagal;
• kode status yang diharapkan dan aktual;
• field respons yang hilang;
• nilai respons yang tidak sesuai.

Contoh perintah untuk output terminal:

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

Jika Anda juga membutuhkan laporan yang dapat dibuka di browser atau dibagikan ke tim, tambahkan reporter HTML:

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

Reporter html menulis laporan mandiri ke:

./apidog-reports

Tetap sertakan reporter cli agar Builder dapat membaca hasil langsung dari terminal. Untuk reporter HTML, JSON, JUnit, dan format lainnya, baca panduan laporan pengujian Apidog CLI.

Jadikan tes API bagian dari perulangan Builder

Tujuan utama konfigurasi ini adalah membuat pengujian API menjadi bagian dari siklus edit-test-fix Builder.

Misalnya, Builder mengubah handler checkout:

1. Builder mengedit kode handler.
2. Builder menjalankan apidog run terhadap environment staging.
3. Builder membaca kode keluar.
4. Jika kode keluar 0, Builder melanjutkan pekerjaan.
5. Jika kode keluar non-nol, Builder membaca assertion yang gagal.
6. Builder memperbaiki kode.
7. Builder menjalankan ulang skenario.

Dengan pola ini, skenario Apidog tidak lagi hanya dijalankan ketika seseorang membuka GUI dan mengklik tombol. Skenario menjadi pemeriksaan yang dapat dipanggil oleh agen selama proses implementasi.

Anda tetap membangun dan memelihara skenario secara visual di Apidog. Builder menjalankan skenario tersebut dan membaca hasilnya. Untuk pola yang lebih luas, lihat cara menggunakan agen AI untuk pengujian API dan alat uji Apidog AI.

Verifikasi bahwa Trae benar-benar menjalankan CLI

Jangan hanya mengandalkan ringkasan dari agen. Verifikasi tiga hal berikut.

1. Pastikan perintah benar-benar dieksekusi

Trae menampilkan perintah yang dijalankan Builder beserta outputnya di terminal. Cari baris literal seperti ini:

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

Jika Builder mengatakan tes sudah dijalankan tetapi Anda tidak melihat perintah dan outputnya, minta Builder menjalankan ulang dan menampilkan output mentah.

2. Periksa kode keluar

Tanyakan secara eksplisit:

Berapa kode keluar dari perintah apidog run itu?

apidog run mengembalikan:

• 0 jika semua assertion lulus;
• kode non-nol jika setidaknya satu assertion gagal.

Jika Builder menyatakan tes lulus tetapi kode keluar non-nol, anggap eksekusi tersebut gagal. Kode keluar adalah sumber kebenaran untuk gating otomatis, baik di Trae maupun di CI.

3. Pastikan Builder memakai skenario yang benar

Jika muncul error seperti “scenario not found”, Builder mungkin menggunakan ID yang salah atau membuat ID sendiri.

Bandingkan nilai berikut:

-t <scenario_id>
-e <env_id>

dengan:

• project_rules.md;
• perintah yang disalin dari tab CI/CD di Apidog.

Gunakan ID yang tersimpan dalam aturan proyek sebagai referensi utama.

Opsional: Hubungkan server Apidog MCP

Menjalankan apidog run dari project_rules.md sudah cukup untuk menjalankan tes API. Jika Anda ingin Builder juga dapat membaca spesifikasi API saat menulis kode, hubungkan server MCP.

Trae dapat bertindak sebagai klien MCP. Untuk menambahkan server:

1. Buka pengaturan Trae.
2. Buka tab MCP.
3. Pilih server dari marketplace, atau pilih Tambahkan Secara Manual.
4. Tempel konfigurasi JSON server yang berisi command, args, dan env.

Ikuti panduan Trae untuk menambahkan server MCP untuk format konfigurasi yang tepat.

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

• Apidog CLI menjalankan pengujian;
• Apidog MCP memberi Builder akses ke spesifikasi API saat implementasi.

Troubleshooting

Builder mengabaikan file aturan

Periksa lokasi file:

.trae/rules/project_rules.md

Pastikan:

• file berada di root repositori;
• folder bernama rules, bukan rule;
• nama file adalah project_rules.md.

Mulai ulang sesi Builder untuk memaksa Trae memuat ulang aturan.

Builder menambahkan --access-token

Jangan simpan token di project_rules.md. Jika mesin sudah diautentikasi dengan:

apidog login

Builder tidak perlu menambahkan --access-token.

Tegaskan kembali aturan tersebut dan hapus token apa pun dari file aturan. Untuk penggunaan kredensial interaktif maupun CI, baca panduan autentikasi Apidog CLI.

Builder menggunakan flag yang tidak dikenal

Jika CLI menampilkan error seperti berikut:

unknown option

jangan menebak flag. Jalankan:

apidog run --help

Lalu gunakan flag yang benar untuk versi CLI yang terinstal pada mesin Anda.

Builder melaporkan lulus, tetapi eksekusi gagal

Selalu prioritaskan kode keluar. Jika ringkasan Builder menyebut “tes lulus” tetapi apidog run mengembalikan kode non-nol, anggap tes gagal dan periksa output assertion.

Ringkasan implementasi

Konfigurasinya hanya membutuhkan beberapa langkah:

1. Instal dan autentikasi apidog-cli.
2. Buat .trae/rules/project_rules.md.
3. Salin perintah apidog run dari tab CI/CD di Apidog.
4. Masukkan ID skenario dan environment ke aturan proyek.
5. Minta Builder menjalankan tes atau biarkan Builder menjalankannya setelah perubahan API.
6. Verifikasi output terminal dan kode keluar.

Dengan konfigurasi ini, endpoint yang rusak dapat terdeteksi saat Builder masih mengerjakan perubahan, bukan setelah perubahan dirilis.

Bangun skenario secara visual di Apidog, lalu tempatkan perintah apidog run di .trae/rules/project_rules.md. Untuk menjalankan skenario yang sama tanpa agen, lihat panduan Apidog CLI di GitHub Actions, yang membahas secret, reporter, dan gating berdasarkan kode keluar.