API testlerini siz yazdınız. Sizin makinenizde çalışıyorlar. Ama orada kalıyorlar, çünkü onları çalıştırmak birinin hatırlaması gereken bir şey. Bir ekip arkadaşı Cuma öğleden sonra bir değişiklik gönderir, kimlik doğrulama uç noktası bir kod yolunda sessizce 500 dönmeye başlar ve bunu öğrenen ilk kişi Pazartesi günü bir kullanıcı olur. Kapsam her zaman vardı. Kimse regresyonu yakalayacağı anda çalıştırmadı. Çözüm, testleri düzenleyicinizden çıkarıp pipeline'a taşımak, böylece insan müdahalesi olmadan her push'ta çalışmasıdır. Bu, API testlerinizi başsız bir şekilde çalıştıran, temiz bir başarı veya hata döndüren ve hali hazırda kullandığınız herhangi bir CI sistemine uyan bir komuta ihtiyacınız olduğu anlamına gelir. Apidog CLI bunu yapar. Test senaryolarınızı Apidog'da görsel olarak oluşturur, ardından Node.js'e sahip herhangi bir CI çalıştırıcının yürütebileceği tek bir terminal komutuyla çalıştırırsınız. GUI yok, testleri kod olarak yeniden yazma yok, barındırılacak fazladan hizmet yok. Bu bir kopyala-yapıştır kılavuzudur. Aşağıda GitHub Actions, GitLab CI, Jenkins, CircleCI ve Azure Pipelines için kullanıma hazır pipeline dosyalarını ve yeşil bir derlemeyi dürüst tutan birkaç kalıbı bulacaksınız. Platformunuza uygun bloğu alın, ID'lerinizi ve bir sırrı değiştirin ve gün sonunda her birleştirme için API testleriniz hazır olsun. Kapsamlı bayrak referansını isterseniz, CI/CD'de API testlerini nasıl otomatikleştirilir konusu stratejiyi kapsar; bu sayfa, çalışan bir pipeline'ı yapıştırmakla ilgilidir.
Neyi bağlıyorsunuz
Apidog CLI, bir npm paketi olan apidog-cli'dır. Apidog uygulamasında yazdığınız test senaryolarını çalıştırır: zincirlenmiş istekler, iddialar, bir yanıttan diğerine çekilen değerler, veri odaklı yineleme. CLI kendi test formatını icat etmez. Projenize erişir, senaryoyu kimliğine göre bulur, uygulamanın çalıştıracağı şekilde çalıştırır ve bir çıkış koduyla rapor verir.
Çıkış kodu asıl meseledir. Her iddia geçtiğinde, çalışma 0 ile sonlanır. Herhangi bir şey başarısız olduğunda, sıfır olmayan bir değerle sonlanır. CI sistemleri bu çıkış kodunu okur, adımı başarısız olarak işaretler ve birleştirmeyi veya dağıtımı engeller. Bir kapı yapılandırmazsınız; kapı çıkış kodudur. apidog run adımı pipeline'ınızda olduğu sürece, başarısız bir iddia hattı durdurur.
Üç şey bir çalışmayı mümkün kılar ve bunları aşağıdaki her blokta göreceksiniz:
- Senaryonuzun yürütülmesine izin verildiğini kanıtlayan bir erişim tokenı. Buna bir parola gibi davranın. Bir CI sırrı olarak saklayın, asla taahhüt edilmiş bir dosyaya yazmayın.
- Ne çalıştırılacağını belirten bir senaryo kimliği (veya klasör kimliği veya test paketi kimliği).
- Nerede çalıştırılacağını belirten bir ortam kimliği: dev, staging veya production.
Bu kimlikleri elle yazmazsınız. Apidog'da test senaryosunu açın, CI/CD sekmesine geçin, komut satırı seçeneğini seçin ve bir erişim tokenı oluşturun. Apidog size senaryo kimliği ve ortam kimliği zaten doldurulmuş olan tam apidog run komutunu verir. Bir kez kopyalayın, ardından tokenı bir sırra taşıyın. Henüz bir senaryo oluşturmadıysanız, Apidog ile test senaryoları nasıl yazılır ile başlayın ve geçiş yaptığınızda geri gelin.
Her şeyin üzerine inşa edildiği tek komut
İşte kanonik çalıştırma. Her pipeline dosyası bu satırın etrafındaki bir sarmalayıcıdır:
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t 605067 \
-e 1629989 \
-n 1 \
-r html,junit \
--out-dir ./apidog-reports
Her bir parçanın ne yaptığı:
--access-tokençalıştırmayı doğrular. Bir sırttan doldurduğunuz$APIDOG_ACCESS_TOKENortam değişkeninden okur.-t 605067o kimliğe sahip test senaryosunu çalıştırır. Tüm bir klasörü çalıştırmak için-tyerine-f <folderId>veya seçilmiş bir paketi çalıştırmak için--test-suite <id>kullanın.-e 1629989bir ortamı hedefler. Aynı senaryo bir PR kontrolünde staging'e ve dağıtım sonrası bir smoke testinde production'a nasıl isabet ettiğini gösterir.-n 1senaryoyu bir kez çalıştırır. Döngüye almak için artırın veya bir CSV veya JSON veri dosyasından yinelemeleri yönlendirmek için-d <file>ile eşleştirin.-r html,junitrapor formatlarını seçer.junitCI panonuzun geçiş/başarısızlık ağacına ayrıştırdığı XML'i çıkarır;htmlbir yapı yapıtı olarak kaydettiğiniz göz atılabilir bir rapordur. Günlükte de okunabilir çıktı istiyorsanızcliekleyin.--out-dir ./apidog-reportsraporların bulunduğu yerdir.
Raporlayıcılar "derleme kırmızı oldu" ile "işte başarısız olan iddia ve onu bozan yanıt" arasındaki farkı yaratır. JUnit XML, hemen hemen her platformun doğal olarak anladığı bir formattır, bu yüzden aşağıdaki beş blokta da görünür.
GitHub Actions
Bunu .github/workflows/api-tests.yml içine bırakın. Senaryonuzu main'e karşı her çekme isteğinde çalıştırır, raporu bir yapıt olarak yükler ve herhangi bir iddia başarısız olursa kontrolü başarısız kılar.
name: API tests
on:
pull_request:
branches: [main]
jobs:
api-tests:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install Apidog CLI
run: npm install -g apidog-cli
- name: Run API test scenario
run: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067 \
-e 1629989 \
-n 1 \
-r html,junit \
--out-dir ./apidog-reports
env:
APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
- name: Upload report
if: always()
uses: actions/upload-artifact@v4
with:
name: apidog-report
path: ./apidog-reports
Önemli iki detay. Token, Ayarlar → Sırlar ve değişkenler → Actions altında APIDOG_ACCESS_TOKEN olarak yaşar ve env: aracılığıyla adıma ulaşır. Ve yükleme adımındaki if: always(), testler başarısız olduğunda bile raporu aldığınız anlamına gelir ki bu, onu gerçekten okumanız gereken tek zamandır. Bir senaryo bozulursa, apidog run adımı sıfır olmayan bir değerle çıkar, iş kırmızıya döner ve PR başarısız bir kontrol gösterir. Özellikle bu platformun daha derinlemesine bir incelemesi için, GitHub Actions'ta API testlerini nasıl otomatikleştirilir bölümüne bakın.
GitLab CI
Aynı fikir .gitlab-ci.yml içinde. node:20 imajı zaten çalışma zamanına sahiptir, bu yüzden tek kurulum yüklemedir.
stages:
- test
api-tests:
stage: test
image: node:20
script:
- npm install -g apidog-cli
- >
apidog run
--access-token "$APIDOG_ACCESS_TOKEN"
-t 605067
-e 1629989
-r junit,cli
--out-dir ./apidog-reports
artifacts:
when: always
paths:
- apidog-reports/
reports:
junit: apidog-reports/*.xml
APIDOG_ACCESS_TOKEN'ı Ayarlar → CI/CD → Değişkenler altında maskeli, korumalı bir değişken olarak saklayın, böylece asla bir günlükte görünmez. reports: junit: bloğu, GitLab kullanıcılarının genellikle kaçırdığı kısımdır: GitLab'a XML'i ayrıştırmasını ve sonuçları doğrudan birleştirme isteği widget'ında göstermesini söyler. Bir incelemeci, hiçbir şey indirmeden hangi iddiaların başarısız olduğunu görür.
Jenkins
Deklaratif bir pipeline için, token'ı bir Jenkins kimlik bilgisi olarak saklayın ve ortama çekin, ardından CLI'yi bir aşamada çağırın. post bloğu JUnit XML'i Jenkins'in test trend grafiklerine besler ve HTML raporunu derlemede tutar.
pipeline {
agent any
environment {
APIDOG_ACCESS_TOKEN = credentials('apidog-access-token')
}
stages {
stage('API tests') {
steps {
sh 'npm install -g apidog-cli'
sh '''
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t 605067 \
-e 1629989 \
-n 1 \
-r html,junit \
--out-dir apidog-reports
'''
}
}
}
post {
always {
junit 'apidog-reports/*.xml'
archiveArtifacts artifacts: 'apidog-reports/**', allowEmptyArchive: true
}
}
}
Eğer derleme ajanlarınızda CLI zaten önbelleğe alınmışsa, npm install satırını kaldırın ve doğrudan apidog run komutunu çağırın. Apidog, bir kabuk adımı yerine eklenti yolunu tercih ediyorsanız Jenkins'e özgü bir entegrasyon kılavuzu da sunar: Apidog otomatik testlerini Jenkins ile CI/CD için entegre etme.
CircleCI
.circleci/config.yml içinde, Node kolaylık görüntüsünü kullanın ve token'ı Proje Ayarları → Ortam Değişkenleri altında bir proje ortam değişkeni olarak saklayın.
version: 2.1
jobs:
api-tests:
docker:
- image: cimg/node:20.11
steps:
- checkout
- run:
name: Install Apidog CLI
command: npm install -g apidog-cli
- run:
name: Run API test scenario
command: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067 \
-e 1629989 \
-r junit,cli \
--out-dir ./apidog-reports
- store_test_results:
path: ./apidog-reports
- store_artifacts:
path: ./apidog-reports
destination: apidog-reports
workflows:
test:
jobs:
- api-tests
store_test_results, CircleCI'ın GitLab'daki JUnit bloğunun karşılığıdır; onu rapor dizinine işaret edin ve CircleCI, başarısız iddiaları Testler sekmesinde gösterir. store_artifacts, HTML raporunu ekli tutar, böylece derleme sayfasından açabilirsiniz.
Azure Pipelines
azure-pipelines.yml içinde, Node'u görevle kurun, CLI'yi çalıştırın ve JUnit sonuçlarını yayınlayın. APIDOG_ACCESS_TOKEN'ı pipeline'da gizli bir değişken olarak ekleyin (veya bir Azure Key Vault değişken grubundan çekin), ardından betik adımının env'sine eşleyin.
trigger:
- main
pool:
vmImage: ubuntu-latest
steps:
- task: NodeTool@0
inputs:
versionSpec: '20.x'
displayName: 'Node.js Kur'
- script: npm install -g apidog-cli
displayName: 'Apidog CLI Kur'
- script: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067 \
-e 1629989 \
-r junit,html \
--out-dir ./apidog-reports
displayName: 'API test senaryosunu çalıştır'
env:
APIDOG_ACCESS_TOKEN: $(APIDOG_ACCESS_TOKEN)
- task: PublishTestResults@2
condition: always()
inputs:
testResultsFormat: 'JUnit'
testResultsFiles: 'apidog-reports/*.xml'
testRunTitle: 'Apidog API testleri'
$(APIDOG_ACCESS_TOKEN) makrosu gizli pipeline değişkenini okur; onu env aracılığıyla eşlemek, görünür komut satırından uzak tutar. PublishTestResults@2 ve condition: always() ile, sonuçlar çalışmanın başarılı veya başarısız olmasına bakılmaksızın Testler sekmesinde görünür. Bu platformun daha kapsamlı bir ele alınışı için, Apidog'un Azure DevOps pipeline API testleri hakkında özel bir rehberi bulunmaktadır.
Kapıyı dürüst tutan kalıplar
Testlerinizi çalıştıran bir pipeline temeldir. Bu tarifler onu günlük hayatta kullanışlı kılan şeylerdir.
Bir dağıtımın hemen ardından smoke testi yapın. Bir sürüm yayınlandığı anda, üretim ortamını hedefleyerek, üretime karşı tek bir hızlı senaryo çalıştırın ve ilk hatada durdurun:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e <prodEnvId> -r cli --on-error end
Gece boyunca tam regresyon. Bir senaryo klasörünün tamamını bir programa göre çalıştırın ve ilkinde durmak yerine her hatayı tek bir raporda toplayın:
apidog run --access-token $APIDOG_ACCESS_TOKEN -f <folderId> -r html,junit --on-error continue --out-dir ./nightly-reports
Buradaki ayar --on-error'dur. end hızlıca başarısız olur, bu bir dağıtım kapısı için istediğiniz bir şeydir. continue her adımı çalıştırır, böylece günlük bir rapor tüm hataları bir kerede gösterir. Her iki durumda da, herhangi bir şey başarısız olursa çalışma yine de sıfır olmayan bir değerle çıkar, bu yüzden kapı tutar.
Birçok giriş üzerinde tek bir senaryo çalıştırın. Bir veri dosyasından yinelemeleri yönlendirin ve her satırı kendi geçişi olarak ele alın:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./test-data.csv -r junit
Ana dalı değil, bir özellik dalını test edin. Senaryoları bir dalda olduğu gibi çalıştırın:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 --branch feature-payments -e 1629989 -r cli
Yalnızca CI'da olan bir hatayı ayıklayın. Bir senaryo yerelde geçiyor ancak pipeline'da başarısız oluyorsa, --verbose ekleyin. Bu, çalıştırıcının gönderdiği tam isteği ve aldığı tam yanıtı yazdırır, bu da neredeyse her zaman boşluğa neden olan ortam farkını bulmanızı sağlar.
Derleme size yalan söylediğinde
Birkaç hata modu, her biri sessizce kapıyı yendiği için yeterince sık ortaya çıkar.
Testin başarısız olması gerektiğinde derleme yeşil kalır. Bu tehlikeli olanıdır. Neredeyse her zaman çıkış kodunun yutulduğu anlamına gelir. Komutu bir kabuk pipeline'ına sardıysanız veya "derlemeyi bozmasını engellemek" için || true eklediyseniz, aynı zamanda hiçbir şeyi yakalamasını da engellediniz. Sıfır olmayan çıkışı maskeleyen her şeyi kaldırın. apidog run adımı, CI adımının okuduğu şey olmalıdır.
Kimlik doğrulama hataları. Token yanlış, süresi dolmuş veya komuta hiç ulaşmamış. CI sırrının gerçekten doldurulduğunu onaylayın (uzunluğunun maskeli bir yankısı, asla değeri değil) ve gerekirse senaryonun CI/CD sekmesinden yeniden oluşturun.
"Senaryo bulunamadı." Senaryo kimliği, proje kimliği veya dal eşleşmiyor. Kimliklerin güncel olduğundan emin olmak için komutu CI/CD sekmesinden yeniden kopyalayın ve --branch'ın düşündüğünüz yeri işaret ettiğinden emin olmak için tekrar kontrol edin.
Yerelde geçer, CI'da başarısız olur. Neredeyse her zaman bir ortam farkıdır. Çalıştırıcı farklı bir -e ortamını hedefleyebilir, ana bilgisayarınıza ulaşamayan bir güvenlik duvarının arkasında olabilir veya senaryonun ihtiyaç duyduğu bir değişken eksik olabilir. --verbose ile çalıştırın ve çalıştırıcının ürettiği isteği, yerelde gönderdiğinizle karşılaştırın.
Dahili ana bilgisayarlara karşı TLS hataları. Uç noktanız dahili bir CA kullanıyorsa, doğrulamayı devre dışı bırakmak yerine ek CA sertifikasını geçirin. Yalnızca kendinden imzalı bir sertifikaya sahip güvenilir dahili bir ana bilgisayarda son çare olarak -k (SSL doğrulamayı atla) kullanın, asla halka açık bir şeye karşı kullanmayın.
Neden görsel olarak inşa edip başsız çalıştırılır?
Tüm bunların altında gerçek bir tasarım seçimi var ve bir paragrafı hak ediyor. Betik öncelikli çalıştırıcılarla, test ve yürütmesi aynı dosyadır, bu nedenle kırılgan bir betik hem testiniz hem de darboğazınızdır. Apidog ile, projenizdeki senaryo testtir ve CLI sadece bir kişinin yapamayacağı yerde çalıştırır. Kimse aynı kontrolün iki temsilini sürdürmez. Görsel oluşturucuda hızlıca yazarsınız, pipeline'da otomatik olarak çalıştırırsınız ve ikisi senkronize kalır çünkü aynı yapıdırlar. CI devreye girdiğinde takımların Apidog'u API testi için Postman alternatifi olarak görmelerinin ve sağlam API iddialarının, onları sardığınız çalıştırıcıdan daha önemli olmasının büyük bir kısmı budur.
Döngü bir kez çalışmaya başladığında basittir. Uygulamada istekleri tasarlayın ve hata ayıklayın. Onları iddialarla bir senaryoda zincirleyin. Kodunuzu gönderin ve CLI, her değişiklikte CI'da bu senaryoyu çalıştırır. Bir şey bozulduğunda, rapor iddiayı adlandırır ve çıkış kodu dağıtımı durdurur. Onarırsınız, tekrar gönderirsiniz ve aynı kapı düzeltmeyi onaylar.
Testleriniz hala birinin düzenleyicisinde yaşıyorsa, bu hafta kapatmanız gereken boşluk budur. Apidog'u indirin, bir senaryoyu geçirin, CI/CD sekmesinden apidog run komutunu kopyalayın ve platformunuz için yukarıdaki bloğu yapıştırın. Aynı öğleden sonra her birleştirme için API testleriniz hazır olacak.
Sıkça Sorulan Sorular
Apidog CLI'yı CI'da kullanmak ücretsiz mi? CLI ücretsiz bir npm paketidir: npm install -g apidog-cli. Apidog projenizdeki senaryoları çalıştırır, bu nedenle ne çalıştırabileceğiniz Apidog planınıza bağlıdır, ancak komut satırı çalıştırıcısının kendisi ayrı ücretli bir ürün değildir.
Testlerimi kod olarak yeniden yazmak zorunda mıyım? Hayır. Senaryoları Apidog'da görsel olarak oluşturursunuz ve CLI onları kimliğe göre çalıştırır. Senaryo testtir; CLI sadece yürütücüdür. Onu betik öncelikli çalıştırıcılardan ayıran ana şey budur.
Başarısız bir test derlememi aslında nasıl başarısız eder? Çıkış kodu aracılığıyla. Herhangi bir iddia başarısız olduğunda, apidog run sıfır olmayan bir değerle çıkar. CI sisteminiz bunu okur, adımı başarısız olarak işaretler ve birleştirmeyi veya dağıtımı engeller. Kapının çalışması için ek bir yapılandırma eklemenize gerek yoktur.
Hangi rapor formatını kullanmalıyım? CI panonuzun geçiş/başarısız sonuçlarına ayrıştırdığı makine tarafından okunabilir XML için junit kullanın ve bir derleme yapıtı olarak kaydedilmiş göz atılabilir bir rapor istiyorsanız html ekleyin. Yaygın bir eşleşme -r junit,html'dir. Derleme günlüğünde okunabilir çıktı istiyorsanız cli'yı da açık tutun.
Apidog'u CI sunucusuna kurmam gerekiyor mu? Hayır. CI çalıştırıcısının yalnızca Node.js'e (v16 veya üzeri) ve apidog-cli paketine ihtiyacı vardır. Masaüstü uygulaması yok, GUI yok, kutuda lisans dosyası yok. Paket artı bir erişim tokenı yeterlidir.
Global bir kurulum olmadan çalıştırabilir miyim? Evet. Her işten sonra kaldırılan geçici çalıştırıcılarda daha temiz olan, kalıcı global bir kurulum olmadan yürütmek için npx apidog-cli run ... kullanın.
Bu Newman'dan nasıl farklı? Newman, Postman koleksiyonlarını komut satırından çalıştırır. Apidog CLI, Apidog test senaryolarını çalıştırır. Roller paraleldir, ancak Apidog çalıştırıcısı, uygulamada yazdığınız senaryoları yürütür ve tek apidog-cli paketi olarak gönderilir. Bu karşılaştırmanın Postman tarafı için Postman CLI vs Newman bölümüne bakın.
Erişim tokenını ve kimlikleri nereden alırım? Hepsi Apidog'daki test senaryosunun CI/CD sekmesinden. Komut satırı seçeneğini seçin, bir erişim tokenı oluşturun ve Apidog'un senaryo ve ortam kimlikleri zaten doldurulmuş olarak oluşturduğu tam apidog run komutunu kopyalayın. Ardından tokenı bir CI sırrına taşıyın ve $APIDOG_ACCESS_TOKEN olarak referans gösterin.