Blog

Playwright Testlerinde API Cevapları Nasıl Doğrulanır?

Ashley Innocent

Ashley Innocent

12 May 2026

Playwright Testlerinde API Cevapları Nasıl Doğrulanır?

Playwright testleriniz geçiyor. Giriş butonu tıklanıyor, kontrol paneli render ediliyor, grafik çiziliyor. Sonra bir müşteri bir hata bildiriyor: grafik sayıları yanlış. Sorunu araştırıyorsunuz ve API'nin bozuk bir yük (payload) ile 200 durum kodu döndürdüğünü, ancak uçtan uca (end-to-end) test paketinizin bunu asla fark etmediğini görüyorsunuz çünkü yalnızca piksellerin ekranda göründüğünü kontrol etmiş. Bu, yalnızca tarayıcı testlerinin kapatamayacağı bir boşluktur ve API doğrulamalarının vazgeçilmez hale geldiği noktadır. Apidog gibi araçlar, API sözleşmelerini, şemalarını ve yanıt semantiğini UI akışlarınıza gösterdiğiniz titizlikle doğrulamanın bir yolunu sunar, ardından her iki paketi de CI'da birlikte çalıştırabilirsiniz.

düğme

TL;DR

Playwright testlerinde API'ları, Playwright'ın request fixture'ı ve page.route engelleyicisini, aynı OpenAPI belirtimini kullanan Apidog senaryolarıyla birleştirerek doğrulayabilirsiniz. Fixture'ları tek bir belirtim dosyası aracılığıyla paylaşın, her iki katmanda da yanıt şemalarını onaylayın ve bir sözleşme değişikliğinin her iki yerde de hızlıca başarısız olmasını sağlamak için her iki paketi tek bir CI işinde çalıştırın.

Giriş

Playwright, 2026'da birçok ekip için varsayılan tarayıcı otomasyon çerçevesidir ve Playwright dokümantasyonu API testini kolay gösterir: birkaç request.get çağrısı, bir expect(response.status()).toBe(200) ve işiniz biter. Sorun, bunu ölçeklendirdiğinizde başlar. Sonuç olarak, durum kodlarını kontrol eden ancak yanıt şeklini kontrol etmeyen yüzlerce testiniz olur, tarayıcı akışlarınız ile API akışlarınız arasında paylaşılan bir doğruluk kaynağı olmaz ve arka uç yavaş veya bozuk olduğunda API'ları çevrimdışı taklit etmenin (mock) bir yolu olmaz.

Çözüm basittir. OpenAPI belirtiminizi sözleşme olarak ele alın, Playwright request çağrılarını ve page.route engelleyicilerini bu sözleşmeden türetin ve derin şema, iş mantığı ve zincirleme istek doğrulaması için aynı belirtime karşı bir Apidog senaryo paketi çalıştırın. CI'da hızlı geri bildirim, ön uç ve arka uç testleri arasında net sahiplik sınırları ve sıfır yinelenen fixture elde edersiniz. Aracı önce kurmak isterseniz, Apidog'u İndirin ve geri gelin; aşağıdaki adımlar aracın yerel olarak mevcut olduğunu varsayar.

Bu yazıdan elde edecekleriniz şunlardır: Playwright paketinde API doğrulamalarının nereye ait olduğuna dair net bir zihinsel model, çalışan bir request.fixture deseni, Playwright ve Apidog arasında fixture'ları paylaşmak için adım adım bir kurulum, CI ve mocking için ileri düzey ipuçları ve ana alternatiflerin karşılaştırma tablosu. Test araçları seçimleri hakkında daha geniş bir bağlam için, QA mühendisleri için API test araçları hakkındaki görüşümüze bakın.

Playwright testleri ve API doğrulamaları arasındaki boşluk

Tipik bir Playwright testi oturum açar, bir sayfaya gider ve bir UI öğesinin görünür olduğunu doğrular. Bu size kullanıcı tarafından görülen akışın çalıştığını söyler. Arkasındaki API hakkında size hiçbir şey söylemez. Üç hata modu gözden kaçar:

Bunun bir kısmını, Playwright belirtimlerinize request.get çağrıları ekleyerek ve yanıt gövdelerini doğrulayarak düzeltebilirsiniz. Bu, birkaç uç nokta için işe yarar. Ancak 200 uç noktanız olduğunda ve “sipariş oluştur, siparişi getir, siparişi iptal et, geri ödeme webhook'unu doğrula” gibi zincirleme senaryolar istediğinizde işler karışır. Playwright öncelikle bir tarayıcı otomasyon çerçevesidir; durum bilgisi olan API iş akışları veya şema düzeyinde doğrulama ergonomisi için tasarlanmamıştır. Özel bir API test aracı işte bu noktada değerini gösterir.

Doğru ayrım şöyledir:

Her iki paket de aynı OpenAPI belirtimini kullanır, böylece asla iki doğruluk sürümüne sahip olmazsınız. Sözleşme öncelikli yaklaşıma daha derinlemesine bir bakış için, sözleşme öncelikli geliştirme araçları hakkındaki yazımız, belirtimin neden öncü olması gerektiğini açıklar.

Halihazırda Postman kullanan ve geçiş yapmayı düşünen ekipler için, kendi kendine barındırılan Postman alternatifleri, geçiş mekaniklerini ele alır.

Playwright ve Apidog arasında fixture'ları nasıl paylaşılır

Tek doğruluk kaynağı, genellikle depo kök dizinindeki openapi.yaml veya openapi.json dosyanız olan OpenAPI belirtiminizdir. Playwright, tipli istek yardımcıları ve örnek yükler için bunu okur; Apidog, senaryo adımlarını doldurmak için doğrudan içe aktarır. Arka uç bir sözleşme değişikliği gönderdiğinde, her iki paket de bunu alır.

Yeniden kullanılabilir test verilerini (kullanıcılar, tokenlar, örnek yükler) içeren bir fixtures/ klasörüyle başlayın. Bunları yükleyen ve testlere sunan bir Playwright fixture dosyası oluşturun:

// tests/fixtures/api.ts
import { test as base, APIRequestContext, expect } from '@playwright/test';
import { readFileSync } from 'fs';
import path from 'path';

type ApiFixtures = {
  apiRequest: APIRequestContext;
  authToken: string;
  sampleOrder: Record<string, unknown>;
};

export const test = base.extend<ApiFixtures>({
  apiRequest: async ({ playwright }, use) => {
    const ctx = await playwright.request.newContext({
      baseURL: process.env.API_BASE_URL ?? 'https://api.staging.example.com',
      extraHTTPHeaders: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
      },
    });
    await use(ctx);
    await ctx.dispose();
  },

  authToken: async ({ apiRequest }, use) => {
    const res = await apiRequest.post('/auth/token', {
      data: { email: 'qa@example.com', password: process.env.QA_PASSWORD },
    });
    expect(res.status()).toBe(200);
    const body = await res.json();
    await use(body.access_token);
  },

  sampleOrder: async ({}, use) => {
    const raw = readFileSync(
      path.join(__dirname, '..', '..', 'fixtures', 'order.json'),
      'utf8',
    );
    await use(JSON.parse(raw));
  },
});

export { expect };

Şimdi her belirtimde `@playwright/test` yerine bu fixture dosyasından `test`'i içe aktarıyorsunuz ve tipli bir `apiRequest`, yeni bir `authToken` ve `sampleOrder` verisi kullanıma hazır hale geliyor. `order.json` dosyası, Apidog'un senaryolarınızdaki `POST /orders` için örnek gövde olarak kullandığı aynı yüktür. Bir kez düzenleyin, her iki paket de değişir.

Apidog tarafı için projeyi açın, “İçe Aktar”a tıklayın ve aynı `openapi.yaml` dosyasını gösterin. Apidog, saniyeler içinde uç noktalar, istek örnekleri ve parametre şemaları oluşturur. Ardından fixture yüklerinizi Apidog “Ortam Değişkenleri” veya “Veri Kümeleri” olarak kaydedin:

// tests/orders.spec.ts
import { test, expect } from './fixtures/api';

test('POST /orders returns a valid order with 15 percent discount', async ({
  apiRequest,
  authToken,
  sampleOrder,
}) => {
  const res = await apiRequest.post('/orders', {
    headers: { Authorization: `Bearer ${authToken}` },
    data: { ...sampleOrder, coupon: 'SAVE15' },
  });

  expect(res.status()).toBe(201);
  const body = await res.json();

  expect(body).toMatchObject({
    id: expect.any(String),
    status: 'pending',
    discount_pct: 15,
    total_cents: expect.any(Number),
  });
  expect(body.total_cents).toBeLessThan(sampleOrder.subtotal_cents);
});

Apidog içinde, eşleşen senaryo adımı aynı yükü gönderir, ardından `openapi.yaml` içindeki `Order` bileşenine karşı yerleşik JSON Şema kontrolünü çalıştırır. Bu size derinlik sağlar: her alan tür kontrolünden geçirilir, gerekli alanlar doğrulanır, enum değerleri uygulanır. Playwright yüksek değerli anlamsal doğrulamayı (discount_pct: 15) yakalar; Apidog, elle doğrulamayı unuttuğunuz alanlar dahil olmak üzere sapma gösteren her alanı yakalar. Belirtim odaklı teste yeniyseniz, tasarım öncelikli API iş akışları hakkındaki kılavuzumuz çevresindeki deseni gösterir.

Halihazırda Postman kullanan ve geçiş yapmayı düşünen ekipler için, kendi kendine barındırılan Postman alternatifleri, geçiş mekaniklerini ele alır.

Apidog + Playwright iş akışını kurma

İşte sizi sıfırdan çift paketli CI'a yaklaşık bir saatte ulaştıracak temiz, tekrarlanabilir bir kurulum.

Adım 1: Hepsini yönetecek tek bir belirtim. `openapi.yaml` dosyasını deponun kök dizinine koyun. Bunu kod olarak ele alın: PR incelemeleri gerekli, bozulma yaratan değişiklikler büyük sürüm artışı gerektirir. Henüz bir belirtiminiz yoksa, mevcut rotalarınızdan bir çerçeve eklentisi (FastAPI, NestJS ve diğerleri OpenAPI'yi yerel olarak yayar) kullanarak bir taslak oluşturun, ardından el ile düzenleyin. Apidog ayrıca bir HAR dosyası içe aktarırsanız trafikten bir belirtimi tersine mühendislikle oluşturabilir.

Adım 2: Playwright'ı bağlayın. Playwright'ı kurun (`npm init playwright@latest`) ve yukarıda gösterilen fixture dosyasını ekleyin. Bir `npm run test:e2e` betiği ve hazırlık (staging) ortamınızı gösteren bir `playwright.config.ts` ekleyin. Testleri küçük tutun; her belirtim için bir senaryo.

Adım 3: Apidog senaryo katmanını ekleyin. Apidog projenizde `openapi.yaml` dosyasını içe aktarın, ardından her kritik kullanıcı yolculuğu (kayıt, ödeme, iade, webhook teslimi vb.) için bir senaryo oluşturun. Her senaryo, birbirine zincirlenmiş doğrulamalarla bir API çağrıları dizisidir. Apidog, ortam değişkenlerini, istek öncesi betikleri ve yanıt sonrası doğrulamaları destekler. Senaryoyu Apidog CLI (`apidog-cli run scenario.json`) aracılığıyla CLI'dan çalıştırılabilir bir JSON olarak dışa aktarın.

Adım 4: Playwright'ta ağ engelleme. UI'ın canlı olarak ulaşmasını istemediğiniz verileri çekerken, `page.route`'u kullanarak engelleme ve sahte yanıtlar (stub) oluşturma işini yapın. Sahte yanıtlar aynı fixture dosyalarından gelir, böylece sözleşme tutarlı kalır:

test('dashboard renders cached order list when offline', async ({
  page,
  sampleOrder,
}) => {
  await page.route('**/api/orders', async (route) => {
    await route.fulfill({
      status: 200,
      contentType: 'application/json',
      body: JSON.stringify({ orders: [sampleOrder] }),
    });
  });

  await page.goto('/dashboard');
  await expect(page.getByTestId('order-row')).toHaveCount(1);
});

Daha sonra Apidog'da, aynı `GET /orders` senaryosunu gerçek arka ucunuza veya bir Apidog mock sunucusuna karşı çalıştırın. Aynı fixture, iki katmanlı doğrulama.

Adım 5: CI entegrasyonu. Her iki paketi de paralel olarak çalıştıran bir GitHub Actions iş akışı ekleyin:

name: tests
on: [push, pull_request]
jobs:
  playwright:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npx playwright test
  apidog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm i -g apidog-cli
      - run: apidog-cli run ./apidog/scenarios/checkout.json --reporters cli,junit

Herhangi bir işin başarısız olması birleştirmeyi engeller. GitHub'ın başarısız doğrulamaları PR üzerinde satır içi olarak işaretlemesi için --reporters junit kullanın. GitHub Actions dokümantasyonu, bunu ölçeklendirmek isterseniz matris yapıları ve önbelleğe almayı kapsar. Özel bir QA işlevi olmayan ekipler için, QA mühendisleri için API test aracı kılavuzu, her bir paketin sahipliğinin nasıl atanacağını açıklar.

Adım 6: Sapma tespiti. Canlı openapi.yaml dosyanızı testlerinizin en son çalıştırıldığı sürüme karşı farklılıkları bulan günlük bir iş zamanlayın. Bir alanın türü değişirse, farklılıklar herhangi bir test çalışmadan önce derlemeyi başarısız kılar. Bu, bahsettiğimiz “yanlış yükle (payload) 200 OK” türündeki hataları yakalar.

Gelişmiş teknikler ve profesyonel ipuçları

Temel kurulum çalıştıktan sonra fayda sağlayacak birkaç adım.

Kaçınılması gereken yaygın hatalar:

Yapay zeka ile testler oluşturan ekipler için, yapay zeka ajan API'lerini nasıl test edeceğiniz kılavuzu, ekstra dikkat gerektiren deterministik olmayan durumları kapsar.

Alternatifler ve araç karşılaştırması

Çeşitli araç kombinasyonları, tarayıcı testlerinin yanı sıra API'ları da doğrulayabilir. İşte ana seçeneklerin karşılaştırması.

Yığın Güçlü Yönler Zayıf Yönler En İyisi
Yalnızca Playwright (request fixture) Tek araç, hızlı, pakete özgü Yüzeysel şema doğrulama, zincirleme senaryo yok, zayıf hata yolu kapsamı Küçük ekipler, basit API'ler
Playwright + Postman Olgun Postman ekosistemi, Newman CLI İki doğruluk kaynağı, Postman koleksiyonları OpenAPI'den sapar, işbirliği için ücretli Zaten Postman'da derinleşmiş ekipler
Playwright + Apidog Tek OpenAPI kaynağı, şema doğrulama, mock'lar, CI için CLI, tasarım öncelikli iş akışı Öğrenilecek iki araç, belirtim disiplini gerektirir Belirtim odaklı, tam kapsamlı test isteyen ekipler
Cypress + cy-api eklentisi Cypress kullananlara tanıdık Cypress yalnızca tarayıcıda çalışır; API testi sınırlıdır; eklentiler daha az cilalı Mevcut Cypress kod tabanları
Pact (tüketici odaklı sözleşmeler) Hizmetler arasında güçlü sözleşme garantileri Yüksek öğrenme eğrisi, aracı altyapısı, UI'a odaklanmamış Birçok dahili API tüketicisi olan mikroservis organizasyonları

Daha eski SOAP dönemi araçlarından geliyorsanız, SoapUI Groovy betik alternatifleri ve ReadyAPI alternatifleri hakkındaki yazılarımız geçiş yolunu kapsar. Yerel öncelikli iş akışları için, REST istemci VSCode uzantıları okumaya değer.

Playwright + Apidog eşleşmesi, bir OpenAPI belirtimine sahip, birden fazla hizmet gönderen ve mühendis başına iki SaaS lisansı ödemeden hem UI hem de API regresyonlarını yakalayan tek bir CI hattı isteyen ekipler için kazançlıdır.

Gerçek dünya kullanım örnekleri

Sonuç

Playwright tarayıcı akışlarında mükemmeldir. Derin API testi için tasarlanmamıştır. Onu Apidog ile eşleştirmek size şunları sağlar:

Ödeme veya kayıt gibi kritik bir yolculukla başlayın. Playwright fixture'ını bağlayın, eşleşen Apidog senaryosunu oluşturun, her ikisini de CI'da çalıştırın. Oradan genişletin. Apidog'u indirin, OpenAPI belirtiminizi içe aktarın ve ilk senaryoyu bugün çalıştırabilirsiniz.

düğme

Sıkça Sorulan Sorular

API'ları Playwright testlerinde Apidog olmadan doğrulayabilir miyim? Evet, Playwright'ın request fixture'ını ve manuel expect çağrılarını kullanarak. Durum kodlarını ve birkaç gövde alanını kapsarsınız. Şema doğrulaması, zincirleme senaryolar, mock'lar ve ölçekte hata yolu kapsamı için, Apidog gibi özel bir araç daha hızlıdır ve daha az yanlış pozitif üretir. Değişimler için QA mühendisleri için API test aracı karşılaştırmamıza bakın.

Bu kurulumu kullanmak için bir OpenAPI belirtimine ihtiyacım var mı? Tam faydayı elde etmek için bir tane ihtiyacınız var. Bir belirtim olmadan, Playwright ve Apidog'u yine de yan yana çalıştırabilirsiniz, ancak paylaşılan doğruluk kaynağını kaybedersiniz ve örnek yükleri iki yerde tutmak zorunda kalırsınız. Mevcut rotalardan bir belirtim oluşturmak bir iki gün sürer.

Her iki araçta da kimlik doğrulamayı nasıl yaparım? Kimlik doğrulama uç noktanızdan yeni bir token getiren bir beforeAll adımı kullanın, ardından bunu bir Playwright fixture'ında ve bir Apidog ortam değişkeninde saklayın. Her test çalıştırmasında tokenları döndürün, böylece eski token'lar asla düzensizliğe neden olmaz.

Apidog senaryoları Playwright'ı tamamen değiştirebilir mi? Hayır. Apidog API iş akışlarında mükemmeldir ancak tarayıcıları render etmez. UI doğrulamaları (görünür metin, düzen, tıklama akışları) için hala Playwright'a ihtiyacınız var. İki araç farklı yüzeyleri kapsar.

Arka ucumun kararlı bir hazırlık (staging) ortamı yoksa ne yapmalıyım? Apidog'un yerleşik mock sunucusunu kullanın. Tek tıklamayla OpenAPI belirtiminizden durum bilgisi olan bir mock sunucusu başlatır ve belirtimde tanımlanan örnek yanıtları döndürür. Playwright paketiniz ve Apidog senaryolarınız mock sunucuya karşı başarılı bir şekilde çalışır ve hazırlık ortamı sağlıklı olduğunda gerçek arka uca geri dönersiniz.

Paket büyüdükçe CI'yı nasıl hızlı tutarım? Testleri önceliğe göre etiketleyin ve her push'ta yalnızca @smoke testlerini çalıştırın. Tam regresyonu ve Apidog senaryo paketini main'e yapılan PR'larda ve gecelik bir programla çalıştırın. Playwright'ı workers: 4 ile ve Apidog senaryolarını CLI'nin --parallel bayrağıyla paralel hale getirin.

CI için ücretli bir Apidog planına ihtiyacım var mı? Apidog CLI, senaryo yürütme için oturum lisansı olmadan yerel olarak ve CI'da çalışır. Büyük ölçekte benimsemeden önce mevcut fiyatlandırma sayfasını kontrol edin. Ücretsiz katman çoğu küçük ekibi kapsar.

API Tasarım-Öncelikli Yaklaşımı Apidog'da Uygulayın

API'leri oluşturmanın ve kullanmanın daha kolay yolunu keşfedin

Ücretsiz Kaydolİndir