Apidog CLI ile API Testleri Nasıl Çalıştırılır?

API testleriniz dizüstü bilgisayarınızda geçer. Sonra birisi gece 2'de bir değişiklik birleştirir, hazırlık (staging) uç noktası bozuk bir yük döndürmeye başlar ve ertesi sabah bir müşteri bildirimde bulunana kadar kimse fark etmez. Testler vardı. Sadece önemli olan yerde hiç çalıştırılmadılar: pipeline içinde, her push işleminde, insan müdahalesi olmadan.

“Mevcut testler” ile “otomatik çalışan testler” arasındaki bu boşluğu bir komut satırı çalıştırıcısı kapatır. Apidog CLI, Apidog masaüstü veya web uygulamasında zaten oluşturduğunuz test senaryolarını bir terminalden başsız (headless) olarak çalıştırır. GUI yok, manuel tıklama yok. Tek bir npm komutuyla kurar, bir test senaryosuna yönlendirir ve temiz bir durum koduyla ve herhangi bir CI sisteminde yayınlayabileceğiniz bir raporla çıkar. Bu, onu görsel test oluşturucu ile CI/CD platformunuz arasında bir köprü haline getirir.

Kısaca

• Apidog CLI, apidog-cli adlı bir npm paketidir. npm install -g apidog-cli ile global olarak kurun, ardından senaryoları apidog run komutuyla çalıştırın.
• Apidog'da tasarladığınız test senaryolarını çalıştırır. Testleri kod olarak yeniden yazmazsınız; CLI, kimlik doğrulama için bir erişim belirteci kullanarak aynı senaryoyu kimliğe göre yürütür.
• Temel çalıştırma: apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenarioId> -e <environmentId> -n 1 -r html,cli.
• Raporlayıcılar cli, html, json ve junit formatlarını kapsar. JUnit XML, doğrudan CI test panolarına takılan formattır.
• Test başarısız olduğunda sıfır olmayan bir çıkış kodu, CLI'yi gerçek bir kalite kapısı yapar. Başarısız testler varsayılan olarak derlemeyi başarısız kılar.
• Node.js'e sahip herhangi bir CI çalıştırıcısında çalışır: GitHub Actions, GitLab CI, Jenkins, CircleCI, Azure Pipelines ve daha fazlası.

Apidog CLI aslında nedir?

Apidog, hepsi bir arada bir API platformudur: şemayı tasarlar, isteklerde hata ayıklar, otomatik test senaryoları oluşturur, uç noktaları taklit eder ve belgeleri tek bir çalışma alanında yayınlarsınız. Bu işin çoğu görsel bir arayüzde gerçekleşir. İstekleri bir test senaryosunda zincirlersiniz, onaylamalar eklersiniz, bir yanıttan diğerine değerler çekersiniz ve bir veri dosyası üzerinde döngü yaparsınız.

CLI, bu senaryolar için başsız (headless) yürütücüdür. Kendi test formatına sahip değildir. Apidog projenize ulaşır, kimliğine göre adlandırdığınız senaryoyu bulur ve uygulamadakiyle tamamen aynı şekilde çalıştırır, ardından raporu geri iletir. Bunu bir derleme aracı ile kaynak kodunuz arasındaki ilişki gibi düşünün: doğruluk kaynağı projede yaşar ve CLI, onu bir kişi olmadan çalıştıran şeydir.

Bu önemlidir çünkü API testlerinin çürümesinin en yaygın nedenini ortadan kaldırır. Testler yalnızca bir masaüstü uygulamasında tıklanabilir adımlar olarak var olduğunda, birisi hatırladığında çalıştırılırlar. Tek satırlık bir komutla çalıştırıldığında, onları bir pipeline'a bağlayabilir ve her commit'te, her birleştirmede, her gece programında çalıştırabilirsiniz. Görsel oluşturucu size hızlı yazma imkanı verir; CLI ise otomasyon sağlar. Seçim yapmadan ikisini de elde edersiniz.

Postman dünyasından geliyorsanız, zihinsel model net bir şekilde eşleşir. Apidog CLI, Postman CLI veya Newman'ın Postman koleksiyonları için oynadığı rolü oynar, ancak Apidog test senaryolarını çalıştırır ve tek bir paket olarak gelir. Bu karşılaştırmayı Postman CLI vs Newman yazımızda ve geçiş yapıyorsanız Newman olmadan CI'da koleksiyonları çalıştırma daha geniş sorusunu derinlemesine ele aldık.

Ön Koşullar

Tek bir komut çalıştırmadan önce üç şeye ihtiyacınız var:

1. Node.js v16 veya üzeri. CLI bir npm paketi olarak gelir, bu nedenle bir Node çalışma zamanı tek sistem bağımlılığıdır. Sizinkini node -v ile kontrol edin. Node 16+ içeren herhangi bir CI imajı zaten yeterlidir.
2. Bir Apidog test senaryosu. CLI senaryoları çalıştırır, tek başına istekleri değil. Önce Apidog uygulamasında bir tane oluşturun: isteklerinizi zincirleyin, onaylamalar ekleyin, ihtiyacınız olan veri odaklı yinelemeyi ayarlayın. Onaylamalar oluşturmaya yeni başlıyorsanız, API onaylamaları: pratik bir rehber yanıtları doğrulamayı anlatır.
3. Bir erişim belirteci. Bu, CLI'yi Apidog hesabınızda doğrular, böylece senaryoyu alıp çalıştırabilir. Bunu test senaryosunun CI/CD sekmesinde oluşturursunuz; aşağıda daha fazlası.

Hepsi bu kadar. CI kutusunda ayrı bir Apidog kurulumu yok, GUI yok, lisans dosyası yok. Paket ve bir belirteç yeterlidir.

Apidog CLI'yı Kurma

npm ile global olarak kurun:

npm install -g apidog-cli

Ardından her şeyin doğru çözümlendiğini onaylayın:

node -v && apidog -v && which node && which npm && which apidog

Bu, sürüm numaralarını ve yolları yazdırırsa, işiniz bitti demektir. İkili dosya apidog'dur, bu nedenle her komut apidog run ile başlar.

Bir geliştirici makinesinde global kurulum sorunsuz çalışır. CI'da iki makul desen vardır. Birincisi, her pipeline çalıştırmasında yeni kurulum yapmak, bu da en son sürümde olmanızı garanti eder:

npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

İkincisi, çalıştırıcının global paketlerini değiştirmekten kaçınan npx aracılığıyla kalıcı global kurulum olmadan çalıştırmaktır:

npx apidog-cli run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

Her ikisi de çalışır. npx yaklaşımı geçici CI çalıştırıcıları için daha temizdir; global kurulum, çalıştırmalar arasında önbelleğe alındığında biraz daha hızlıdır.

Erişim belirtecinizi ve senaryo kimliğinizi alma

CLI'nın iki şeyi bilmesi gerekir: hangi senaryoyu çalıştıracağını ve onu çalıştırmaya yetkisinin olup olmadığını. Apidog, bunları sizin için otomatik olarak oluşturur, böylece arayüzde aramanıza gerek kalmaz.

Otomatikleştirmek istediğiniz test senaryosunu açın. CI/CD sekmesine geçin. Komut satırı seçeneğini seçin, ardından Erişim belirteci ekle ve Belirteç oluştur'a tıklayın. Apidog, erişim belirteci, senaryo kimliği ve ortam kimliği zaten doldurulmuş olarak sizin için tam apidog run komutunu oluşturur. Kopyalamak için komuta tıklayın.

Oluşturulan bu komut, temel başlangıç noktasıdır. Şuna benzer:

apidog run --access-token YOUR_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r html,cli

Sayılar, projenizdeki gerçek kimliklerdir. 605067 test senaryosu kimliğidir. 1629989 ortam kimliğidir. Bunları neredeyse hiç elle yazmazsınız; bir kez CI/CD sekmesinden kopyalar ve ardından belirteci parametrelendirirsiniz.

Erken belirtilmesi gereken bir kural: erişim belirtecini bir parola gibi ele alın. Onu bir commit edilmiş yapılandırma dosyasına veya genel bir pipeline tanımına yapıştırmayın. Onu CI sisteminizde bir sır olarak saklayın ve bir ortam değişkeni olarak referans alın. Aşağıdaki her örnek, tam da bu nedenle $APIDOG_ACCESS_TOKEN kullanır.

apidog run komutu, bayrak bayrak

Tüm CLI tek bir komut etrafında döner. İşte her grubun neyi kontrol ettiğine göre gruplandırılmış tüm seçenek yüzeyi.

Ne çalıştırılacağını seçme

Kapsama bağlı olarak -t, -f veya --test-suite'den birini seçersiniz. Odaklanmış bir smoke testi için tek bir senaryo, bir özellik alanı için bir klasör, küratörlüğünü yapılmış senaryolar kümesini tek bir mantıksal iş olarak birlikte çalıştırmak istediğinizde bir test süiti.

Kimlik Doğrulama

Bu, her CI komutunun ihtiyaç duyduğu tek bayraktır. Onu bir sır olarak geçirin, asla satır içine yazmayın.

Ortam ve yineleme

Ortam bayrağı, aynı senaryoyu bir çekme isteği kontrolünde hazırlık ortamına ve bir dağıtım sonrası smoke testinde üretim ortamına, senaryoyu çoğaltmadan nasıl hedefleyeceğinizi gösterir. Yineleme verileri, bir senaryoyu elli satır girdi üzerinde çalıştırmanın ve her satırı ayrı bir geçiş olarak ele almanın yoludur. Veri odaklı deseni, test süitleri ile otomatik API testini ölçeklendirme rehberinde daha ayrıntılı olarak ele alıyoruz.

Raporlar

CLI'nın bir pipeline'daki yerini kazandığı yer burasıdır. Birden fazla formatı aynı anda, virgülle ayrılmış olarak geçirin:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -r html,junit --out-dir ./test-reports

cli, derleme günlüklerini okuyan insanlar için okunabilir terminal çıktısı sağlar. html, bir derleme yapıtı olarak arşivleyebileceğiniz ve bir tarayıcıda açabileceğiniz, kendi içinde eksiksiz bir rapor üretir. junit, standart JUnit formatında XML yayınlar; bu formatı neredeyse her CI panosu bir geçiş/başarısızlık ağacına ayrıştırmayı bilir. json, sonradan işlemek isterseniz ham yapılandırılmış sonucu verir.

Hata işleme ve çıkış davranışı

--on-error, senaryo ortasında ne olacağını kontrol eder. end, çalıştırmayı ilk başarısızlıkta durdurur; bu, hızlı başarısız olan bir smoke testi için genellikle istediğiniz şeydir. continue, her adımı çalıştırır, böylece tüm başarısızlıkları tek bir raporda görebilirsiniz. ignore, bir adımın bilinen bir zayıflığı olduğu ve çalıştırmayı bozmasını istemediğiniz nadir durumlar içindir.

TLS ve Sertifikalar

Bunları, karşılıklı TLS arkasındaki uç noktaları veya dahili CA zincirleriyle test ettiğinizde kullanın. -k'yi yalnızca sertifikanın kendinden imzalı olduğu güvenilir dahili hostlara karşı kullanın; asla herkese açık bir şeye karşı kullanmayın.

Çıktı ve Teşhis

--verbose, bir test yerel olarak geçerken CI'da başarısız olduğunda ilk adımınızdır; çalıştırıcının gönderdiği tam isteği ve aldığı tam yanıtı gösterir. --silent, yalnızca çıkış kodunu ve kaydedilmiş raporu önemsediğiniz gürültülü gece işleri içindir.

Çıkış kodları: CI'yı çalıştıran kısım

Bir test çalıştırıcısı, ancak testlerin geçip geçmediğini pipeline'a bildirdiğinde bir pipeline'da kullanışlıdır. Apidog CLI bunu, her iyi davranışlı komut satırı aracının yaptığı gibi yapar: her onaylama geçtiğinde 0 koduyla, bir şey başarısız olduğunda ise sıfır olmayan bir kodla çıkar.

Bu tek davranış, apidog run komutunu bir kalite kapısına dönüştürür. CI sistemleri her adımın çıkış kodunu okur. Sıfır olmayan bir çıkış, adımı başarısız olarak işaretler, bu da işi başarısız kılar ve birleştirme veya dağıtımı engeller. Ekstra hiçbir şey yapılandırmanıza gerek yoktur. apidog run adımı pipeline'ınızda olduğu sürece, başarısız bir test hattı durdurur.

Bunu --on-error ile şekillendirebilirsiniz. Varsayılan davranış, geri bildirimi hızlı tutan ilk bozuk onaylamada başarısız olur. Derleme kırmızıya dönmeden önce her başarısızlığı tek bir raporda görmek istediğinizde --on-error continue'ye geçin. Her iki durumda da, bir şey başarısız olursa çalıştırma yine de sıfır olmayan bir çıkışla biter, bu yüzden kapı geçerliliğini korur.

GitHub Actions'ta çalıştırma

Her çekme isteğinde bir Apidog senaryosu çalıştıran ve raporu bir yapıt olarak yayınlayan eksiksiz bir iş akışı.

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

Belirteç, depo sırlarında yaşar ve adıma bir ortam değişkeni olarak ulaşır. Yükleme adımındaki if: always(), testler başarısız olsa bile raporu alacağınız anlamına gelir, ki bu tam da raporu okumak istediğiniz zamandır. Bir test bozulursa, apidog run adımı sıfır olmayan bir değerle çıkar, iş kırmızıya döner ve çekme isteği başarısız bir kontrol gösterir.

GitLab CI'da çalıştırma

.gitlab-ci.yml'deki aynı desen:

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

İki şeye dikkat edin. APIDOG_ACCESS_TOKEN'ı dosyada değil, Ayarlar altında maskelenmiş, korumalı bir CI/CD değişkeni olarak saklayın. Ve reports: junit: bloğu, GitLab'a JUnit XML'ini ayrıştırmasını ve sonuçları birleştirme isteği widget'ında göstermesini söyler, böylece bir gözden geçiren herhangi bir şey indirmeden hangi onaylamaların başarısız olduğunu görür.

Jenkins'te çalıştırma

Deklaratif bir pipeline'da, belirteci bir Jenkins kimlik bilgisi veya global ortam değişkeni olarak saklayın, ardından CLI'yi bir aşamada çağırın:

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
 }
 }
}

Derleme aracılarınızda CLI zaten kurulu ve önbelleğe alınmışsa, npm install satırını kaldırın ve doğrudan apidog run komutunu çağırın. post bloğundaki junit adımı, XML'i Jenkins'in test trend grafiklerine besler; archiveArtifacts HTML raporunu derlemeye ekli tutar. Jenkins'i diğer çalıştırıcılarla karşılaştırıyorsanız, ReadyAPI Jenkins CI kurulumu ve daha basit bir alternatif başlıklı makaledeki karşılaştırma, avantaj ve dezavantajları kapsar.

Yaygın desenler ve tarifler

Dağıtım sonrası smoke testi. Bir sürümden hemen sonra üretime karşı, üretim ortamını hedefleyerek hızlı bir senaryo çalıştırın:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e <prodEnvId> -r cli --on-error end

Tam regresyon gecelik. Bir klasör dolusu senaryoyu programlı olarak çalıştırın, tüm başarısızlıklar tek bir raporda toplanır:

apidog run --access-token $APIDOG_ACCESS_TOKEN -f <folderId> -r html,junit --on-error continue --out-dir ./nightly-reports

Veri odaklı çalıştırma. Bir senaryoyu bir test durumları CSV'si üzerinde döngüye alın:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./test-data.csv -r junit

Dala özel kontrol. Senaryoları ana daldaki gibi değil, bir özellik dalındaki haliyle çalıştırın:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 --branch feature-payments -e 1629989 -r cli

Yalnızca CI başarısızlığını ayıklama. Bir senaryo yerel olarak geçerken pipeline'da başarısız olduğunda, çalıştırıcının ürettiği tam tel seviyesi isteğini ve yanıtını görmek için --verbose ekleyin.

Sorun Giderme

Kimlik doğrulama hataları. Çalıştırma bir kimlik doğrulama hatasıyla başarısız olursa, belirteç yanlış, süresi dolmuş veya komuta ulaşmıyordur. Maskelenmiş bir kontrol yankılayın (asla tam belirteci değil) ve CI sırrınızın gerçekten dolu olduğunu onaylayın. Gerekirse senaryonun CI/CD sekmesinden belirteci 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'in beklediğiniz yeri gösterdiğini onaylayın.

Testler yerel olarak geçer ancak CI'da başarısız olur. Neredeyse her zaman bir ortam farkıdır. CI çalıştırıcısı farklı bir -e ortamını hedefleyebilir, ulaşamadığı bir hosta çarpabilir veya senaryonuzun bağımlı olduğu bir değişkenden yoksun olabilir. --verbose ile çalıştırın ve CI çalıştırıcısının gönderdiği isteği yerel olarak gönderdiğinizle karşılaştırın.

Dahili hostlara karşı ağ veya TLS hataları. Uç noktanız dahili bir CA kullanıyorsa, --ssl-extra-ca-certs parametresini geçirin. -k'yi yalnızca sertifikanın kendinden imzalı olduğu güvenilir dahili hostlarda son çare olarak kullanın.

Bir testin başarısız olması gerektiğinde bile derleme yeşil kalır. apidog run adımının çıkış kodunun gerçekten CI'ya ulaştığını onaylayın. Eğer onu bir kabuk pipeline'ına sardıysanız veya || true eklediyseniz, sıfır olmayan çıkış yutulur ve kapı çalışmayı durdurur. Çıkış kodunu maskeleyen her şeyi kaldırın.

Apidog CLI gerçek bir iş akışına nasıl uyar?

CLI, bir döngünün bir parçasıdır. Apidog uygulamasında istekleri tasarlar ve hata ayıklarsınız. Onları onaylamalarla bir senaryoda zincirlersiniz. Çalışmanızı commit edersiniz ve CLI, her değişiklikte bu senaryoyu CI'da çalıştırır. Bir şey bozulduğunda, rapor hangi onaylamanın başarısız olduğunu söyler ve çıkış kodu dağıtımı durdurur. Onu düzeltir, tekrar push edersiniz ve aynı kapı düzeltmeyi onaylar.

Testleri görsel olarak oluşturmanın ve başsız olarak çalıştırmanın avantajı, kimsenin aynı testin iki farklı temsilini sürdürmek zorunda kalmamasıdır. Projedeki senaryo testtir. CLI onu sadece bir insanın olamayacağı yerde çalıştırır. Bu, test ve yürütmesinin aynı kırılgan dosya olduğu, betik öncelikli çalıştırıcılardan farklı bir modeldir ve ekiplerin API testi için Postman alternatifi olarak Apidog'a geçmesinin büyük bir nedenidir.

Testleri henüz oluşturmadıysanız, uygulamadan başlayın, bir senaryoyu geçirin, ardından CI/CD sekmesinden CLI komutunu bağlayın. İlk otomatik senaryonuzu kurmak için Apidog'u indirin ve aynı öğleden sonra pipeline'ınızı korumaya başlayacaktır.

Sıkça Sorulan Sorular

Apidog CLI ücretsiz mi? CLI'nın kendisi ücretsiz bir npm paketidir. Onu npm install -g apidog-cli ile kurarsınız. Test senaryolarını Apidog projenizden çalıştırır, bu nedenle neyi çalıştırabileceğiniz Apidog planınıza bağlıdır, ancak komut satırı çalıştırıcısı ayrı ücretli bir ürün değildir.

CLI'yı kullanmak için testlerimi kod olarak yeniden yazmak zorunda mıyım? Hayır. Betik öncelikli çalıştırıcılardan temel fark budur. Senaryoları Apidog'da görsel olarak oluşturursunuz ve CLI bunları kimliğe göre çalıştırır. Senaryo testtir; CLI sadece yürütücüdür.

Apidog CLI ile Newman arasındaki fark nedir? 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ı Apidog uygulamasında oluşturduğunuz senaryoları yürütür ve tek bir apidog-cli paketi olarak gelir. Bu karşılaştırmanın Postman tarafı için Postman CLI vs Newman'a bakın.

CI'da hangi rapor formatını kullanmalıyım? CI panonuzun geçiş/başarısızlık ağacına ayrıştırdığı makine tarafından okunabilir sonuç 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 seçim -r html,junit'dir. Derleme günlüğünde okunabilir çıktı istiyorsanız cli'yi de açık tutun.

CLI bir derlemeyi nasıl başarısız kılar? Çıkış kodu aracılığıyla. Herhangi bir onaylama başarısız olduğunda, apidog run sıfır olmayan bir değerle çıkar. CI sistemleri bu çıkış kodunu okur, adımı başarısız olarak işaretler ve birleştirmeyi veya dağıtımı engeller. Bunun çalışması için ekstra hiçbir şey yapılandırmanıza gerek yoktur.

CLI'yı global olarak kurmadan çalıştırabilir miyim? Evet. Kalıcı bir global kurulum olmadan yürütmek için npx apidog-cli run ... kullanın, bu geçici CI çalıştırıcılarında kullanışlıdır.

Hangi Node.js sürümüne ihtiyacım var? Node.js v16 veya üzeri. Node 16+ içeren herhangi bir modern CI imajı zaten gereksinimi karşılar.

Erişim belirtecini ve senaryo kimliğini nereden alırım?** Her ikisi de Apidog'daki test senaryosunun CI/CD sekmesinden gelir. Komut satırı seçeneğini seçin, bir erişim belirteci oluşturun ve Apidog'un sizin için kimlikleri zaten doldurulmuş olarak oluşturduğu tam apidog run komutunu kopyalayın. Ardından belirteci bir CI sırrına taşıyın.