DEV Community

Cover image for API Regresyon Testi: Kırıcı Değişiklikleri Nasıl Erken Tespit Edersiniz
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

API Regresyon Testi: Kırıcı Değişiklikleri Nasıl Erken Tespit Edersiniz

Bir uç noktaya küçük bir değişiklik gönderiyorsunuz. Kod derleniyor, özellik çalışıyor ve dağıtım yapıyorsunuz. İki gün sonra bir mobil istemci çökmeye başlıyor: yeniden adlandırdığınız alan eskiden string idi, şimdi object. Değişiklik yerel görünüyordu; aslında API sözleşmesini bozdu.

Apidog'u bugün deneyin

API regresyon testi bu tür hataları kullanıcıya ulaşmadan yakalamak için kullanılır. API’nizin bugünkü davranışını test paketi olarak kaydedersiniz; her değişiklikte aynı paketi tekrar çalıştırırsınız. Yanıt şekli, durum kodu veya kritik alan değeri beklenenden saparsa paket başarısız olur ve kırılmanın nerede olduğunu gösterir.

Bu yazıda şunları uygulamalı olarak ele alacağız:

  • Hangi API davranışlarını baseline olarak sabitlemelisiniz?
  • Yeniden kullanılabilir regresyon paketi nasıl tasarlanır?
  • Testler CI’da her pull request için nasıl otomatik çalıştırılır?
  • Şema ve sözleşme farkları dağıtımdan önce nasıl yakalanır?

API regresyon testi nedir?

Regresyon testi, bir değişiklikten sonra daha önce çalışan davranışın hâlâ çalıştığını doğrulamaktır.

API tarafında bu davranış, tüketicilerin bağlı olduğu HTTP sözleşmesidir:

  • Route’lar
  • HTTP durum kodları
  • Yanıt şeması
  • Alan adları ve veri tipleri
  • Kritik alan değerleri
  • OpenAPI sözleşmesi

API’ler genellikle şu küçük görünen değişikliklerle geriler:

  • JSON alanı yeniden adlandırılır.
  • 200 yerine 204 dönmeye başlanır.
  • Yeni validasyon kuralı eski girdiyi reddeder.
  • ORM güncellemesi tarih formatını değiştirir.
  • Bağımlılık güncellemesi hata mesajı formatını değiştirir.

Bunların çoğu derleme hatası üretmez. Hata, entegrasyon bozulduğunda ortaya çıkar.

API regresyon testi, tüm uygulama davranışını değil, HTTP yüzeyini test eder. Bu yüzden hızlıdır ve her commit veya pull request üzerinde çalıştırılabilir.

Neleri baseline olarak sabitlemelisiniz?

Regresyon paketi yalnızca iddia ettiği davranışları korur. Çok az iddia yazarsanız kırılmalar kaçar. Çok fazla iddia yazarsanız her kasıtlı değişiklik paketi kırmızıya döner.

Odaklanmanız gereken şey: istemcinin bozulmasına neden olacak davranışlar.

1. Durum kodları

Her uç nokta bilinen girdiler için beklenen status code’u dönmelidir.

Örnek:

POST /v1/users -> 201
GET /v1/users/42 -> 200
GET /v1/users/unknown -> 404
POST /v1/users invalid-body -> 422
Enter fullscreen mode Exit fullscreen mode

Bir 201 yanıtının 200’e dönüşmesi bile istemci davranışını etkileyebilir.

2. Yanıt şeması

Alan adları, iç içe yapı ve veri tipleri sabitlenmelidir.

Örnek kırıcı değişiklikler:

{
  "id": 42,
  "email": "alice@example.com"
}
Enter fullscreen mode Exit fullscreen mode

şundan buna dönüşürse:

{
  "id": 42,
  "contact": {
    "email": "alice@example.com"
  }
}
Enter fullscreen mode Exit fullscreen mode

istemci body.email bekliyorsa kırılır.

3. Kritik alan değerleri

Her alanı sabitlemeyin. Sözleşme anlamı taşıyan alanları sabitleyin:

  • id mevcut olmalı.
  • status bilinen enum içinde olmalı.
  • total sayı olmalı.
  • email string ve email formatında olmalı.

Örnek minimal kontrol seti:

GET /v1/users/42 -> 200

body.id       exists, type number
body.email    exists, type string, email format
body.status   one of ["active", "pending", "suspended"]
body.roles    type array
response time < 800 ms
Enter fullscreen mode Exit fullscreen mode

Bu kontroller tüketicinin gerçekten bağlı olduğu davranışı kapsar.

Daha fazla örnek için API iddiaları rehberine bakabilirsiniz.

4. OpenAPI sözleşmesi

OpenAPI spesifikasyonunuz email alanını zorunlu gösteriyor ama canlı API artık email döndürmüyorsa bu bir sözleşme ihlalidir.

Bu yüzden regresyon testini sözleşme testiyle birlikte kullanmak daha güçlüdür. Konu için API sözleşme testi yazısına bakabilirsiniz.

Manuel test mi, otomatik test mi?

Manuel regresyon testi küçük kapsamda işe yarar:

  1. API istemcisini açarsınız.
  2. Kayıtlı birkaç isteği çalıştırırsınız.
  3. Yanıtları gözle kontrol edersiniz.

Ancak bu yaklaşım hızla dağılır:

  • İnsanlar sıkıcı edge case’leri atlar.
  • Her pull request’te aynı dikkat korunamaz.
  • Gece çalışan bağımlılık güncellemeleri yakalanamaz.
  • Kapsam arttıkça maliyet artar.

Otomatik regresyon testinde paket bir kez oluşturulur, sonra her değişiklikte makine tarafından çalıştırılır.

Kriter Manuel Otomatik
Her değişiklikte çalışır Hayır, disipline bağlıdır Evet
Kapsam Birkaç uç nokta Tüm paket
Çalıştırma maliyeti İnsan zamanı CI zamanı
Gece kırılmalarını yakalar Hayır Evet
Başlangıç eforu Düşük Orta

Oyuncak proje dışında regresyon testini otomatikleştirin.

Yeniden kullanılabilir regresyon paketi oluşturma

Bir regresyon paketi; kayıtlı istekler, veri setleri ve iddialardan oluşur. Amaç, aynı paketi farklı ortamlarda tekrar tekrar çalıştırmaktır.

1. Testleri kaynağa göre gruplayın

Özellik adına göre değil, API kaynağına göre gruplayın:

/users
/orders
/payments
/auth
Enter fullscreen mode Exit fullscreen mode

Böylece /users tarafında değişiklik yaptığınızda hangi test grubunun kritik olduğunu bilirsiniz.

2. Ortam değişkenleri kullanın

Base URL, token ve tenant ID gibi değerleri isteklere gömmeyin.

Kötü:

https://staging.example.com/v1/users
Authorization: Bearer hardcoded-token
Enter fullscreen mode Exit fullscreen mode

İyi:

{{baseUrl}}/v1/users
Authorization: Bearer {{accessToken}}
Enter fullscreen mode Exit fullscreen mode

Bu sayede aynı paket şu ortamlarda çalışabilir:

  • Local
  • Staging
  • Production smoke test

Sadece ortam değerlerini değiştirirsiniz.

3. Bağımlı istekleri zincirleyin

Gerçekçi bir akış genellikle tek istekten oluşmaz.

Örnek CRUD akışı:

POST /v1/users
  -> response.body.id değerini userId olarak kaydet

GET /v1/users/{{userId}}
  -> userId ile oluşturulan kullanıcıyı oku

PATCH /v1/users/{{userId}}
  -> kullanıcıyı güncelle

DELETE /v1/users/{{userId}}
  -> kullanıcıyı sil
Enter fullscreen mode Exit fullscreen mode

Bu akış, tekil isteklerin yakalayamayacağı regresyonları yakalar. Bu nokta regresyon testinin API entegrasyon testi ile kesiştiği yerdir.

4. Edge case’leri veriyle yönetin

Aynı isteği farklı girdilerle test etmek için veri dosyası kullanın.

Örnek CSV:

email,expectedStatus
alice@example.com,201
bob@test.co,201
not-an-email,422
,422
a@b,422
Enter fullscreen mode Exit fullscreen mode

Tek istek, beş test durumu üretir.

Her satır için şu iddia çalışır:

response.status == expectedStatus
Enter fullscreen mode Exit fullscreen mode

Yeni bir edge case bulduğunuzda yeni test yazmak yerine CSV’ye satır eklersiniz.

5. Paketi hızlı tutun

CI’da 20 dakika süren regresyon paketi zamanla atlanır.

Pratik kurallar:

  • Pull request için hızlı çekirdek paket çalıştırın.
  • Uzun uçtan uca akışları gece çalıştırın.
  • Bağımsız istekleri paralel çalıştırın.
  • Yavaş üçüncü taraf sistemleri mock veya sandbox ile izole edin.
  • Uçucu alanlara aşırı iddia yazmayın.

CI’da her değişiklikte çalıştırma

Regresyon paketi sadece lokal makinenizde çalışıyorsa sadece sizi korur. Asıl değer, paketin CI’da otomatik çalışmasıdır.

Temel akış:

  1. Headless test runner kurulur.
  2. Kayıtlı regresyon paketi çalıştırılır.
  3. Herhangi bir iddia başarısız olursa CI job kırmızıya döner.
  4. Pull request merge edilmez.

Apidog CLI bu iş için kullanılabilir.

Kurulum:

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

Kayıtlı senaryo veya paketi çalıştırma:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t 123456 \
  -e 789012 \
  -r cli,html,junit
Enter fullscreen mode Exit fullscreen mode

Parametreler:

  • --access-token: Apidog erişim token’ı. CI secret olarak saklayın.
  • -t: Çalıştırılacak senaryo, klasör veya paket ID’si.
  • -e: Ortam ID’si.
  • -r: Rapor formatları. cli, html, junit kullanılabilir.

junit çıktısı CI sistemlerinin test sonucu olarak okuyabileceği XML üretir.

GitHub Actions örneği

Aşağıdaki workflow her pull request’te API regresyon paketini çalıştırır:

name: API Regression

on: [pull_request]

jobs:
  regression:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v6

      - uses: actions/setup-node@v6
        with:
          node-version: '22'

      - run: npm install -g apidog-cli

      - run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 123456 \
            -e 789012 \
            -r cli,junit
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
Enter fullscreen mode Exit fullscreen mode

Bir test başarısız olursa apidog run sıfır olmayan exit code döner. GitHub Actions job kırmızı olur ve pull request bloklanır.

Daha kapsamlı CI örnekleri için:

Veri dosyasıyla çalıştırma

Test senaryonuz veri dosyası kullanıyorsa -d parametresiyle geçirin:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t 123456 \
  -e 789012 \
  -d ./test-data/emails.csv \
  -r cli,junit
Enter fullscreen mode Exit fullscreen mode

Özellik dalındaki API sürümünü test ediyorsanız kayıtlı branch’i kullanmak için --branch ekleyebilirsiniz.

Rapor geçmişini bulutta tutmak için:

--upload-report
Enter fullscreen mode Exit fullscreen mode

bayrağını kullanabilirsiniz.

Şema ve sözleşme farklandırması

İddialar canlı davranıştaki regresyonları yakalar. Şema farklandırması ise bozulmayı genellikle dağıtımdan önce yakalar.

Önerilen yaklaşım:

  1. OpenAPI dosyasını repoda version control altında tutun.
  2. Pull request’te yeni şemayı önceki şemayla karşılaştırın.
  3. Değişiklikleri sınıflandırın:
    • Güvenli değişiklik
    • Potansiyel kırıcı değişiklik
    • Kesin kırıcı değişiklik
  4. Kırıcı değişiklik varsa incelemede görünür yapın.

Kırıcı değişiklik örnekleri:

  • Alan kaldırmak
  • Alan yeniden adlandırmak
  • Tipi değiştirmek
  • Opsiyonel alanı zorunlu yapmak
  • Enum değerini kaldırmak

Örnek:

User:
  required:
    - id
    - email
Enter fullscreen mode Exit fullscreen mode

Eğer email artık yanıtta yoksa bu sözleşme ihlalidir.

Bunu canlı API sözleşme testiyle birleştirin:

  • Spesifikasyonun vaat ettiği alanlar gerçekten dönüyor mu?
  • API, spesifikasyonun yasakladığı tipte veri dönüyor mu?
  • Zorunlu alanlar eksiksiz mi?
  • Enum değerleri sözleşmeye uygun mu?

Kırıcı değişiklikler her zaman hata değildir. Bazen bilinçli olarak endpoint veya alan değiştirmek istersiniz. Bu durumda değişikliği sürümleme ve kullanımdan kaldırma sürecinden geçirin. Detay için API’leri ölçekte sürümleme ve kullanımdan kaldırma stratejisi yazısına bakabilirsiniz.

Apidog ile regresyon paketi çalıştırma

Apidog, API tasarımı, test senaryoları, veri setleri ve CI çalıştırmasını aynı akışta toplar.

Uygulama akışı:

  1. API isteklerini senaryo olarak kaydedin.
  2. Yanıttan değer çıkarıp sonraki istekte kullanın.
  3. Status code, şema ve alan değerleri için iddialar ekleyin.
  4. CSV veya JSON veri seti bağlayın.
  5. İlgili senaryoları test paketi altında gruplayın.
  6. apidog-cli ile CI’da headless çalıştırın.

Örnek senaryo:

POST /users
  assert status == 201
  save body.id as userId

GET /users/{{userId}}
  assert status == 200
  assert body.id == {{userId}}
  assert body.email is string

PATCH /users/{{userId}}
  assert status == 200

DELETE /users/{{userId}}
  assert status == 204
Enter fullscreen mode Exit fullscreen mode

Apidog’da API tasarımı ve testler aynı projede bulunduğu için yanıtları kayıtlı şemaya karşı doğrulayabilirsiniz. Şemayı test içinde ayrıca tekrar yazmanız gerekmez.

apidog-cli etkileşimli istek gönderici veya yük testi aracı değildir. Görevi nettir: kayıtlı test senaryolarını ve paketleri headless olarak çalıştırır, sonucu raporlar.

CLI iş akışı için Apidog CLI CI/CD işlem hattı kılavuzuna bakabilirsiniz.

Bu hafta uygulanabilir başlangıç planı

Sıfırdan büyük bir test stratejisi kurmanız gerekmez. Aşağıdaki küçük planla başlayın.

  1. En çok çağrılan beş endpoint’i seçin.

    Regresyon riski genellikle trafiğin yoğun olduğu yerde daha kritiktir.

  2. Her endpoint için bir istek ve temel iddialar ekleyin.

    Minimum olarak status code, yanıt şeması ve 2-3 kritik alanı kontrol edin.

  3. Bir zincirleme akış oluşturun.

    Örneğin create-read-update-delete akışı.

  4. Validasyon ağırlıklı bir endpoint’e veri tablosu ekleyin.

    Geçerli, boş, sınır ve hatalı girdileri kapsayın.

  5. Paketi CI’a bağlayın.

    apidog-cli kurun, paketi -r junit ile çalıştırın, başarısızlıkta merge’i engelleyin.

  6. Kaçan her hatayı yeni test yapın.

    Üretime kaçan her regresyon, regresyon paketine yeni bir test durumu olarak eklenmelidir.

Bu döngü zamanla paketi güçlendirir. Amaç, üretim olayı olabilecek bir alan değişikliğini pull request üzerinde kırmızı kontrole dönüştürmektir.

SSS

API regresyon testi genel regresyon testinden nasıl farklıdır?

Genel regresyon testi UI, iş mantığı ve sistem davranışını kapsar. API regresyon testi HTTP yüzeyine odaklanır: route’lar, status code’lar, yanıt şeması ve kritik alan değerleri. Bu dar kapsam, testlerin her commit’te çalışacak kadar hızlı olmasını sağlar.

Regresyon paketini ne sıklıkla çalıştırmalıyım?

API’yi etkileyebilecek her değişiklikte çalıştırmalısınız. Pratikte bu, her pull request ve ana dala yapılan her merge anlamına gelir. Hızlı çekirdek paketi PR’da, daha büyük uçtan uca paketi gece çalıştırabilirsiniz.

Kırılgan testlerden kaçınmak için neye iddia yazmalıyım?

İstemcinin gerçekten bağlı olduğu davranışlara iddia yazın:

  • Status code
  • Yanıt yapısı
  • Veri tipleri
  • Kritik enum değerleri
  • Zorunlu alanlar

Timestamp gibi her istekte değişen alanlarda sabit değere değil, tip ve formata iddia yazın.

Kod yazmadan API regresyon testi çalıştırabilir miyim?

Evet. Apidog gibi araçlarla senaryoları ve iddiaları görsel olarak oluşturabilir, sonra apidog-cli ile CI’da headless çalıştırabilirsiniz. Böylece test paketi manuel test aracı olmaktan çıkıp otomatik pipeline kontrolüne dönüşür.

Kasıtlı kırıcı değişiklikleri nasıl yönetmeliyim?

Kasıtlı kırıcı değişiklikleri sessizce üretime göndermeyin. Şema farklandırmasıyla pull request’te görünür yapın, sürümleme veya kullanımdan kaldırma sürecinden geçirin ve tüketiciler bilgilendirildikten sonra regresyon baseline’ını bilinçli olarak güncelleyin.

Top comments (0)