Tavern YAML Kalıp Kodu Olmadan API Testleri Nasıl Çalıştırılır

Tavern, akıllıca tasarlanmış bir mühendislik ürünüdür. pytest'e entegre olur, bir API testini bir YAML dosyası olarak tanımlamanıza olanak tanır ve bu dosyayı normal bir pytest testiymiş gibi çalıştırır. pytest'in tüm ekosistemini ücretsiz olarak elde edersiniz: fixture'lar, eklentiler, pytest-xdist ile paralel çalıştırmalar, kod kapsamı, Python ekibinizin zaten kullandığı komut. pytest ile yaşayan bir backend ekibi için, birim testlerinin yanına bir tane daha test_*.tavern.yaml yazmak doğal hissettirir.

Ancak YAML büyüdükçe sorunlar ortaya çıkar. Bir gövde gönderen, bir jeton kaydeden ve birkaç yanıt alanını kontrol eden tek bir istek, tam olarak doğru girinti yapmanız gereken iç içe geçmiş request, response, save ve verify_response_with anahtarlarından oluşan bir bloğa dönüşür. Çok aşamalı akışlar (giriş yapma, kaynak oluşturma, geri okuma, silme) bu blokları uzun bir dosyada bir araya getirir; burada yanlış yerleştirilmiş bir boşluk ayrıştırmayı bozar ve testin doğruladığı API sözleşmesi tamamen başka bir yerde yaşar: bir Swagger dosyası, bir wiki sayfası, aylarca güncelliğini yitirmiş bir Postman koleksiyonu.

Tavern neyi iyi yapar

Övgüyle başlayalım, çünkü Tavern bunu hak ediyor.

pytest'i değiştirmek yerine onu kullanır. Tavern bir pytest eklentisidir. pip install tavern ile kurarsınız, test dizininize bir YAML dosyası bırakırsınız ve pytest onu diğer testler gibi keşfeder ve çalıştırır. Bu, ekibinizin zaten sahip olduğu her pytest alışkanlığını koruduğunuz anlamına gelir: filtrelemek için -k, ilk hatada durmak için -x, raporlar için pytest-html, paralel çalıştırmalar için pytest-xdist, paylaşılan kurulum için fixture'lar. Çalıştırıcınızda hiçbir şey değişmez. Bir Python şirketi için bu gerçek bir avantajdır ve çok az API test aracı mevcut bir paketle bu kadar temiz bir şekilde entegre olur.

YAML bildirimsel ve okunabilirdir. Basit bir Tavern testi gerçekten kolayca taranabilir:

test_name: Tek bir sipariş al

stages:
  - name: Sipariş 1042'yi getir
    request:
      url: https://api.shop.test/orders/1042
      method: GET
    response:
      status_code: 200
      json:
        id: 1042
        status: shipped

Yapıştırıcı kod yok, içe aktarılacak doğrulama kütüphanesi yok, yazılacak test çerçevesi yok. İstek ve beklenen yanıt yan yana durur. Bir durum kodunu ve birkaç alanı kontrol etmek için, bu, eşdeğer requests artı assert Python kodundan daha iyi okunur.

Değişken kaydetme ve zincirleme. Tavern, bir yanıttan bir değeri çekebilir ve save ve {variable} ikamesiyle bir sonraki aşamaya enjekte edebilir, böylece özel kod olmadan bir giriş-ardından-çağrı akışı çalışır:

stages:
  - name: Giriş yap
    request:
      url: https://api.shop.test/auth/login
      method: POST
      json:
        username: tester
        password: hunter2
    response:
      status_code: 200
      save:
        json:
          token: access_token

  - name: Kaydedilmiş jetonla profili oku
    request:
      url: https://api.shop.test/me
      method: GET
      headers:
        Authorization: "Bearer {token}"
    response:
      status_code: 200

HTTP'den fazlasını yapar. Tavern ayrıca MQTT'yi de test eder; bu, IoT veya mesaj odaklı sistemlerle çalışıyorsanız önemlidir. Ve temelinde pytest olduğu için, aynı çalıştırmada ve aynı raporda YAML API testlerini ve normal Python testlerini karıştırabilirsiniz.

Bunların hiçbiri pazarlama değil. Tavern sağlam bir araçtır. Asıl soru, varsayımlarının sizinkilerle eşleşip eşleşmediğidir.

YAML şablonunun biriktiği yerler

Tavern modeliyle birlikte üç maliyet gelir ve bunların önemli olup olmadığı, paketinizin ne kadar büyüdüğüne bağlıdır.

YAML boşluk hassastır ve şeması derindir. Yukarıdaki basit örnek temizdir. Gerçekçi bir test öyle değildir. Başlıkları, sorgu parametrelerini, bir istek gövdesini, yanıt gövdesi onaylarını, tip kontrollerini, kaydedilmiş değişkenleri ve verify_response_with harici fonksiyonları eklediğinizde, dört veya beş katman derinliğe ulaşırsınız; burada yanlış bir boşluk açık bir mesaj yerine ayrıştırma hatasıdır. Editörler, bir IDE'nin bir Python metodunu otomatik tamamladığı gibi Tavern'in anahtarlarını otomatik tamamlamaz, bu nedenle her yeni alanda status_code mu yoksa status mu, json mı yoksa body mi olduğunu belgelerden kontrol edersiniz.

Test ve API sözleşmesi iki ayrı artefakttır. Tavern YAML'ınız URL'yi, metodu, beklenen alanları ve tiplerini sabit kodlar. Gerçek API tanımı bir OpenAPI dosyasında, bir çerçevenin rota dekoratörlerinde veya kimsenin tam olarak emin olmadığı bir yerde yaşar. API bir alan adını değiştirdiğinde, YAML'a hiçbir şey bilgi vermez. Test, eski şekli CI'da başarısız olana kadar veya daha kötüsü, eski bir beklentiye karşı geçmeye devam edene kadar doğrulamaya devam eder. Birinin ikisini elle senkronize tutması gerekir ve bu genellikle sabah 2'de hata ile karşılaşan kişidir.

Bir Python araç zinciri ve Python bilen kişiler varsayar. Testçileriniz Python yazıyorsa Tavern harikadır. QA grubunuz, frontend mühendisleriniz veya ürün ekibiniz bir test eklemek veya okumak isterse, sadece bir HTTP isteği göndermek ve bir yanıtı kontrol etmek için pip, virtualenv'ler, pytest konvansiyonları ve YAML şema kurallarıyla aynı anda karşılaşırlar. Python dünyasının dışındaki herkes için öğrenme eğrisi diktir.

YAML'ı atlama yolu

Alternatif, testleri metin dosyaları olarak yazmayı bırakmak ve zaten sahip olduğunuz API tanımına göre oluşturmaya başlamaktır.

Apidog'da API spesifikasyonu, istek ve test aynı nesnedir. API'nizi bir kez içe aktarır veya tasarlarsınız (OpenAPI, Swagger veya bir Postman koleksiyonu tek tıkla içe aktarılır) ve her uç nokta gerçek şemasını beraberinde taşır. Test senaryosu, bu uç noktaları görsel olarak zincirleyerek oluşturulur: giriş çağrısını sürükleyin, jetona ihtiyaç duyan çağrıyı sürükleyin ve save: blokları veya {variable} dizeleri yazmadan değeri iletin. Doğrulamalar, ezberlemeniz gereken girintili YAML anahtarları yerine bir paneldeki onay kutuları ve ifadelerdir.

Test spesifikasyona göre oluşturulduğu için, spesifikasyon tek doğruluk kaynağıdır. Tasarımda bir yanıt alanını değiştirin ve ona atıfta bulunan test senaryoları, sessizce farklılaşmak yerine değişikliği yüzeye çıkarır. Tavern'in yapısal olarak yapamadığı kısım budur: YAML'ının sözleşmeye geri dönen bir bağlantısı yoktur.

Ve otomasyon zamanı geldiğinde, Tavern'i çekici kılan başsız, CI dostu özelliği kaybetmezsiniz. Apidog CLI, bu senaryoları komut satırından, CI'da, GUI olmadan, pytest'in Tavern dosyalarınızı bugün çalıştırdığı gibi çalıştırır.

Apidog CLI'yı yükleme ve çalıştırma

Çalıştırıcı, apidog-cli adında ücretsiz bir npm paketidir. Global olarak kurun:

npm install -g apidog-cli

Ardından bir test senaryosunu apidog run komutuyla çalıştırın:

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

Her bir parçanın ne işe yaradığı aşağıdadır:

• --access-token, çalıştırmayı Apidog hesabınıza karşı doğrular. Jetonu senaryonun CI/CD sekmesinden oluşturun ve dosyaya değil, bir sır olarak saklayın.
• -t test senaryosu kimliğidir.
• -e ortam kimliğidir (dev, staging, prod), böylece aynı senaryo doğru temel URL'ye ve değişkenlere ulaşır.
• -r raporlayıcıları seçer. cli terminale okunabilir çıktı yazdırır.

Bu kimlikleri ezberlemenize gerek yok. Apidog'da test senaryosunu açın, CI/CD sekmesine geçin, komut satırı seçeneğini seçin ve Jeton Oluştur'a tıklayın. Apidog, senaryo kimliği ve ortam kimliği zaten doldurulmuş olarak sizin için tam apidog run komutunu oluşturur. Kopyalayın, ardından jetonu bir CI sırrına taşıyın.

Global olarak yüklemek istemiyorsanız, özellikle geçici bir CI çalıştırıcısında, npx ile çalıştırın:

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

Raporlayıcılar cli, html, json ve junit'i kapsar. CI için kullanışlı kombinasyon -r html,junit'dir: junit, hemen hemen her CI gösterge panosunun bir geçme/kalma ağacına ayrıştırdığı standart XML'i yayar ve html, bir yapı artefaktı olarak arşivleyebileceğiniz göz atılabilir bir rapor üretir. Nereye ineceklerini kontrol etmek için --out-dir ekleyin:

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

Yüklü sürümünüzdeki tam bayrak listesi için apidog run --help komutunu çalıştırın.

Yan yana

Ekibiniz tamamen Python'a odaklıysa ve testlerinizi birim testlerinizle aynı depoda ve aynı pytest çalıştırmasında tutmak istiyorsanız Tavern kazanır. YAML bakımını bırakmak, sözleşmeyi ve testi tek bir şey olarak tutmak ve Python yazmayan kişilerin testlere katkıda bulunmasını sağlamak istiyorsanız Apidog kazanır.

CI'ya entegre etme

Başsız çalıştırma, yerel bir test dosyasından bir pipeline'a geçmenin tüm amacıdır. İşte GitHub Actions yapısı:

name: API tests
on: [push, pull_request]

jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Install Apidog CLI
        run: npm install -g apidog-cli

      - name: Run API test scenario
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e 1629989 \
            -r html,junit \
            --out-dir apidog-reports
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: apidog-report
          path: apidog-reports

Jeton, repository sırlarından gelir ve bir ortam değişkeni olarak adıma ulaşır. Yükleme adımındaki if: always(), testler başarısız olsa bile raporu alacağınız anlamına gelir ki bu, tam da onu okumak istediğiniz zamandır. Bir onay başarısız olursa, apidog run adımı sıfır olmayan bir değerle çıkar, iş kırmızıya döner ve çekme isteği başarısız bir kontrol gösterir.

Bu çıkış kodu davranışı, kalite kapısıdır ve Tavern'in yaptığı gibi çalışır: CI her adımın çıkış kodunu okur, sıfır olmayan bir çıkış işi başarısız yapar ve başarısız bir iş birleşmeyi veya dağıtımı engeller. Bunun çalışması için ekstra bir şey yapılandırmanıza gerek yoktur. Daha derin pipeline kurulumları için, CI/CD pipeline'ınızdaki Apidog CLI ve GitHub Actions rehberi ayrıca GitLab CI ve Jenkins varyantlarını da kapsar.

pytest ve daha geniş Python test dünyasına dair bir not

Tavern'in YAML'ından vazgeçmek pytest'i terk etmek anlamına gelmez. Birçok ekip, saf Python birim ve entegrasyon testlerini pytest'te tutar ve API sözleşme katmanı için Apidog'u kullanır; bu kısımda testin spesifikasyonu takip etmesi ve Python dışındaki katkıda bulunanlar için de çalışması gerekir. İkisi birbirini dışlamaz. Tavern'in değeri her zaman pytest bilen kişilerin API testlerini ham requests kodundan daha hafif bir formatta yazmasına olanak sağlamaktı; Apidog'un değeri, bu API testlerinin sözleşmeyi takip etmesini ve paket birkaç dosyayı aştıkça okunabilir kalmasını sağlamaktır.

Diğer çalıştırıcıları da düşünüyorsanız, aynı mantık Postman'in Postman CLI vs Newman'daki komut satırı hikayesi ve Postman olmadan API testi'ndeki ek araçlar olmadan koleksiyonları çalıştırmak için de geçerlidir.

SSS

Apidog CLI ücretsiz mi? Evet. apidog-cli npm paketi npm install -g apidog-cli ile ücretsiz olarak kurulabilir ve çalıştırılabilir. Apidog projenizdeki test senaryolarını yürütür, bu nedenle ne çalıştırabileceğiniz Apidog planınıza bağlıdır, ancak komut satırı çalıştırıcısının kendisi ayrı bir ücretli ürün değildir.

Apidog ile birlikte pytest kullanabilir miyim? Evet. Python birim ve entegrasyon testlerinizi pytest'te tutun ve API sözleşme testi katmanı için Apidog'u kullanın. Birçok ekip ikisini de çalıştırır. Fark, Apidog testlerinin spesifikasyonu ayrı bir dosyada sabit kodlamak yerine takip etmesidir.

Apidog, CI'da kötü bir birleşmeyi nasıl engeller? Çıkış kodu aracılığıyla. Herhangi bir onay başarısız olduğunda, apidog run sıfır olmayan bir değerle çıkar. CI bu çıkış kodunu okur, adımı başarısız olarak işaretler ve birleşmeyi veya dağıtımı engeller. Bunun çalışması için ekstra bir şey yapılandırmanıza gerek yoktur.

CI için hangi raporlayıcıyı kullanmalıyım? CI gösterge panonuzun bir geçme/kalma ağacına ayrıştırdığı makine tarafından okunabilir sonuç için junit kullanın ve bir artefakt olarak kaydedilmiş göz atılabilir bir rapor istiyorsanız html ekleyin. Yaygın bir seçim, okunabilir yapı günlüğü çıktısı için cli ile birlikte -r html,junit'dir.

Apidog, Tavern'in HTTP modu gibi sadece HTTP'yi mi test ediyor? Hayır. Apidog, HTTP'nin yanı sıra SOAP, WebSocket, Server-Sent Events ve gRPC'yi kapsar. Tavern, HTTP'ye MQTT'yi ekler; bu, protokol kapsamının Apidog'un kapsamadığı tek yerdir, bu nedenle MQTT yığınınızın merkezinde ise bunu aklınızda bulundurun.

Dürüst sonuç

Tavern, zaten pytest ve YAML düşünüyorsanız API testleri yazmanın temiz bir yoludur ve pytest entegrasyonu gerçekten en iyi özelliğidir. Maliyeti YAML'ın kendisidir: paketler büyüdükçe derin ve kırılgan hale gelir ve doğruladığı API sözleşmesine geri dönen bir bağlantısı yoktur. Aynı başsız, CI'da hata veren davranışı, YAML'ı elle girintilemeden ve spesifikasyonunuzun ikinci bir kopyasını sürdürmeden istiyorsanız, testleri sözleşmeye göre oluşturmak ve apidog run ile çalıştırmak daha hafif bir yoldur.

Apidog'u indirin ve taahhüt etmeden önce spesifikasyon-test akışını hissetmek için mevcut bir API'yi içe aktarın. Başlamak ücretsizdir.