DEV Community

Cover image for Schemathesis Nedir? OpenAPI Spesifikasyonundan Özellik Tabanlı API Testi
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

Schemathesis Nedir? OpenAPI Spesifikasyonundan Özellik Tabanlı API Testi

Bir OpenAPI veya GraphQL şemanız varsa, Schemathesis bu şemayı binlerce API test senaryosuna dönüştürebilir. Araç, şartnameyi okur, geçerli ve sınır değerleri içeren girdiler üretir, bunları API’nize gönderir ve yanıtların sözleşmeyi nerede ihlal ettiğini raporlar. Bu rehberde Schemathesis’i nasıl kuracağınızı, nasıl çalıştıracağınızı, özellik tabanlı testin pratikte ne anlama geldiğini ve sözleşme testi iş akışını Apidog ile nasıl tamamlayacağınızı göreceksiniz.

Apidog'u bugün deneyin

Schemathesis Nedir?

Schemathesis, OpenAPI veya GraphQL şemalarından otomatik API testleri üreten açık kaynaklı bir Python aracıdır. Şemanızdaki türleri, formatları, zorunlu alanları ve kısıtlamaları kullanarak test girdileri oluşturur. Python’daki özellik tabanlı test kütüphanesi olan Hypothesis üzerine kuruludur ve MIT lisansı ile dağıtılır.

Schemathesis demo

Temel kullanım modeli şudur:

  1. API sözleşmenizi OpenAPI veya GraphQL olarak tanımlarsınız.
  2. Schemathesis bu sözleşmeden istekler üretir.
  3. İstekleri canlı API’ye gönderir.
  4. Yanıtları şemaya göre doğrular.
  5. 500 hatalarını, şema ihlallerini ve belgelenmemiş durum kodlarını raporlar.

Örneğin API’niz geçerli görünen bir istek için 500 Internal Server Error döndürüyorsa veya 200 yanıtı şemada tanımlanan gövdeyle eşleşmiyorsa, Schemathesis bunu başarısız test olarak işaretler.

Schemathesis’i genellikle CLI üzerinden çalıştırırsınız:

schemathesis run http://127.0.0.1:8000/openapi.json
Enter fullscreen mode Exit fullscreen mode

Kısa takma ad da kullanılabilir:

st run http://127.0.0.1:8000/openapi.json
Enter fullscreen mode Exit fullscreen mode

pytest entegrasyonu da vardır, ancak çoğu ekip ilk adımda CLI ile başlar çünkü kurulumu daha hızlıdır.

Özellik Tabanlı Test Ne Anlama Geliyor?

Klasik API testleri genellikle örnek tabanlıdır. Belirli bir istek yazarsınız, beklenen yanıtı tanımlarsınız ve test yalnızca o senaryo için çalışır.

Örnek:

GET /users/123
Enter fullscreen mode Exit fullscreen mode

Beklenti:

{
  "id": 123,
  "name": "Ayşe"
}
Enter fullscreen mode Exit fullscreen mode

Bu yaklaşım değerlidir, ancak yalnızca aklınıza gelen durumları test eder.

Özellik tabanlı test ise farklı çalışır. Tek bir sabit örnek yerine, sistemin her zaman sağlaması gereken bir özelliği tanımlarsınız. Schemathesis bağlamında bu özellik kabaca şudur:

Geçerli bir istek sunucuyu çökertmemeli ve yanıt, API şemasıyla uyumlu olmalıdır.

Schemathesis, şemanızdaki kısıtlamalardan çok sayıda girdi üretir. Örneğin bir alan şu şekilde tanımlandıysa:

age:
  type: integer
  minimum: 1
Enter fullscreen mode Exit fullscreen mode

Schemathesis şunlara benzer değerleri deneyebilir:

  • 1
  • büyük tamsayılar
  • sınır değerleri
  • doğrulama mantığını zorlayabilecek değerler

Bir hata bulduğunda Hypothesis, girdiyi küçültür. Böylece 4 KB’lık rastgele bir payload yerine hatayı yeniden üreten en küçük örneği görürsünüz. Bu, hata ayıklamayı çok daha kolay hale getirir.

Bu yaklaşım maymun testinden farklıdır. Maymun testi genellikle rastgele girdiler gönderir. Schemathesis ise girdileri şemaya göre üretir ve sonucu yine şemaya göre değerlendirir.

Schemathesis Kurulumu ve Çalıştırılması

Schemathesis bir Python paketidir. Python 3 ve pip kuruluysa şu komutla yükleyebilirsiniz:

pip install schemathesis
Enter fullscreen mode Exit fullscreen mode

Kalıcı kurulum yapmak istemiyorsanız ve uv kullanıyorsanız şu şekilde de çalıştırabilirsiniz:

uvx schemathesis run http://127.0.0.1:8000/openapi.json
Enter fullscreen mode Exit fullscreen mode

1. Şema URL’si ile çalıştırma

API’niz OpenAPI şemasını bir URL’den sunuyorsa:

st run http://127.0.0.1:8000/openapi.json
Enter fullscreen mode Exit fullscreen mode

2. Yerel OpenAPI dosyası ile çalıştırma

Şemanız diskteyse ve API farklı bir adreste çalışıyorsa:

st run ./openapi.yaml --url http://127.0.0.1:8000
Enter fullscreen mode Exit fullscreen mode

3. Kimlik doğrulama başlığı ekleme

Bearer token kullanan bir API için:

st run http://127.0.0.1:8000/openapi.json \
  --header 'Authorization: Bearer your-token'
Enter fullscreen mode Exit fullscreen mode

Birden fazla başlık gerekiyorsa:

st run ./openapi.yaml \
  --url http://127.0.0.1:8000 \
  --header 'Authorization: Bearer your-token' \
  --header 'X-Tenant-ID: test-tenant'
Enter fullscreen mode Exit fullscreen mode

4. CI içinde çalıştırma

Basit bir CI adımı şöyle olabilir:

pip install schemathesis
st run ./openapi.yaml --url http://localhost:8000
Enter fullscreen mode Exit fullscreen mode

GitHub Actions örneği:

name: API fuzz tests

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  schemathesis:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install Schemathesis
        run: pip install schemathesis

      - name: Start API
        run: |
          docker compose up -d
          sleep 10

      - name: Run Schemathesis
        run: |
          st run ./openapi.yaml --url http://localhost:8000
Enter fullscreen mode Exit fullscreen mode

Schemathesis, şartnamedeki işlemleri keşfeder, her biri için test girdileri üretir ve başarılı/başarısız kontrolleri özetler. Başarısızlık çıktılarında gönderilen istek de yer alır. Böylece aynı isteği curl, Apidog veya başka bir API istemcisinde yeniden çalıştırabilirsiniz.

Not: Bayrak adları ve varsayılan davranışlar sürümler arasında değişebilir. Kendi kurulu sürümünüz için her zaman şu komutu kontrol edin:

st run --help
Enter fullscreen mode Exit fullscreen mode

Schemathesis Neleri Yakalar?

Schemathesis’in varsayılan kontrolleri, API sözleşmenizde vaat edilen davranış ile gerçek sunucu davranışı arasındaki farkları bulmaya odaklanır.

Sorun Nasıl Görünür
Sunucu hataları Geçerli görünen bir istek, işlenmiş 4xx veya geçerli yanıt yerine 500 döndürür
Şema ihlalleri Yanıt gövdesi, ilgili durum kodu için tanımlanan şemayla eşleşmez
Durum kodu uyuşmazlıkları API, şartnamede belgelenmeyen bir durum kodu döndürür
İçerik türü kayması Yanıtın Content-Type değeri şemadaki tanımla eşleşmez
Durumlu hatalar Tek başına çalışan bir işlem, çok adımlı akışta başarısız olur

Durumlu testler neden önemli?

Bazı hatalar tek istekle ortaya çıkmaz. Örneğin:

  1. Kaynak oluşturulur.
  2. Kaynak güncellenir.
  3. Kaynak tekrar okunur.
  4. Dönen durum eski veya hatalıdır.

Schemathesis, şemanızdaki bağlantıları kullanarak işlemleri zincirleyebilir. Böylece create → get → update → delete gibi gerçekçi akışlarda ortaya çıkan sorunları yakalayabilir.

Kancalar ile özelleştirme

Varsayılan üretim yeterli olmadığında Schemathesis kancaları kullanılabilir. Kancalar, veri üretimini değiştirmek, özel kontroller eklemek veya belirli operasyonları filtrelemek için yazılan Python işlevleridir.

Örneğin yalnızca belirli endpoint’leri test etmek veya test verisini uygulamanıza göre ayarlamak isteyebilirsiniz. Bu özellikle şu durumlarda faydalıdır:

  • Karmaşık kimlik doğrulama akışları
  • Tenant bazlı API’ler
  • Şemanın ifade edemediği iş kuralları
  • Test ortamına özel veri bağımlılıkları

Schemathesis Ne Zaman Kullanılmalı?

Schemathesis en iyi şu koşullarda işe yarar:

  • Güncel ve anlamlı bir OpenAPI veya GraphQL şemanız vardır.
  • API’nin beklenmeyen girdilerle çökmesini istemezsiniz.
  • CI içinde düşük maliyetli bir fuzzing katmanı eklemek istersiniz.
  • Sözleşme ile uygulama arasındaki sapmaları erken yakalamak istersiniz.
  • API’nizde sıralamanın önemli olduğu durumlu iş akışları vardır.

İyi kullanım senaryoları:

  • Bir OpenAPI şartnamesi tutuyorsunuz ve canlı sunucunun buna uyduğunu doğrulamak istiyorsunuz.
  • İşlenmeyen 500 hatalarını pull request aşamasında yakalamak istiyorsunuz.
  • Manuel testlerle kapsaması zor sınır değerlerini otomatik denemek istiyorsunuz.
  • Ekibiniz Python, pip ve pytest ekosistemine aşina.

Ancak Schemathesis her problemi çözmez. Şemanız eksik veya güncel değilse, araç yalnızca tanımlı olanı test edebilir. Eksik sözleşme, eksik test anlamına gelir.

Ayrıca Schemathesis örnek tabanlı işlevsel testlerin yerine geçmez. Bir endpoint’in çökmediğini bilmek, belirli bir iş kuralını doğru uyguladığını bilmekle aynı şey değildir.

Örneğin Schemathesis şunu yakalayabilir:

  • API 500 döndürdü.
  • Yanıt şemaya uymadı.
  • Belgelenmemiş durum kodu döndü.

Ama şunu doğrulamak için hâlâ işlevsel teste ihtiyacınız vardır:

  • İndirim doğru hesaplandı mı?
  • Kullanıcı yetkisi doğru uygulandı mı?
  • Sipariş durumu beklenen iş akışına göre değişti mi?

Schemathesis ve Apidog: Her Birinin Yeri

Apidog ve Schemathesis farklı sorunları çözer. Birbirlerinin alternatifi değil, tamamlayıcısı olarak düşünülmelidir.

Apidog; API tasarımı, hata ayıklama, test, mock sunucu ve dokümantasyon için kullanılan hepsi bir arada bir platformdur. Schemathesis ise OpenAPI veya GraphQL şemasından özellik tabanlı test girdileri üreten odaklı bir fuzzing aracıdır.

Önemli ayrım şudur:

  • Apidog özellik tabanlı fuzzing yapmaz.
  • Apidog’un buna en yakın özelliği, çökmeleri bulmak için rastgele girdiler gönderen maymun testidir.
  • Schemathesis ise girdileri şemadan üretir ve yanıtları şemaya göre doğrular.
İş akışı aşaması Schemathesis Apidog
Şemadan özellik tabanlı fuzzing Evet, temel özellik Hayır
Görsel API tasarımı ve şartname düzenleme Hayır Evet
Örnek tabanlı işlevsel testler Sınırlı Evet, görsel test oluşturucu
Şartnameye karşı sözleşme testi Kısmen, şema kontrolleriyle Evet, özel iş akışı
Şemadan mock sunucu Hayır Evet, akıllı mock
CI test çalıştırıcısı Evet, st run Evet, apidog run
Otomatik dokümantasyon Hayır Evet

Pratik bir iş akışı şöyle kurulabilir:

  1. API şartnamesini Apidog’da tasarlayın ve güncel tutun.
  2. Apidog ile örnek tabanlı işlevsel test senaryoları oluşturun.
  3. Mock sunucu ile frontend veya entegrasyon ekiplerini bloklamadan çalıştırın.
  4. CI içinde apidog run ile işlevsel testleri çalıştırın.
  5. Aynı OpenAPI şemasını Schemathesis’e verin.
  6. CI içinde st run ile fuzzing ve sözleşme ihlali kontrollerini çalıştırın.

Örnek CI mantığı:

apidog run
st run ./openapi.yaml --url http://localhost:8000
Enter fullscreen mode Exit fullscreen mode

Bu iki katman farklı hata sınıflarını yakalar:

  • Apidog, bilinen senaryolarda API’nin doğru davranıp davranmadığını doğrular.
  • Schemathesis, beklenmeyen ama şemaya göre geçerli girdilerle API’nin dayanıklı olup olmadığını test eder.

Amacınız şemayı bir fuzzing çalıştırmasına değil, çalıştırılabilir işlevsel test koleksiyonuna dönüştürmekse, Apidog OpenAPI şartnamelerinizden doğrudan API test koleksiyonları oluşturabilir. Bu akışı denemek için Apidog’u indirebilirsiniz.

Sıkça Sorulan Sorular

Schemathesis ücretsiz mi?

Evet. Schemathesis, MIT lisansı altında açık kaynaklıdır. CLI aracı şu komutla ücretsiz kurulabilir:

pip install schemathesis
Enter fullscreen mode Exit fullscreen mode

Yerel geliştirme ortamında ve CI içinde maliyetsiz şekilde çalıştırabilirsiniz. Yönetilen bir deneyim isteyen ekipler için ticari seçenekler de bulunur, ancak çekirdek araç açık kaynaklıdır.

schemathesis run ve st run arasındaki fark nedir?

Fark yoktur. st, schemathesis komutu için kısa takma addır.

Aşağıdaki iki komut aynı işi yapar:

schemathesis run http://127.0.0.1:8000/openapi.json
Enter fullscreen mode Exit fullscreen mode 
st run http://127.0.0.1:8000/openapi.json
Enter fullscreen mode Exit fullscreen mode

İkisi de şema yolu veya URL alır ve --url, --header gibi seçeneklerle kullanılabilir.

Schemathesis işlevsel API testlerimin yerini alabilir mi?

Hayır. Schemathesis bunun için tasarlanmamıştır.

Schemathesis şunları kontrol eder:

  • API çöküyor mu?
  • Yanıt şemaya uyuyor mu?
  • Belgelenmeyen durum kodu dönüyor mu?
  • İçerik türü beklenenle eşleşiyor mu?

Ancak iş mantığını doğrulamaz. Örneğin bir indirim hesaplamasının doğru olup olmadığını veya bir yetkilendirme kuralının doğru çalışıp çalışmadığını anlamak için hâlâ örnek tabanlı işlevsel testlere ve sözleşme testine ihtiyacınız vardır.

Bu testleri Apidog’da oluşturup CI içinde çalıştırabilirsiniz. Schemathesis’i yedek değil, ek bir fuzzing katmanı olarak konumlandırın.

Schemathesis GraphQL ile çalışıyor mu?

Evet. Schemathesis hem OpenAPI hem de GraphQL şemalarını destekler. GraphQL tarafında şemanın tür tanımlarından sorgular üretir ve yanıtları kontrol eder. OpenAPI’de REST endpoint’leri için yaptığı sözleşme doğrulama yaklaşımını GraphQL şemaları için de uygular.

Sonuç

Schemathesis, OpenAPI veya GraphQL şartnamenizi alıp canlı API’nizi özellik tabanlı girdilerle test eden odaklı bir araçtır. Örnek tabanlı testlerin kaçırabileceği çökmeleri, şema ihlallerini ve belgelenmemiş davranışları bulur. CI’a eklemesi de genellikle basittir.

En pratik kurulum şudur:

pip install schemathesis
st run ./openapi.yaml --url http://localhost:8000
Enter fullscreen mode Exit fullscreen mode

Ancak Schemathesis API tasarlamaz, mock sunucu üretmez, dokümantasyon oluşturmaz ve iş mantığını doğrulamaz. Bu alanlarda Apidog tamamlayıcı rol oynar.

Şartnameyi Apidog’da tasarlayın, işlevsel testler ve mock’lar oluşturun, bunları apidog run ile CI’da çalıştırın. Ardından aynı şemayı Schemathesis ile fuzzing katmanına bağlayın. Böylece hem bilinen iş senaryolarını hem de beklenmeyen sınır durumlarını kapsayan daha sağlam bir API test süreci kurarsınız.

Bu iş akışının tasarım ve işlevsel test tarafını oluşturmak için Apidog’u indirin ve köşe durum avını Schemathesis’e bırakın.

Top comments (0)