Travis CI'da Apidog CLI Kullanarak API Testleri Nasıl Otomatikleştirilir?

API'niz kendi makinenizde çalışıyor. Birim testler yeşil. Birleştiriyor, dağıtıyor ve bir saat sonra bir ekip arkadaşınız size mesaj atıyor: /checkout uç noktası boş sepeti olan herkes için 500 hatası döndürüyor. Hata, değiştirdiğiniz kodda değildi; kimsenin tekrar test etmediği, iki hizmet ötedeki bir sözleşmedeydi. İşte entegrasyon seviyesindeki API testlerinin doldurduğu boşluk bu ve tam da her taahhütte otomatik olarak çalışmasını istediğiniz kontrol türü, birinin kafasında değil.

Travis CI, en eski barındırılan sürekli entegrasyon hizmetlerinden biridir ve hala tek bir şeyi iyi yapar: Git deponuzu izler, her push ve pull request için temiz bir ortam oluşturur ve bir .travis.yml dosyasına koyduğunuz komutları çalıştırır. Çoğu ekip bunu derleme ve birim testi döngüleri için kullanır. Çalışan bir API'ye karşı gerçek HTTP testleri çalıştırmak için çok daha az kişi kullanır, oysa pahalı hataların saklandığı yer burasıdır. Bunun nedeni sürtünmedir. Bir API test çalıştırıcısını bir CI kutusuna bağlamak, sırları güvenli bir şekilde iletmek ve bir geçme/kalma sinyali almak o kadar zahmetlidir ki insanlar bunu atlar.

Bu kılavuz, Apidog komut satırı çalıştırıcısı ile bu boşluğu kapatmayı anlatıyor. API testlerinizi, istekleri ve onayları görsel olarak görebileceğiniz Apidog masaüstü uygulamasında tasarlar ve hata ayıklarsınız, ardından bu aynı testleri Travis CI içinde tek bir komutla başsız (headless) olarak çalıştırırsınız. Test mantığını kod olarak yeniden yazmaya, ayrı bir test donanımı sürdürmeye gerek yok. Makale, tüm yolu kapsıyor: minimal bir .travis.yml, çalıştırıcının yüklenmesi, erişim jetonunuzu güvenli bir şekilde geçirme, ne çalıştırılacağını seçme, raporlar oluşturma ve bir uç nokta bozulduğunda derlemenin yüksek sesle başarısız olmasını sağlama. Takip etmek isterseniz Apidog'u indirin.

API testlerini neden CI'da çalıştırmalıyız?

Birim testler bir fonksiyonun doğru değeri döndürdüğünü doğrular. API testleri ise tüm istek-yanıt döngüsünün doğru davrandığını doğrular: rota mevcut mu, kimlik doğrulama uygulanmış mı, durum kodu doğru mu, JSON şeması eşleşiyor mu ve yanıt gövdesindeki değerler geçerli mi. Bunlar farklı hata modlarıdır ve ikinci tür, kullanıcılarınızın gerçekten karşılaştığı türdür.

Onları yerel olarak çalıştırmak, çalışmayana kadar iyidir. Yerel çalıştırmalar, onları çalıştırmayı hatırlamanıza, makinenizin üretim yapılandırmasıyla eşleşmesine ve bir gerileme (regression) sorunu ortaya çıktığında kahve molasında olmamanıza bağlıdır. Sürekli entegrasyon bu üç bahaneyi de ortadan kaldırır. Her push, aynı paketi aynı ortamda tetikler ve sonuç, herkesin görmesi için taahhüt ve pull request'e eklenir.

Özellikle API ekipleri için daha derin bir fayda var. Testleriniz API tasarımınızın yanında yaşadığında, bozucu bir değişiklik push edildiği anda başarısız bir onay olarak görünür, bir destek bileti olarak değil. Bunun bir teslimat hattında nereye oturduğuna dair kavramsal arka planı merak ediyorsanız, CI/CD nedir açıklaması iyi bir yardımcı okumadır; bu makale pratik Travis CI derlemesine odaklanmaktadır.

Başlamadan önce ihtiyacınız olanlar

Üç şey ve muhtemelen ikisine zaten sahipsinizdir.

• Travis CI'a bağlı bir Git deposu. travis-ci.com üzerindeki ücretsiz katman, kullanım limitleri dahilinde genel ve özel depolar için çalışır.

• Masaüstü uygulamasında zaten başarıyla oluşturduğunuz ve çalıştırdığınız en az bir test senaryosuna sahip bir Apidog projesi. Apidog'da bir test senaryosu, onaylamalarla birlikte sıralı bir API istekleri kümesidir; bunu "giriş yap, sipariş oluştur, siparişi getir, sil" gibi tek bir uçtan uca akış olarak düşünebilirsiniz.
• Node.js. Apidog CLI, Node üzerinde çalışır ve sürüm 16 veya daha yenisini gerektirir. Travis, node_js dil ortamında Node'u kutudan çıktığı gibi sağlar, bu nedenle bu genellikle tek satırlık bir bildirimdir.

Henüz bir test senaryosu oluşturmadıysanız, bunu önce uygulamada yapın. Bu iş akışının tüm amacı, bir kez görsel olarak hata ayıklamak, sonra sonsuza dek otomatikleştirmektir. Bir CI günlüğü içinde körü körüne test yazmaya çalışmak yavaş bir yoldur. İyi kontroller yazmanın temelleri için, API onaylamaları: pratik bir rehber, push etmeden önce durum kodlarını, yanıt gövdelerini ve JSON şemasını nasıl doğrulayacağınızı anlatır.

Adım 1: Erişim jetonunuzu ve senaryo kimliğinizi alın

Apidog CLI, bulutta depolanan testlerinizi başsız (headless) olarak çalıştırır, bu nedenle iki kimlik bilgisine ihtiyaç duyar:

1. Erişim jetonu, çalıştırıcının projenizi okumasına izin verildiğini kanıtlayan. Apidog hesap ayarlarınızdan erişim jetonları altında oluşturun. Buna bir parola gibi davranın; proje verilerinize API erişimi sağlar.
2. Bir test senaryosu kimliği. Senaryoyu masaüstü uygulamasında açın ve kimliğini kopyalayın veya kimliğin zaten doldurulmuş olduğu hazır bir komut oluşturan "CI/CD'de Çalıştır" seçeneğini kullanın.

Doğru bir ilk komut almanın en kolay yolu, Apidog'un bunu sizin için yazmasına izin vermektir. Bir test senaryosu içinde, CI/CD çalıştırma seçeneği şöyle bir şey üretir:

apidog run --access-token <your-access-token> -t 5564321 -e 4417023 -r cli

İşte tam hali: kimlik doğrulayın, bir senaryoyu (-t) hedefleyin, bir ortamı (-e) hedefleyin ve bir raporlayıcı (-r) seçin. Bunu kopyalayın, önce kendi dizüstü bilgisayarınızda çalıştığını doğrulayın ve ancak ondan sonra Travis'e taşıyın. Yerel olarak doğrulamak, bir jetondaki yazım hatasını ayıklamak için harcadığınız bir düzine başarısız derlemeden sizi kurtarır.

Adım 2: Jetonu şifrelenmiş bir Travis değişkeni olarak saklayın

Erişim jetonunuzu asla .travis.yml içine yapıştırmayın. Bu dosya Git'e taahhüt edilir ve sızdırılmış bir jeton, herhangi birine API projenize okuma erişimi verir. Travis'in iki güvenli seçeneği vardır.

Temiz yol, Travis web UI'da ayarlanan depo ortam değişkenleridir. Travis'teki depo ayarlarınıza gidin, ortam değişkenlerini bulun ve ekleyin:

• Jeton değerinizle APIDOG_ACCESS_TOKEN
• Test etmek istediğiniz ortam kimliğiyle APIDOG_ENV_ID

Jetonun asla yazdırılmaması için "derleme günlüğünde değeri göster" seçeneğini kapalı bırakın. Travis bunları her derlemeye gerçek ortam değişkenleri olarak enjekte eder ve yapılandırmanız bunları adlarıyla referans alır. Bu, sırları depodan tamamen uzak tutar, ki istediğiniz davranış budur; bir katkıda bulunan depoyu çatallarsa, jetonunuz birlikte gelmez.

Her şeyi dosyada tercih ediyorsanız, Travis CLI aracılığıyla şifrelenmiş değişkenleri de destekler:

travis encrypt APIDOG_ACCESS_TOKEN="your-token-here" --add env.global

Bu, yalnızca deponuzun derlemesinin şifresini çözebileceği şifrelenmiş bir bloğu .travis.yml dosyasına yazar. Her iki yaklaşım da işe yarar. UI yolu çoğu ekip için daha basittir ve bir jetonun süresi dolduğunda döndürmek daha kolaydır.

Adım 3: .travis.yml dosyasını yazın

İşte Apidog CLI'yı yükleyen ve her push ve pull request'te bir senaryoyu çalıştıran eksiksiz, minimal bir yapılandırma:

language: node_js
node_js:
  - "18"

cache:
  npm: true

install:
  - npm install -g apidog-cli

script:
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -r cli

Üç blok işi yapar. Bir sürümle language: node_js, CLI için yeterince yeni bir Node çalışma zamanı sağlar. install adımı apidog-cli'yı global olarak yükler, böylece apidog komutu PATH'te olur. script adımı testlerinizi çalıştırır. -r cli raporlayıcı, okunabilir bir geçme/kalma özetini doğrudan Travis günlüğüne yazdırır, bu da bir şeyler bozulduğunda bakacağınız şeydir.

Senaryo kimliğinin sabit kodlandığını ancak sırların ortam değişkenlerinden geldiğini fark edin. Doğru ayrım budur: kimlik hassas değildir, jeton hassastır. Bu dosyayı taahhüt edin, push edin ve Travis API testlerinizi otomatik olarak çalıştırır. İlk yeşil derleme, API'nizin bir güvenlik ağına sahip olduğu anıdır.

Birkaç hizmeti sürdürüyor ve çalıştırıcılar arasında ortak bir zihinsel model istiyorsanız, CI/CD'de API testlerini otomatikleştirme kılavuzu, diğer platformlara uygulanan aynı modeli gösterir ve GitHub Actions sürümü, bir gün geçiş yaparsanız ruh olarak neredeyse aynıdır.

Adım 4: Bir test başarısız olduğunda derlemenin başarısız olmasını sağlayın

Bu, ekiplerin unuttuğu ve tüm uygulamanın sessizce boşa çıktığı kısımdır. Bir CI işi, ancak başarısız bir test derlemeyi kırmızıya çevirirse faydalıdır. Çalıştırıcı ne olursa olsun sıfır ile çıkarsa, çok pahalı bir günlük yazıcısı inşa etmişsiniz demektir.

İyi haber: Apidog CLI zaten doğru şeyi yapıyor. Bir onaylama başarısız olduğunda, apidog run süreci sıfır olmayan bir durum koduyla çıkar ve Travis, script aşamasındaki herhangi bir sıfır olmayan çıkışı bir derleme hatası olarak değerlendirir. Yani yukarıdaki minimal yapılandırma zaten kutudan çıktığı gibi doğru bir şekilde başarısız olur. Ekstra bir şeye ihtiyacınız yok.

Ayarlayabileceğiniz şey, tek bir isteğin hata verdiğinde senaryo ortasında çalıştırmanın nasıl davranacağıdır. --on-error bayrağı bunu kontrol eder:

• --on-error end senaryoyu ilk hatada durdurur. En hızlı geri bildirim, daha az çıktı.
• --on-error continue kalan adımları çalıştırır, böylece her hatayı tek geçişte görürsünüz.
• --on-error ignore devam eder ve hataların çalıştırmayı durdurmasına izin vermez.

CI için continue genellikle en uygun noktadır: işin ilk başarısız onaylamadan sonra kesilmeden neyin bozulduğuna dair tam resmi görmek istersiniz, aynı zamanda derlemenin başarısız olması için sıfır olmayan bir çıkışla bitirirsiniz. Makul bir script satırı şöyle görünür:

script:
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -r cli --on-error continue

Komuta || true ekleyerek "derlemeyi geçirme" cazibesinden kaçının. Bu, çıkış kodunu yutar ve ortadan kaldırmayı hedeflediğiniz kör noktayı yeniden ortaya çıkarır.

Adım 5: Bir HTML raporu oluşturun ve saklayın

cli raporlayıcı hızlı bir bakış için iyidir, ancak bir derleme başarısız olduğunda genellikle daha zengin bir çıktı istersiniz: hangi istek, hangi onaylama, gerçek yanıt gövdesi neydi. CLI, html raporlayıcı ile bir HTML raporu oluşturur ve tek bir çalıştırmada raporlayıcıları bir araya getirebilirsiniz.

script:
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -r cli,html --out-dir ./apidog-reports

-r cli,html günlüğe yazdırır ve bağımsız bir HTML dosyası oluşturur. --out-dir raporun kaydedileceği yeri ayarlar, varsayılan olarak ./apidog-reports'tur. Bu raporun derleme bittikten sonra da kalmasını sağlamak için, onu bir S3 kovası veya GitHub Pages gibi Travis'in yayınlayabileceği bir yere, bir deploy bloğunda dağıtın. Yaygın bir desen:

deploy:
  provider: pages
  skip_cleanup: true
  github_token: $GITHUB_TOKEN
  local_dir: apidog-reports
  on:
    branch: main

Yapıt depolamasını hiç yönetmek istemiyorsanız, CLI raporu --upload-report ile Apidog bulutuna gönderebilir, ek bir barındırma olmadan ekibiniz bunu bir bağlantıdan açabilir. Bu, dağıtılmış ekipler için en az bakım gerektiren seçenektir.

Adım 6: Ortamlar, veriler ve matris çalıştırmaları ekleyin

Tek bir ortama karşı tek bir senaryo iyi bir başlangıçtır. Gerçek işlem hatları üç yönde büyür ve CLI bayrakları her birine düzgün bir şekilde eşlenir.

Çoklu ortamlar. -e bayrağı, hangi ortamın temel URL'lerini ve değişkenlerini kullanacağını seçer. Ortam kimliğini değiştirerek her push'ta hazırlık (staging) ortamına ve gecelik cron derlemesinde üretim ortamına karşı aynı senaryoyu çalıştırın. Travis cron işleri, ayarlar UI'sında depo başına yapılandırılır.

Veri odaklı çalıştırmalar. -d bayrağı (uzun hali --iteration-data), senaryonuza bir CSV veya JSON dosyası besler, böylece her satır için bir kez çalışır. Kenar durumlarını (edge cases) bu şekilde kapsarsınız: geçerli giriş, eksik alanlar, aşırı büyük yükler, özel karakterler, hepsi tek bir senaryo tanımından. Dosya odaklı yinelemeler yerine sabit sayıda tekrar istediğinizde bunu -n (--iteration-count) ile eşleştirin.

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -d ./test-data.csv -r cli

Paralel senaryolar. Travis derleme matrisleri, birden fazla senaryoyu aynı anda paralel işlerde çalıştırmanıza olanak tanır. Her girişi farklı bir senaryo kimliği taşıyan bir ortam değişkeni matrisi tanımlayın ve her matris işi birini çalıştırsın. Derleme yalnızca hepsi geçtiğinde yeşile döner.

env:
  - SCENARIO_ID=5564321   # checkout flow
  - SCENARIO_ID=5564322   # auth flow
  - SCENARIO_ID=5564323   # search flow

script:
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t $SCENARIO_ID -e $APIDOG_ENV_ID -r cli

Paketler büyüdükçe, senaryoları otomatik API testi için test paketleri halinde düzenlemek, matrisin bir kimlik duvarı haline gelmesini önler ve yönetilebilir kalmasını sağlar.

Bu, testleri CI betiğinizde el ile kodlamaktan neden daha iyi?

API testlerini doğrudan bir Travis betiğinde curl ve jq ile veya dışa aktarılmış bir koleksiyonun Newman çalıştırması olarak yazabilirsiniz. Her ikisi de çalışır ve her ikisi de zamanla kötüleşir.

curl-artı-shell yaklaşımı, her onaylamayı kırılgan bir dize karşılaştırmasına dönüştürür. İç içe bir JSON alanını kontrol etmek bir jq büyüsü haline gelir; bir şemayı kontrol etmek temelde imkansızdır; ve API'niz bir alan eklediği anda, greplerinizin yarısının yeniden yazılması gerekir. Sonunda Bash'te API bilginizin ikinci, daha kötü bir kopyasını sürdürmek zorunda kalırsınız.

Koleksiyon çalıştırıcısı yaklaşımı daha iyidir ancak CI'nizi bir dışa aktarma ve senkronizasyon ritüeline bağlar: testleri bir araçta düzenle, dışa aktar, JSON'u taahhüt et, gerçeklikten sapmadığını um. Sapma gerçektir ve "testler geçiyor ama API bozuk" şikayetlerinin kaynağıdır. Bu başarısızlık modunu Postman koleksiyonlarınızın neden tek doğruluk kaynağı olmadığı yazısında ele aldık ve bugün CI'da koleksiyonlar çalıştırıyorsanız, Newman olmadan CI'da Postman koleksiyonları nasıl çalıştırılır geçiş yolunu kapsar.

Apidog modeli döngüyü kısaltır. Testleriniz, API tasarımınız, ortamlarınız ve sahte sunucularınız tek bir yerde yaşar. CLI, bu testlerin canlı, güncel sürümünü çalıştırır; dışa aktarılacak veya sapacak hiçbir şey yoktur. Uygulamada görsel olarak kararsız bir onaylamayı hata ayıklarsınız, kaydedersiniz ve bir sonraki CI çalıştırması değişikliği alır. Bu tek doğruluk kaynağı, bir yığın shell betiği yerine amaca yönelik bir çalıştırıcı kullanmanın tüm nedenidir. Mevcut kurulumunuza karşı değerlendiriyorsanız, API testi için en iyi Postman alternatifleri derlemesi seçenekleri yan yana koyar.

Travis CI özelinde bir not

Travis, yıllarca varsayılan açık kaynaklı CI idi ve birçok eski depo hala üzerinde çalışıyor. 2026'da yeni başlıyorsanız, alanın değiştiğini bilmekte fayda var; GitHub Actions, GitLab CI ve CircleCI artık çoğu yeni projeyi taşıyor ve en iyi CI/CD araçları karşılaştırmamız her birinin nereye oturduğunu açıklıyor. İyi haber şu ki, Apidog CLI tasarım gereği platformdan bağımsızdır. .travis.yml dosyanızda çalışan aynı apidog run komutu, bir GitHub Actions adımında, bir GitLab .gitlab-ci.yml dosyasında veya bir Jenkins aşamasında da çalışır. Travis'ten ayrılırsanız, API testleriniz sizinle birlikte değişmeden taşınır; yalnızca çevredeki YAML anahtarları farklılık gösterir. Bu taşınabilirlik, test mantığını CI'ya özgü sözdiziminden ayrı tutmanın sessiz ama gerçek bir faydasıdır.

Sıkça sorulan sorular

Apidog masaüstü uygulamasını CI kutusuna yüklemem gerekiyor mu? Hayır. Masaüstü uygulaması testleri tasarlamak ve hata ayıklamak içindir. Travis'in yalnızca apidog-cli npm paketine ve node_js dil ortamının zaten sağladığı Node 16+ çalışma zamanına ihtiyacı vardır. CLI, bulutta depolanan senaryolarınızı başsız (headless) olarak getirir ve çalıştırır.

Erişim jetonumu ve senaryo kimliğimi nerede bulabilirim? Erişim jetonunu Apidog hesap ayarlarınızdan erişim jetonları altında oluşturun. Senaryo kimliği, masaüstü uygulamasındaki her test senaryosunda görünür; yerleşik "CI/CD'de Çalıştır" seçeneği de kimliği önceden doldurulmuş tam bir komut oluşturur, bu da çalışan bir temel elde etmenin en hızlı yoludur.

Jetonu depomdan nasıl uzak tutarım? Travis web UI'da derleme günlüğü görüntüsü kapalıyken bir depo ortam değişkeni olarak ayarlayın, ardından yapılandırmanızda $APIDOG_ACCESS_TOKEN olarak referans verin. Alternatif olarak, .travis.yml içine şifrelenmiş bir değer depolamak için travis encrypt kullanın. Ham jetonu asla taahhüt etmeyin.

Bir test başarısız olursa derleme gerçekten başarısız olur mu? Evet. Bir onaylama başarısız olduğunda apidog run komutu sıfır olmayan bir değerle çıkar ve Travis, script aşamasındaki herhangi bir sıfır olmayan çıkışı başarısız bir derleme olarak değerlendirir. Sadece çıkış kodunu || true ile bastırmayın. Derlemenin yine de başarısız olmasını sağlarken her hatanın tek bir çalıştırmada raporlanmasını istiyorsanız --on-error continue kullanın.

Testleri birden fazla ortama veya birden fazla veri setiyle çalıştırabilir miyim? Evet. Ortamları değiştirmek için -e (push'ta hazırlık, gece cron'unda üretim), veri odaklı yinelemeler için bir CSV veya JSON veri dosyası beslemek için -d ve paralel işlerde birden fazla senaryoyu çalıştırmak için bir Travis derleme matrisi kullanın.

Travis CI kullanmıyorsam bunu kullanabilir miyim? Evet. CLI komutu platformlar arasında aynıdır. GitHub Actions, GitLab CI veya Jenkins için çevredeki YAML'ı değiştirin ve apidog run satırı aynı kalır.

Özetliyor

API testlerini Travis CI'a entegre etmek dört adıma iner: erişim jetonunuzu şifrelenmiş bir değişken olarak saklayın, yükleme adımında apidog-cli'yi kurun, senaryonuzu script adımında apidog run ile çalıştırın ve sıfır olmayan çıkış kodunun derlemeyi başarısız etmesine izin verin. Oradan, paketiniz büyüdükçe HTML raporları, birden fazla ortam, veri odaklı yinelemeler ve paralel bir matris eklersiniz.

curl çağrılarından oluşan bir duvar yerine özel bir çalıştırıcı ile yapmanın nedeni, tek doğruluk kaynağıdır. Görsel olarak tasarlar ve hata ayıklarsınız, ardından bu aynı testlerin canlı sürümünü her taahhütte çalıştırırsınız, senkronizasyondan sapacak bir dışa aktarma adımı olmaz. /checkout gerilemeniz üretimde değil, pull request'te yakalanır.

İlk test senaryonuzu oluşturun, ardından Apidog'u indirin ve bir sonraki push'unuza entegre edin. İlk derleme yeşile döndüğünde, sonraki her taahhüt bir güvenlik ağı ile birlikte gelir.