Windsurf'ün Cascade aracısı bir döngüde çalışır: dosyaları düzenler, terminal komutlarını çalıştırır, çıktıyı okur ve sonra ne yapacağına karar verir. Peki neden API testleriniz bu döngüde değil? Bir GUI'nin arkasında Apidog'da duruyorlar ve biri tıklamayı hatırladığında çalışıyorlar. Cascade onlara asla dokunmaz.
Çözüm tek bir yapılandırma bloğudur. Apidog CLI, Apidog'da oluşturduğunuz test senaryolarını doğrudan bir terminalden çalıştıran bir npm paketi olan apidog-cli'dir. CLI yüklendikten ve Cascade varlığını öğrendikten sonra, Windsurf bir Apidog senaryosunu birim testlerinizi çalıştırdığı gibi çalıştırır: komutu ateşleyin, çıkış kodunu okuyun, kırmızı dönerse kodu düzeltin.
CLI'yı henüz yüklemediyseniz, önce bunu yapın. Bir AI kodlama aracısı ile Apidog CLI nasıl yüklenir, npm kurulumunu, kimlik doğrulamayı ve ilk çalıştırmayı bir aracının yazmasıyla anlatır. Bu makale, apidog --version komutunun bir sayı yazdırdığını ve Apidog hesabınızın kimliğinin doğrulandığını varsayar.
Bu hangi Windsurf hakkında?
Windsurf, Codeium'un aracı tabanlı IDE'sidir ve yerleşik aracısının adı Cascade'dir. Cascade yerel olarak çalışır, deponuzu okur, dosyaları düzenler ve entegre terminalinizde kabuk komutlarını yürütür, otomatik yürütme ayarınıza göre onay ister. Bu, bir tarayıcı uzantısı veya otomatik tamamlama eklentisi değil, düzenleyici ve aracıdır.
Henüz kurmadıysanız, Windsurf'ü nasıl indirip kuracağınız ile başlayın. Cascade projenizde açıldığında, ona Apidog CLI hakkında kendi kural mekanizması aracılığıyla öğretebilirsiniz, bu da tek seferlik "testlerimi çalıştır" komutunu Cascade'in kendi başına yapacağı bir şeye dönüştürür.
Adım 1: .windsurf/rules dosyasına bir Apidog kuralı ekleyin
Cascade, çalışmaya başlamadan önce proje kurallarını Markdown dosyalarından okur. Bunları deponuzun kök dizinindeki .windsurf/rules/ dizinine, her dosya için bir kural olacak şekilde yerleştirin. Windsurf hala çalışma alanı kökündeki eski tek dosyalı .windsurfrules dosyasını ve her projeye uygulanan genel bir ~/.codeium/windsurf/memories/global_rules.md dosyasını okur, ancak proje bazında bir talimat için .windsurf/rules/ dizini doğru yerdir. Bu, Windsurf'ün kurallar ve hafızalar referansında belgelenmiştir.
Şöyle bir blok ile .windsurf/rules/apidog.md dosyasını oluşturun:
# 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.
Neden bir sohbet mesajı yerine bir kural dosyası? Sohbete yazılan bir senaryo kimliği, oturum sona erdiğinde kaybolur. .windsurf/rules/apidog.md dosyasındaki ise bundan sonra her ekip üyesi ve her Cascade oturumu için oradadır. Kalıcıdır, Git'te sürümlenir ve Cascade başlangıçta otomatik olarak bağlama yükler.
Adım 2: Komutu Apidog'dan alın
Bu bloktaki <scenario_id> ve <env_id> tahmin edeceğiniz yer tutucular değildir. Apidog sizin için tam komutu oluşturur.
Apidog'da test senaryosunu açın, CI/CD sekmesine gidin ve hazır apidog run komutunu kopyalayın. Doğru senaryo Kimliği, ortam Kimliği ve raporlayıcı bayrakları zaten doldurulmuştur. Bu komutu örnek satırın yerine .windsurf/rules/apidog.md dosyanıza yapıştırın. Artık kural, projenize karşı gerçekten çalışan bir komut içeriyor, bir şablon değil.
Bu komutun ve kabul ettiği her bayrağın tam yapısı için apidog çalıştırma komutu referansına bakın.
Adım 3: Cascade'in testi çalıştırmasını sağlayın
Kural yerindeyken, deponuzda Cascade'i açın. Başladığında .windsurf/rules/apidog.md dosyasını yükler, böylece CLI'ın orada olduğunu zaten bilir. API'nizi etkileyen bir değişiklik yapın veya sadece kontrolü çalıştırmasını isteyin:
Run the Apidog scenario and tell me the exit code.
Cascade, kuralınızdaki apidog run komutunu verir. Bir istem olmadan çalışıp çalışmadığı, otomatik yürütme ayarınıza bağlıdır. Windsurf dört seviye sunar: Devre Dışı (her komut onay gerektirir), Yalnızca İzin Verilenler Listesi (yalnızca izin verilenler listenizle eşleşen komutlar otomatik çalışır), Otomatik (premium modelde bir yargı çağrısı) ve Turbo (yasaklı komutlar dışında her şey otomatik çalışır). Turbo modunda basit bir apidog run kendi kendine çalışır; daha sıkı modlarda Cascade duraklar ve önce sorar.
apidog run'ın her şeyi gevşetmeden otomatik olarak yürütülmesini istiyorsanız, onu izin verilenler listenize ekleyin. Ayar, Komut Paleti'nden Ayarları Aç altında erişilebilen windsurf.cascadeCommandsAllowList'tir; apidog ekleyin ve Cascade komutu sormadan çalıştırır. Eşleşen engelleme listesi ayarı windsurf.cascadeCommandsDenyList'tir ve bir komut her ikisiyle de eşleştiğinde engelleme listesi kazanır. Her ikisi de Windsurf'ün terminal belgelerinde ele alınmıştır. Staging'e karşı salt okunur bir senaryo, bir izin verilenler listesi girişinin tam da oluşturulduğu güvenli, çalışma alanı içi komut türüdür.
Adım 4: Raporu Windsurf içinde okuyun
Bir çalıştırma kırmızıya döndüğünde, rapor cevabı içerir. -r cli raporlayıcısı, Cascade'in terminalinde adım adım bir sonuç ve özet yazdırır: her istek, her onay ve beklenen değere karşı gerçek değerle hangisinin başarısız olduğu. Başarısız olan onay, genellikle Cascade'in bir sonraki geçişinde düzeltmeyi bulması için yeterli olan tam alanı veya durum kodunu belirtir.
Bir tarayıcıda açabileceğiniz veya bir ekip arkadaşınıza verebileceğiniz bir rapor için HTML raporlayıcısını ekleyin:
apidog run -t <scenario_id> -e <env_id> -r cli,html
html raporlayıcısı, ./apidog-reports konumuna bağımsız bir dosya yazar. cli'yi listede tutun ki Cascade, bir sonraki adımına karar vermek için okuduğu satır içi çıktıyı hala alabilsin. JUnit formatı CI panolarının ayrıştırdığı her raporlayıcı dahil olmak üzere, eksiksiz Apidog CLI rehberine ve Apidog CLI test raporlarını nasıl okuyacağınıza bakın.
Kendi döngüsü içinde Windsurf testi
Buradaki mesele, siz sormayı bıraktığınızda ve kural ona söylediği için Cascade'in senaryoyu kendi başına çalıştırması durumunda ne olduğudur.
Cascade'in bir ödeme yanıtı oluşturan bir işleyiciyi düzenlediğini hayal edin. Döngüsü değişir. Kodu düzenler, sonra zafer ilan etmek yerine, Apidog senaryonuzu staging'e karşı çalıştırır, çıkış kodunu okur ve buna göre hareket eder. Yeşilse, devam eder. Kırmızıysa, raporu açar, hangi onaylamanın başarısız olduğunu okur (durum kodu, eksik alan, yanlış değer), bir düzeltme denemesi yapar ve yeniden çalıştırır. API testi, Cascade'in birim testlerinizi zaten çalıştırdığı aynı düzenle-test et-düzelt döngüsünün bir parçası haline gelir. Tek bir kural yazdınız ve Cascade komutu zaten nasıl çalıştığına dahil etti.
Bu, herhangi bir aracı iş akışını güvenli hale getiren delege et-doğrula modelidir. Cascade komutu çalıştırır ve sonucu okur; siz Apidog'da senaryoları görsel olarak yazmaya devam eder ve aracının çıkış kodlarını dürüstçe okuduğunu kontrol edersiniz. Daha geniş kalıp için, API testi için AI aracıları nasıl kullanılır ve Apidog AI test donanımına bakın.
Cascade'in gerçekten CLI'yı çalıştırdığını doğrulayın
Aracılar hak etmedikleri başarıyı bildirir ve Cascade de bir istisna değildir. Üç kontrol, sorunları ne sıklıkta yakaladıklarına göre sıralanmıştır.
Öncelikle, komutun çalışıp çalışmadığını onaylayın. Cascade, yürüttüğü komutları ve çıktılarını terminalde satır içi olarak gösterir. apidog run ... satırını ve altında bir sonuç arayın. Cascade testleri çalıştırdığını söylüyorsa ancak komutu görmüyorsanız, hiç yapmadığı bir şeyi özetlemiştir. Tekrar çalıştırmasını isteyin ve ham çıktıyı gösterin.
İkincisi, önemli olan çıkış kodunu onaylayın. Ona doğrudan sorun:
What was the exit code of that apidog run command?
apidog run, her onaylama geçtiğinde 0 ile ve herhangi bir şey başarısız olduğunda sıfır olmayan bir değerle çıkar. Bu tek davranış, Cascade'in veya bir işlem hattının çalıştırmayı temiz bir kapı olarak ele almasını sağlar. Cascade'in yazısı "testler geçti" dese de çıkış kodu sıfır değilse, doğru olan çıkış kodudur.
Üçüncüsü, gerçek senaryoyu kullandığını onaylayın. Bir çalıştırma "senaryo bulunamadı" hatasıyla başarısız olursa, Cascade bir Kimlik uydurmuş veya yanlış hatırlamış olabilir. -t ve -e değerlerini kural dosyanıza ve Apidog'un CI/CD sekmesinde oluşturduğu komuta göre yeniden kontrol edin. .windsurf/rules/apidog.md dosyasındaki Kimlikler gerçektir.
İsteğe bağlı: Apidog MCP sunucusunu bağlayın
Bir kuraldan apidog run çalıştırmak, ihtiyacınız olanın çoğunu karşılar. Bir adım daha ileri gitmek için bir MCP sunucusu bağlayın.
Cascade, Model Bağlam Protokolü'nü destekler. Windsurf, sunucu listesini doğrudan düzenleyebileceğiniz veya Cascade MCP paneli aracılığıyla yönetebileceğiniz ~/.codeium/windsurf/mcp_config.json dosyasından okur; format Windsurf'ün MCP referansında belgelenmiştir ve Windsurf'te MCP sunucuları nasıl kurulur panel aracılığıyla anlatılır. Apidog MCP sunucusu, API belirtimlerinizi MCP üzerinden sunar, böylece Cascade, kod yazarken şemanızı okuyabilir, sadece sonradan değil. İş bölümü nettir: CLI testleri çalıştırır ve MCP, aracıya belirtimi besler.
Windsurf yanlış yaptığında
Kurulum sırasında birkaç hata sıkça ortaya çıkar.
Kuralı yok sayar. Cascade genel bir komut çalıştırırsa veya hiç çalıştırmazsa, kural yüklenmiyor olabilir. Dosyanın deponuzun kök dizinindeki .windsurf/rules/ içinde yaşadığını ve .md uzantısına sahip olduğunu onaylayın. Her kural dosyası 12.000 karakterle sınırlıdır, bu nedenle Apidog bloğunu kısa tutun. Cascade'i yeniden başlatmak yeni bir okumayı zorlar.
Yine de bir erişim jetonu gönderir. Cascade, komuta bir erişim jetonu eklemeye çalışırsa, genel örneklerden tahmin yürütüyordur. Makine apidog login aracılığıyla kimliği doğrulandığı için kuralınız zaten bunu yapmamasını söyler. Satırı pekiştirin ve hiçbir zaman gerçek bir jetonu taahhüt edilecek bir kural dosyasına koymayın. Kimlik doğrulamanın gerçekte nasıl çalıştığına dair Apidog CLI kimlik doğrulama rehberine bakın.
Bir bayrak uydurur. Bir "bilinmeyen seçenek" hatası, Cascade'in sürümünüzde olmayan bir bayrak tahmin ettiği anlamına gelir. Ona apidog run --help komutunu çalıştırmasını ve tam bayrağı oradan kopyalamasını söyleyin, bu her zaman yüklü sürümünüz için doğrudur.
Başarısız bir çalıştırmada başarılı olduğunu bildirir. En maliyetli olanı ve çıkış kodu kuralının hem kural dosyanızda hem de doğrulama adımınızda olmasının nedeni budur. Özet ve çıkış kodu çeliştiğinde, çıkış kodu kazanır.
Günlük bir ajandan test edilmiş bir döngüye
Kurulum budur. Kurulum kılavuzunu takip ederek apidog-cli'yi bir kez yükleyin, deponuzun .windsurf/rules/ dizinine kısa bir Apidog kuralı ekleyin ve Cascade, API testlerinizi nasıl çalıştıracağını ve kodu düzenlemek için zaten kullandığı aynı döngü içinde sonucu nasıl okuyacağını bilir. Bozuk bir uç nokta, Cascade hala değişiklik üzerinde çalışırken yakalanır, yayınlandıktan sonra değil.
Bir GUI'nin arkasındaki bir test, bir insan tıkladığında çalışır; tek satırlık bir komut ise Cascade ne zaman isterse çalışır. Siz Apidog'da senaryoları görsel olarak oluşturmaya devam edersiniz ve aracınız onları siz izlemezken çalıştırır. Yerel olarak çalıştığında aynı komutu bir işlem hattında çalıştırmak için, GitHub Actions'ta Apidog CLI sırları, raporlayıcıları ve çıkış kodu geçişini kapsar. Apidog'u indirin, bir senaryo oluşturun, apidog run komutunu bir Windsurf kuralına bırakın ve Cascade'in bir sonraki değişiklikte onu nasıl alacağını izleyin.