Cara Menggunakan Apidog CLI di Kode Claude

Claude Code bekerja dalam satu siklus: mengedit berkas, menjalankan perintah terminal, membaca output, lalu menentukan langkah berikutnya. Jika pengujian API Anda masih berada di GUI Apidog dan hanya berjalan saat seseorang mengkliknya, agen tidak akan pernah memakainya dalam siklus tersebut.

Coba Apidog hari ini

Solusinya adalah menambahkan satu konfigurasi proyek. Apidog CLI, paket npm bernama apidog-cli, dapat menjalankan skenario pengujian yang dibuat di Apidog langsung dari terminal. Setelah CLI terinstal dan Claude Code mengetahui perintahnya, agen dapat menjalankan skenario Apidog seperti menjalankan unit test: eksekusi perintah, periksa kode keluar, lalu perbaiki kode jika pengujian gagal.

Panduan ini berfokus pada integrasi dengan Claude Code: isi CLAUDE.md, aturan izin untuk apidog run, dan cara memakai hasil pengujian dalam siklus edit–uji–perbaiki.

Sebelum melanjutkan, pastikan kondisi berikut sudah terpenuhi:

apidog --version

Perintah tersebut harus menampilkan versi CLI, dan mesin Anda harus sudah terautentikasi ke Apidog. Jika belum, ikuti cara menginstal Apidog CLI dengan agen pengodean AI.

Claude Code yang dimaksud

Artikel ini membahas Claude Code CLI, agen pengodean Anthropic yang berjalan di terminal atau aplikasi desktop. Claude Code dapat membaca repositori, mengedit berkas, dan menjalankan perintah shell sesuai mode izin yang Anda gunakan.

Ini bukan aplikasi obrolan Claude atau panggilan API biasa. Jika Anda menjalankan:

claude

di dalam repositori dan mendapatkan agen interaktif yang mengusulkan perubahan serta perintah terminal, Anda menggunakan Claude Code yang dimaksud.

Claude Code mempelajari aturan proyek melalui berkas CLAUDE.md. Untuk referensi perintah terminal dan slash command, lihat perintah garis miring Claude Code.

Langkah 1: Tambahkan instruksi Apidog ke CLAUDE.md

Claude Code membaca CLAUDE.md saat sesi dimulai. Berkas ini setara dengan AGENTS.md untuk Codex. Dokumentasi Anthropic menjelaskan bahwa Claude Code membaca CLAUDE.md, bukan AGENTS.md. Jika proyek Anda sudah memiliki AGENTS.md, Anda dapat mengimpornya melalui:

@AGENTS.md

Jika sebelumnya Anda sudah mengatur Apidog CLI di Codex, konsepnya sama; yang berubah hanya nama berkas instruksinya.

Simpan CLAUDE.md di akar repositori. Claude Code juga mendukung lokasi berikut:

./CLAUDE.md
./.claude/CLAUDE.md
~/.claude/CLAUDE.md

Claude Code memuat CLAUDE.md dari direktori aktif hingga direktori induk. Untuk aturan tingkat proyek, letakkan berkas di akar repositori.

Tambahkan blok berikut ke CLAUDE.md:

## Pengujian API dengan Apidog CLI

Proyek ini memiliki skenario pengujian Apidog. Untuk memeriksa API, jalankan:

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

- Kode keluar 0 berarti setiap asersi berhasil. Non-nol berarti ada yang gagal; buka laporan dan perbaiki sebelum melanjutkan.
- Mesin sudah terautentikasi melalui `apidog login`. Jangan pernah menambahkan flag `--access-token` dan jangan pernah meletakkan token di berkas ini.
- Jika sebuah flag tidak dikenal, jalankan `apidog run --help` dan gunakan flag persis dari sana.

Ganti <scenario_id> dan <env_id> dengan nilai skenario Anda.

Menulis instruksi ini di CLAUDE.md lebih andal daripada memberikannya sekali di obrolan. Instruksi sesi dapat hilang ketika sesi berakhir, sedangkan CLAUDE.md tersedia untuk setiap anggota tim dan setiap sesi Claude Code. Berkas ini juga tetap dimuat setelah /compact.

Langkah 2: Salin perintah dari Apidog

Jangan menebak nilai <scenario_id> atau <env_id>.

1. Buka skenario pengujian di Apidog.
2. Buka tab CI/CD.
3. Salin perintah apidog run ... yang dihasilkan.
4. Tempel perintah atau ID yang sesuai ke CLAUDE.md.

Perintah dari Apidog sudah memuat ID skenario, ID lingkungan, dan pelapor -r cli.

Contoh:

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

Pelapor -r cli menampilkan hasil langkah demi langkah dan ringkasan langsung di terminal. Output ini dapat dibaca Claude Code untuk menentukan tindakan berikutnya.

Untuk detail flag, gunakan:

apidog run --help

Anda juga dapat merujuk ke panduan lengkap Apidog CLI dan referensi perintah apidog run.

Langkah 3: Jalankan pengujian dari Claude Code

Mulai Claude Code dari akar repositori:

claude

Saat dimulai, Claude Code memuat CLAUDE.md. Setelah Anda mengubah endpoint, handler, validasi, atau kode lain yang memengaruhi API, minta Claude menjalankan pengujian API.

Contoh instruksi:

Jalankan skenario pengujian Apidog yang tercantum di CLAUDE.md. Jika gagal, baca outputnya, perbaiki kode, lalu jalankan ulang.

Claude Code akan menggunakan perintah apidog run yang Anda simpan di CLAUDE.md.

Atur izin untuk apidog run

Dalam mode default, Claude Code dapat meminta persetujuan sebelum menjalankan perintah shell yang belum pernah diizinkan. Saat diminta, setujui perintah apidog run.

Jika Anda ingin mengizinkan perintah tersebut tanpa prompt berulang, gunakan:

/permissions

Atau tambahkan aturan ke .claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(apidog run *)"
    ]
  }
}

Skenario read-only terhadap environment staging dapat menjadi kandidat yang sesuai untuk daftar izin.

Claude Code juga memiliki opsi --dangerously-skip-permissions, tetapi opsi ini melewati semua prompt. Gunakan untuk CI atau eksekusi terkontrol, bukan penggunaan harian di mesin pengembangan.

Pastikan Claude Code menampilkan:

• Perintah apidog run ... yang benar-benar dieksekusi.
• Output pengujian mentah.
• Ringkasan hasil.
• Kode keluar proses.

Jangan hanya mengandalkan kalimat seperti “pengujian berhasil”.

Langkah 4: Baca laporan pengujian

Saat pengujian gagal, output -r cli menyediakan informasi yang diperlukan untuk perbaikan:

• Permintaan yang dijalankan.
• Asersi yang diperiksa.
• Asersi yang gagal.
• Nilai yang diharapkan dan nilai aktual.
• Kode status atau bidang respons yang bermasalah.

Contoh kegagalan yang dapat ditindaklanjuti:

Expected status code: 200
Actual status code: 500

Atau:

Expected field: checkoutId
Actual: field missing

Claude Code dapat menggunakan detail tersebut untuk mencari handler, skema respons, atau validasi yang perlu diperbaiki.

Tambahkan laporan HTML

Untuk laporan yang dapat dibuka di browser atau dibagikan ke tim, tambahkan pelapor HTML:

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

Pelapor html menulis laporan mandiri ke:

./apidog-reports

Tetap sertakan cli agar Claude Code tetap menerima output terminal yang diperlukan untuk mengambil keputusan.

Untuk laporan JUnit dan format pelapor lain, lihat laporan pengujian Apidog CLI.

Masukkan pengujian API ke siklus Claude Code

Tujuan utamanya bukan sekadar meminta Claude Code menjalankan pengujian sekali. Tujuannya adalah membuat pengujian API menjadi bagian dari alur kerjanya.

Contoh siklus untuk perubahan endpoint checkout:

1. Claude Code mengedit handler checkout.
2. Claude Code menjalankan skenario Apidog terhadap staging.
3. Claude Code membaca kode keluar dan output asersi.
4. Jika kode keluar 0, Claude melanjutkan pekerjaan.
5. Jika kode keluar non-nol, Claude membaca kegagalan.
6. Claude memperbaiki kode.
7. Claude menjalankan ulang skenario.

Dengan konfigurasi ini, pengujian API diperlakukan seperti unit test: perubahan tidak dianggap selesai hanya karena kode berhasil diedit.

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

Verifikasi Claude Code benar-benar menjalankan CLI

Agen dapat merangkum pekerjaan yang belum dilakukan. Gunakan tiga pemeriksaan berikut.

1. Pastikan perintah benar-benar dieksekusi

Claude Code menampilkan perintah shell dan outputnya secara sebaris. Cari perintah literal seperti:

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

Jika Claude mengatakan pengujian telah dijalankan tetapi Anda tidak melihat perintah dan outputnya, minta Claude menjalankan ulang serta menampilkan output mentah.

2. Periksa kode keluar

Tanyakan secara langsung:

Berapa kode keluar dari perintah apidog run?

Aturannya sederhana:

0       Semua asersi berhasil
non-nol Ada asersi atau eksekusi yang gagal

Jika ringkasan Claude mengatakan “berhasil” tetapi kode keluar non-nol, percayai kode keluar.

3. Pastikan skenario yang dipakai benar

Jika output menyatakan skenario tidak ditemukan, Claude Code mungkin memakai ID yang salah.

Bandingkan nilai berikut:

-t <scenario_id>
-e <env_id>

dengan:

• Nilai di CLAUDE.md.
• Perintah yang dihasilkan Apidog pada tab CI/CD.

Jadikan CLAUDE.md sebagai sumber kebenaran tingkat proyek.

Opsional: Hubungkan server Apidog MCP

apidog run dari CLAUDE.md sudah cukup untuk menjalankan pengujian. Jika Anda ingin Claude Code juga membaca spesifikasi API saat menulis kode, tambahkan server MCP.

Claude Code mendukung Model Context Protocol. Anda dapat menambahkan server melalui claude mcp add ... atau dengan melakukan commit .mcp.json di akar proyek dan menggunakan scope project.

Server Apidog MCP mengekspos spesifikasi API melalui MCP.

Pembagian perannya sederhana:

• Apidog CLI menjalankan skenario pengujian.
• Apidog MCP menyediakan spesifikasi API agar Claude Code dapat membaca skema saat mengode.

Troubleshooting

Claude Code mengabaikan CLAUDE.md

Pastikan:

• Nama berkas tepat: CLAUDE.md.
• Berkas berada di akar repositori atau direktori induk dari direktori aktif.
• Anda memulai Claude Code dari dalam repositori.

Jalankan:

/memory

Perintah ini menampilkan daftar berkas memori yang dimuat Claude Code. Jika CLAUDE.md Anda tidak muncul, Claude Code tidak dapat membacanya.

Mulai ulang sesi untuk memaksa pembacaan ulang.

Claude Code mencoba meneruskan --access-token

Jangan simpan token di CLAUDE.md.

Pastikan instruksi berikut tetap ada:

Mesin sudah terautentikasi melalui `apidog login`. Jangan pernah menambahkan flag `--access-token`.

Jika Claude tetap menambahkan token, perkuat instruksi tersebut dan pastikan autentikasi CLI sudah dilakukan. Lihat autentikasi Apidog CLI.

Claude Code membuat flag yang tidak valid

Jika muncul kesalahan seperti:

unknown option

jangan gunakan flag hasil tebakan. Jalankan:

apidog run --help

Lalu gunakan flag yang tersedia pada versi CLI yang terinstal.

Claude Code melaporkan sukses pada eksekusi gagal

Prioritaskan kode keluar, bukan ringkasan bahasa alami.

Kode keluar 0       = lulus
Kode keluar non-nol = gagal

Simpan aturan ini di CLAUDE.md agar Claude Code memiliki instruksi eksplisit untuk memperlakukan eksekusi gagal sebagai pekerjaan yang belum selesai.

Dari agen harian ke siklus yang teruji

Penyiapannya ringkas:

1. Instal apidog-cli mengikuti panduan instalasi.
2. Autentikasi sekali dengan apidog login.
3. Salin perintah apidog run dari tab CI/CD di Apidog.
4. Simpan perintah tersebut di CLAUDE.md.
5. Izinkan Bash(apidog run *) jika sesuai dengan kebijakan proyek.
6. Minta Claude Code menjalankan pengujian setelah perubahan API.

Dengan konfigurasi ini, endpoint yang rusak dapat terdeteksi saat Claude Code masih mengerjakan perubahan, bukan setelah perubahan dikirim.

Anda tetap membangun skenario secara visual di Apidog, lalu Claude Code menjalankannya dari terminal sebagai bagian dari siklus pengembangan. Unduh Apidog, buat satu skenario, masukkan perintah apidog run ke CLAUDE.md, lalu gunakan pada perubahan API berikutnya.

Untuk menjalankan perintah yang sama di pipeline CI tanpa Claude Code, lihat Apidog CLI di GitHub Actions.