Çoğu API testi hayatına bir GUI'de başlar. Tıklarsınız, birkaç onay ekler ve elle çalıştırırsınız. Bu, aynı testlerin her gönderimde, her gece veya kimsenin izlemediği bir pipeline içinde çalışması gerekene kadar işe yarar. Bu noktada, yazabileceğiniz, komut dosyası haline getirebileceğiniz ve CI'ya yönlendirebileceğiniz tek bir komut istersiniz.
Bu komut Apidog CLI'dir. Bu eğitim, terminalinizden gerçek bir REST API'yi uçtan uca test etme konusunda size yol gösterir: aracı kurun, bir API'yi içe aktarın, bir ortam kurun, bir test senaryosu oluşturun, onaylarla çalıştırın, ona veri besleyin ve raporları toplayın. Aşağıdaki her komut ve çıktı, canlı bir genel API'ye karşı Apidog CLI sürüm 2.2.2 üzerinde gerçek bir çalışmadan alınmıştır, böylece siz de takip edebilir ve aynı sonuçları alabilirsiniz.
Aynı platformun görsel tarafını istiyorsanız, Apidog'u indirebilir ve testleri önce uygulamada tasarlayabilirsiniz. Ancak buradaki her şey komut satırında kalır.
Ne inşa edeceksiniz?
restful-api.dev adlı, /objects kaynağı üzerinde gerçek CRUD işlemlerine sahip ücretsiz bir genel REST API'yi test edeceksiniz. Sonunda şunlara sahip olacaksınız:
- Bir OpenAPI dosyasından beslenmiş bir Apidog projesi
- Bir nesne oluşturan, geri okuyan ve silen, her adımda onaylama yapan üç adımlı bir test senaryosu
- Her test verisi satırı için bir kez bir isteği tekrarlayan veri odaklı bir çalıştırma
- CLI, HTML, JSON ve JUnit raporları, ayrıca paylaşılabilir bir bulut raporu
Aynı akış kendi API'nize de ölçeklenir ve CI/CD'de API testleri çalıştırmak için temel oluşturur.
Başlamadan önce
Node.js 16 veya daha yenisine ve bir Apidog hesabına ihtiyacınız var. Koşucuları ilk karşılaştırıyorsanız, kısa versiyonu şudur: Apidog CLI, tam test senaryolarını çalıştırır ve API kaynaklarını kod olarak yönetir, bu da onu Newman ve Postman CLI'dan ayırır.
Adım 1: Kurulum ve oturum açma
CLI'yi npm'den global olarak kurun:
npm install -g apidog-cli@latest
Kurulduğunu doğrulayın:
apidog --version
# 2.2.2
Şimdi kimlik doğrulayın. Apidog uygulamasından avatarınızın altından, Hesap Ayarları, API Erişim Tokeni bölümünden bir token alın, ardından çalıştırın:
apidog login --with-token <YOUR_TOKEN>
Token, ~/.apidog/config.toml dosyasına kaydedilir, bu yüzden bunu her makinede yalnızca bir kez yaparsınız. Kim olduğunuzu kontrol edin:
Her komut, komut dosyası oluşturmayı veya jq'ya yönlendirmeyi kolaylaştıran bir success bayrağı ve yararlı agentHints içeren yapılandırılmış JSON döndürür.
Adım 2: Bir proje oluşturun
Projeyi oluşturmak için takımı seçin, ardından oluşturun:
apidog team list
apidog project create --team 329562 --name "CLI Saha Testi"
Yeni proje kimliğini geri alırsınız.
Geri kalan bu eğitimin kopyala-yapıştır olabilmesi için bunu bir kabuk değişkenine kaydedin:
PID=1314366 # kendi proje kimliğinizle değiştirin
apidog project get $PID
Adım 3: REST API'nizi içe aktarın
Uç noktaları elle oluşturabilirsiniz, ancak bir OpenAPI dosyasını içe aktarmak daha hızlıdır ve gerçek projelerin nasıl başladığını yansıtır. İşte /objects CRUD uç noktalarını açıklayan küçük bir özellik (bunu objects-api.openapi.json olarak kaydedin):
{
"openapi": "3.0.3",
"info": { "title": "Nesneler API", "version": "1.0.0" },
"servers": [{ "url": "https://api.restful-api.dev" }],
"paths": {
"/objects": {
"get": { "summary": "Nesneleri listele" },
"post": { "summary": "Nesne oluştur" }
},
"/objects/{id}": {
"get": { "summary": "Kimliğe göre nesne al" },
"put": { "summary": "Nesneyi güncelle" },
"delete": { "summary": "Nesneyi sil" }
}
}
}
İçe aktarın:
apidog import --project $PID --format openapi --file ./objects-api.openapi.json
# "createCount": 5 (5 uç nokta oluşturuldu, 0 hata)
İçe aktarıcı ayrıca openapi, postman, har, insomnia, jmeter ve daha fazlasını okur. Nelerin geldiğini listeleyin:
apidog endpoint list --project $PID
# 37921721 get /objects
# 37921722 post /objects
# 37921723 get /objects/{id}
# 37921724 put /objects/{id}
# 37921725 delete /objects/{id}
Adım 4: Bir ortam kurun
Bir ortam, temel URL'yi ve testlerinizin yeniden kullandığı herhangi bir değişkeni tutar. Bir tane oluşturun ve kimliğini kaydedin:
apidog environment create "Production" --project $PID --base-url "https://api.restful-api.dev"
apidog environment list --project $PID
# { "id": 6334917, "name": "Production", "baseUrls": { "default": "https://api.restful-api.dev" } }
ENV=6334917 # ortam kimliğinizle değiştirin
Daha sonra çalıştırma komutuna -e $ENV parametresini geçireceksiniz, böylece test, istekleri nereye göndereceğini bilir.
Adım 5: Otomasyon yazma engelini aşın
İnsanları şaşırtan ilk şey bu. Test senaryoları ve test verileri otomasyon kaynaklarıdır ve bunları harici bir araçtan ana dalınıza yazmak varsayılan olarak engellenir:
apidog test-scenario create --project $PID --name "x" --description "" --folder-id 0 --priority 1
# "error": { "code": "403075", "message": "Automation caller branch required" }
Bu bir güvenlik önlemidir, bir hata değil. Bunu aşmak için iki yolunuz var:
- Apidog masaüstü uygulamasında Proje Ayarları, Özellik Ayarları, Yapay Zeka Özelliği Ayarları, Harici Yapay Zeka Düzenleme İzinleri altında doğrudan düzenleme iznini açın.
- Yapay zeka dalında çalışın, bu da otomasyon değişikliklerini birleştirmeyi seçene kadar izole tutar. Bu yol tamamen komut satırında kalır, bu yüzden bunu kullanacağız.
Dalı main'den oluşturun:
apidog branch create --project $PID --type ai \
--name "ai/20260616-from-main-cli-field-test" --from main
BR="ai/20260616-from-main-cli-field-test"
ai/YYYYMMDD-from-<kaynak>-<özellik> adlandırma deseni, CLI'nin beklediği kuraldır. import, environment create ve uç nokta düzenlemelerinin kilitli olmadığını; sadece otomasyon kaynaklarının kilitli olduğunu unutmayın.
Adım 6: Bir test senaryosu oluşturun
Bir senaryo, aralarında onaylamalar bulunan sıralı bir istek akışıdır. Önce kabuğu oluşturursunuz, sonra adımları eklersiniz. Yapay zeka dalınızda oluşturun:
apidog test-scenario create --project $PID --branch "$BR" \
--name "Nesne CRUD yaşam döngüsü" \
--description "Bir nesne oluşturun, okuyun, sonra silin ve her adımı onaylayın" \
--folder-id 0 --priority 1
SID=1836498 # döndürülen senaryo kimliği
Adımlar, bir JSON dosyasıyla update aracılığıyla eklenir. Herhangi bir JSON yazımında altın kural, göndermeden önce doğrulamaktır, böylece hiçbir zaman hatalı bir yük göndermezsiniz:
apidog cli-schema get test-scenario-update # tam şekli görün
apidog cli-schema validate test-scenario-update --file ./steps-crud.json
# "veri dosyası geçerli"
Her adım, bir istek artı yanıtı doğrulayan ve bir sonraki adımlara veri aktaran küçük bir komut dosyasıdır. Yeni bir nesne gönderen ve daha sonraki adımlar için id'sini kaydeden oluşturma adımının şekli şöyledir:
{
"type": "customHttp",
"name": "Nesne oluştur",
"customHttpRequest": {
"path": "https://api.restful-api.dev/objects",
"method": "post",
"requestBody": { "type": "json", "data": "{\"name\":\"Apidog CLI Saha Testi\",\"data\":{\"price\":42}}" },
"postProcessors": [{
"type": "customScript",
"data": "pm.test('oluşturma 200 döndürür', function () { pm.response.to.have.status(200); });\nvar body = pm.response.json();\npm.globals.set('objId', body.id);",
"enable": true
}],
"projectId": 1314366
}
}
Sonraki adımlar, aynı nesneyi almak ve sonra silmek için URL'de {{objId}}'yi yeniden kullanır. Tam üç adımlı dosyayı uygulayın:
apidog test-scenario update $SID --project $PID --branch "$BR" --file ./steps-crud.json
# "success": true
Senaryoları JSON olarak yazmak zorunda değilsiniz. Bunları Apidog'da görsel olarak oluşturmak ve CLI'den çalıştırmak da aynı derecede geçerlidir. JSON yolu, testlerinizi diğer kodlar gibi sürüm kontrollü ve incelenebilir kılmak istediğinizde önemlidir.
Adım 7: Komut satırından çalıştırın
İşte karşılığı. Senaryoyu CLI raporlayıcısı ile çalıştırın:
apidog run -t $SID --project $PID --branch "$BR" -e $ENV -r cli
❏ Nesne CRUD yaşam döngüsü
↳ Nesne oluştur POST .../objects [200 OK]
✓ oluşturma 200 döndürür ✓ yanıtta bir kimlik var ✓ isim geri yansıtıldı
↳ Oluşturulan nesneyi al GET .../objects/ff80...3de [200 OK]
✓ alma 200 döndürür ✓ kimlik oluşturulan nesneyle eşleşiyor ✓ fiyat verilerde kalıcı
↳ Nesneyi sil DELETE .../objects/ff80...3de [200 OK]
✓ silme 200 döndürür
Http İstekleri 3 / 0 başarısız
Onaylamalar 7 / 0 başarısız
Üç istek, yedi onaylama, sıfır hata ve oluşturulan id ilk adımdan sonraki iki adıma aktı. Bu, tek bir tıklama olmadan çalışan eksiksiz bir API testidir.
Konsol çıktısı yerine dosya mı istiyorsunuz? Aynı anda birkaç raporlayıcı isteyin ve onları bir klasöre işaret edin:
apidog run -t $SID --project $PID --branch "$BR" -e $ENV \
-r cli,html,json,junit --out-dir ./reports --out-file "crud-report"
ls ./reports
# crud-report.html crud-report.json crud-report.xml
JUnit XML, CI sunucunuzun her yapı için geçiş/başarısızlık durumunu okuduğu formattır. HTML raporu, ekip arkadaşlarınızla paylaştığınız rapordur.
Adım 8: Aynı testi birçok girdiye karşı çalıştırın
Gerçek test paketleri birden fazla durumu kapsar. Veri odaklı çalıştırmalar, her veri satırı için bir senaryoyu tekrarlar, böylece on senaryo yazmadan on girdiyi test edersiniz. Bu, CSV ve JSON'dan parametreli test ile aynı fikirdir.
Satırlarınızı bir dosyaya koyun:
[
{ "name": "Pixel 8 Pro", "price": 999 },
{ "name": "iPhone 15", "price": 899 },
{ "name": "Galaxy S24", "price": 799 }
]
Verilere -d ile referans verin ve senaryonun her satırdan {{name}} ve {{price}} okumasına izin verin:
apidog run -t $DID --project $PID --branch "$BR" -e $ENV -d ./objects-data.json -r cli
İterasyon 1/3 … ✓ satır oluşturuldu (200) ✓ isim veri satırıyla eşleşiyor
İterasyon 2/3 … ✓ satır oluşturuldu (200) ✓ isim veri satırıyla eşleşiyor
İterasyon 3/3 … ✓ satır oluşturuldu (200) ✓ isim veri satırıyla eşleşiyor
İterasyonlar 3 / 0 başarısız Onaylamalar 6 / 0 başarısız
Üç satır girdi, üç iterasyon çıktı. Dosyayı bir CSV ile değiştirin, başka hiçbir şey değişmez.
Adım 9: Raporları toplayın
Yerel çalıştırmalar dosyaları yazar. Tüm ekibinizin bir tarayıcıda açabileceği bir rapor almak için --upload-report ekleyin:
apidog run -t $SID --project $PID --branch "$BR" -e $ENV -r cli --upload-report
# Apidog CLI veri çalıştırmaları başarıyla buluta yüklendi.
# https://app.apidog.com/link/project/1314366/api-test/test-report/2605398
Bilmeye değer bir pürüz var: bir bulut raporu, üzerinde çalıştığı dallla etiketlenir. Bu çalıştırma sizin AI dalınızda gerçekleştiğinden, basit bir apidog test-report list --project $PID (ki bu main'i hedefler) bunu göstermez. Bunun yerine yükleme bağlantısından kimliğine göre alın:
apidog test-report get 2605398 --project $PID
apidog test-report download 2605398 --project $PID --format json --output ./cloud-report.json
Adım 10: API'nizi belge veya özellik olarak dışa aktarın
CLI ayrıca verileri dışarı aktarır. Projeyi bir OpenAPI dosyası, Markdown veya HTML belgeleri olarak dışa aktarın:
apidog export --project $PID --format openapi --oas-version 3.0 --output ./openapi-export.json
apidog export --project $PID --format markdown --output ./api-docs.md
apidog export --project $PID --format html --output ./api-docs.html
Bu, her değişiklikte yeni bir spesifikasyonu kaydetmek veya bir pipeline'dan statik belgeleri yayınlamak için kullanışlıdır.
Adım 11: CI/CD'ye bağlayın
Elle çalıştırdığınız her şey bir pipeline'da üç satır haline gelir. Temel olanı kurmak, ardından CI sunucusunun sonuçları okuyabilmesi için JUnit raporlayıcısıyla çalıştırmaktır:
- run: npm install -g apidog-cli@latest
- run: apidog login --with-token $APIDOG_TOKEN
- run: apidog run -t $SID --project $PID -e $ENV -r junit --out-dir ./reports
Tokenı bir sır olarak saklayın ve bir test başarısız olduğunda yapıyı başarısız kılın (CLI, başarısızlık durumunda sıfırdan farklı bir çıkış kodu döndürür). Tam, kopyala-yapıştır bir iş akışı için, GitHub Actions'da Apidog CLI testlerini çalıştırma kılavuzuna bakın veya bir pipeline'a uyan API test otomasyon araçlarına göz atın.
Sonuç
Boş bir terminalden, paylaşılabilir raporlarla geçen, veri odaklı bir API testine geçtiniz ve komut satırından hiç ayrılmadınız. Desen her zaman aynıdır: API'nizi içe aktarın veya tasarlayın, bir ortam oluşturun, onaylamalarla bir senaryo oluşturun, ardından apidog run ile çalıştırın. Bu komut yerel olarak çalıştığında, onu CI'ye düşürmek üç satırlık bir değişikliktir.
Aynı adımları kendi API'nize yönlendirin, senaryo dosyalarını kodunuzla birlikte kaydedin ve testleriniz bir kabuk olan her yerde çalışsın. Başlamak için Apidog'u indirin ve CLI'nin aşırıya kaçtığı hızlı tek seferlik kontroller için REST API testi için curl alternatiflerini elinizin altında bulundurun.