DEV Community

Cover image for Windsurf'te Apidog CLI Nasıl Kullanılır
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

Windsurf'te Apidog CLI Nasıl Kullanılır

Windsurf’ün Cascade aracısı dosyaları düzenler, terminal komutlarını çalıştırır, çıktıyı okur ve sonraki adımı seçer. API testleriniz yalnızca bir GUI içinde çalışıyorsa bu döngünün dışında kalır. apidog-cli ile Apidog senaryolarını terminalden çalıştırabilir; Cascade’in test sonucuna göre kodu düzeltmesini sağlayabilirsiniz.

Apidog'u bugün deneyin

Apidog’da oluşturduğunuz test senaryolarını terminalden çalıştırmak için apidog-cli kullanılır. CLI yüklendiğinde Cascade aşağıdaki döngüyü uygulayabilir:

  1. API ile ilgili kodu değiştirir.
  2. apidog run komutunu çalıştırır.
  3. Çıkış kodunu okur.
  4. Test başarısızsa rapora göre düzeltme yapar ve testi yeniden çalıştırır.

Önce CLI’nin çalıştığını doğrulayın:

apidog --version
Enter fullscreen mode Exit fullscreen mode

Kurulum, kimlik doğrulama ve ilk çalıştırma için bir AI kodlama aracısı ile Apidog CLI nasıl yüklenir rehberini kullanın. Bu makale, apidog login ile oturum açtığınızı varsayar.

Bu hangi Windsurf?

Windsurf, Codeium’un ajan tabanlı IDE’sidir; yerleşik ajanının adı Cascade’dir. Cascade:

  • deponuzu okur,
  • dosyaları düzenler,
  • entegre terminalde komut çalıştırır,
  • komut çıktısına göre sonraki adımı belirler.

Henüz kurmadıysanız Windsurf’ü nasıl indirip kuracağınız rehberiyle başlayın.

Adım 1: Apidog kuralını ekleyin

Cascade, proje kurallarını Markdown dosyalarından okur. Proje seviyesinde kural eklemek için deponuzun kökünde şu dosyayı oluşturun:

.windsurf/rules/apidog.md
Enter fullscreen mode Exit fullscreen mode

Dosyaya aşağıdaki kuralı ekleyin:

# Apidog API tests

This project has Apidog test scenarios. Run them with the Apidog CLI:

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

Rules:
- Use the exact command above; do not invent flags. Run `apidog run --help` if unsure.
- `apidog run` exits 0 when every assertion passes, non-zero when any fails.
  Treat exit 0 as pass and non-zero as fail. Report the real exit code.
- The machine is already authenticated via `apidog login`. Never add an
  access token to the command or commit one to this file.
- After you change code that touches the API, run the scenario and act on the result.
Enter fullscreen mode Exit fullscreen mode

.windsurf/rules/ proje bazlı kurallar için önerilen konumdur. Windsurf ayrıca eski .windsurfrules dosyasını ve genel ~/.codeium/windsurf/memories/global_rules.md kurallarını okuyabilir. Ayrıntılar için Windsurf kurallar ve hafızalar referansına bakın.

Bu kuralı sohbet mesajı yerine dosyada tutun:

  • Her Cascade oturumunda tekrar kullanılabilir.
  • Ekip üyeleriyle Git üzerinden paylaşılır.
  • Senaryo komutu kalıcı ve sürümlenmiş olur.
  • Cascade başlangıçta kuralı bağlama yükler.

Adım 2: Gerçek apidog run komutunu Apidog’dan alın

<scenario_id> ve <env_id> yer tutucularını tahmin etmeyin.

Apidog’da:

  1. Test senaryosunu açın.
  2. CI/CD sekmesine gidin.
  3. Oluşturulan apidog run komutunu kopyalayın.
  4. .windsurf/rules/apidog.md içindeki örnek komutun yerine yapıştırın.

Örneğin:

apidog run -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

Apidog’un oluşturduğu komutta doğru senaryo kimliği, ortam kimliği ve raporlayıcı seçenekleri bulunur. Desteklenen seçenekler için apidog çalıştırma komutu referansını inceleyin.

Adım 3: Cascade ile senaryoyu çalıştırın

Cascade’i depo içinde açtıktan sonra doğrudan şu isteği verin:

Run the Apidog scenario and tell me the exit code.
Enter fullscreen mode Exit fullscreen mode

Cascade, kural dosyasındaki apidog run komutunu terminalde çalıştırmalıdır.

Komutun otomatik çalışması Windsurf yürütme ayarlarına bağlıdır:

  • Devre Dışı: Her komut için onay ister.
  • Yalnızca İzin Verilenler Listesi: Sadece izin verilen komutlar otomatik çalışır.
  • Otomatik: Premium model, çalıştırma için karar verir.
  • Turbo: Yasaklı komutlar dışındaki komutları otomatik çalıştırır.

apidog run komutunu onay istemeden çalıştırmak istiyorsanız, Komut Paleti üzerinden windsurf.cascadeCommandsAllowList ayarına apidog ekleyin.

{
  "windsurf.cascadeCommandsAllowList": [
    "apidog"
  ]
}
Enter fullscreen mode Exit fullscreen mode

Engelleme için kullanılan ayar windsurf.cascadeCommandsDenyListtir. Bir komut her iki listeyle eşleşirse engelleme listesi önceliklidir. Ayrıntılar için Windsurf terminal belgelerine bakın.

Adım 4: Terminal raporunu okuyun

-r cli raporlayıcısı sonucu doğrudan terminale yazar. Cascade bu çıktıyı okuyarak başarısızlığın nedenini anlayabilir:

  • yanlış durum kodu,
  • eksik alan,
  • beklenen ve gerçek değer farkı,
  • başarısız assertion.

Başarısızlıkları ekip arkadaşlarıyla paylaşmak veya tarayıcıda incelemek için HTML raporu da ekleyin:

apidog run -t <scenario_id> -e <env_id> -r cli,html
Enter fullscreen mode Exit fullscreen mode

html raporlayıcısı bağımsız raporu ./apidog-reports dizinine yazar. cli raporlayıcısını koruyun; böylece Cascade karar vermek için terminal çıktısını da okuyabilir.

JUnit dahil diğer raporlayıcılar için eksiksiz Apidog CLI rehberine ve Apidog CLI test raporlarını nasıl okuyacağınıza bakın.

Cascade’in düzenle-test-düzelt döngüsü

Ödeme yanıtı oluşturan bir endpoint’i değiştirdiğinizi düşünün. Cascade’in beklenen akışı şöyle olmalıdır:

  1. Handler veya servis kodunu düzenler.
  2. Staging ortamına karşı Apidog senaryosunu çalıştırır.
  3. Çıkış kodunu kontrol eder.
  4. Kod 0 ise değişikliğe devam eder.
  5. Kod sıfır değilse başarısız assertion’ı inceler.
  6. Düzeltme yapar ve senaryoyu yeniden çalıştırır.

Bu yaklaşım API testini manuel bir kontrol olmaktan çıkarır ve ajan tabanlı geliştirme döngüsüne dahil eder.

Bu, “delege et, doğrula” modelidir: Cascade komutu çalıştırır ve sonucu okur; siz ise Apidog’da senaryoları görsel olarak yönetirsiniz. Daha geniş yaklaşım için API testi için AI aracıları nasıl kullanılır ve Apidog AI test donanımı içeriklerine bakın.

Cascade’in CLI’ı gerçekten çalıştırdığını doğrulayın

Ajanın “testler geçti” özetine tek başına güvenmeyin. Üç kontrol uygulayın.

1. Terminalde gerçek komutu görün

Cascade’in terminal çıktısında şu satırı arayın:

apidog run ...
Enter fullscreen mode Exit fullscreen mode

Komut ve hemen altındaki ham çıktı görünmüyorsa Cascade testi çalıştırmamış, yalnızca bir özet üretmiş olabilir. Bu durumda ham terminal çıktısını göstermesini isteyin.

2. Çıkış kodunu sorun

Cascade’e doğrudan şunu sorun:

What was the exit code of that apidog run command?
Enter fullscreen mode Exit fullscreen mode

Kural basittir:

  • 0: Tüm assertion’lar geçti.
  • Sıfır olmayan değer: En az bir assertion başarısız oldu.

Metin özeti ile çıkış kodu çelişirse çıkış kodunu doğru kabul edin.

3. Doğru senaryo ve ortamın kullanıldığını kontrol edin

Aşağıdaki türden bir hata görürseniz:

scenario not found
Enter fullscreen mode Exit fullscreen mode

Cascade yanlış veya uydurulmuş bir kimlik kullanmış olabilir. .windsurf/rules/apidog.md içindeki -t ve -e değerlerini, Apidog’un CI/CD sekmesinden aldığınız komutla karşılaştırın.

İsteğe bağlı: Apidog MCP sunucusunu bağlayın

apidog run kuralı test çalıştırmak için yeterlidir. Cascade’in API şemanıza kod yazarken erişmesini istiyorsanız MCP sunucusu ekleyebilirsiniz.

Windsurf, Model Bağlam Protokolü’nü destekler. MCP yapılandırmasını şu dosyadan okuyabilir:

~/.codeium/windsurf/mcp_config.json
Enter fullscreen mode Exit fullscreen mode

Yapılandırmayı Cascade MCP panelinden de yönetebilirsiniz. Ayrıntılar için Windsurf MCP referansını ve Windsurf’te MCP sunucuları nasıl kurulur rehberini inceleyin.

Apidog MCP sunucusu, API belirtimlerini MCP üzerinden sunar. İş bölümü nettir:

  • Apidog CLI: Testleri çalıştırır ve sonuç üretir.
  • Apidog MCP: Cascade’e API şemasını ve belirtim bağlamını sağlar.

Sık karşılaşılan sorunlar

Cascade kuralı yok sayıyor

Cascade genel bir komut kullanıyorsa veya hiçbir komut çalıştırmıyorsa şunları doğrulayın:

<repository-root>/.windsurf/rules/apidog.md
Enter fullscreen mode Exit fullscreen mode
  • Dosya depo kökünün altındadır.
  • Dosya uzantısı .mddir.
  • Kural dosyası 12.000 karakter sınırını aşmaz.
  • Cascade yeniden başlatılmıştır.

Cascade erişim jetonu eklemeye çalışıyor

Makine zaten apidog login ile kimlik doğrulaması yaptıysa komuta erişim jetonu eklemeyin. Jetonları Git’e girebilecek kural dosyalarında saklamayın.

Kimlik doğrulama davranışı için Apidog CLI kimlik doğrulama rehberini inceleyin.

Cascade olmayan bir bayrak kullanıyor

“Bilinmeyen seçenek” hatası, Cascade’in yüklü sürümünüzde bulunmayan bir bayrak uydurduğunu gösterir. Önce şunu çalıştırın:

apidog run --help
Enter fullscreen mode Exit fullscreen mode

Ardından bayrakları bu çıktıya göre kullanın.

Cascade başarısız testi başarılı olarak raporluyor

Özet yerine çıkış koduna bakın:

echo $?
Enter fullscreen mode Exit fullscreen mode

apidog run sonrasında 0 dışında bir değer dönüyorsa test başarısızdır.

Günlük kontrolden sürekli doğrulamaya

Kurulum için gerekenler şunlardır:

  1. Apidog CLI’ı kurun.
  2. Depoya .windsurf/rules/apidog.md ekleyin.
  3. Apidog CI/CD sekmesinden gerçek apidog run komutunu kural dosyasına yapıştırın.
  4. Cascade’in komutu çalıştırıp çıkış kodunu raporlamasını sağlayın.

Böylece API testleri GUI arkasında beklemek yerine Cascade’in geliştirme döngüsüne girer. Bozuk endpoint’ler, değişiklik yayınlanmadan önce yakalanabilir.

Apidog senaryolarını görsel olarak oluşturmaya devam edebilir, Cascade’in ise bunları terminalden çalıştırmasını sağlayabilirsiniz. Aynı komutu CI içinde kullanmak için GitHub Actions’ta Apidog CLI rehberini inceleyin.

Apidog’u indirin, bir senaryo oluşturun, apidog run komutunu Windsurf kuralınıza ekleyin ve Cascade’in sonraki API değişikliğinde testi çalıştırmasını sağlayın.

Top comments (0)