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 müşteri “grafik sayıları yanlış” diyor. İncelediğinizde API’nin bozuk bir payload ile 200 OK döndürdüğünü, fakat E2E testlerinizin yalnızca ekranda piksel gördüğü için bunu yakalamadığını fark ediyorsunuz. Bu boşluğu kapatmak için tarayıcı testlerinin yanına API sözleşmesi, şema ve yanıt semantiği doğrulamaları eklemeniz gerekir. Apidog gibi araçlar, aynı titizliği API katmanına taşıyıp Playwright paketinizle birlikte CI’da çalıştırmanıza yardımcı olur.

Apidog'u bugün deneyin

TL;DR

Playwright testlerinde API doğrulamalarını üç katmanda ele alın:

1. Playwright request fixture’ı ile kritik uç noktalara hızlı smoke check ekleyin.
2. page.route ile UI testlerinde kontrollü mock/stub yanıtlar kullanın.
3. Apidog senaryoları ile aynı OpenAPI belirtimine karşı şema, iş mantığı, zincirleme istek ve hata yolu doğrulamaları çalıştırın.

Ana hedef: Playwright ve Apidog’un aynı openapi.yaml dosyasını ve aynı fixture verilerini kullanması. Böylece sözleşme değiştiğinde iki test katmanı da hızlıca başarısız olur.

Problem: Playwright UI testleri API hatalarını her zaman yakalamaz

Playwright, tarayıcı otomasyonu için güçlüdür. Playwright API testing dokümantasyonu, request.get, request.post ve expect(response.status()).toBe(200) ile API çağrısı yapmayı kolaylaştırır.

Ancak ölçek büyüdükçe şu sorunlar ortaya çıkar:

• Testler yalnızca 200 OK kontrol eder, gövde şemasını kontrol etmez.
• UI testleri API payload değişikliklerini gizleyebilir.
• Tarayıcı akışları ve API senaryoları farklı fixture dosyaları kullanır.
• Hata yolları (401, 403, 409, 429, 500) çoğu zaman test edilmez.
• Backend bozukken veya yavaşken UI testlerini izole çalıştırmak zorlaşır.

Örnek regresyon:

{
  "total_count": 120
}

alanı şu hale gelir:

{
  "totalCount": 120
}

UI hâlâ bir sayı gösterebilir. Playwright testi geçer. Fakat sözleşme bozulmuştur.

Bu nedenle ayrımı net yapın:

• Playwright: UI akışı, kullanıcı etkileşimi, ağ engelleme, kritik uç noktalarda hafif smoke check.
• Apidog: OpenAPI uyumluluğu, JSON Schema doğrulaması, zincirleme API senaryoları, hata yolları, mock sunucu.

Kurulumdan önce aracı yerel olarak hazırlamak isterseniz Apidog’u indirin. Test aracı seçimi için daha geniş bağlam gerekiyorsa QA mühendisleri için API test araçları yazısına bakabilirsiniz.

Hedef mimari

Depoda tek bir sözleşme dosyası tutun:

repo/
├─ openapi.yaml
├─ fixtures/
│  └─ order.json
├─ tests/
│  ├─ fixtures/
│  │  └─ api.ts
│  └─ orders.spec.ts
├─ apidog/
│  └─ scenarios/
│     └─ checkout.json
└─ playwright.config.ts

Kural basit:

• openapi.yaml: tek doğruluk kaynağı.
• fixtures/*.json: hem Playwright hem Apidog tarafından kullanılan örnek veri.
• Playwright: hızlı UI + API smoke doğrulamaları.
• Apidog: derin API sözleşme ve senaryo doğrulamaları.

Sözleşme öncelikli yaklaşımı daha detaylı uygulamak isterseniz sözleşme öncelikli geliştirme araçları rehberi faydalı olur. Postman’dan geçiş planlayan ekipler için kendi kendine barındırılan Postman alternatifleri yazısı da geçiş mekaniklerini ele alır.

1. OpenAPI belirtimini merkeze koyun

openapi.yaml dosyasını repo köküne koyun ve kod gibi yönetin:

• PR incelemesi zorunlu olsun.
• Bozucu değişiklikler açıkça işaretlensin.
• Backend değişikliği önce sözleşmeye yansısın.
• Playwright ve Apidog aynı dosyayı kullansın.

Henüz OpenAPI belirtiminiz yoksa:

• FastAPI, NestJS vb. framework’lerden otomatik taslak çıkarın.
• Eksik alanları manuel tamamlayın.
• Elinizde HAR dosyası varsa Apidog ile trafikten belirtim oluşturabilirsiniz.

Tasarım öncelikli API akışları için bu kılavuzu referans alabilirsiniz.

2. Playwright için ortak API fixture’ı 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: '[e-mail]',
        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 };

Artık testlerde @playwright/test yerine bu fixture dosyasını kullanın:

import { test, expect } from './fixtures/api';

Bu size üç şey sağlar:

• Hazır apiRequest
• Her test çalıştırmasında alınan authToken
• Apidog ile ortak kullanılan sampleOrder

3. Playwright’ta kritik API smoke check yazın

tests/orders.spec.ts:

import { test, expect } from './fixtures/api';

test('POST /orders valid order ve 15 percent discount döndürür', 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);
});

Burada Playwright’ın rolü derin şema doğrulaması yapmak değil; kritik iş kuralını hızlıca yakalamaktır:

expect(body.discount_pct).toBe(15);

Derin alan kontrolünü Apidog tarafına bırakın.

4. Apidog’da aynı OpenAPI dosyasını içe aktarın

Apidog tarafında:

1. Projeyi açın.
2. Import / İçe Aktar seçeneğini kullanın.
3. Repo’daki aynı openapi.yaml dosyasını seçin.
4. Kritik kullanıcı yolculukları için senaryolar oluşturun:
   • Kayıt
   • Giriş
   • Sipariş oluşturma
   • Ödeme
   • İade
   • Webhook teslimi
5. Ortak fixture verilerini Apidog ortam değişkenleri veya veri kümeleri olarak tanımlayın.

Örneğin POST /orders senaryosunda:

• İstek gövdesi: fixtures/order.json ile aynı yapı.
• Doğrulama: openapi.yaml içindeki Order şemasına karşı JSON Schema kontrolü.
• Ek assertion: discount_pct === 15.

Bu yapı iki katmanlı güvence verir:

• Playwright: yüksek değerli iş kuralını hızlı yakalar.
• Apidog: her alanı şema, tür, required ve enum seviyesinde doğrular.

Postman’dan geçiş yapan ekipler için kendi kendine barındırılan Postman alternatifleri yazısı geçiş kararlarını netleştirebilir.

5. UI testlerinde page.route ile kontrollü mock kullanın

Backend’e bağımlı olmayan UI senaryoları için Playwright’ta ağ çağrılarını stub’layın:

import { test, expect } from './fixtures/api';

test('dashboard offline iken cached order list render eder', 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);
});

Önemli nokta: Bu mock yanıtlar gerçek API testlerinin yerine geçmez.

• page.route: UI izolasyonu için.
• Apidog senaryoları: gerçek API doğrulaması için.

Aynı sampleOrder fixture’ını iki yerde kullanarak veri sapmasını önlersiniz.

6. CI’da Playwright ve Apidog’u birlikte çalıştırın

GitHub Actions örneği:

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
        env:
          API_BASE_URL: ${{ secrets.API_BASE_URL }}
          QA_PASSWORD: ${{ secrets.QA_PASSWORD }}

  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
        env:
          API_BASE_URL: ${{ secrets.API_BASE_URL }}
          QA_PASSWORD: ${{ secrets.QA_PASSWORD }}

Bir iş başarısız olursa merge’i engelleyin.

--reporters junit kullanarak CI çıktısını PR üzerinde daha okunabilir hale getirebilirsiniz. Daha büyük iş akışları için GitHub Actions dokümantasyonu matris yapıları ve cache stratejilerini kapsar.

QA sahipliği konusunda daha fazla pratik öneri için QA mühendisleri için API test aracı rehberine bakabilirsiniz.

7. Şema sapmasını erken yakalayın

Ayrı bir günlük iş ekleyin:

• Canlı openapi.yaml dosyasını alın.
• Repo’daki son test edilmiş sürümle karşılaştırın.
• Alan adı, tür, required veya enum değiştiyse pipeline’ı başarısız yapın.

Böylece şu tip hatalar test çalışmadan önce yakalanır:

- total_count: integer
+ totalCount: integer

Apidog’da şema uyumsuzluklarını uyarı olarak bırakmayın. CI’da sıfır olmayan çıkış kodu ile başarısız olmasını sağlayın.

Gelişmiş pratikler

Playwright trace’i açın

playwright.config.ts:

import { defineConfig } from '@playwright/test';

export default defineConfig({
  retries: 2,
  use: {
    trace: 'on-first-retry',
  },
});

Başarısız testlerde:

• Ağ çağrılarını
• DOM snapshot’larını
• Console log’larını
• Zaman çizelgesini

tek dosyada inceleyebilirsiniz.

API tarafında bunu Apidog HTML raporlarıyla eşleştirin.

Apidog mock sunucularını kullanın

Backend kararsızsa veya staging veritabanı sıfırlanıyorsa:

1. Apidog’da OpenAPI belirtiminden mock sunucu başlatın.
2. Playwright API_BASE_URL değerini mock sunucuya yönlendirin.
3. UI testlerini izole çalıştırın.
4. Apidog senaryolarını gerçek backend’e karşı ayrı çalıştırın.

Mock sunucuların test üretimindeki rolü için yapay zeka destekli API test üretimi yazısına bakabilirsiniz.

Retry sayısını sınırlı tutun

Playwright:

export default defineConfig({
  retries: 2,
});

Bir testin geçmesi için 5 retry gerekiyorsa bu flaky testtir. Aynı prensip Apidog senaryoları için de geçerli: istek başına düşük retry kullanın ve kök nedeni düzeltin.

Testleri etiketleyin

Örnek strateji:

• Her push: @smoke
• PR: @regression
• Gecelik: tüm Apidog senaryo paketi

Playwright’ta:

test.describe('@smoke checkout', () => {
  test('user can complete checkout', async ({ page }) => {
    // ...
  });
});

Durum bilgisi olan akışlarda:

test.describe.configure({ mode: 'serial' });

Yapay zeka API’lerini ayrı ele alın

Deterministik olmayan API’lerde assertion stratejisi farklıdır. Bu senaryolar için yapay zeka ajan API’lerini nasıl test edeceğiniz rehberine bakabilirsiniz.

Kaçınılması gereken hatalar

• Yalnızca status === 200 kontrol etmek.
• Bearer token’ları fixture dosyalarına sabit yazmak.
• Playwright ve Apidog için ayrı örnek payload tutmak.
• Apidog CLI’yı CI’dan çıkarmak.
• page.route stub’larını gerçek API testlerinin yerine koymak.
• OpenAPI dosyasını PR incelemesi dışında değiştirmek.
• Şema sapmasını “warning” olarak bırakmak.

Alternatifler ve araç 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ı

SOAP veya ReadyAPI geçmişinden gelen ekipler için şu geçiş kaynakları faydalı olabilir:

• SoapUI Groovy betik alternatifleri
• ReadyAPI alternatifleri
• REST istemci VSCode uzantıları

Playwright + Apidog eşleşmesi özellikle şu ekipler için uygundur:

• OpenAPI belirtimi olanlar
• Birden fazla servis gönderenler
• UI ve API regresyonlarını tek CI hattında yakalamak isteyenler
• Mock sunucu ve sözleşme doğrulamasını birlikte kullanmak isteyenler

Gerçek dünya kullanım örnekleri

E-ticaret ödeme akışı

Playwright:

• Sepete ürün ekleme
• Ödeme ekranına gitme
• Onay sayfasını görme

Apidog:

• Payment intent oluşturma
• Fraud check çağrısı
• Inventory decrement
• Refund webhook doğrulaması

Ödeme sağlayıcısı error_code alanını errorCode olarak değiştirdiğinde, UI yalnızca genel bir hata gösterebilir. Apidog ise şema sapmasını doğrudan yakalar.

SaaS analitik kontrol paneli

Playwright:

• Dashboard render oluyor mu?
• Grafik bileşenleri görünüyor mu?
• Filtreler çalışıyor mu?

Apidog:

• Toplamlar doğru mu?
• Yüzdelikler doğru mu?
• Zaman aralıklı seri beklenen formatta mı?
• Aykırı değerler yanlışlıkla düşüyor mu?

Grafik görsel olarak doğru görünebilir; API toplamları yanlış olabilir. Bu kontrol API katmanında yapılmalıdır.

Webhook güdümlü fintech akışı

Playwright:

• Kullanıcı portalı
• İşlem durum ekranı
• Bildirimler

Apidog:

• Webhook imza doğrulaması
• Retry mantığı
• Idempotency kontrolü
• Yinelenen webhook ID reddi
• Nihai tutarlılık penceresi

Bu tür akışlarda tarayıcı testi tek başına yeterli değildir.

Sonuç

Playwright tarayıcı akışlarında mükemmeldir, fakat derin API testi için tek başına yeterli değildir. Apidog ile birlikte kullandığınızda daha sağlam bir test mimarisi elde edersiniz:

• Tek OpenAPI sözleşmesi
• Ortak fixture verileri
• Playwright ile UI ve smoke API kontrolleri
• Apidog ile şema ve zincirleme senaryo doğrulamaları
• Mock sunucularla çevrimdışı geliştirme
• CI’da hem UI hem API regresyonlarını yakalama
• Net sahiplik sınırları

Başlamak için küçük ilerleyin:

1. Kritik bir akış seçin: ödeme, kayıt veya sipariş oluşturma.
2. openapi.yaml dosyasını merkeze alın.
3. Playwright API fixture’ını ekleyin.
4. Aynı payload ile Apidog senaryosu oluşturun.
5. İkisini de CI’da çalıştırın.
6. Sonra kapsamı genişletin.

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ı kullanabilirsiniz. Ancak şema doğrulaması, zincirleme senaryolar, mock’lar ve geniş hata yolu kapsamı için Apidog gibi özel bir araç daha uygundur. Karşılaştırma için QA mühendisleri için API test aracı yazısına bakabilirsiniz.

Bu kurulum için OpenAPI belirtimi şart mı?

Tam fayda için evet. OpenAPI olmadan Playwright ve Apidog’u yan yana çalıştırabilirsiniz, ancak tek doğruluk kaynağını kaybedersiniz. Bu da fixture ve örnek payload’ların zamanla sapmasına neden olur.

Kimlik doğrulamayı iki araçta nasıl yönetmeliyim?

Her test çalıştırmasında auth endpoint’ten yeni token alın. Playwright’ta bunu fixture içinde, Apidog’da ortam değişkeni olarak saklayın. Token’ları sabit dosyalara yazmayın.

Apidog senaryoları Playwright’ın yerini alabilir mi?

Hayır. Apidog API iş akışlarını doğrular; tarayıcı render etmez. Görünür metin, layout, tıklama akışı ve kullanıcı etkileşimi için Playwright gerekir.

Staging ortamım kararlı değilse ne yapmalıyım?

Apidog mock sunucusunu kullanın. OpenAPI belirtiminizden mock sunucu başlatıp Playwright testlerini bu sunucuya yönlendirebilirsiniz. Staging sağlıklı olduğunda gerçek backend’e geri dönersiniz.

CI süresini nasıl kısa tutarım?

Testleri önceliklendirin:

• Push: @smoke
• PR: regression
• Gecelik: tam Apidog senaryo paketi

Playwright tarafında worker sayısını artırın, Apidog tarafında CLI paralelleştirme seçeneklerini kullanın.

CI için ücretli Apidog planına ihtiyacım var mı?

Apidog CLI yerel ve CI ortamlarında senaryo yürütmek için kullanılabilir. Büyük ölçekli kullanıma geçmeden önce güncel fiyatlandırma sayfasını kontrol edin.