Dari PRD hingga Pengujian: Alur Kerja Agen Lengkap dengan Apidog CLI

Ini adalah seri 10 bagian yang menceritakan bagaimana Apidog mengembangkan Apidog CLI, sebuah alat baris perintah untuk pengujian API dan manajemen siklus hidup API. Bacalah secara berurutan atau lompat ke postingan mana pun yang menarik minat Anda:

Ikuti contoh nyata: sebuah tim memiliki PRD dan basis kode Pengembalian Dana Pesanan. Lihat bagaimana Agent menggunakan Apidog CLI + SKILL untuk menghasilkan OpenAPI, membuat pengujian, memvalidasi, dan memverifikasi—secara menyeluruh.

Skenario

Mari kita buat semuanya konkret dengan alur kerja nyata.

Konteks:

Sebuah tim baru saja selesai menulis PRD "Pengembalian Dana Pesanan". Basis kode sudah memiliki rute dan pengontrol yang sesuai.

Permintaan pengguna ke Agent:

"Hasilkan pengujian API untuk fungsionalitas pengembalian dana berdasarkan PRD dan basis kode, lalu jalankan verifikasi."

Masalah Pendekatan Lama

Dengan alat MCP, Agent menghadapi serangkaian dilema:

Agent menghabiskan banyak upaya hanya untuk memutuskan jalur—bukan untuk mengeksekusi tugas.

Jalur CLI + SKILL

CLI + SKILL memenuhi alur R&D nyata dengan urutan yang jelas:

Hasilkan OpenAPI dari PRD & basis kode
        ↓
Impor ke Apidog
        ↓
Tambahkan kasus uji satu endpoint
        ↓
Validasi sebelum menulis
        ↓
Hasilkan skenario uji untuk alur bisnis
        ↓
Validasi sebelum menulis
        ↓
Jalankan pengujian otomatis

Mari kita jelajahi setiap langkah.

Langkah 1: Hasilkan & Impor OpenAPI

Agent membaca PRD dan basis kode, lalu menghasilkan spesifikasi OpenAPI.

Kutipan PRD:

API Pengembalian Dana Pesanan

POST /api/orders/{orderId}/refund
- Badan permintaan: { "reason": string, "amount": number }
- Respons: { "refundId": string, "status": string, "processedAt": datetime }

GET /api/orders/{orderId}/refund/{refundId}
- Respons: { "refundId": string, "status": string, "amount": number }

Agent menghasilkan OpenAPI:

{
  "openapi": "3.0.0",
  "paths": {
    "/api/orders/{orderId}/refund": {
      "post": {
        "summary": "Buat permintaan pengembalian dana",
        "parameters": [...],
        "requestBody": {...},
        "responses": {...}
      }
    },
    "/api/orders/{orderId}/refund/{refundId}": {
      "get": {
        "summary": "Dapatkan status pengembalian dana",
        ...
      }
    }
  }
}

Impor ke Apidog:

apidog import --project <projectId> --format openapi --file ./openapi.json

Output CLI:

{
  "success": true,
  "data": {
    "importedEndpoints": ["POST /refund", "GET /refund/{refundId}"],
    "endpointIds": ["ep-001", "ep-002"]
  },
  "agentHints": {
    "summary": "OpenAPI berhasil diimpor. 2 endpoint dibuat.",
    "nextSteps": [
      "Daftar endpoint yang diimpor untuk mengonfirmasi struktur.",
      "Tambahkan kasus uji untuk setiap endpoint.",
      "Buat skenario uji untuk alur pengembalian dana lengkap."
    ]
  }
}

Langkah 2: Kasus Uji Single-Endpoint

Agent fokus pada "endpoint pengembalian dana" terlebih dahulu.

Agent membaca endpoint:

apidog endpoint get ep-001 --project <projectId>

CLI mengembalikan struktur endpoint:

{
  "id": "ep-001",
  "method": "POST",
  "path": "/api/orders/{orderId}/refund",
  "requestBody": {
    "schema": {
      "type": "object",
      "properties": {
        "reason": { "type": "string" },
        "amount": { "type": "number" }
      },
      "required": ["reason", "amount"]
    }
  },
  "responses": {
    "200": {...}
  }
}

Agent menghasilkan kasus uji:

{
  "name": "Buat pengembalian dana - sukses",
  "endpointId": "ep-001",
  "request": {
    "path": "/api/orders/order-123/refund",
    "body": {
      "reason": "Permintaan pelanggan",
      "amount": 99.99
    }
  },
  "assertions": [
    {
      "subject": "responseJson.status",
      "comparator": "equal",
      "target": "processed"
    }
  ]
}

Validasi sebelum menulis:

apidog cli-schema validate test-case-create --file ./test-case-create.json

Hasil validasi CLI:

{
  "success": true,
  "agentHints": {
    "summary": "Struktur kasus uji valid.",
    "nextSteps": [
      "Buat kasus uji di Apidog.",
      "Baca kembali kasus uji yang dibuat untuk konfirmasi.",
      "Tambahkan lebih banyak assertions jika diperlukan."
    ]
  }
}

Buat kasus uji:

apidog test-case create --project <projectId> --file ./test-case-create.json

Output CLI:

{
  "success": true,
  "data": {
    "id": "tc-001",
    "name": "Buat pengembalian dana - sukses"
  },
  "agentHints": {
    "summary": "Kasus uji berhasil dibuat.",
    "nextSteps": [
      "Baca kembali kasus uji tc-001 untuk mengonfirmasi assertions.",
      "Buat kasus uji untuk GET /refund/{refundId}.",
      "Bangun skenario uji untuk alur pengembalian dana lengkap."
    ]
  }
}

Langkah 3: Skenario Uji untuk Alur Lengkap

Berdasarkan PRD, alur bisnis lengkapnya adalah:

Buat pesanan → Bayar → Pengembalian dana → Query status pengembalian dana

Agent menghasilkan skenario:

{
  "name": "Alur Lengkap Pengembalian Dana Pesanan",
  "steps": [
    { "type": "case", "caseId": "tc-create-order" },
    { "type": "case", "caseId": "tc-pay" },
    { "type": "case", "caseId": "tc-001" },
    { "type": "case", "caseId": "tc-get-refund" }
  ]
}

Validasi sebelum menulis:

apidog cli-schema validate test-scenario-update --file ./scenario-update.json

Buat skenario:

apidog test-scenario create --project <projectId> --file ./scenario-update.json

Langkah 4: Jalankan Verifikasi

Setelah kasus uji dan skenario siap:

apidog run --project <projectId> \
  --test-scenario scenario-001 \
  --environment env-production \
  -r "cli,html,junit" \
  --out-dir ./apidog-reports

Output CLI:

{
  "success": true,
  "stats": {
    "total": 4,
    "passed": 4,
    "failed": 0
  },
  "reportFiles": {
    "cli": "./apidog-reports/cli-report.txt",
    "html": "./apidog-reports/report.html",
    "junit": "./apidog-reports/junit.xml"
  },
  "agentHints": {
    "summary": "Semua pengujian berhasil. 4 langkah dieksekusi dengan sukses.",
    "nextSteps": [
      "Tinjau laporan HTML untuk hasil rinci.",
      "Jika terjadi kegagalan, debug menggunakan detail kesalahan CLI.",
      "Integrasikan pengujian ini ke dalam pipeline CI."
    ]
  }
}

Rantai Lengkap

Semua elemen sekarang terhubung:

Semuanya dapat diverifikasi dan dilacak.

agentHints Melalui Alur

Perhatikan bagaimana agentHints memandu setiap transisi:

Agent tidak perlu menebak apa yang harus dilakukan selanjutnya.

Perbandingan: MCP vs. CLI + SKILL untuk Tugas Ini

Apa Selanjutnya

Contoh praktis ini menunjukkan bagaimana CLI + SKILL bekerja dalam alur kerja nyata.

Namun ada fondasi di balik semua ini: kompatibilitas CI/CD.

Dalam Bagian 8, Mengapa Kompatibilitas CI/CD Tidak Dapat Dinegosiasikan untuk Alat Agent, kita akan menjelajahi mengapa apidog run melayani pipeline CI dan Agent AI—dan mengapa tujuan ganda itu penting untuk desain alat yang berkelanjutan.

Poin-Poin Penting

• Alur kerja lengkap: PRD → OpenAPI → Impor → Kasus Uji → Skenario → Verifikasi
• Setiap langkah memiliki perintah CLI + validasi + agentHints
• Impor langkah-langkah + baca kembali lebih aman daripada menulis skenario secara manual
• --with-case-detail memberikan struktur nyata untuk pembaruan
• agentHints memandu setiap transisi
• Semuanya dapat diverifikasi dan dilacak

Unduh Apidog untuk mendesain, membuat mock, menguji, dan mendokumentasikan API dalam satu ruang kerja. Pelajari lebih lanjut tentang Apidog CLI untuk pengujian API baris perintah, otomatisasi CI, dan alur kerja Agen AI.