Apidog CLI ile PRD'den Test Döngüsüne Eksiksiz Agent İş Akışı

Bu, Apidog'un API testi ve API yaşam döngüsü yönetimi için bir komut satırı aracı olan Apidog CLI'ı nasıl geliştirdiğini paylaşan 10 bölümlük bir seridir. Sırasıyla okuyun veya ilginizi çeken herhangi bir gönderiye atlayın:

Gerçek bir örneği inceleyin: bir ekibin Sipariş İadesi PRD'si ve kod tabanı var. Bir Temsilcinin OpenAPI oluşturmak, testler oluşturmak, doğrulamak ve uçtan uca kontrol etmek için Apidog CLI + SKILL'i nasıl kullandığını görün.

Senaryo

Her şeyi gerçek bir iş akışı ile somutlaştıralım.

Bağlam:

Bir ekip "Sipariş İadesi" PRD'sini yazmayı yeni bitirdi. Kod tabanında ilgili rotalar ve denetleyiciler zaten mevcut.

Kullanıcının Temsilciye isteği:

"PRD ve kod tabanına dayanarak iade işlevi için API testleri oluştur, ardından doğrulama çalıştır."

Eski Yaklaşım Sorunu

MCP araçlarıyla Temsilci, bir dizi ikilemle karşı karşıya kalır:

Temsilci, görevi yürütmek yerine sadece yolu belirlemek için önemli çaba harcar.

CLI + SKILL Yolu

CLI + SKILL, açık bir sıra ile gerçek Ar-Ge akışlarını karşılar:

PRD ve kod tabanından OpenAPI oluştur
        ↓
Apidog'a aktar
        ↓
Tek uç nokta test durumları ekle
        ↓
Yazmadan önce doğrula
        ↓
İş akışı için test senaryosu oluştur
        ↓
Yazmadan önce doğrula
        ↓
Otomatik testleri çalıştır

Her adımı inceleyelim.

Adım 1: OpenAPI Oluştur ve İçeri Aktar

Temsilci, PRD'yi ve kod tabanını okur, ardından OpenAPI spesifikasyonunu oluşturur.

PRD alıntısı:

Sipariş İadesi API

POST /api/orders/{orderId}/refund
- İstek gövdesi: { "reason": string, "amount": number }
- Yanıt: { "refundId": string, "status": string, "processedAt": datetime }

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

Temsilci OpenAPI oluşturur:

{
  "openapi": "3.0.0",
  "paths": {
    "/api/orders/{orderId}/refund": {
      "post": {
        "summary": "İade isteği oluştur",
        "parameters": [...],
        "requestBody": {...},
        "responses": {...}
      }
    },
    "/api/orders/{orderId}/refund/{refundId}": {
      "get": {
        "summary": "İade durumunu al",
        ...
      }
    }
  }
}

Apidog'a aktar:

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

CLI çıktısı:

{
  "success": true,
  "data": {
    "importedEndpoints": ["POST /refund", "GET /refund/{refundId}"],
    "endpointIds": ["ep-001", "ep-002"]
  },
  "agentHints": {
    "summary": "OpenAPI başarıyla içe aktarıldı. 2 uç nokta oluşturuldu.",
    "nextSteps": [
      "Yapıyı doğrulamak için içe aktarılan uç noktaları listele.",
      "Her uç nokta için test durumları ekle.",
      "Tam iade akışı için bir test senaryosu oluştur."
    ]
  }
}

Adım 2: Tek Uç Nokta Test Durumları

Temsilci önce "iade uç noktasına" odaklanır.

Temsilci uç noktayı okur:

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

CLI uç nokta yapısını döndürür:

{
  "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": {...}
  }
}

Temsilci test durumu oluşturur:

{
  "name": "İade oluştur - başarı",
  "endpointId": "ep-001",
  "request": {
    "path": "/api/orders/order-123/refund",
    "body": {
      "reason": "Müşteri isteği",
      "amount": 99.99
    }
  },
  "assertions": [
    {
      "subject": "responseJson.status",
      "comparator": "equal",
      "target": "işlendi"
    }
  ]
}

Yazmadan önce doğrula:

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

CLI doğrulama sonucu:

{
  "success": true,
  "agentHints": {
    "summary": "Test durumu yapısı geçerli.",
    "nextSteps": [
      "Apidog'da test durumunu oluştur.",
      "Oluşturulan test durumunu doğrulamak için geri oku.",
      "Gerekirse daha fazla iddia ekle."
    ]
  }
}

Test durumu oluştur:

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

CLI çıktısı:

{
  "success": true,
  "data": {
    "id": "tc-001",
    "name": "İade oluştur - başarı"
  },
  "agentHints": {
    "summary": "Test durumu başarıyla oluşturuldu.",
    "nextSteps": [
      "Iddiaları doğrulamak için tc-001 test durumunu geri oku.",
      "GET /refund/{refundId} için test durumu oluştur.",
      "Tam iade akışı için test senaryosu oluştur."
    ]
  }
}

Adım 3: Tam Akış İçin Test Senaryosu

PRD'ye göre, tam iş akışı şöyledir:

Sipariş oluştur → Öde → İade et → İade durumunu sorgula

Temsilci senaryo oluşturur:

{
  "name": "Sipariş İadesi Tam Akış",
  "steps": [
    { "type": "case", "caseId": "tc-create-order" },
    { "type": "case", "caseId": "tc-pay" },
    { "type": "case", "caseId": "tc-001" },
    { "type": "case", "caseId": "tc-get-refund" }
  ]
}

Yazmadan önce doğrula:

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

Senaryo oluştur:

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

Adım 4: Doğrulamayı Çalıştır

Test durumları ve senaryolar hazır olduktan sonra:

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

CLI çıktısı:

{
  "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": "Tüm testler geçti. 4 adım başarıyla yürütüldü.",
    "nextSteps": [
      "Ayrıntılı sonuçlar için HTML raporunu incele.",
      "Hatalar oluştuysa, CLI hata ayrıntılarını kullanarak hata ayıkla.",
      "Bu testi CI hattına entegre et."
    ]
  }
}

Tam Zincir

Tüm elementler şimdi birbirine bağlı:

Her şey doğrulanabilir ve izlenebilirdir.

Akış Boyunca agentHints

agentHints'in her geçişi nasıl yönlendirdiğine dikkat edin:

Temsilci bir sonraki adımda ne yapacağını asla tahmin etmek zorunda kalmaz.

Karşılaştırma: Bu Görev İçin MCP ve CLI + SKILL

Sırada Ne Var

Bu pratik örnek, CLI + SKILL'in gerçek bir iş akışında nasıl çalıştığını gösteriyor.

Ancak tüm bunların altında yatan bir temel var: CI/CD uyumluluğu.

8. Bölümde, CI/CD Uyumluluğu Neden Temsilci Araçları İçin Tartışılmazdır, apidog run'ın hem CI hatlarına hem de AI Temsilcilerine neden hizmet ettiğini ve bu çifte amacın sürdürülebilir araç tasarımı için neden önemli olduğunu inceleyeceğiz.

Temel Çıkarımlar

• Tam iş akışı: PRD → OpenAPI → İçeri Aktar → Test Durumları → Senaryo → Doğrula
• Her adımda CLI komutu + doğrulama + agentHints bulunur
• Adımları içeri aktarmak + geri okumak, senaryoları elle yazmaktan daha güvenlidir
• --with-case-detail güncellemeler için gerçek yapı sağlar
• agentHints her geçişi yönlendirir
• Her şey doğrulanabilir ve izlenebilirdir

Tek bir çalışma alanında API'leri tasarlamak, taklit etmek, test etmek ve belgelemek için Apidog'u indirin. Komut satırı API testi, CI otomasyonu ve AI Temsilci iş akışları için Apidog CLI hakkında daha fazla bilgi edinin.