CSV ve JSON ile Parametreli API Testleri Nasıl Çalıştırılır

Bir giriş testi yazdınız. Test geçiyor. Sonra bir ekip arkadaşınız bariz soruyu sorar: kilitli hesap için de geçiyor mu, doğrulanmamış e-posta için de, sonda boşluk bulunan parola için de, sonunda birinin alana yapıştıracağı SQL enjeksiyon dizesi için de? Şimdi bir seçiminiz var. Bu testi beş kez kopyalayıp her kopyada bir değeri değiştirmek ya da aynı teste birçok girdi satırı besleyip hepsini çalıştırmanın bir yolunu bulmak.

Kopyala-yapıştır yolu, çoğu test paketinin çürüdüğü yoldur. Bir yıl içinde birbirine çok benzeyen beş test birbirinden ayrılır. Biri yeni bir iddiaya sahip olur, diğerleri olmaz. Bir alan yeniden adlandırması dördünü sessizce bozar. Bir olması gereken beş şeyi sürdürmek zorunda kalırsınız. Parametreli test, bunu kökünden düzeltir: testi bir kez yazarsınız, sonra onu bir girdi ve beklenen çıktı tablosuna yönlendirirsiniz. Tek bir senaryo, yüzlerce durum, düzenlenecek tek bir yer.

button

Parametreli Test Gerçekte Ne Anlama Geliyor

Bazen veri odaklı test olarak da adlandırılan parametreli test, bir testin mantığını, karşı çalıştığı verilerden ayırır. Mantık, adım dizisidir: bir istek gönder, durum kodunu kontrol et, yanıttaki bir alanı doğrula. Veri ise, o mantığın karşı çalışmasını istediğiniz girdi ve beklentiler kümesidir.

Bir indirim kodu uç noktası için tek bir test senaryosu hayal edin. Mantık her zaman aynıdır. Bir kod ile POST /api/orders isteği gönderin, sonra yanıtı iddia edin. Veri, her durum için değişir:

kod	sipariş_toplamı	beklenen_durum	beklenen_indirim
WELCOME10	100	200	10
WELCOME10	5	422	0
EXPIRED	100	410	0
(boş)	100	400	0
FAKE123	100	404	0

Beş satır, beş farklı davranış, bir test. Çalıştırıcı satırlar üzerinde yineler. Her geçişte sütun değerlerini değişkenlere bağlar, isteği tetikler ve iddiaları o satırın beklentilerine göre kontrol eder. 3. satır, süresi dolmuş kodun 410 yerine 200 döndürmesi nedeniyle başarısız olduğunda, tek bir satırı işaret eden net bir hata alırsınız. Hangi kopyanın bozulduğunu bulmak için beş ayrı test dosyasını avlamak zorunda kalmazsınız.

Bu desen en çok uç noktalarda önemlidir. "Happy-path" kapsamı yazması kolaydır ve sizi sabah 2'de uyandıran hatayı nadiren yakalar. Hatalar, sınır durumlarında yaşar: boş dize, negatif sayı, unicode adı, süresi dolmuş belirteç, limitin bir sent üzerinde olan değer. Parametreleştirme, bir sınır durumu eklemeyi bir e-tabloya satır eklemek kadar ucuz hale getirir.

Ayrı Bir Veri Dosyası Neden Sabit Kodlanmış Değerlerden Daha İyidir

Her durumu doğrudan teste sabit kodlayabilirsiniz. Çoğu insan buradan başlar. Sorun daha sonra ortaya çıkar.

Veriler testin içinde olduğunda, mühendis olmayan biri durumları katkıda bulunamaz. QA lideriniz bu uç noktayı daha önce bozan on beş zorlu girdiyi bilir, ancak kod düzenlemeden ve bir çekme isteği açmadan bunları ekleyemezler. Veriler bir CSV'de olduğunda, bir e-tabloyu düzenler ve taahhüt ederler. Engel neredeyse sıfıra düşer.

Ayrı bir dosya ayrıca test senaryonuzun okunabilirliğini korur. Harici bir dosya üzerinde döngü yapan bir test kısadır: bir istek, birkaç iddia, bitti. Otuz satır içi durumu olan bir test, kimsenin dokunmak istemediği bir tekrar duvarıdır. Ve durumları programlı olarak üretmeniz gerektiğinde, örneğin üretim günlüklerinden çekilen binlerce satır, bir dosya tek mantıklı seçenektir. Binlerce durumu bir test gövdesine yapıştıramazsınız.

Seçtiğiniz format, verilerinizin şekline bağlıdır. Düz, tablo şeklindeki durumlar CSV'ye uyar. İç içe veya yapılandırılmış yükler JSON'a uyar. Her ikisi de Apidog'un çalıştırıcısında birinci sınıf girdilerdir, bu nedenle seçim aracın sınırlamalarıyla ilgili değil, verilerinizle ilgilidir.

Veri Dosyanızı Ayarlama

Tablo şeklindeki durumlar için CSV ile başlayın. Başlık satırı değişkenlerinizi adlandırır; aşağıdaki her satır bir yinelemedir. İşte indirim kodu tablosu gerçek bir dosya olarak, discount-cases.csv:

code,order_total,expected_status,expected_discount
WELCOME10,100,200,10
WELCOME10,5,422,0
EXPIRED,100,410,0
,100,400,0
FAKE123,100,404,0

Her sütun başlığı, testin içinde başvurduğunuz bir değişken haline gelir. İstek gövdesinde {{code}} ve {{order_total}} yazarsınız; iddialarda ise {{expected_status}} ve {{expected_discount}} ile karşılaştırırsınız. Çalıştırıcı bağlamayı satır satır yapar.

Girdileriniz iç içe olduğunda JSON'a yönelin. Her yineleme için bir nesne içeren bir nesne dizisi, her durumun sütunlara düzleştirilmesi zor olacak yapılandırılmış verileri taşımasına olanak tanır. İşte yükün iç içe alanlara sahip olduğu bir kullanıcı oluşturma uç noktası için user-cases.json:

[
  {
    "scenario": "valid full profile",
    "user": {
      "email": "ada@example.com",
      "roles": ["admin", "billing"],
      "profile": { "country": "US", "timezone": "America/New_York" }
    },
    "expected_status": 201
  },
  {
    "scenario": "missing email",
    "user": {
      "email": "",
      "roles": ["viewer"],
      "profile": { "country": "GB", "timezone": "Europe/London" }
    },
    "expected_status": 400
  },
  {
    "scenario": "unknown role",
    "user": {
      "email": "grace@example.com",
      "roles": ["wizard"],
      "profile": { "country": "CA", "timezone": "America/Toronto" }
    },
    "expected_status": 422
  }
]

Testin içinde yapılandırılmış değerlere aynı {{user}}, {{expected_status}} sözdizimi ile başvurursunuz ve Apidog, her nesnenin alanlarını yinelemeye aktarır. scenario sütunu kendiniz için bir etikettir; raporda görünür, böylece başarısız bir yineleme "yineleme 3" yerine "bilinmeyen rol" olarak okunur.

Birkaç kural, veri dosyalarının sizi ısırmasını engeller:

Her dosya için tek bir kaygıyı koruyun. Bir indirim kodu dosyası ve bir kullanıcı oluşturma dosyası, karışık sütunlara sahip tek bir dosya değil, iki ayrı dosyadır.
Beklenen sonucu teste değil, verilere koyun. Tüm mesele, satır 2'nin 422 beklerken satır 1'in 200 beklemesidir. Beklenti sabit kodlanmışsa, her durum için tek bir teste geri dönersiniz.
CSV'de virgül içeren her şeyi tırnak içine alın veya o dosyayı JSON'a çevirin. İçinde virgül bulunan serbest metin alanı klasik bir CSV kendi kendine sorun çıkarma durumudur.
Bu dosyaları, test yapılandırmanızın geri kalanıyla birlikte deponuzda saklayın, böylece çalıştıkları kodla birlikte sürümlendirilirler.

Apidog'da Parametreli Senaryo Oluşturma

Apidog uygulamasında, test senaryosunu diğerleri gibi bir kez oluşturun. Uç noktanıza isteği ekleyin. Gövdede, değişmez değerleri değişken referanslarla değiştirin: {{code}}, {{order_total}} vb. Bunlar veri dosyanızdaki sütunlardır.

Ardından, aynı dosyadan okuyan iddiaları ekleyin. İndirim örneği için, yanıt durumunun {{expected_status}}'a ve JSON gövdesindeki indirim alanının {{expected_discount}}'a eşit olduğunu iddia edersiniz. Hem girdi hem de beklenen çıktı satırdan geldiği için, aynı iddia mantığı her durumu doğru şekilde doğrular. Daha önce Apidog'da iddia yazmadıysanız, API iddiaları: pratik bir rehber desenleri kapsar ve JSON yanıtından iddialar nasıl ayarlanır ve değişkenler nasıl çıkarılır JSONPath tarafını ayrıntılı olarak gösterir.

Verileri bağlamak için, test senaryosunun çalıştırma ayarlarını açın ve CSV veya JSON dosyanızı yineleme veri kaynağı olarak ekleyin. Apidog dosyayı okur, satırları sayar ve her satır için senaryoyu bir kez çalıştırır, her satırın sütunlarını eşleşen değişkenlere bağlar. Uygulamanın içinde çalıştırdığınızda, her yineleme için bir döküm alırsınız: hangi satırların geçtiği, hangilerinin başarısız olduğu ve her başarısız iddia için gerçek ile beklenen değer.

Bu aynı zamanda parametreleştirmenin süitinizin geri kalanıyla birleştiği yerdir. Parametreli bir senaryo hala bir senaryodur, bu nedenle birkaçını bir test süitinde gruplandırabilir ve tüm seti tek bir iş olarak çalıştırabilirsiniz. Veri odaklı döngü tek bir uç nokta içindeki genişliği ele alır; test süiti uç noktalar arası kapsamı ele alır.

Komut Satırından Çalıştırma

Uygulama, inşa ettiğiniz ve hata ayıkladığınız yerdir. CI ise testin değerini kazandığı yerdir, kimse bir düğmeye tıklamadan her çekme isteğinde çalışır. Bu aktarım için Apidog CLI kullanılır. Uygulamada oluşturduğunuz senaryoyu alır ve aynı yineleme verileriyle bir terminalden başsız olarak çalıştırır.

CLI bir npm paketi olarak gelir. Genel olarak yükleyin:

npm install -g apidog-cli

İkili dosya apidog'dur, bu nedenle her komut apidog run ile başlar. Temel bir çalıştırma, senaryoyu kimliğine ve ortamı kimliğine göre işaret eder:

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

Bu senaryoyu bir veri dosyasından sürmek için yineleme veri bayrağını ekleyin. JSON veya CSV dosyasına bir yol kabul eder:

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

-d bayrağı (uzun biçimi --iteration-data), komut satırından parametreli çalıştırmaların kalbidir. Apidog dosyayı okur, senaryoyu her satır için bir kez çalıştırır ve her yinelemeyi raporlar. discount-cases.csv'yi user-cases.json ile değiştirin ve aynı bayrak JSON dizisini işler; çalıştırıcı formatı dosyadan alır. Erişim belirtecini bir parola gibi ele alın ve bir CI sırrı olarak saklayın, asla taahhüt edilmiş bir dosyada değil. Bu yüzden her örnek değişmez bir değer yerine $APIDOG_ACCESS_TOKEN'a başvurur.

Birkaç bayrak, parametreli çalıştırmalarla doğal olarak eşleşir:

-d, --iteration-data <path>, çalıştırmayı CSV veya JSON dosyanıza yönlendirir. Bu, tek geçişli bir çalıştırmayı veri odaklı bir çalıştırmaya dönüştüren bayraktır.
-n, --iteration-count <n>, senaryoyu sabit sayıda çalıştırır. Bir veri dosyası sağladığınızda, satır sayısı genellikle yinelemeleri yönlendirir, bu nedenle -n'yi esas olarak "soak testleri" gibi veri olmadan tekrar eden durumlar için kullanırsınız.
-r, --reporters <list>, çıktı formatlarını seçer. Okunabilir yapı günlüğü çıktısı için cli'yi ve CI panolarının her yineleme için bir geçiş/başarısızlık ağacına ayrıştırdığı XML'i yaymak için junit'i kullanın.
--out-dir <path>, raporların nereye kaydedileceğini ayarlar, böylece bunları yapı yapıtları olarak arşivleyebilirsiniz.

Yüklü sürümünüz için yetkili, güncel bayrak listesini istiyorsanız, apidog run --help komutunu çalıştırın. CLI, her seçeneği kısa ve uzun biçimiyle birlikte yazdırır.

Parametreli Çalıştırmaları CI'ya Bağlama

Parametreli testlere yatırım yapmanın nedeni, otomatik olarak karşılığını vermesidir. İşte CLI'yı kuran ve her çekme isteğinde CSV odaklı bir senaryoyu çalıştıran bir GitHub Actions işi:

name: API tests
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: Install Apidog CLI
        run: npm install -g apidog-cli
      - name: Run parameterized API tests
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
        run: |
          apidog run --access-token $APIDOG_ACCESS_TOKEN \
            -t 605067 -e 1629989 \
            -d ./tests/discount-cases.csv \
            -r cli,junit --out-dir ./test-reports
      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: api-test-report
          path: ./test-reports

Belirteç, depo ayarlarınızda bir kez ayarlanan secrets.APIDOG_ACCESS_TOKEN'dan gelir. junit raporlayıcısı, çoğu CI panosunun her yineleme için bir sonuç ağacına dönüştürdüğü XML'i yazar, bu nedenle başarısız bir satır, bir günlük metni duvarı yerine adlandırılmış bir başarısız test olarak görünür. Yükleme adımındaki if: always(), çalıştırma başarısız olsa bile raporu sakladığınız anlamına gelir ki bu, tam da istediğiniz zamandır. Actions tarafının daha derin bir incelemesi için, GitHub Actions'ta API testleri nasıl otomatikleştirilir bölümüne bakın.

Aynı senaryo ve aynı veri dosyası herhangi bir CI sisteminde çalışır. GitLab CI, Jenkins, CircleCI ve diğerleri hepsi aynı üç harekete indirgenir: Node ve CLI'yı kurun, belirteci bir ortam değişkeni olarak ifşa edin, apidog run'ı -d ile çağırın. Testlerinizin platforma özel yeniden yazılması gerekmez.

Parametreli Test Yaklaşımlarını Karşılaştırma

Apidog, veri odaklı API testlerini çalıştırmanın tek yolu değildir. Doğru olanı seçebilmek için genel görünümü bilmekte fayda var.

Postman ve çalıştırıcıları da veri dosyalarını destekler. Postman'ın Collection Runner'ı veya Newman komut satırı aracı ile bir CSV veya JSON dosyası eklersiniz ve isteklerde {{column}} değişkenlerine başvurursunuz, tıpkı buradaki desendeki gibi. Bu yetenekli bir yaklaşımdır ve iyi belgelenmiştir. Değiş tokuş ise, test mantığınızın JavaScript ön-istek ve test betiklerinde yaşamasıdır, bu nedenle iddialarınız arttıkça daha fazla kod sürdürmeniz gerekir. Özellikle komut satırı çalıştırıcılarını değerlendiriyorsanız, Postman CLI ve Newman karşılaştırması farklılıkları ayrıntılarıyla açıklar.

@pytest.mark.parametrize ile pytest, JUnit'in @ParameterizedTest'i veya REST Assured gibi kod öncelikli çerçeveler size tam programlama dili kontrolü sağlar. Test mantığınızın gerçekten koda ihtiyacı olduğunda doğru seçimdirler: karmaşık kurulum, özel veri üretimi, mevcut bir test kod tabanına sıkı bağlılık. Maliyet ise her durumun kodda yaşamasıdır, bu nedenle mühendis olmayanlar katkıda bulunamaz ve HTTP tesisatını kendiniz sürdürürsünüz.

Apidog'un bakış açısı, senaryonun görsel olması ve verilerin harici olmasıdır, bu nedenle mantık okunabilir kalır ve durumlar bir e-tabloyu düzenleyebilen herkese açık kalırken, aynı senaryo CI'da başsız olarak çalışmaya devam eder. CSV ve JSON veri odaklı çalıştırmalar için özellikle bir araç seçiyorsanız, CSV veya JSON ile veri odaklı API testi için hangi araç karşılaştırması ödünleşmeleri daha derinlemesine inceler. Bunlardan hiçbiri yanlış değildir. Yaklaşımı, durumları kimin yazdığına ve her durumun ne kadar özel mantığa ihtiyaç duyduğuna göre eşleştirin.

Ölçeklenebilir Pratik Bir İş Akışı

Ekibinizin rutininde yer aldığında bu şöyle görünür.

Dar başlayın. Daha önce başınızı ağrıtmış bir uç nokta seçin. İsteğe değişken referansları ve iddialara beklenen sonucu içeren tek senaryoyu Apidog'da yazın. Üç satırlı bir CSV oluşturun: bir başarılı yol, bir bilinen hata, bir sınır durumu. Üç yinelemenin de beklendiği gibi davranana kadar uygulamada çalıştırın.

Sonra veriyi büyütün, testi değil. Her bir hata raporu geldiğinde, hataya neden olan girdiyi doğru beklenen çıktısıyla yeni bir satır olarak ekleyin. Hata kalıcı bir regresyon durumu haline gelir ve siz yeni bir test yazmadan, bir dosyaya bir satır eklemiş olursunuz. Birkaç ay içinde dosya, uç noktanızın gerçek dünyada karşılaştığı çirkinlikleri biriktirir.

Son olarak, otomatikleştirin. Tüm tablonun her çekme isteğinde çalışması için apidog run -d komutunu CI'ya bırakın. Şimdi, süresi dolmuş kod yolunu bozan bir değişiklik, itildiği anda yapıyı bozar ve adlandırılmış bir yineleme doğrudan bozuk satırı işaret eder.

Bileşik kazanç bakımdır. Uç noktanın yanıt şekli değiştiğinde, iddiayı bir kez düzeltirsiniz ve her durum düzeltmeyi alır. Elli vaka daha ihtiyacınız olduğunda, elli satır eklersiniz. Kapsamınız ne kadar geniş olursa olsun, test mantığı tek, küçük, okunabilir bir şey olarak kalır.

Sıkça Sorulan Sorular

Parametreli test ile veri odaklı test arasındaki fark nedir? Aynı fikri tanımlarlar ve insanlar terimleri birbirinin yerine kullanır. Her ikisi de, testin dışından sağlanan farklı girdiler ve beklenen çıktılarla bir testi tekrar tekrar çalıştırmak anlamına gelir. "Parametreli" parametre bağlama mekanizmasına dayanırken; "veri odaklı" harici veri kaynağına dayanır. Pratikte, onları eş anlamlı olarak kabul edin.

Veri dosyam için CSV mi yoksa JSON mı kullanmalıyım? Formatı veri şeklinize göre eşleştirin. Her satırın aynı basit sütunlara sahip olduğu düz, tablo şeklindeki durumlar CSV'ye uyar ve CSV, mühendis olmayanların bir e-tabloda düzenlemesi daha kolaydır. Diziler ve alt nesneler içeren bir istek gövdesi gibi iç içe veya yapılandırılmış yükler JSON'a uyar. Apidog her ikisini de yineleme verisi olarak okur, bu nedenle durumlarınızı zorlama olmadan temsil eden hangisiyse onu seçin.

Yüzlerce yineleme hattımı yavaşlatır mı? Her satır, senaryonun bir çalıştırmasıdır, bu nedenle toplam süre satır sayısının istek başına gecikme süresiyle ölçeklenir. Çoğu API testi için bu saniyelerdir, dakikalar değil. Büyük bir veri kümesi derlemenizi zorlarsa, onu bölün: her çekme isteğinde hızlı bir "smoke" alt kümesini ve gece veya ön sürüm işinde tam tabloyu çalıştırın. Aynı senaryo ve dosya her ikisine de güç verir; sadece veri alt kümesi değişir.

Sırları veri dosyalarımdan ve test yapılandırmamdan nasıl uzak tutarım? Kimlik bilgilerini veri dosyasından tamamen uzak tutun. Belirteçler ve parolalar, ortam değişkenlerinde veya CI sisteminizin sır deposunda, $APIDOG_ACCESS_TOKEN ve benzeri şekillerde referans gösterilerek bulunmalıdır. Veri dosyası, kimlik doğrulama materyali değil, test girdilerini ve beklenen sonuçları içermelidir. Depoyu okuyabilen herkes CSV'yi okuyabilir, bu yüzden ona bu şekilde davranın.

Aynı parametreli senaryoyu hazırlık (staging) ve üretim (production) ortamlarına karşı çalıştırabilir miyim? Evet. Senaryoyu ve veri dosyasını sabit tutun ve -e bayrağıyla ortamları değiştirin. Aynı senaryo kimliği ve aynı verileri kullanarak, sadece farklı bir ortam kimliğiyle, bir çekme isteği kontrolünü hazırlık ortamına ve dağıtım sonrası "smoke" testini üretim ortamına yönlendirin. Ortam ve verilerin ayrı girdiler olmasının tüm nedeni budur.

Özetle

Parametreli API testi, kapsamı bir kopyala-yapıştır angaryasından bir veri girişi görevine dönüştürür. Testi bir kez yazar, her durumu bir CSV veya JSON dosyasında bir satır olarak tanımlar ve gerisini çalıştırıcıya bırakırsınız. Mantık küçük ve okunabilir kalır, durumlar ekipteki herkese açık kalır ve CI her değişiklikte tüm tabloyu çalıştırır.

Apidog size oluşturma için görsel senaryo oluşturucu, veriler için harici CSV ve JSON dosyaları ve herhangi bir CI sisteminde başsız yürütme için apidog run -d komutunu sunar. Tek bir senaryo oluşturun, onu büyüyen bir durum tablosuna işaret edin ve birisi her satır eklediğinde test kapsamınız genişler. Apidog'u indirin ve bir sonraki kararsız tek seferlik testinizi ölçeklenebilir parametreli bir senaryoya dönüştürün.

button