Apidog CLI ile Veri Odaklı API Testi: CSV ve JSON Yinelemeleri

Apidog CLI -d bayrağına yönelik uygulamalı bir rehber: bir CSV, JSON veya depolanmış veri setinden test senaryosu yürütme, bağlamaların hata ayıklamasını yapma ve CI'da veri odaklı testler çalıştırma.

INEZA Felin-Michel

INEZA Felin-Michel

16 June 2026

Apidog CLI ile Veri Odaklı API Testi: CSV ve JSON Yinelemeleri

enterprise.banner.title

enterprise.banner.feature1

enterprise.banner.feature2

enterprise.banner.feature3

enterprise.banner.ctaB

Ödeme uç noktanız için sağlam bir test senaryosu oluşturdunuz. Üç isteği zincirler, her yanıtı doğrular ve Çalıştır'a tıkladığınızda her seferinde geçer. Ardından, pipeline'ınızın kırk girdi kombinasyonunu kapsamasını, verileri Kalite Güvence liderinizin tuttuğu bir dosyadan çekmesini ve aynı senaryoyu farklı kimlik bilgileriyle hazırlık ve üretim ortamlarında çalıştırmasını istiyorsunuz. Dizüstü bilgisayarınızda çalışan, tıklamalı çalıştırma buna dönüşmüyor ve senaryoyu kırk kez klonlamak istemiyorsunuz.

İşte o son mil, komut satırının üstlendiği yerdir. Apidog ile, görsel oluşturucuda bir kez bir test senaryosu yazarsınız, ardından bunu apidog-cli paketi ile bir terminalden yönetirsiniz. Tek bir senaryoyu veri odaklı bir çalıştırmaya dönüştüren işaret -d'dir, yani --iteration-data'nın kısaltmasıdır. Bir CSV dosyası, bir JSON dosyası veya Apidog projenizde depoladığınız bir veri kümesini alır ve senaryoyu her satır için bir kez çalıştırır, her satırın değerlerini isteklerinizin referans aldığı değişkenlere bağlar.

düğme

-d bayrağı bir dosyayı nasıl okur

Tüm özellik tek bir seçenekte bulunur. İşte apidog run --help'ten alınmış uzun ve kısa hali:

-d, --iteration-data <path|testDataId>   Yinelemeler için kullanılacak verileri tanımlar (JSON veya CSV)

O <path|testDataId> çoğu kişinin gözden kaçırdığı ayrıntıdır. Argüman aşırı yüklenmiştir. Ona bir yol ilettiğinizde CLI, yerel bir dosyayı diskten okur. Ona bir test-veri kimliği ilettiğinizde CLI, Apidog projenizin içine kaydettiğiniz bir veri kümesini çeker. Aynı bayrak, iki kaynak ve çalıştırıcı hangisini verdiğinizi anlar.

Yerel dosya biçimi, ortak başlangıç noktasıdır. Komutu çalıştırdığınız yere göre bir dosyayı işaret edin:

apidog run --access-token $APIDOG_ACCESS_TOKEN \
  -t 605067 -e 1629989 \
  -d ./test-data/checkout-cases.csv -r cli

CLI, checkout-cases.csv dosyasını açar, başlığın altındaki satırları sayar ve senaryo 605067'yi her satır için bir kez çalıştırır. Her geçişte, sütunları isteklerinizdeki eşleşen değişkenlere bağlar, senaryoyu tetikler ve o yinelemenin sonucunu kaydeder. Kırk satır, kırk geçiş, tek senaryo.

Biçim dosyayı takip eder. Aynı bayrak, ek bir seçenek olmadan JSON'u kabul eder:

apidog run --access-token $APIDOG_ACCESS_TOKEN \
  -t 605067 -e 1629989 \
  -d ./test-data/checkout-cases.json -r cli

CLI'ya hangi formatı kullandığınızı söylemezsiniz. Uzantıyı ve dosya şeklini okur. Bu, sütun adları ve JSON anahtarları senaryonuzun beklediği değişkenlerle eşleştiği sürece, projenizin ortasında komuta dokunmadan bir CSV dosyasını bir JSON dizisiyle değiştirebileceğiniz anlamına gelir.

CLI her dosyanın içinde ne bekler

CSV, düz, tablosal durumlar için bir formattır. Başlık satırı değişkenlerinizin adlarını verir. Altındaki her satır bir yinelemedir. İşte bir indirim uç noktası için gerçek bir checkout-cases.csv:

sku,quantity,coupon,expected_status,expected_total
DESK-01,1,SAVE10,200,89.10
DESK-01,0,SAVE10,422,0
CHAIR-09,3,,200,447.00
DESK-01,1,EXPIRED,410,0
GHOST-99,1,SAVE10,404,0

Beş sütun beş değişken haline gelir. İstek gövdesinin içine {{sku}} ve {{quantity}} yazarsınız; onaylamalarda yanıtı {{expected_status}} ve {{expected_total}} ile karşılaştırırsınız. Çalıştırıcı bunları her satıra göre bağlar. Üçüncü satırdaki boş coupon hücresi boş bir dize haline gelir, ki bu tam olarak kapsamak istediğiniz kuponsuz durumdur.

JSON, durumlarınızın sütunlara kötü bir şekilde düzleştirilen iç içe yapı taşıdığı zamanki formattır. Dosya, her yineleme için bir nesne olmak üzere bir nesne dizisidir:

[
  {
    "label": "geçerli sipariş, iki ürün",
    "order": {
      "items": [
        { "sku": "DESK-01", "qty": 1 },
        { "sku": "CHAIR-09", "qty": 2 }
      ],
      "shipping": { "country": "US", "method": "ground" }
    },
    "expected_status": 200
  },
  {
    "label": "gönderilemez ülke",
    "order": {
      "items": [{ "sku": "DESK-01", "qty": 1 }],
      "shipping": { "country": "ZZ", "method": "ground" }
    },
    "expected_status": 422
  }
]

Senaryo içinde {{order}} ve {{expected_status}} öğelerine aynı şekilde referans verirsiniz ve çalıştırıcı her nesnenin alanlarını yinelemeye iletir. label alanı sizin içindir. Raporda, başarısız bir geçişin "ikinci yineleme" yerine "gönderilemez ülke" olarak görünmesini sağlar, bu da beş saniyelik bir teşhis ile beş dakikalık bir teşhis arasındaki farktır.

Birkaç kural, bu dosyaların CI'da sizi ısırmasını engeller:

Bu bağlı değerleri okuyan onaylamaları yazmanın JSONPath tarafı için, JSON yanıtından onaylamaları ayarlama ve değişkenleri ayıklama sözdizimini ayrıntılı olarak açıklar.

Bir dosya yerine depolanmış bir veri kümesinden çalıştırma

-d'nin ikinci biçimi, çoğu kılavuzda gösterilmeyen biçimdir. Bir yol yerine, bir test-veri Kimliği iletirsiniz:

apidog run --access-token $APIDOG_ACCESS_TOKEN \
  -t 605067 -e 1629989 \
  -d 38291 -r cli

Artık CLI, çalıştırıcının diskinden bir dosya okumak yerine, Apidog projenizden o kimliğe sahip veri kümesini getirir. Bu, verilerin repo ile değil, ekiple birlikte yaşadığı durumlarda kullanışlıdır. QA lideriniz, Apidog içinde durum tablosunu korur, uygulamada düzenler ve her CI çalıştırması, kimsenin bir CSV dosyası commitlemesine gerek kalmadan mevcut sürümü alır. Senaryo, ortam ve veriler tamamen sunucu tarafındadır; komut sadece onları Kimlikleriyle adlandırır.

Taviz, doğruluk kaynağınızın nerede oturduğudur. Commit edilmiş bir CSV, size çekme isteklerinde karşılaştırılabilir ve test edilen commite sabitlenmiş bir veri kümesi verir. Depolanmış bir test-veri kimliği, herkese tek bir yerde düzenleme imkanı veren tek bir paylaşılan tablo sağlar. İkisi de yanlış değildir. Verilerin kodla eşzamanlı hareket etmesi gerektiğinde commit edilmiş dosyayı, verilerin repoya dokunmayan kişiler tarafından sahiplenildiği zaman ise depolanmış kimliği seçin.

Dışa aktarılmış bir dosyadan çevrimdışı çalıştırma

CLI'yı beslemenin üçüncü bir yolu var ve bu, tüm komutun şeklini değiştiriyor. Bir test senaryosunu Apidog'dan bağımsız bir dosya olarak dışa aktarabilir ve bu dosyayı doğrudan, senaryo kimliği olmadan ve senaryoyu almak için ağ gidiş-dönüşü olmadan çalıştırabilirsiniz:

apidog run ./checkout.apidog-cli.json -r cli,html

Burada ilk argüman, bir bayrak değil, dışa aktarılan test durumunun kendisi olan bir file-source'dur. CLI, dosyanın içindekini çalıştırır. Yine de -d ile üzerine yineleme verilerini katmanlayabilirsiniz:

apidog run ./checkout.apidog-cli.json -d ./checkout-cases.csv -r cli,junit

Bu iki durum için önemlidir. Birincisi, bir senaryo kimliğini çözümlemek için Apidog bulutuna erişemeyen, hava boşluklu veya kilitli bir CI çalıştırıcısıdır; dışa aktarılan dosya, çalıştırma için gereken her şeyi taşır. İkincisi ise tekrarlanabilirliktir: dışa aktarılan dosya, dışa aktarım anındaki senaryonun dondurulmuş bir anlık görüntüsüdür, bu nedenle ondan yapılan bir çalıştırma, daha sonra uygulamada senaryoyu düzenleyen birinden etkilenmez. Bunun arkasındaki kurulum ve ilk çalıştırma mekaniği için, Apidog CLI kurulum kılavuzu ikiliyi yerine koymayı kapsar ve tam Apidog CLI referansı her bayrağı tek bir tabloda belgeler.

-d'yi -n ve değişken geçersiz kılmalarıyla eşleştirme

Veri odaklı çalıştırmalar nadiren yalnız seyahat eder. Üç bayrak -d ile sürekli eşleşir.

-n, --iteration-count, senaryonun kaç kez çalışacağını ayarlar. Bir veri dosyası sağladığınızda, satır sayısı zaten yinelemeleri yönlendirir, bu yüzden genellikle -n'yi kapalı bırakır ve dosyanın karar vermesine izin verirsiniz. -n'ye esas olarak tabloyu birden fazla çalıştırmak istediğinizde veya bir veri dosyası olmadan hiç çalıştığınızda, tek bir sabit senaryoyu tekrarlayan bir dayanıklılık testi gibi durumlarda ulaşırsınız:

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

--env-var ve --global-var, projenizdeki ortama dokunmadan çalışma zamanında key=value çiftlerini enjekte eder. Bu, sırları ve pipeline başına yapılandırmayı hem senaryodan hem de veri dosyasından uzak tutmanızın yoludur. Veri dosyası test durumlarını tutar; geçersiz kılmalar ise her çalıştırmada değişen şeyleri tutar:

apidog run --access-token $APIDOG_ACCESS_TOKEN \
  -t 605067 -e 1629989 \
  -d ./checkout-cases.csv \
  --env-var "base_url=https://staging.internal" \
  --global-var "api_key=$RUNTIME_API_KEY" \
  -r cli,junit

Bu ayrım kasıtlıdır. Yineleme verisi, çalıştırmanın her yerde aynı olan kısmıdır: uç noktanızın ele alması gereken durumlar. Değişken geçersiz kılmaları ise ortama göre değişen kısımdır: ana bilgisayar, anahtar, kiracı. Kimlik bilgilerini CI gizli deposunuzda saklayın ve yukarıdaki $RUNTIME_API_KEY gibi bir ortam değişkeninden --global-var aracılığıyla geçirin. Asla CSV'ye yerleştirmeyin, aksi takdirde repo erişimi olan herkes onları okuyabilir.

Yineleme başına sonuçları okuma

Veri odaklı bir çalıştırma, hangi satırın başarısız olduğunu anlayabiliyorsanız kullanışlıdır. Raporlayıcı bayrakları, ne elde edeceğinize karar verir.

apidog run --access-token $APIDOG_ACCESS_TOKEN \
  -t 605067 -e 1629989 \
  -d ./checkout-cases.csv \
  -r cli,junit --out-dir ./test-reports

-r cli, terminale okunabilir, yineleme başına bir döküm yazdırır, bu da bir derleme günlüğünde taradığınız şeydir. -r junit, neredeyse her CI kontrol panelinin bir geçme/başarısız olma ağacına ayrıştırdığı bir biçim olan JUnit XML yazar, böylece başarısız bir satır, gömülü günlük metni yerine adlandırılmış bir başarısız test olarak görünür. Ayrıca html ve json da geçirebilirsiniz; html, bir derleme yapıtı olarak arşivlemek için göz atılabilir bir rapor verir ve json, sonuçları sonradan işlerseniz ham yapılandırılmış çıktı verir. --out-dir, dosyaların nerede depolanacağını kontrol eder, böylece onları yapıt olarak saklayabilirsiniz.

Varsayılan olarak, çalıştırma ilk bozuk onaylamada durur. Geniş bir veri tablosu için bu genellikle yanlış bir karardır, çünkü her başarısız satırı tek bir geçişte görmek istersiniz, birini düzeltip sonrakini bulmak için yeniden çalıştırmak istemezsiniz. Davranışı --on-error ile değiştirin:

apidog run --access-token $APIDOG_ACCESS_TOKEN \
  -t 605067 -e 1629989 \
  -d ./checkout-cases.csv \
  --on-error continue \
  -r cli,junit --out-dir ./test-reports

--on-error continue, öncekiler başarısız olsa bile her yinelemeyi çalıştırır, böylece tek bir rapor size ikinci, yedinci ve on dokuzuncu satırların tek seferde bozuk olduğunu gösterir. Bir şey başarısız olursa çalıştırma yine de sıfır olmayan bir çıkış koduyla biter, bu yüzden gerçek bir engel olarak kalır. --on-error end hızlı bir duman testi için hızlı başarısız varsayılanıdır; ignore ise çalıştırmayı raydan çıkarmak istemediğiniz nadir bilinen kararsız adım içindir.

Hiçbir şey yapmayan bir bağlamayı sessizce hata ayıklama

Veri odaklı çalıştırmalarda en çok zaman kaybına neden olan hata modu, kırmızı bir onaylama değildir. Hiçbir şeyi test etmeyen yeşil bir çalıştırmadır, çünkü veriler hiçbir zaman isteğe bağlanmamıştır. İstek boş değerlerle tetiklenmiş, uç nokta boş bir yük için 200 dönmüş ve onaylama tesadüfen geçmişti. Kapsama alanı iyi görünür; öyle değildir.

Veri odaklı bir çalıştırma garip davrandığında, --verbose ekleyin:

apidog run --access-token $APIDOG_ACCESS_TOKEN \
  -t 605067 -e 1629989 \
  -d ./checkout-cases.csv \
  --verbose -r cli

--verbose, her yineleme için tam isteği ve yanıtı yazdırır. Çalıştırıcının gerçekten gönderdiği istek gövdesine bakın. Eğer {{sku}} orada ikamesiz duruyorsa veya CSV hücresi boş değilken boş bir değer varsa, bağlama bozulmuştur. Üç yaygın neden, ne sıklıkla ortaya çıktıklarına göre:

Genel kural: Yinelemeler geçiyor ancak geçmemesi gerektiğinden şüpheleniyorsanız, yeşile güvenmeden önce bir ayrıntılı isteği okuyun. Boş girdiyle çalışan bir test, hiçbir testten daha kötüdür, çünkü uç nokta test edilmeden her şeyin yolunda olduğunu söyler.

CI'ya bağlama

Karşılığı, tüm tablonun her değişiklikte kimse Çalıştır'a tıklamadan çalışmasıdır. İşte CLI'yi kuran ve her çekme isteğinde CSV odaklı bir senaryo çalıştıran bir GitHub Actions işi:

name: Veri odaklı API testleri
on: [pull_request]

jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Apidog CLI Kurulumu
        run: npm install -g apidog-cli
      - name: Veri odaklı senaryoyu çalıştır
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
        run: |
          apidog run --access-token $APIDOG_ACCESS_TOKEN \
            -t 605067 -e 1629989 \
            -d ./test-data/checkout-cases.csv \
            --on-error continue \
            -r cli,junit --out-dir ./test-reports
      - name: Raporu yükle
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: api-test-report
          path: ./test-reports

Token, repo ayarlarında bir kez ayarlanan secrets.APIDOG_ACCESS_TOKEN'dan gelir. --on-error continue, her başarısız satırı tek bir rapora toplar, ilkinde durmak yerine. Yükleme üzerindeki if: always(), çalıştırma başarısız olsa bile raporu tutar, ki bu onu en çok okumak istediğiniz zamandır. CSV yolunu bir JSON dosyasıyla veya depolanmış bir test veri kimliğiyle değiştirin ve başka hiçbir şey değişmez.

Aynı üç hareket herhangi bir CI sistemine de uygulanır: Node.js ve CLI'yi kurun, token'ı bir ortam değişkeni olarak ifşa edin, -d ile apidog run çağrısı yapın. GitLab CI, Jenkins, CircleCI ve diğerleri testlerinizin platform başına yeniden yazılmasına ihtiyaç duymaz. Actions tarafının daha derinlemesine bir incelemesi için, GitHub Actions'ta API testlerini otomatikleştirmeyi ve CLI'nin raporlayıcılar, hata işleme ve TLS genelindeki tam bayrak yüzeyi için tam Apidog CLI kılavuzu her seçeneği detaylandırır.

Testi büyütmeden ölçeklenen bir iş akışı

Tek bir senaryo ve üç satırla başlayın. Uygulamada, isteklerde değişken referansları ve onaylamalarda beklenen sonuçla senaryoyu oluşturun. Mutlu bir yol, bilinen bir hata ve bir sınır durumu içeren bir CSV dosyası yazın. Üç yineleme de düzgün çalışana kadar yerel olarak -d ile çalıştırın.

Sonra senaryoyu değil, veriyi büyütün. Her hata raporu, doğru beklenen çıktısıyla yeni bir satır haline gelir. Hata kalıcı bir regresyon durumu haline gelir ve yeni bir test yazmadınız; bir dosyaya bir satır eklediniz. Birkaç ay içinde bu dosya, uç noktanızın üretimde karşılaştığı gerçek çirkinlikleri toplar.

Son olarak, apidog run -d komutunu --on-error continue ve junit raporlayıcısı ile CI'ya bırakın. Artık süresi dolmuş kupon satırını bozan bir değişiklik, itildiği anda derlemeyi başarısız kılar, bozuk durumu doğrudan işaret eden adlandırılmış bir yineleme ile. Tablo ne kadar genişlerse genişlesin, senaryo küçük, okunabilir bir şey olarak kalır. Bu, bileşik kazançtır: kapsama veri girişiyle büyür ve bakım düz kalır.

Hala böyle bir CLI çalıştırıcının yığınınıza kod öncelikli bir çerçeveye karşı uyup uymadığına karar vermekte zorlanıyorsanız, CSV veya JSON ile veri odaklı API testi için hangi aracı seçeceğiniz karşılaştırması yaklaşımları karşılaştırır ve Apidog CLI vs Newman, Postman dünyasındaki en yakın komut satırı analogunu kapsar.

Sıkça sorulan sorular

-d hem dosya yolu hem de depolanmış bir veri kümesi alabilir mi? -d bayrağı, her çalıştırma başına yalnızca birini kabul eder: yerel bir CSV veya JSON yolu ya da Apidog projenizde kayıtlı bir veri kümesini işaret eden bir test verisi kimliği. Tek bir değer iletirsiniz. Verilerin reponuzla birlikte sürümlemesi gerektiğinde dosya yolunu, paylaşılan bir tablonun uygulamada yaşadığı ve bir kopyasını commitlemek istemediğinizde depolanmış kimliği kullanın.

Dosyamın CSV mi yoksa JSON mu olduğunu CLI'ya söylemek zorunda mıyım? Hayır. Çalıştırıcı, formatı dosyanın kendisinden okur, bu nedenle aynı -d bayrağı ikisini de işler. Sütun adlarınızı (CSV) veya nesne anahtarlarınızı (JSON) senaryonuzun referans aldığı değişken adlarıyla eşleştirin ve komutu değiştirmeden formatları değiştirebilirsiniz.

-d ve -n'yi birlikte kullanırsam ne olur? Veri dosyasının satır sayısı, yineleme sayısını belirler, bu nedenle -d ile birlikte -n genellikle gereksizdir. Veri dosyası olmadan bir çalıştırmayı tekrarlamak istediğinizde, örneğin bir dayanıklılık testi gibi, veya özellikle tüm tabloyu birden fazla çalıştırmak istediğinizde -n'yi kullanın.

Veri odaklı çalıştırmam neden hiçbir şey test etmeden geçti? En yaygın neden, asla gerçekleşmeyen bir bağlamadır: değişken adıyla eşleşmeyen bir sütun adı veya hiçbir şey okumayan CI'da yanlış bir dosya yolu. Bir kez --verbose ile çalıştırın ve CLI'nın gönderdiği istek gövdesini inceleyin. Eğer yerine konmamış {{variables}} veya boş değerler görürseniz, yeşil sonuca güvenmeden önce isim uyuşmazlığını veya yolu düzeltin.

Kimlik bilgilerini veri dosyamdan nasıl uzak tutarım? Token'ları ve anahtarları CSV veya JSON'dan tamamen uzak tutun. Bunları çalışma zamanında --global-var veya --env-var ile CI gizli deponuzdan geçirin, tıpkı --global-var "api_key=$RUNTIME_API_KEY" örneğinde olduğu gibi. Veri dosyası test girdilerini ve beklenen sonuçları içermelidir, çalıştırmayı kimlik doğrulayan hiçbir şeyi değil.

Aynı veriyi hazırlık ve üretim ortamlarında çalıştırabilir miyim? Evet. Senaryoyu ve veri dosyasını sabit tutun ve hedefi -e ile değiştirin. Bir çekme isteği kontrolünü hazırlık ortamı kimliğine, bir dağıtım sonrası duman testini ise üretim ortamına aynı senaryo ve aynı veriyle, sadece farklı bir -e değeri kullanarak yönlendirin. Ortamı veriden ayırmak, bunun çalışmasının ana nedenidir.

Özet

-d bayrağı, Apidog CLI için tüm veri odaklı hikayesidir ve ilk bakışta göründüğünden daha esnektir. Yerel bir CSV veya JSON dosyasını ya da projenizde kimliğine göre depolanmış bir veri kümesini okur. Tekrarlar için -n ile, çalıştırma başına yapılandırma için --env-var ve --global-var ile ve her başarısız satırı tek bir çalıştırmada ortaya çıkarmak için --on-error continue ile eşleşir. Çevrimiçi bir senaryo kimliğinden veya çevrimdışı dışa aktarılmış bir dosyadan çalıştırın ve junit ve cli raporlayıcıları aracılığıyla yineleme başına sonuçları okuyun.

Senaryoyu bir kez oluşturun, her durumu bir satır olarak tanımlayın ve her bir kişi dosyaya bir satır eklediğinde çalıştırıcının kapsama alanınızı genişletmesine izin verin. Apidog'u indirin, apidog run komutunu ilk veri dosyanıza yöneltin ve tek bir senaryoyu, her itmede çalışan bir durum tablosuna dönüştürün.

API Tasarım-Öncelikli Yaklaşımı Apidog'da Uygulayın

API'leri oluşturmanın ve kullanmanın daha kolay yolunu keşfedin