Hiçbir işe yarar çıktı vermeyen bir test çalıştırmasına kimse güvenmez. İşlem hattınız kırmızıya döner, biri derleme günlüğünü açar ve tek bulduğu şey bir zaman damgası yığını ile sıfır olmayan bir çıkış kodudur. Hangi iddia başarısız oldu? Hangi ortama karşı? Veri dosyasının hangi satırında? Çalıştırma biliyordu. Sadece daha sonra okuyabileceğiniz bir yere asla kaydetmedi.
İşte bu boşluğu bir raporlayıcı doldurur. API testlerini komut satırından çalıştırdığınızda, rapor aslında birlikte yaşadığınız kısımdır: arşivlediğiniz yapıt, CI kontrol panelinizin ayrıştırdığı dosya, sabah 9'da gece 2'de işlem hattını izlemeyen bir ekip arkadaşınıza verdiğiniz şey. Testin sonucu işin sadece yarısıdır. Diğer yarısı ise bu sonucu hem bir insan hem de bir makine için aynı anda okunabilir kılmaktır.
Apidog komut satırı çalıştırıcısı her ikisini de halleder. Apidog, uygulamada görsel olarak oluşturduğunuz test senaryolarını çalıştıran bir CLI sunar ve ürettiği her raporu tek bir bayrak kontrol eder: -r, --reporters. Buna virgülle ayrılmış bir liste verirsiniz, çalıştırıcı her formatı diske yazar ve kimin ne okuyacağına siz karar verirsiniz. Bu kılavuz, bu bayrak ve ürettiği dosyalar hakkındadır: her raporlayıcının ne için olduğu, diske neyin indiği, nereye indiği ve her birini gerçek bir iş akışına nasıl bağlayacağınız. Çalıştırıcının kabul ettiği her bayrağın daha geniş kapsamlı turunu istiyorsanız, apidog çalıştırma komutu referansı tüm yüzeyi kapsar; bu sayfa raporlara odaklanır.
Rapor neden çalıştırmadan daha önemlidir
Bir senaryoyu yerel olarak çalıştırdığınızda, ne olduğunu izlersiniz. Her isteğin ateşlendiğini, her iddianın yeşile döndüğünü, sonunda özetini görürsünüz. Geri bildirim döngüsü, önünüzdeki terminaldir, canlıdır.
CI'da bu döngü yoktur. Çalıştırma, hiç görmediğiniz bir makinede, izlemediğiniz bir zamanda gerçekleşir ve tek kayıt, çalıştırıcı çıkmadan önce diske yazılanlardır. Eğer çalıştırma bir rapor üretmediyse, bir hata size sadece bir şeyin bozulduğunu söyler. Tümünü yerel olarak yeniden çalıştırmak ve aynı şekilde bozulmasını ummak zorunda kalırsınız.
İyi bir rapor bu mesafeyi kapatır. Hangi senaryonun çalıştığını, hangi ortama karşı, kaç iterasyon yapıldığını, hangi iddiaların geçtiğini, hangilerinin başarısız olduğunu ve her hatanın arkasındaki istek ve yanıt detayını yakalar. Bunu diske kaydettiğinizde, sabah 2'deki bir hata, ertesi sabah bir yeniden üretim avı yerine beş dakikalık bir okumaya dönüşür. Raporlayıcı bayrağının var olmasının tek nedeni budur ve her kitle için doğru formatı seçmenin birkaç dakikalık düşünmeye değer olmasının nedeni de budur.
Her raporu kontrol eden tek bayrak
Apidog CLI, apidog-cli adlı bir npm paketidir. Bir kez kurduğunuzda, ana alt komutu run olan tek bir ikili dosya, apidog elde edersiniz. Küresel olarak kurun:
npm install -g apidog-cli
Çalıştırıcının üretebileceği her rapor, o komuttaki tek bir bayraktan gelir: -r, --reporters. Virgülle ayrılmış bir liste alır ve kabul ettiği dört değer cli, html, json ve junit'dir. Hiçbir şey iletmezseniz, varsayılan cli'dir.
İki raporlayıcı ile tam bir çalıştırma şöyle görünür:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r html,cli
Bu, bir jetonla kimlik doğrulaması yapar, 605067 test senaryosunu 1629989 ortamına karşı bir kez çalıştırır ve hem bir HTML dosyası hem de okunabilir terminal çıktısı verir. Kimlikler senaryo kimliği ve ortam kimliğidir; her ikisini de erişim jetonuyla birlikte Apidog'daki senaryonun CI/CD sekmesinden elinizle yazmak yerine kopyalarsınız. Bu kurulumlardan herhangi biri size yabancı geliyorsa, Apidog CLI eksiksiz kılavuzu kurulum, jetonlar ve baştan sona ilk çalıştırmanızı anlatır.
Ana fikir: tek bir çalıştırma aynı anda birden fazla rapor üretebilir. Tek bir format seçmiyorsunuz. Her çıktı için bir kitle seçip bunları birlikte listeliyorsunuz. Tipik bir CI satırı, aynı yürütmeden insan tarafından okunabilir bir HTML dosyası ve makine tarafından okunabilir bir JUnit dosyası çıkarır, böylece aynı çalıştırma hem bir kişiye hem de bir kontrol paneline hizmet eder.
cli: derleme günlüğünde okuduğunuz rapor
cli raporlayıcısı, doğrudan terminale okunabilir bir özet basar. Bu varsayılandır ve bir insanın ilk olarak taradığı rapor türüdür.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
Size verdiği, canlı karardır: kaç isteğin çalıştığı, kaç iddianın geçtiği ve başarısız olduğu ve hangi özel iddiaların bozulduğu. Bir CI derleme günlüğünde, bu, başarısız bir işe tıkladıklarında birinin okuduğu bloktur. Herhangi bir şey indirmeye zahmet etmeden önce, hatanın bir mi yoksa elli mi bozuk iddia olduğunu ve hangi uç noktanın ilgili olduğunu bir bakışta söyler.
Makine formatları yazarken bile cli'yi açık tutun. Hiçbir maliyeti yoktur ve derleme günlüğünü kendi başına kullanışlı tutar. Yalnızca JUnit XML yayan bir işlem hattı mükemmel bir kontrol paneli ve işe yaramaz bir günlük üretir; ham çıktıyı okuyan herkes, çalıştırıcının başlaması ve çıkmasından başka bir şey görmez. Listeye cli eklemek bunu düzeltir:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,junit --out-dir ./apidog-reports
cli'nin ne yazdırdığını şekillendiren iki bayrak daha vardır. --verbose bunu her adım için tam istek ve yanıta genişletir; bu, bir senaryo dizüstü bilgisayarınızda geçtiği ancak işlem hattında başarısız olduğu durumlarda ilk hareketinizdir; ayrıntılar, çalıştırıcının tam olarak ne gönderdiğini ve ne aldığını gösterir. --silent bunun tam tersini yapar ve konsol çıktısını tamamen bastırır; bu, yalnızca çıkış kodu ve kaydedilen dosyayla ilgilendiğiniz gürültülü zamanlanmış bir iş için uygundur.
html: bir insana verdiğiniz rapor
html raporlayıcısı, kendi kendine yeten bir HTML dosyası yazar. Herhangi bir tarayıcıda açtığınızda, tüm çalıştırmayı görsel olarak düzenlenmiş olarak görürsünüz: her istek, üzerindeki iddialar, geçme ve başarısız olma durumu ve her adımın arkasındaki istek ve yanıt detayı. Kurulacak hiçbir şey yok, çalıştırılacak sunucu yok; çift tıkladığınız tek bir dosya.
Bu, arşivlediğiniz ve paylaştığınız formattır. Bunu bir derleme yapıtı olarak kaydedin ve rapor işlem hattı çalıştırmasından daha uzun ömürlü olur, böylece bir hafta sonra bile bozulan dağıtımdan gelen tam raporu açabilirsiniz. Ayrıca “ne başarısız oldu?” diye soran kişiye CLI'yı kurdurmadan veya hiçbir şeyi yeniden çalıştırmadan gönderdiğiniz şeydir. Dosyayı açarlar, kırmızı adımı görürler, iddiayı tetikleyen yanıt gövdesini okurlar ve işleri biter.
HTML, en çok veri odaklı bir çalıştırmada yerini alır. Bir senaryo elli satırlık bir CSV üzerinde döngü yaptığında, HTML raporu size her iterasyon için sonucu gösterir, böylece 1'den 49'a kadar olan satırların geçtiğini ve 50. satırın bir hesabın eski bir jetona sahip olması nedeniyle başarısız olduğunu görebilirsiniz. Yalnızca geçme veya başarısız olma sayısı bunu size söyleyemez. Senaryoları veri dosyaları arasında çalıştırırsanız, bu desen CSV ve JSON ile veri odaklı API testi makalesinde ele alınmıştır.
Taviz: HTML gözler içindir, ayrıştırma için değil. Bir betikte geçme/başarısız olma durumu için kazımaya çalışmayın. JSON ve JUnit bunun içindir.
junit: CI kontrol panelinizin ayrıştırdığı rapor
junit raporlayıcısı, standart JUnit formatında XML yayar. Bu format önemlidir çünkü CI test raporlamasının ortak dilidir. Neredeyse her CI sistemi, GitHub Actions, GitLab CI, Jenkins, CircleCI, Azure Pipelines, JUnit XML'ini nasıl okuyacağını ve onu bir geçme/başarısız olma ağacına dönüştüreceğini, bir birleştirme isteği widget'ında hataları yüzeye çıkaracağını ve zaman içinde derlemeler arasında sonuçları trend olarak göstereceğini bilir.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r junit --out-dir ./apidog-reports
CI için tam olarak bir makine formatı seçerseniz, bunu seçin. Bunun getirisi, test sonuçlarınızın yalnızca bir günlük dosyasında yaşamak yerine, ekibinizin zaten baktığı kontrol panelinde yaşamaya başlamasıdır. Bir gözden geçiren bir çekme isteği açar ve hangi iddiaların başarısız olduğunu satır içi olarak işlenmiş olarak görür, günlük araştırması veya yapıt indirme olmaz.
Bunu bağlamak iki adımdır: XML'i üretmek, sonra CI sisteminize onu nerede bulacağını söylemek. GitLab CI'da, bu ikinci adım reports: junit: bloğudur:
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
Jenkins'te, eşdeğeri aynı dosyalara işaret eden bir post bloğundaki junit adımıdır. GitHub Actions'ta, dizini bir yapıt olarak yüklersiniz ve JUnit'ten anlayan bir eylemin onu işlemesine izin verirsiniz. Testler başarısız olsa bile çalışan yapıt yüklemesini içeren tam GitHub iş akışı, GitHub Actions'ta Apidog CLI testlerini çalıştırma makalesinde yer almaktadır.
json: betiklerinizin işlem sonrası yaptığı rapor
json raporlayıcısı, ham yapılandırılmış sonucu üretir. HTML gözler için ve JUnit kontrol panelleri içinse, JSON kendi yazdığınız kod içindir.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r json --out-dir ./apidog-reports
Yerleşik formatların sonuçla yapmak istediğiniz şeye uymadığı durumlarda buna başvurun. Başarı oranı metriklerini bir izleme sistemine gönderin. Özel bir Slack özeti oluşturun. Sonucu bir dağıtımın geri alınıp alınmayacağına karar veren bir betiğe besleyin. Bugünkü çalıştırmayı dününkiyle karşılaştırın. Herhangi bir programatik işlem JSON'dan başlar, çünkü yapıyı tahmin etmeden ayrıştırabileceğiniz bir formattır.
Bir rapor bayrağı özellikle JSON çıktısı için oluşturulmuştur. --out-json-failures-separated <value> hataları kendi JSON dosyalarına ayırır. Bu size yalnızca hataları içeren bir belge verir, bu da bozulan birkaç adımı bulmak için tam bir sonucu taramaktan çok daha kolay okunabilir ve karşılaştırılabilir. Çoğu adımın geçtiği büyük bir regresyon taramasında, yalnızca hataları içeren bir dosya, bir bakış ile bir grep arasındaki farktır.
Dosyaların nereye indiği: --out-dir, --out-file ve yer tutucular
Formatları seçmek resmin yarısıdır. Diğer yarısı, dosyaların nereye indiğini ve adlarının ne olduğunu kontrol etmektir; bu, birden fazla çalıştırmanın raporlarını tuttuğunuz anda önemlidir.
--out-dir <dir>, raporların yazıldığı dizini ayarlar. Varsayılan ./apidog-reports'tur. CI'da, yapıt adımınızın bulabileceği bir yere işaret edin ve yükleme yapılandırmanızın asla değişmemesi için tutarlı tutun:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r html,junit --out-dir ./apidog-reports
--out-file <name>, rapor dosya adını ayarlar ve işte burası işe yarar hale gelir. Bu olmadan, her çalıştırma bir öncekini üzerine yazma eğilimindedir, bu nedenle yalnızca en son raporu tutarsınız. Bayrak, çalıştırıcının yazma sırasında doldurduğu yer tutucuları kabul eder:
{SCENARIO_NAME}, çalışan senaryonun adı olur.{FOLDER_NAME}, bir senaryo klasörünü çalıştırdığınızda klasör adı olur.{GENERATE_TIME}, bir zaman damgası olur.
Bir dosya adını senaryo adı ve bir zaman damgası ile damgalayın ve her çalıştırma, bir öncekini bozmak yerine ayrı, kendi kendini açıklayan bir dosya yazar:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r html --out-file "{SCENARIO_NAME}-{GENERATE_TIME}"
Şimdi rapor dizininiz bir geçmiş gibi okunur. Hangi raporun hangi senaryodan geldiğini ve ne zaman çalıştığını tek bir dosya açmadan anlayabilirsiniz, bu da gecelik çalıştırmaların olduğu bir klasörü tarayarak işlerin ilk nerede yanlış gittiğini bulmak istediğinizde tam olarak aradığınız şeydir.
Bir rapor bayrağı daha bulut tarafını tamamlar. --upload-report [value], bir rapor özetini Apidog bulutuna yükler, böylece çalıştırma yerel dosyalarla birlikte projenizin geçmişinde de görünür. Bu, sonucu yalnızca CI çalıştırıcısındaki bir dosya olarak değil, Apidog'un içinde de görünür kılmak istediğinizde başvuracağınız seçenektir.
Kitleye göre bir raporlama stratejisi
Karar vermenin en temiz yolu, her raporlayıcıyı kimin okuyacağına göre eşleştirmek, sonra ihtiyacınız olanları birlikte geçirmektir.
- Derleme günlüğünü şu anda tarayan bir kişi
cliokur. Her zaman dahil edin. - Kaydedilmiş bir raporu daha sonra açan bir kişi
htmlokur. Bunu bir yapıt olarak arşivleyin. - CI kontrol paneli
junitokur. Birleştirme isteğindeki hataları işleyen ve derlemeler boyunca sonuçları trend olarak gösteren budur. - Yazdığınız bir betik
jsonokur. Kendi kodunuz tarafından ayrıştırılması amaçlanan tek formattır.
Çoğu CI işlem hattı için, işgücü kombinasyonu, insanlar için HTML artı kontrol paneli için JUnit'tir ve ham günlüğün okunabilir kalması için CLI açık tutulur:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,html,junit --out-dir ./apidog-reports
Bu tek çalıştırma, okunabilir bir günlük, göz atılabilir bir yapıt ve ayrıştırılabilir bir XML dosyası üretir. Üç kitle, tek bir yürütme, yineleme yok.
Açıkça belirtmeye değer bir uyarı: rapor size ne olduğunu söyler, ancak işlem hattını harekete geçiren çıkış kodudur. Herhangi bir iddia başarısız olduğunda Apidog CLI sıfır olmayan bir değerle çıkar ve derlemeyi başarısız kılan ve birleştirmeyi engelleyen rapor değil, bu çıkış kodudur. Rapor hatayı açıklar; çıkış kodu onu uygular. Komutu, bir kabukta || true eklemek gibi bu kodu yutacak hiçbir şeyle sarmayın, aksi takdirde hala yeşil olan bir derlemeye eklenmiş mükemmel bir kırmızı rapor alırsınız. Bu kalite kapısı mantığının daha derin versiyonu, CI/CD'de API testlerini otomatikleştirme kılavuzunda yer almaktadır.
Hepsini bir araya getirmek
CI'da bir senaryo çalıştırın ve üç kitle için üç kullanışlı yapıtın tümünü yayınlayın:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r cli,html,junit --out-dir ./apidog-reports
Gecelik bir klasör taraması yapın, her hatayı tek bir raporda toplayın ve her dosyaya kendi kendini açıklayan bir ad verin:
apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit --on-error continue --out-dir ./nightly-reports --out-file "{FOLDER_NAME}-{GENERATE_TIME}"
Veri odaklı bir senaryo çalıştırın ve hızlı farklar için yalnızca hataları içeren bir JSON tutun:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./accounts.csv -r json --out-json-failures-separated true --out-dir ./apidog-reports
Geçici bir çalıştırıcıya CLI'yı global olarak kurmak istemiyorsanız, kurulumu npx ile değiştirin ve aynı raporlayıcı bayraklarını koruyun:
npx apidog-cli run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r html,junit --out-dir ./apidog-reports
Raporlayıcı davranışı her iki durumda da aynıdır; global kurulum ile npx arasındaki seçim, elde ettiğiniz raporlarla değil, çalıştırıcı hijyeni ile ilgilidir.
Bayrak adları, varsayılanlar ve raporlayıcılar CLI sürümleri arasında değişebilir, bu nedenle çalıştırıcı her zaman kendi doğruluk kaynağıdır. Yüklü sürümünüzde apidog run --help komutunu çalıştırın ve bu makale de dahil olmak üzere herhangi bir makaleye güvenmek yerine buna güvenin. CLI'nın en başta çalıştırdığı senaryoyu kurmak için, Apidog'u İndirin, uygulamada bir senaryo oluşturun, ardından CI/CD sekmesinden oluşturulan komutu kopyalayın ve ihtiyacınız olan raporlayıcıları ekleyin.