Trae'de Apidog CLI Nasıl Kullanılır

Trae bir döngüdür. Builder aracı deponuzu okur, dosyaları düzenler, terminalde komutlar çalıştırır ve bir sonraki adımda ne yapacağına karar vermek için çıktıyı okur. Peki neden API testleriniz bu döngüde değil? Bir GUI'nin arkasında Apidog'da dururlar ve birisi tıklamayı hatırladığında çalışırlar. Aracınız onlara asla dokunmaz.

Apidog'u bugün deneyin

Çözüm tek bir yapılandırma bloğudur. Apidog CLI, Apidog'da oluşturduğunuz test senaryolarını doğrudan terminalden çalıştıran bir npm paketi olan apidog-cli'dir. CLI yüklendikten ve Trae'nin varlığını bildiği anda Builder, Apidog senaryosunu birim testlerinizi çalıştırdığı gibi çalıştırır: komutu başlatır, çıkış kodunu okur, kırmızıysa kodu düzeltir.

CLI'yi henüz yüklemediyseniz önce bunu yapın. Yapay zeka kodlama aracısı ile Apidog CLI nasıl kurulur makalesi; npm kurulumu, kimlik doğrulaması ve ilk çalıştırmayı kapsar. Bu makale, aşağıdaki koşulların sağlandığını varsayar:

• apidog --version bir sürüm numarası döndürüyor.
• Apidog hesabınız için kimlik doğrulaması tamamlandı.

Konu: Hangi Trae?

Trae, ByteDance'ın VS Code üzerine inşa edilmiş, Builder adı verilen aracı moduyla dosyaları düzenleyen ve terminal komutları çalıştıran bir yapay zeka IDE'sidir. Ürün detaylarını Trae'nin resmi sitesinde inceleyebilirsiniz.

Bu makale, GitHub'daki bağımsız trae-agent araştırma projesiyle değil, masaüstü IDE ile ilgilidir. Trae'yi açtığınızda düzenleyicinin yanında bir sohbet paneli görüyorsanız ve aracıyı Builder moduna geçirebiliyorsanız doğru yerdesiniz.

Bu ayrım önemlidir çünkü Trae'nin proje kurallarını öğrenmek için kendi mekanizması vardır. Bu mekanizma, tek seferlik bir “testlerimi çalıştır” isteğini Builder'ın her çalıştırmada başvuracağı kalıcı bir davranışa dönüştürür: proje kuralları dosyası.

Araçtan bağımsız bir CLI iş akışı için Apidog CLI kapsamlı kılavuzuna bakın.

Adım 1: Proje kuralları dosyasını ekleyin

Trae, Builder çalışmaya başlamadan önce kural dosyalarını okur. Trae kurallar belgelerine göre proje düzeyindeki dosya, depo kökünde şu konumda olmalıdır:

.trae/rules/project_rules.md

Builder bu kuralları başlatma sırasında yükler ve kod üretirken veya düzenlerken onlara başvurur. Tüm projeleriniz için geçerli olan kullanıcı düzeyinde bir user_rules.md dosyası da vardır; ancak bu iş akışı için proje içindeki dosya yeterlidir.

.trae/rules/project_rules.md dosyasına aşağıdaki içeriği ekleyin:

## Apidog CLI ile API testi

Bir API uç noktasına dokunan kodu değiştirdiğinizde, bunu birim testlerle değil,
Apidog test senaryosunu çalıştırarak doğrulayın.

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

Kurallar:
- `apidog run`, her onaylama geçtiğinde 0, herhangi bir başarısızlık durumunda sıfır olmayan bir değerle çıkar.
  Özet iyi görünse bile, sıfır olmayan bir çıkış kodunu başarısız bir test olarak değerlendirin.
- Bu makine `apidog login` aracılığıyla zaten kimliği doğrulanmıştır. Asla bir
  --access-token bayrağı eklemeyin ve bu dosyaya asla bir jeton koymayın.
- Bir bayrak bilinmiyorsa, `apidog run --help` komutunu çalıştırın ve oradaki tam bayrağı kullanın.

CLI komutunu yalnızca sohbette belirtmek yerine bu dosyaya yazmanızın nedeni kalıcılıktır. Sohbet paneline yazılan senaryo kimliği oturum bittiğinde kaybolabilir. Buna karşılık .trae/rules/project_rules.md içindeki senaryo, her ekip üyesi ve her Builder çalıştırması için kullanılabilir.

Trae ayrıca alt dizinlerdeki .trae/rules/ klasörlerini de okur. Monorepo kullanıyorsanız, her servisin yanında servis özelinde kurallar tanımlayabilirsiniz.

Adım 2: Komutu Apidog'dan alın

Komutu tahmin etmeyin. Apidog'da test senaryosunu açın, CI/CD sekmesine gidin ve oluşturulan apidog run komutunu kopyalayın.

Komut zaten şunları içerir:

• -t sonrasında gerçek senaryo kimliği
• -e sonrasında ortam kimliği

Örneğin:

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

Bu kimlikleri .trae/rules/project_rules.md içindeki yer tutucularla değiştirin. Böylece elle kimlik üretmek yerine Apidog'un oluşturduğu geçerli komutu kullanırsınız.

Bayrakların tamamı için apidog run komut referansına bakın.

Adım 3: Builder'ın testi çalıştırmasını sağlayın

Kural bloğunu ekledikten sonra Trae aracısını Builder moduna alın ve depo içinde bir görev başlatın. Builder, başlangıçta project_rules.md dosyasını yüklediği için CLI komutunu zaten bilir.

API'nizi etkileyen bir değişiklik yapın veya doğrudan şu isteği verin:

Apidog test senaryosunu çalıştır ve bana çıkış kodunu söyle.

Builder, kural dosyasındaki apidog run komutunu önerir. Trae'nin onay modeli burada önemlidir:

1. Builder çalıştırmak istediği kabuk komutunu gösterir.
2. Bir Çalıştır düğmesi sunar.
3. Siz onaylayana kadar komut terminalde yürütülmez.
4. Komut tamamlandığında Builder çıktıyı ve çıkış kodunu okur.

-r cli raporlayıcısı, adım adım sonuçları ve özeti doğrudan terminale yazdırır. Builder her isteği ve onaylamayı terminal çıktısından değerlendirebilir.

Adım 4: Raporu Trae içinde okuyun

Çalıştırma başarısız olduğunda rapor, hatanın bağlamını içerir. -r cli ile Builder, Trae terminalinde şunları görebilir:

• Her istek
• Her onaylama
• Beklenen ve gerçek değerler
• Başarısız olan alan veya durum kodu

Bu bilgiler genellikle Builder'ın düzeltme için hangi dosya veya davranışa odaklanacağını belirlemesine yeterlidir.

Tarayıcıda açabileceğiniz veya ekip arkadaşlarınızla paylaşabileceğ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ı kendi kendine yeten raporu şu dizine yazar:

./apidog-reports

cli raporlayıcısını listede tutun. Böylece Builder, bir sonraki adımına karar vermek için ihtiyaç duyduğu satır içi terminal çıktısını almaya devam eder.

JSON ve JUnit gibi CI araçlarının ayrıştırabildiği diğer rapor formatları için Apidog CLI test raporları kılavuzuna bakın.

Trae'nin kendi döngüsü içinde test etmesi

Asıl değer, siz istemeden Builder'ın project_rules.md içindeki yönergeye göre senaryoyu çalıştırmasıyla ortaya çıkar.

Örneğin Builder'ın ödeme yanıtı oluşturan bir işleyiciyi düzenlediğini düşünün. Döngü şu hale gelir:

1. Kodu düzenler.
2. Apidog senaryosunu hazırlık ortamında çalıştırır.
3. Çıkış kodunu okur.
4. Sonuca göre devam eder veya düzeltme yapar.

Çıkış kodu 0 ise görevine devam eder. Çıkış kodu sıfır değilse raporu inceler, başarısız onaylamayı belirler ve düzeltmeyi dener:

• Yanlış durum kodu
• Eksik alan
• Beklenmeyen alan değeri
• Başarısız doğrulama

Ardından testi yeniden çalıştırır. Böylece API testi, Builder'ın birim testleriyle aynı düzenle-test et-düzelt döngüsünün parçası olur.

Bu yaklaşım, aracı iş akışlarında kullanılan delege et-sonra doğrula modelidir. Builder komutu çalıştırır ve sonucu okur; siz de Apidog'da senaryoları görsel olarak yönetmeye devam edersiniz.

Daha geniş kullanım kalıpları için API testi için yapay zeka aracılarını ve Apidog yapay zeka test donanımını inceleyin.

Trae'nin gerçekten CLI'yi çalıştırdığını doğrulayın

Aracılar bazen gerçekte yapmadıkları işlemleri başarılı olarak özetleyebilir. Builder için üç kontrol uygulayın.

1. Komutun gerçekten çalıştığını kontrol edin

Trae, Builder'ın yürüttüğü komutları ve terminal çıktılarını gösterir. Terminalde tam apidog run komutunu ve hemen altındaki sonucu arayın.

Builder testleri çalıştırdığını söylüyor ancak komut görünmüyorsa, ham çıktıyı göstermesini ve komutu yeniden çalıştırmasını isteyin.

2. Çıkış kodunu doğrulayın

Builder'a şu soruyu sorun:

O apidog run komutunun çıkış kodu neydi?

apidog run davranışı nettir:

• Tüm onaylamalar geçtiğinde 0 ile çıkar.
• Herhangi bir başarısızlıkta sıfır olmayan bir kodla çıkar.

Builder “testler geçti” dese bile çıkış kodu sıfır değilse, başarısızlık olarak çıkış kodunu esas alın.

3. Doğru senaryonun çalıştığını kontrol edin

Çalıştırma senaryo bulunamadı hatası verirse Builder yanlış kimlik kullanmış olabilir. Şunları karşılaştırın:

• .trae/rules/project_rules.md içindeki -t değeri
• .trae/rules/project_rules.md içindeki -e değeri
• Apidog'un CI/CD sekmesinde oluşturduğu komut

Kural dosyasındaki kimlikler, Apidog'daki güncel komutu yansıtmalıdır.

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

project_rules.md üzerinden apidog run çalıştırmak çoğu test ihtiyacını karşılar. MCP sunucusu bağlamak ise Builder'ın yalnızca testi çalıştırmasını değil, kod yazarken API spesifikasyonunu da kullanmasını sağlar.

Trae ajanları MCP istemcisi olarak çalışabilir ve bir MCP sunucusunun sunduğu araçları çağırabilir.

Sunucu eklemek için:

1. Trae ayarlarını açın.
2. MCP sekmesine geçin.
3. Pazardan bir sunucu seçin veya Manuel Ekle seçeneğini kullanın.
4. Sunucunun command, args ve env değerlerini içeren JSON yapılandırmasını girin.

Yapılandırma ayrıntıları için Trae MCP sunucuları ekleme kılavuzuna bakın.

Apidog MCP sunucusu, API spesifikasyonlarınızı MCP üzerinden sunar. Böylece Builder kod yazarken şemanızı okuyabilir.

İş bölümü nettir:

• CLI: Test senaryolarını çalıştırır.
• MCP: Ajana API spesifikasyonunu sağlar.

Trae yanlış anladığında

Kurulum sırasında sık karşılaşılan sorunları doğrudan kontrol listesiyle çözebilirsiniz.

Kural dosyasını görmezden geliyor

Builder genel bir komut çalıştırıyorsa veya hiç komut çalıştırmıyorsa, dosya yüklenmiyor olabilir.

Şunları doğrulayın:

<depo-kökü>/.trae/rules/project_rules.md

Klasör adı rule değil, rules olmalıdır. Gerekirse Trae oturumunu yeniden başlatın; böylece kurallar yeniden yüklenir.

Erişim jetonu eklemeye çalışıyor

Builder --access-token eklemeye çalışıyorsa genel örneklerden tahmin yapıyor olabilir.

Makine zaten apidog login ile kimliği doğrulanmışsa:

• Kural dosyasına erişim jetonu koymayın.
• Builder'ın --access-token eklememesini açıkça belirtin.
• Gerçek bir token'ı asla project_rules.md içine yazmayın.

CLI'nin etkileşimli kullanımda ve CI ortamında kimlik bilgilerini nasıl yönettiği için Apidog CLI kimlik doğrulaması makalesini inceleyin.

Bir bayrak uyduruyor

Bilinmeyen seçenek hatası, Builder'ın yüklü sürümünüzde bulunmayan bir bayrağı kullandığını gösterir.

Bu durumda Builder'a şunu çalıştırmasını söyleyin:

apidog run --help

Ardından yalnızca yardım çıktısındaki bayrakları kullanın. Bu çıktı, yüklü CLI sürümünüz için geçerli kaynaktır.

Başarısız çalıştırmayı başarılı raporluyor

Bu en maliyetli hatadır. Önlem olarak hem kural dosyanızda hem de doğrulama adımınızda çıkış kodu kontrolü bulunmalıdır.

Özet metni ile çıkış kodu çelişirse, çıkış kodu kazanır.

Günlük bir ajandan test edilmiş bir döngüye

Kurulum bu kadar:

1. Kurulum kılavuzunu izleyerek apidog-cli'yi yükleyin.
2. .trae/rules/project_rules.md dosyasına Apidog komut bloğunu ekleyin.
3. Gerçek senaryo ve ortam kimliklerini Apidog'un CI/CD sekmesinden alın.
4. Builder'ın API değişikliklerinden sonra apidog run komutunu çalıştırmasını sağlayın.
5. Sonucu her zaman çıkış koduyla doğrulayın.

Böylece bozuk bir uç nokta, değişiklik gönderildikten sonra değil, Builder hâlâ kod üzerinde çalışırken yakalanır.

GUI arkasındaki bir test, bir insan tıkladığında çalışır. Terminalden çalışan bir komut ise Builder ihtiyaç duyduğunda çalışabilir. Senaryolarınızı Apidog'da görsel olarak oluşturmaya devam edin, apidog run komutunu .trae/rules/project_rules.md dosyasına ekleyin ve Builder'ın sonraki API değişikliğinde bu testi çalıştırmasını sağlayın.

Apidog'u indirin, bir senaryo oluşturun ve CLI komutunu proje kurallarınıza ekleyin. Aynı senaryoyu bir ajan olmadan CI içinde çalıştırmak için GitHub Actions'ta Apidog CLI rehberine bakın.