apidog run ile CI'da API Testleri Nasıl Çalıştırılır

Bir CI/CD sekmesinden bir komutu kopyalayıp bir pipeline'a yapıştırdınız ve çalıştı. Sonra bir ekip arkadaşınız, bir testin açıkça başarısız olmasına rağmen derlemenin neden hala yeşil yandığını, aynı çalıştırmayı üretim yerine hazırlık ortamına yönlendirip yönlendiremeyeceğinizi veya CI panonuzun gerçekten ayrıştıracağı bir raporu nasıl alacağınızı sordu. Aniden tek satırlık komut yeterli gelmedi. Her bir parçasının ne işe yaradığını bilmeniz gerekiyor.

apidog run, Apidog komut satırı çalıştırıcısının kalbindeki tek komuttur. Apidog'da oluşturduğunuz API test senaryolarını terminalden, GUI olmadan ve hiçbir insanın düğmeye tıklamasına gerek kalmadan başsız bir şekilde yürütür. Çalıştırıcının yapabildiği her şeyi, bu tek komut üzerindeki flag'ler aracılığıyla yapar: hangi senaryoyu çalıştıracağını, hangi ortamı hedefleyeceğini, kaç kez döngü yapacağını, hangi raporları yayınlayacağını ve neyin bir hata olarak sayılacağını. Flag yüzeyini bir kez öğrendiğinizde, körü körüne kopyala-yapıştır yapmaktan vazgeçersiniz.

apidog run nedir

Apidog CLI, apidog-cli adlı bir npm paketi olarak gönderilir. Bir kez yüklediğinizde, birincil alt komutu run olan tek bir ikili dosya, apidog elde edersiniz. Bu alt komut, Apidog test senaryolarınızdan birini alır ve masaüstü uygulamasının yaptığı gibi çalıştırır, ardından bir çıkış kodu ve istediğiniz tüm rapor dosyalarıyla geri bildirimde bulunur.

Genel olarak yükleyin:

npm install -g apidog-cli

apidog -v

Flag'lerden önce anlaşılması gereken şey, apidog run'ın ne üzerinde çalıştığıdır. Kendi test formatını tanımlamaz. Test, Apidog uygulamasında yazdığınız senaryodur: zincirleme istekler, onaylamalar, bir yanıttan bir sonrakine çekilen değerler, isteğe bağlı veri odaklı yineleme. CLI, projenize ulaşır, senaryoyu kimliğine göre bulur ve çalıştırır. Bu nedenle çoğu flag, çalıştırıcıya neyi alacağını ve çalışırken nasıl davranacağını söylemekle ilgilidir, testleri satır içinde yazmakla değil.

Minimal gerçek bir komut şuna benzer:

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

Bu, şunu ifade eder: bu belirteçle kimlik doğrulaması yapın, 605067 test senaryosunu 1629989 ortamına karşı bir kez çalıştırın ve bir HTML raporu ile okunabilir terminal çıktısı üretin. Bu satırdaki her flag, aşağıda, bu komutun dışarıda bıraktıklarıyla birlikte açıklanmıştır.

Seçeneklerin tüm yüzeyi bir bakışta

İş gruplarına göre düzenlenmiş seçeneklerin tam kümesi aşağıdadır. Bunu bir arama tablosu olarak kullanın; ardından gelen bölümler, tek bir cümleden fazlasına ihtiyaç duyanları açıklar.

Flag adları ve varsayılanlar CLI sürümleri arasında değişebilir. Şüpheniz olduğunda, çalıştırıcının kendisi doğruluk kaynağınızdır: yüklü sürümünüzde apidog run --help komutunu çalıştırın ve bu makale de dahil olmak üzere diğer tüm makalelerden önce buna güvenin.

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

Üç flag, çalıştırmanın kapsamını belirler ve komut başına bunlardan tam olarak birini seçersiniz.

-t, --test-scenario <id> tek bir senaryoyu çalıştırır. Bu günlük durumdur: odaklanmış bir smoke test, bir regresyon senaryosu, bir pull request'te kontrol etmek istediğiniz tek bir şey.

-f, --test-scenario-folder <id> bir klasördeki her senaryoyu çalıştırır. Bir özellik alanını bir klasörde düzenlediğinizde ve tüm grubun tek bir iş olarak çalışmasını istediğinizde (örneğin, gece regresyon taraması gibi) bunu kullanın.

--test-suite <id>, bir araya getirip tek bir mantıksal birim olarak çalıştırılmak üzere derlediğiniz bir test paketini çalıştırır. Bir paket, istediğiniz senaryoların hepsi tek bir klasörde olmasa bile aynı test geçişine ait olduğunda doğru araçtır.

İki seçici daha, çalıştırıcının nereye baktığını belirler. --project <id>, bir senaryonun içinde bulunduğu projeyi adlandırır; bu, belirtecinizin birden fazla projeye erişimi olduğunda kullanışlıdır. --branch <name>, senaryoyu main yerine belirli bir daldaki haliyle çalıştırır; bu da birleştirilmeden önce bir özellik dalındaki test değişikliklerini doğrulamanıza olanak tanır.

# tek senaryo
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

# tüm bir klasör
apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit

# derlenmiş bir paket
apidog run --access-token $APIDOG_ACCESS_TOKEN --test-suite 40231 -r junit

Çalıştırmayı doğrulama

--access-token <token>, her çevrimiçi çalıştırmanın ihtiyaç duyduğu tek flag'dir. Çalıştırmanın senaryonuzu almasına ve yürütmesine izin verildiğini kanıtlar. Belirteci, Apidog'daki bir test senaryosunun CI/CD sekmesinde oluşturursunuz; burada uygulama, senaryo kimliği ve ortam kimliği zaten doldurulmuş olarak sizin için tam apidog run komutunu da oluşturur.

Belirteci bir parola gibi kullanın. Onu işlenmiş bir pipeline dosyasına veya paylaşılan bir betiğe yapıştırmayın. CI sisteminizde bir sır olarak saklayın ve bir ortam değişkeni aracılığıyla geçirin; bu yüzden buradaki her örnek, literal bir dize yerine $APIDOG_ACCESS_TOKEN'ı referans alır. Bir belirteç sızarsa, aynı CI/CD sekmesinden yeniden oluşturun ve eski olan çalışmayı durdurur.

Bir ortamı hedefleme ve yineleme

Ortam flag'i, tek bir senaryonun birçok amaca hizmet etmesini sağlar. -e, --environment <id>, çalıştırmayı belirli bir ortama yönlendirir, böylece aynı senaryo, herhangi bir şeyi tekrar etmenize gerek kalmadan bir pull request kapısında hazırlık ortamını ve dağıtım sonrası bir smoke testte üretim ortamını kontrol edebilir. Ortamlar arası değerleri yönetiyorsanız, API istemcileri için ortam ve sır yönetimi kılavuzu bu değerlerin nasıl aktığını kapsar.

-n, --iteration-count <n>, senaryoyu art arda n kez çalıştırır. Hızlı bir kararlılık kontrolü veya idempotent olması gereken bir akışın tekrarlanması için kullanışlıdır.

-d, --iteration-data <path>, veri odaklı flag'dir. Bunu bir JSON veya CSV dosyasına yönlendirin ve çalıştırıcı, her bir satırı kendi giriş değerleriyle ayrı bir geçiş olarak ele alarak senaryoyu her satır için bir kez yürütür. Elli hesapta bir oturum açma senaryosu veya bir yük tablosu üzerinde bir sipariş oluşturma akışı böyle çalıştırılır. Daha derin model, CSV ve JSON ile veri odaklı API testinde yer almaktadır.

Üç flag, senaryoyu düzenlemeden değerler enjekte eder. --variables <path>, değişkenleri yerel bir dosyadan yükler. --global-var key=value, satır içi global bir değişken ayarlar. --env-var key=value, yalnızca bu çalıştırma için tek bir ortam değişkenini geçersiz kılar. Bunlar, bir değerin (bir temel URL, bir özellik flag'i) pipeline başına farklılık gösterdiği ve her biri için ayrı bir ortam istemediğiniz CI'da kullanışlıdır. Apidog'daki değişkenler size yeniyse, Apidog'da değişkenleri ustalaşmak kapsamları açıklar.

# bir girdi CSV'si üzerinde bir senaryoyu 50 kez çalıştırın
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./accounts.csv -r junit

# yalnızca bu çalıştırma için bir ortam değişkenini geçersiz kılın
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 --env-var baseUrl=https://staging.internal -r cli

Raporlayıcılar: apidog run'ın üretebileceği her çıktı formatı

Bu, insanların en çok aradığı gruptur, bu yüzden her raporlayıcı ve ne işe yaradığı aşağıdadır. Onları -r, --reporters ile seçersiniz ve virgülle ayrılmış olarak birden fazlasını aynı anda geçirebilirsiniz. Varsayılan cli'dir.

cli, terminale okunabilir bir özet yazdırır. İnsanların geçme/kalma sayılarını ve hangi onaylamaların bozulduğunu görmek için derleme günlüğünde taradıkları şeydir. Makine formatlarının yanı sıra bunu da açık tutun ki günlük kullanışlı kalsın.

html, bağımsız bir HTML raporu yazar. Bunu bir derleme yapıtı olarak arşivleyin ve istek ve yanıt detaylarıyla tam çalıştırmayı görmek için bir tarayıcıda açın. Bu, pipeline'ı izlemeyen birine teslim ettiğiniz formattır.

junit, standart JUnit formatında XML yayar. Neredeyse her CI panosu, JUnit XML'i bir geçme/kalma ağacına ayrıştırmayı, birleştirme isteği widget'ında hataları göstermeyi ve sonuçları zaman içinde eğilim haline getirmeyi bilir. CI için yalnızca bir makine formatı seçerseniz, bunu seçin.

json, ham yapılandırılmış sonucu üretir. Sonucu kendiniz işlemek istediğinizde bunu kullanın: bir betiğe besleyin, metrikleri bir yere itin veya özel bir özet oluşturun.

Yaygın bir CI kombinasyonu, insanlar için HTML ve pano için JUnit'tir:

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

Kalan rapor flag'leri, çıktının nereye kaydedileceğini ve hangi ek bilgileri içereceğini kontrol eder:

• --out-dir <dir>, raporların yazıldığı dizini ayarlar. Varsayılan ./apidog-reports'tur.
• --out-file <name>, rapor dosya adını ayarlar ve {FOLDER_NAME}, {SCENARIO_NAME} ve {GENERATE_TIME} yer tutucularını kabul eder, böylece her çalıştırmada bir dosyayı üzerine yazmak yerine dosyaları senaryo adı ve zaman damgasıyla damgalayabilirsiniz.
• --out-json-failures-separated <value>, hataları kendi JSON dosyalarına ayırır, bu da yalnızca hataların farkını okumayı kolaylaştırır.
• --upload-report [value], rapor özetini Apidog bulutuna yükler, böylece çalıştırma, yerel dosyalarınızın yanı sıra projenizin geçmişinde görünür.

Hataları kontrol etme: hata işleme ve çıkış kodları

Bir çalıştırıcı, yalnızca testlerin geçip geçmediğini pipeline'a bildirdiğinde bir pipeline'da kullanışlıdır. apidog run bunu, iyi huylu komut satırı araçlarının yaptığı gibi yapar: her onaylama geçtiğinde 0 ile, herhangi bir şey başarısız olduğunda ise sıfır olmayan bir kodla çıkar. Bu tek davranış, tüm kalite kapısıdır. CI çıkış kodunu okur, adımı başarısız olarak işaretler ve birleştirmeyi veya dağıtımı engeller. Bir kapıyı yapılandırmazsınız; çıkış kodu kapının kendisidir.

--on-error <behavior>, bir adım senaryo ortasında başarısız olduğunda ne olacağını şekillendirir ve üç değeri vardır:

• end, ilk başarısız adımda çalıştırmayı durdurur. Bir şey bozulduğu anda geri bildirim istediğiniz hızlı başarısız olan bir smoke test için kullanın.
• continue, kalan her adımı çalıştırır, böylece tüm hataları tek bir raporda toplarsınız. Her kırılmayı bir kerede görmenin bir gidiş-dönüşü kurtardığı bir regresyon taraması için kullanın.
• ignore, bilinen dengesiz bir adımın fatal olarak kabul edilmeden çalıştırmanın devam etmesine izin verir. Bunu dikkatli kullanın; göz ardı edilen bir adım gerçek bir regresyonu gizlememelidir.

Her durumda, herhangi bir onaylama başarısız olursa, çalıştırma hala sıfır olmayan bir kodla biter, bu nedenle hangi davranışı seçerseniz seçin kapı geçerli kalır. Kapıyı sessizce bozan bir şey: komutu, kabukta || true eklemek gibi çıkış kodunu yutan bir şeyle sarmak. Yapmayın. Sıfır olmayan çıkış, olayın tüm amacıdır.

Dört flag, çalıştırma sırasında istek davranışını ayarlar:

• --ignore-redirects, çalıştırıcının HTTP yönlendirmelerini otomatik olarak takip etmesini durdurur, böylece yönlendirme yanıtının kendisi üzerinde onaylama yapabilirsiniz.
• --delay-request [n], istekler arasında n milisaniye bekler, bu da hız sınırlarına veya yüke duyarlı uç noktalara karşı yardımcı olur.
• --timeout-request [n], tek bir isteğin ne kadar sürebileceğini milisaniye cinsinden sınırlar.
• --timeout-script [n], bir istek öncesi veya sonrası betiğin ne kadar çalışabileceğini milisaniye cinsinden sınırlar.

# smoke test: ilk hatada dur
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli --on-error end

# regresyon: her şeyi çalıştır, tüm hataları topla
apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit --on-error continue --out-dir ./nightly-reports

TLS ve sertifikalar

Karşılıklı TLS veya dahili bir sertifika otoritesinin arkasındaki uç noktaları test ederken, bu grup bağlantıyı nasıl kuracağınızı gösterir.

-k, --insecure, SSL sertifika doğrulamasını tamamen devre dışı bırakır. Bunu yalnızca kendi kendine imzalı sertifikası olan güvenilir bir dahili ana bilgisayara karşı kullanın; asla herkese açık bir şeye yönlendirmeyin, çünkü bu, bağlantıyı koruyan kontrolü kapatır.

Uygun karşılıklı TLS için bunun yerine istemci kimlik bilgilerini sağlayın: PEM sertifikası için --ssl-client-cert <path>, özel anahtarı için --ssl-client-key <path> ve anahtar şifreliyse --ssl-client-passphrase <passphrase>. Farklı ana bilgisayarlar farklı sertifikalara ihtiyaç duyduğunda, --ssl-client-cert-list <path> bunları eşleyen bir yapılandırma dosyasını işaret eder. Ve --ssl-extra-ca-certs <path>, güvenilir CA sertifikalarını ekler; bu, çalıştırıcının başka türlü tanıyamayacağı dahili bir CA zinciri için temiz bir çözümdür, -k kullanmaktan daha iyidir.

Çıktı ve tanılama

Son grup, çalıştırıcının ne yazdıracağını ve bir avuç yürütme detayını kontrol eder.

--verbose, her adım için tam isteği ve yanıtı yazdırır. Bir senaryo yerel olarak geçiyor ancak CI'da başarısız oluyorsa bu, ilk hamlenizdir: çalıştırıcının gönderdiği ve geri aldığı tam baytları gösterir, böylece elinizle gönderdiğinizle karşılaştırabilirsiniz. --silent, tam tersini yapar, yalnızca çıkış kodunu ve kaydedilen raporu önemsediğiniz gürültülü zamanlanmış işler için konsol çıktısını bastırır. --color <value>, renkli çıktıyı açmaya veya kapatmaya zorlar; bu, bir CI günlük görüntüleyicisinin ANSI kodlarını karıştırması durumunda kullanışlıdır.

Diğerleri belirli senaryo özellikleri içindir:

• --external-program-path <path>, bir senaryonun çağırdığı özel mantık için harici programların bulunduğu bir dosyayı işaret eder.
• --database-connection <path>, doğrudan bir veritabanını sorgulayan adımlara sahip senaryolar için bir veritabanı yapılandırması sağlar.
• --preferred-http-version <version>, çalıştırıcının tercih ettiği HTTP protokol sürümünü ayarlar.
• -b, --bigint, BigInt işlemeyi etkinleştirir, böylece büyük sayısal değerler hassasiyetini kaybetmez.
• --lang <language>, CLI'nin görüntüleme dilini ayarlar.
• -h, --help, yüklü sürümünüz için yetkili liste olan yardım metnini yazdırır.

Hepsini bir araya getirme: Gerçekten çalıştıracağınız komutlar

Dağıtımdan hemen sonra üretime karşı smoke test, hızlı başarısızlık:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e $PROD_ENV_ID -r cli --on-error end

Bir klasör üzerinde tam gece regresyonu, her hata tek bir HTML ve JUnit raporunda:

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

CSV üzerinde veri odaklı çalıştırma, CI için makine tarafından okunabilir çıktı:

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

Birleştirilmeden önce bir özellik dalındaki test değişikliklerini doğrulayın:

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

Yalnızca CI'da oluşan bir hatayı kablo detayını dökerek hata ayıklayın:

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

CLI'yi geçici bir CI çalıştırıcısında çalıştırıyorsanız ve genel olarak yüklemek istemiyorsanız, yüklemeyi npx ile değiştirin:

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

Bu aynı yüzeyi kapsar. Genel yükleme ile npx arasındaki seçim, çalıştırıcı hijyeni ile ilgilidir, yetenekle değil. CLI'nin çalıştırdığı senaryoyu kurmak için Apidog'u indirin, uygulamada bir senaryo oluşturun, ardından oluşturulan komutu CI/CD sekmesinden kopyalayın ve belirteci parametrelendirin.