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, yeni özellik çalışıyor ve dağıtım yapıyorsunuz. İki gün sonra bir mobil istemci çökmeye başlıyor çünkü yeniden adlandırdığınız bir alan eskiden bir dizeydi ve şimdi bir nesne. Kimse bozmak istemedi. Değişiklik yerel görünüyordu. Değildi.

API regresyon testi, bu tür hataları kimseye ulaşmadan yakalamak için mevcuttur. API'nizin bugün nasıl davrandığını açıklayan bir test paketi kaydedersiniz, ardından her değişiklikte bu paketi yeniden çalıştırırsınız. Bir yanıt şekli, durum kodu veya anahtar değeri kaydettiğinizden saparsa, paket başarısız olur ve size tam olarak nerede olduğunu söyler. Bu kılavuz, neleri temel alacağınızı, yeniden kullanılabilir bir paket nasıl oluşturacağınızı ve bir yeniden adlandırmanın asla bir olaya dönüşmemesi için onu CI'da otomatik olarak nasıl çalıştıracağınızı kapsar.

düğme

API regresyon testi nedir (ve API'ler neden geriler)

Regresyon testi, bir değişiklikten sonra mevcut davranışın hala geçerli olduğunu doğrulamak için daha önce geçen testleri yeniden çalıştırmak anlamına gelir. API'ler için "mevcut davranış", tüketicilerinizin güvendiği sözleşmedir: rotalar, durum kodları, yanıt şeması ve anahtar alanlardaki değerler.

API'ler sıradan nedenlerle geriler. Biri bir JSON alanını yeniden adlandırır. Bir yeniden düzenleme, bir 200'ü 204'e dönüştürür. Yeni bir doğrulama kuralı, eskiden kabul edilen girdiyi reddeder. Bir ORM yükseltmesi, tarih biçimlendirmesini sessizce değiştirir. Bir bağımlılık yükseltmesi, bir istemcinin ayrıştırdığı bir hata mesajını değiştirir. Bunların hiçbiri derleme hatası olarak görünmez. Bunlar, bozuk entegrasyonlar olarak görünür ve genellikle yalnızca çağrı yapanların bir alt kümesi için geçerlidir.

Burada önemli olan ayrım: API regresyon testi, genel yazılım regresyon testinden daha dardır. Uygulamanın tamamındaki iş mantığını yeniden doğrulamıyorsunuz. HTTP yüzeyinin, diğer sistemlerin bağlandığı kısmın hareket etmediğini kontrol ediyorsunuz. Bu odak, onu her taahhütte çalıştırmayı ucuz yapan şeydir.

Neleri temel almalı

Bir regresyon paketi, yalnızca iddia ettiği şeyler kadar iyidir. Çok az şey iddia ederseniz, gerçek kırılmalar gözden kaçar. Çok fazla şey iddia ederseniz, her kasıtlı değişiklik paketi kırmızıya çevirir. Bir tüketicinin gerçekten fark edeceği alanları hedefleyin.

Bu dört katmanı temel alın:

Durum kodları. Her uç nokta, bilinen girdiler için bilinen bir durum döndürmelidir. Bir 200'ün 500'e dönüşmesi veya bir 201'in 200'e dönüşmesi, gövde iyi görünse bile bir regresyondur.
Yanıt şeması. Yanıtın yapısı ve türleri. Alan adları, iç içe geçme ve bir değerin dize, sayı, dizi veya nesne olup olmadığı. Şema kayması, en yaygın sessiz kırılmadır.
Anahtar alan değerleri. Her değer değil, ancak sözleşme anlamı taşıyanlar: mevcut olması gereken bir id, bilinen bir küme içinde kalması gereken bir status enum'u, bir sayı olması gereken bir total.
Sözleşmeler. OpenAPI spesifikasyonunuz ile canlı yanıt arasındaki ilişki. Spesifikasyon email'in gerekli olduğunu söylüyor ve API bunu döndürmeyi durduruyorsa, bu bir sözleşme ihlalidir. Spesifikasyonu doğruluk kaynağı haline getirmek için API sözleşme testi bölümüne bakın.

Faydalı bir kural: bir istemcinin neyin üzerinde bozulacağını iddia edin, bugün yükte ne olduğuna değil. Bir createdAt zaman damgası her istekte değişir, bu nedenle değerini değil, türünü ve biçimini sabitleyin.

İşte tek bir uç nokta için minimal bir iddia kümesi, bir yanıta karşı çalıştıracağınız düz kontroller olarak yazılmış:

GET /v1/users/42  ->  200
  body.id            is present, type number
  body.email         is present, type string, matches email format
  body.status        is one of ["active", "pending", "suspended"]
  body.roles         type array
  response time      < 800 ms

Bu beş satır sözleşmeyi açıklar. Bir değişiklikten sonra herhangi biri başarısız olursa, bir regresyonunuz var demektir. Yanıt gövdelerine karşı kontroller yazma hakkında daha derinlemesine bilgi için API iddiaları bölümüne bakın.

Manuel ve otomatik regresyon testi

Regresyon testini elle yapabilirsiniz. Bir değişiklikten sonra API istemcinizi açar, bir avuç kayıtlı isteği yeniden oynatırsınız ve yanıtları gözden geçirirsiniz. Bu, bir uç nokta için işe yarar ve on uç noktada dağılır. İnsanlar sıkıcı durumları atlar ve regresyonlar sıkıcı durumlarda saklanır. Manuel kontroller, planlanmış bir iş bağımlılık güncellemesini birleştirdiğinde sabah 2'de de çalışamaz.

Otomatik regresyon testi, döngüden insanı çıkarır. Paketi bir kez kaydedersiniz, ardından bir makine her itme, her çekme isteği ve her dağıtımda yeniden çalıştırır. Değer, tek bir çalıştırmadaki hız değildir. Paket her seferinde, kimsenin buna değip değmeyeceğine karar vermesine gerek kalmadan çalışmasıdır.

Değiş tokuş, ön çalışma maliyetidir. Paketi oluşturmanız ve güncel tutmanız gerekir. Bu bakım maliyeti gerçektir, ancak beş saniyelik bir testin yakalayacağı bir üretim olayının maliyetinden daha küçüktür.

	Manuel	Otomatik
Her değişiklikte çalışır	Hayır, disipline bağlıdır	Evet, varsayılan olarak
Kapsam	Birkaç uç nokta	Tüm paket
Çalıştırma başına maliyet	İnsan zamanı dakikaları	Hesaplama saniyeleri
Sabah 2'deki kırılmaları yakalar	Hayır	Evet
Ön çaba	Düşük	Orta

Bir oyuncak projenin ötesindeki her şey için onu otomatikleştirin.

Yeniden kullanılabilir bir regresyon paketi oluşturma

Bir regresyon paketi, her biri iddialar içeren, birlikte çalıştırılabilmeleri için gruplandırılmış bir dizi kayıtlı istektir. Amaç yeniden kullanımdır: bir kez inşa edin, sonsuza kadar çalıştırın, uç noktalar eklediğinizde genişletin.

Paketi değişikliğe dayanacak şekilde yapılandırın:

Özelliğe göre değil, kaynağa göre gruplandırın. Tüm /users testlerini bir araya, tüm /orders testlerini bir araya getirin. Kullanıcı hizmetine dokunduğunuzda, hangi grubu izleyeceğinizi bilirsiniz.

Değişen her şey için ortam değişkenlerini kullanın. Temel URL, kimlik doğrulama belirteçleri ve kiracı kimlikleri her istekte sabit kodlanmamalı, bir ortama ait olmalıdır. Bu, aynı paketin tek bir ayarı değiştirerek yerel, hazırlık ve üretim ortamlarına karşı çalışmasına olanak tanır.

Birbirine bağımlı istekleri zincirleyin. Gerçekçi bir akış, bir kaynak oluşturur, onu geri okur, günceller ve siler. Oluşturma yanıtından id'yi çıkarın ve bir sonraki isteğe iletin. Bu, yalnızca bir dizi boyunca ortaya çıkan, izole olarak değil, regresyonları yakalar. Burası regresyon testinin API entegrasyon testi ile örtüştüğü yerdir.

Uç durumları verilerle yönetin. On adet neredeyse aynı istek yerine, bir istek yazın ve ona bir girdi tablosu besleyin: geçerli değerler, boş değerler, sınır değerleri ve bilinen-kötü değerler. Her satır bir test durumu haline gelir. Veri odaklı testler, kapsama alanını genişletirken paketi küçük tutar.

İşte tek bir doğrulama testi için bir veri tablosunun CSV olarak nasıl görünebileceği:

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

Tek bir istek, beş durum, durum kodu üzerinde beş iddia. Yeni bir uç durum bulduğunuzda bir satır ekleyin ve paket yeni kod olmadan büyür.

Paketi hızlı tutun. Yirmi dakika süren bir regresyon paketi atlanır. Yavaş üçüncü taraf bağımlılıklarını taklit edin, aracınız izin veriyorsa bağımsız istekleri paralel olarak çalıştırın ve tam uçtan uca akışları daha küçük, daha yavaş bir gece çalıştırmasına ayırın.

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

Dizüstü bilgisayarınızda yaşayan bir regresyon paketi yalnızca dizüstü bilgisayarınızı korur. Amaç, sürekli entegrasyonda, bir regresyonu tetikleyebilecek aynı olaylar üzerinde çalıştırmaktır: çekme istekleri ve ana dalınıza yapılan birleştirmeler.

Desen, CI sistemlerinde aynıdır. Başsız bir çalıştırıcı kurun, onu kayıtlı paketinize yönlendirin ve herhangi bir iddia başarısız olursa yapıyı başarısız edin. Apidog, tam olarak bunun için bir komut satırı çalıştırıcısı sunar. Node ile kurun:

npm install -g apidog-cli

Ardından kayıtlı bir test senaryosunu veya paketini kimliğiyle, seçilen bir ortama karşı çalıştırın ve raporlar oluşturun:

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

Bunu ayrıştıralım:

--access-token çalıştırmayı doğrular. Belirteci bir CI sırrı olarak depolayın, asla depoda değil.
-t çalıştırılacak senaryonun, klasörün veya paketin kimliğidir.
-e ortam kimliğidir, böylece aynı paket tek bir değeri değiştirerek hazırlık veya üretim ortamını hedefleyebilir.
-r rapor biçimlerini listeler. cli konsola yazdırır, html okunabilir bir rapor üretir ve junit, CI'nizin test başına geçiş/başarısızlığı göstermek için ayrıştırabileceği XML'i yayar.

Çalıştırıcı başsızdır. Node çalıştırabilen herhangi bir CI adımına uyar, bu nedenle aynı komut GitHub Actions, GitLab CI, Jenkins veya CircleCI'da çalışır. İşte her çekme isteğinde paketi çalıştıran bir GitHub Actions işi:

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 }}

Bir senaryo başarısız olduğunda, çalıştırıcı sıfır olmayan bir kodla çıkar ve iş kırmızıya döner. Çekme isteği, biri bakana kadar engellenir. Tam bir kopyala-yapıştır işlem hattı ve daha fazla CI deseni için CI/CD için Apidog CLI ve GitHub Actions'ta API testlerini otomatikleştirme bölümüne bakın.

Pakete bir veri dosyası beslerseniz, -d ile geçirin:

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

Kendi API sürümüne sahip bir özellik dalını mı test ediyorsunuz? Varsayılan yerine o dalın kayıtlı paketine karşı çalıştırmak için --branch ekleyin. Bulutta çalıştırma geçmişini tutmak için yalın --upload-report bayrağını ekleyin.

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

İddialar, davranışlardaki regresyonları yakalar. Şema farklandırması, bunları tanımda, genellikle dağıtımdan önce yakalar.

Fikir: OpenAPI spesifikasyonunuz deponuzda sürümü olan bir dosyadır. Biri onu düzenlediğinde, yeni spesifikasyonu öncekiyle karşılaştırırsınız ve değişikliği sınıflandırırsınız. İsteğe bağlı bir alan eklemek güvenlidir. Bir alanı kaldırmak, yeniden adlandırmak, bir türü sıkılaştırmak veya isteğe bağlı bir alanı zorunlu kılmak bozucu bir değişikliktir. Bir farklandırma aracı, bozucu olanları çekme isteğinde işaretleyebilir, böylece inceleyen kişi bir YAML duvarı yerine "bu user.phone'u kaldırır" ifadesini görür.

Bunu canlı API'ye karşı sözleşme testi ile eşleştirin. Her çalıştırmada, gerçek yanıtları mevcut şemaya göre doğrulayın. Eğer spesifikasyon API'nin artık döndürmediği bir alan vaat ediyorsa veya API spesifikasyonun yasakladığı bir tür döndürüyorsa, kontrol başarısız olur. Bu iki taraflı korumadır: spesifikasyon farkı, sözleşmedeki kasıtlı düzenlemeleri yakalar ve sözleşme testi, kodun sözleşmeden uzaklaşmasını yakalar.

Bozucu değişiklikler her zaman hata değildir. Bazen bir alanı kaldırmak istersiniz. Farklandırmanın amacı, bu kararı açık hale getirmek ve bir müşteriyi şaşırtmak yerine sürümleme ve kullanımdan kaldırma sürecinizden geçirmektir. Bilerek yaptığınız değişiklikleri yönetmek için API'leri ölçekte sürümleme ve kullanımdan kaldırma stratejisi bölümüne bakın.

Apidog regresyon paketlerini nasıl çalıştırır

Apidog, yukarıda açıklanan parçaları tek bir yerde kapsar, bu da paketi ve spesifikasyonu yan yana tutar.

Test senaryolarını görsel olarak oluşturursunuz: istekleri zincirleyin, bir yanıttaki değerleri bir sonraki yanıta çıkarın ve durum, şema ve alan değerleri üzerinde iddialar ekleyin. API tasarımı ve testleri aynı projede yer aldığından, yanıtları uç noktanın kayıtlı şemasına karşı şemayı iki kez yazmadan doğrulayabilirsiniz. Tasarım değiştiğinde, testlerin kontrol ettiği şema da değişir.

Veri odaklı durumlar için, bir senaryoya bir CSV veya JSON veri kümesi ekleyin ve Apidog satır başına bir durum çalıştırır. İlişkili senaryoları bir test paketine kaydedin, böylece tek bir çalıştırma tüm bir kaynağı veya akışı çalıştırır.

apidog-cli çalıştırıcısı, bu kayıtlı paketleri yukarıda gösterildiği gibi başsız olarak CI'ya götürür. Kayıtlı senaryoları ve paketleri çalıştırır. Etkileşimli bir istek göndericisi değildir ve bir yük üreteci değildir. Tek bir iş yapar: regresyon paketinizi yeniden oynatır ve geçenleri raporlar. Bu dar kapsam, onu Node uyumlu herhangi bir CI adımına yerleştirmesini sağlar. CLI ve betiklenmiş bir iş akışı için Apidog CLI CI/CD işlem hattı kılavuzuna bakın.

Başlangıç iş akışı

İşte test stratejinizi yeniden inşa etmeden bu hafta benimseyebileceğiniz bir dizi:

En çok çağrılan beş uç noktanızı seçin. Regresyon riski, trafiğin yoğun olduğu yerlerde yoğunlaşır. Oradan başlayın.
Her uç nokta için iddialarla birlikte bir istek kaydedin. Durum kodu, yanıt şeması ve her biri iki veya üç anahtar alan. Bu sizin temelinizdir.
Bir zincirleme akış ekleyin. Temel kaynağınız üzerinde oluştur, oku, güncelle, sil. Bu, izole testlerin kaçırdığı çapraz istek regresyonlarını yakalar.
Bir doğrulama ağırlıklı uç noktaya bir veri tablosu ekleyin. Bir avuç geçerli, boş ve hatalı girdi.
Çekme isteklerinde bunu CI'ya bağlayın. apidog-cli'yi yükleyin, paketi -r junit ile çalıştırın ve başarısızlık durumunda birleştirmeleri engelleyin.
Bir hata kaçtığında paketi büyütün. Her sızan üretim regresyonu yeni bir test durumu haline gelir. Paket kendi kaçırdıklarından güçlenir.

Birinci ila dördüncü adımlar bir öğleden sonra. Beşinci adım tek bir CI dosyasıdır. Bundan sonra, paket kendi kendine çalışır ve onu yalnızca gerçeklik size yeni bir hata modu öğrettiğinde genişletirsiniz. Bu geri bildirim döngüsü tüm amaçtır: bir olay olabilecek bir yeniden adlandırma, bir çekme isteğinde kırmızı bir kontrol haline gelir.

SSS

API regresyon testi, genel regresyon testinden nasıl farklıdır? Genel regresyon testi, UI ve iş mantığı dahil olmak üzere tüm sistemdeki uygulama davranışını yeniden doğrular. API regresyon testi bunu HTTP yüzeyine daraltır: rotalar, durum kodları, yanıt şeması ve anahtar alan değerleri. Dar odak, her taahhütte çalışacak kadar hızlı olmasını sağlar ve diğer sistemlerin tam olarak neye bağlandığını hedefler.

Regresyon paketini ne sıklıkla çalıştırmalıyım? API'yi etkileyebilecek her değişiklikte. Pratikte bu, her çekme isteği ve ana dalınıza yapılan her birleştirme anlamına gelir ve CI'da otomatik olarak çalıştırılır. Çekme istekleri için hızlı bir çekirdek paket ve gece derlemeleri için daha büyük bir uçtan uca çalıştırma tutun, böylece taahhüt başına kontrol hızlı kalır.

Kırılgan bir paketten kaçınmak için neye iddia etmeliyim? Bir tüketicinin neyin üzerinde bozulacağını iddia edin. Durum kodlarını, yanıt yapısını ve türlerini ve kimlikler ve durum enum'ları gibi sözleşme anlamı taşıyan alanların değerlerini sabitleyin. Zaman damgaları gibi her istekte değişen değerler için, değişmez değere değil, tür ve biçime iddia edin. Uçucu veriler üzerinde aşırı iddia etmek, yanlış başarısızlıkların ana nedenidir.

Kod yazmadan API regresyon testleri çalıştırabilir miyim? Evet. Apidog gibi araçlar, senaryoları ve iddiaları görsel olarak oluşturmanıza, ardından bunları apidog-cli ile CI'da başsız olarak çalıştırmanıza olanak tanır. Paketi arayüz aracılığıyla bir kez kaydedersiniz ve komut satırı çalıştırıcısı onu işlem hattınızda yeniden oynatır, böylece testler elle yazılmış bir test donanımı olmadan otomatik olarak çalışır.

Kasıtlı bozucu değişiklikleri nasıl ele alırım? Bunları sürpriz test başarısızlıkları olarak yüzeye çıkarmalarına izin vermek yerine, sürümleme ve kullanımdan kaldırma sürecinizden geçirin. Değişikliği incelemede işaretlemek için şema farklandırması kullanın, uç noktayı sürümlendirin veya alanı önce isteğe bağlı olarak ekleyin ve değişiklik amaçlandığında ve tüketicilere bildirildiğinde regresyon temelini kasıtlı olarak güncelleyin.