DEV Community

Cover image for Apidog CLI ile PRD'den Test Döngüsüne Eksiksiz Agent İş Akışı
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

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

Bu seri, Apidog'un API testi ve API yaşam döngüsü yönetimi için geliştirdiği komut satırı aracı Apidog CLI'ın nasıl tasarlandığını anlatır. Sırayla okuyabilir veya ilginizi çeken bölüme atlayabilirsiniz:

Apidog'u bugün deneyin

Başlık Odak
1 126 MCP Aracı Kurduk. Ama Temsilci İçin En İyi Çözüm Bu Değil Sorun keşfi
2 Neden Yepyeni Apidog CLI'ı Geliştirdik Mimari geliştirme
3 Altın Kural: CLI Gerçekleri Üretir, Model Gerçekler Üzerinde Hareket Eder Temel felsefe
4 agentHints: CLI'lara Temsilcilerle Konuşmayı Öğretmek Yapılandırılmış çıktı
5 SKILL: Operasyonel Deneyimi Kod Olarak Göndermek Operasyonel deneyim
6 Sayılar Yalan Söylemez: %30 Daha Az Araç Çağrısı, %25 Daha Az Token Nicel sonuçlar
7 PRD'den Test Döngüsüne: Apidog CLI ile Tam Bir Temsilci İş Akışı Pratik eğitim
8 CI/CD Uyumluluğu Neden Temsilci Araçları İçin Tartışılmazdır DevOps bakış açısı
9 AI Branch: AI Temsilcileri ile Daha Güvenli Proje Değişiklikleri Güvenlik katmanı
10 Önce Şartname Dündü. Yetenek Odaklıya Hoş Geldiniz. Vizyon ve gelecek

Gerçek bir örnek üzerinden ilerleyelim: Bir ekibin “Sipariş İadesi” PRD'si ve mevcut kod tabanı var. Amaç, bir Temsilcinin Apidog CLI + SKILL kullanarak OpenAPI oluşturması, testleri üretmesi, doğrulaması ve uçtan uca çalıştırmasıdır.

Senaryo

Bu akışta Temsilciye verilen görev şudur:

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

Başlangıç durumu:

  • PRD hazır.
  • Kod tabanında ilgili rota ve denetleyiciler mevcut.
  • Hedef, API tanımından test çalıştırmaya kadar izlenebilir bir zincir kurmak.

Eski Yaklaşımın Sorunu

MCP araçlarıyla Temsilci, işi yürütmeden önce hangi aracı hangi sırayla kullanacağını çözmek zorunda kalır.

Karar Noktası Belirsizlik
Önce projeyi sorgula? Yoksa önce uç nokta mı oluştur?
Önce test durumu yaz? Yoksa önce şema mı oluştur?
Testleri doğrudan çalıştır? Yoksa önce kaynakları mı geri oku?
Her adım için hangi araç? 126 araç arasında seçim yap

Sonuç: Temsilci zamanının önemli kısmını API testi üretmek yerine operasyon yolunu tahmin etmeye harcar.

CLI + SKILL ile Hedef Akış

CLI + SKILL yaklaşımı, görevi açık bir geliştirme/test sırasına böler:

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
Enter fullscreen mode Exit fullscreen mode

Bu akışın avantajı basittir:

  • Her adım CLI komutuyla çalışır.
  • Her yazma işleminden önce yerel doğrulama yapılır.
  • CLI çıktısı agentHints ile sonraki adımı önerir.
  • Üretilen her varlık geri okunabilir ve izlenebilir.

Adım 1: OpenAPI Oluştur ve Apidog'a Aktar

Temsilci önce PRD'yi ve kod tabanını okur. Ardından API sözleşmesini OpenAPI formatında üretir.

PRD'deki ilgili bölüm:

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 }
Enter fullscreen mode Exit fullscreen mode

Temsilcinin üreteceği örnek OpenAPI parçası:

{
  "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"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

OpenAPI dosyasını Apidog'a aktarın:

apidog import \
  --project <projectId> \
  --format openapi \
  --file ./openapi.json
Enter fullscreen mode Exit fullscreen mode

Örnek 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."
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

Burada önemli nokta: Temsilci bir sonraki adımı tahmin etmek zorunda kalmaz. CLI çıktısı, doğrulanabilir sonraki işlemleri açıkça verir.

Adım 2: Tek Uç Nokta İçin Test Durumu Oluştur

İlk olarak POST /api/orders/{orderId}/refund uç noktasına odaklanın.

Uç nokta detayını okuyun:

apidog endpoint get ep-001 --project <projectId>
Enter fullscreen mode Exit fullscreen mode

Örnek uç nokta yapısı:

{
  "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": {}
  }
}
Enter fullscreen mode Exit fullscreen mode

Bu yapıya göre test durumu dosyasını hazırlayın:

{
  "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"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Yazmadan önce şemayı doğrulayın:

apidog cli-schema validate test-case-create \
  --file ./test-case-create.json
Enter fullscreen mode Exit fullscreen mode

Örnek 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."
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

Doğrulama başarılıysa test durumunu oluşturun:

apidog test-case create \
  --project <projectId> \
  --file ./test-case-create.json
Enter fullscreen mode Exit fullscreen mode

Örnek çıktı:

{
  "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."
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

Pratik kural: Yazma işlemi yapmadan önce cli-schema validate kullanın. Bu, alan hatalarını ve eksik yapıları Apidog'a göndermeden yakalamanızı sağlar.

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

PRD'ye göre uçtan uca iş akışı şöyledir:

Sipariş oluştur → Öde → İade et → İade durumunu sorgula
Enter fullscreen mode Exit fullscreen mode

Bu akış için senaryo dosyası oluşturun:

{
  "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" }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Senaryo yapısını yazmadan önce doğrulayın:

apidog cli-schema validate test-scenario-update \
  --file ./scenario-update.json
Enter fullscreen mode Exit fullscreen mode

Ardından senaryoyu oluşturun:

apidog test-scenario create \
  --project <projectId> \
  --file ./scenario-update.json
Enter fullscreen mode Exit fullscreen mode

Bu adımda amaç, tekil testleri manuel olarak tekrar yazmak değil; mevcut test durumlarını senaryo adımları olarak bağlamaktır. Böylece her test durumu ayrı ayrı yönetilebilir, senaryo ise iş akışını temsil eder.

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

Test durumları ve senaryo hazır olduğunda otomatik çalıştırmayı başlatın:

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

Örnek çıktı:

{
  "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."
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

Rapor formatları farklı kullanım alanlarına hizmet eder:

  • cli: Yerel geliştirme ve hızlı kontrol
  • html: İnsan tarafından okunabilir ayrıntılı rapor
  • junit: CI/CD sistemleriyle entegrasyon

Tam Zincir

Bu noktada tüm zincir birbirine bağlanmış olur:

Element Durum
PRD Okundu ve işlendi
Kod tabanı Rotalar için analiz edildi
OpenAPI Oluşturuldu ve içe aktarıldı
Uç nokta varlıkları Apidog'da oluşturuldu
Tek uç nokta testleri Oluşturuldu ve doğrulandı
İş senaryosu Oluşturuldu ve doğrulandı
Test çalıştırması Raporlandı

Sonuç: Her şey doğrulanabilir ve izlenebilirdir.

Akış Boyunca agentHints

agentHints, Temsilcinin sonraki adımı tahmin etmesini engeller. Her CLI çıktısı, bir sonraki güvenli işlemi önerir.

İşlem Sonrası agentHints Ne Önerir?
Uç noktaları içe aktar Uç noktaları listele, test durumları ekle
Test durumu oluştur Geri oku, daha fazla test durumu oluştur, senaryo oluştur
Senaryo oluştur İddialar ekle, doğrula, çalıştır
Testleri çalıştır Raporu incele, gerekirse hata ayıkla, CI'a entegre et

Bu yapı, Temsilciyi araç aramaktan çıkarıp doğrulanmış görev yürütmeye yönlendirir.

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

Boyut MCP Yaklaşımı CLI + SKILL Yaklaşımı
Başlangıç noktası Temsilci proje araçlarını arar SKILL görev türünü belirler
Uç nokta oluşturma Temsilci hangi aracı ve alanları kullanacağını tahmin eder OpenAPI'dan CLI içe aktarımı
Test durumu oluşturma Alan hatalarında birden çok yeniden deneme Yazmadan önce yerel doğrulama
Senaryo oluşturma Temsilci yapıyı elle yazar Adımları içe aktar, geri oku, güncelle
Doğrulama Temsilci çalıştırma aracını bulur agentHints senaryodan sonra önerir
Toplam adımlar Yeniden denemelerle ~20-25 çağrı ~10-12 doğrulanmış çağrı

Sırada Ne Var

Bu örnek, CLI + SKILL'in gerçek bir API test iş akışında nasıl çalıştığını gösterir:

PRD → OpenAPI → İçeri Aktar → Test Durumları → Senaryo → Doğrula
Enter fullscreen mode Exit fullscreen mode

Ancak bu akışın üretim ortamında sürdürülebilir olması için kritik bir temel daha vardır: CI/CD uyumluluğu.

  1. Bölümde, CI/CD Uyumluluğu Neden Temsilci Araçları İçin Tartışılmazdır başlığı altında apidog run komutunun hem CI hatlarına hem de AI Temsilcilerine nasıl hizmet ettiğini inceleyeceğiz.

Temel Çıkarımlar

  • Tam iş akışı: PRD → OpenAPI → İçeri Aktar → Test Durumları → Senaryo → Doğrula
  • Her adım CLI komutu, doğrulama ve agentHints ile desteklenir.
  • Yazmadan önce şema doğrulamak, yeniden denemeleri azaltır.
  • Senaryoları elle yazmak yerine mevcut test durumlarını adım olarak bağlamak daha güvenlidir.
  • agentHints, Temsilcinin sonraki adımı tahmin etmesini engeller.
  • Üretilen API tanımı, test durumu, senaryo ve rapor izlenebilir durumdadır.

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

Top comments (0)