Cara Memvalidasi Respons API dalam Pengujian Playwright

Tes Playwright Anda berhasil. Tombol login diklik, dasbor dirender, grafik tergambar. Kemudian seorang pelanggan melaporkan bug: angka pada grafik salah. Anda menyelidiki dan menemukan bahwa API mengembalikan status 200 dengan payload yang salah format, dan suite end-to-end Anda tidak pernah menyadarinya karena hanya memeriksa bahwa piksel muncul di layar. Inilah celah yang tidak bisa ditutup oleh tes browser saja, dan di sinilah penegasan API menjadi tidak bisa ditawar. Alat seperti Apidog memberi Anda cara untuk memvalidasi kontrak API, skema, dan semantik respons dengan ketelitian yang sama seperti yang Anda berikan pada alur UI Anda, lalu menjalankan kedua suite secara bersamaan di CI.

TL;DR

Anda dapat memvalidasi API dalam tes Playwright dengan menggabungkan fixture request Playwright dan interseptor page.route dengan skenario Apidog yang menggunakan spesifikasi OpenAPI yang sama. Bagikan fixture melalui satu file spesifikasi, tegaskan skema respons di kedua lapisan, dan jalankan kedua suite dalam satu pekerjaan CI sehingga perubahan kontrak akan cepat gagal di salah satu tempat.

Pendahuluan

Playwright adalah kerangka kerja otomatisasi browser default bagi banyak tim pada tahun 2026, dan dokumentasi Playwright membuat pengujian API terlihat mudah: beberapa panggilan request.get, expect(response.status()).toBe(200), dan selesai. Masalah dimulai ketika Anda meningkatkan skalanya. Anda akan berakhir dengan ratusan tes yang memeriksa kode status tetapi bukan bentuk respons, tidak ada sumber kebenaran bersama antara alur browser dan alur API Anda, dan tidak ada cara untuk mengejek API secara offline ketika backend lambat atau rusak.

Perbaikannya mudah. Perlakukan spesifikasi OpenAPI Anda sebagai kontrak, dorong panggilan request Playwright dan interseptor page.route dari kontrak tersebut, dan jalankan suite skenario Apidog terhadap spesifikasi yang sama untuk validasi skema mendalam, logika bisnis, dan permintaan berantai. Anda mendapatkan umpan balik cepat di CI, batasan kepemilikan yang jelas antara tes frontend dan backend, dan nol fixture duplikat. Jika Anda ingin menginstal alat ini terlebih dahulu, Unduh Apidog dan kembali; langkah-langkah di bawah ini mengasumsikan bahwa alat tersebut tersedia secara lokal.

Berikut adalah apa yang akan Anda dapatkan dari postingan ini: model mental yang jelas tentang di mana penegasan API seharusnya berada dalam suite Playwright, pola request.fixture yang berfungsi, pengaturan langkah demi langkah untuk berbagi fixture antara Playwright dan Apidog, kiat-kiat lanjutan untuk CI dan mocking, serta tabel perbandingan alternatif utama. Untuk konteks yang lebih luas tentang pilihan alat pengujian, lihat pandangan kami tentang alat pengujian API untuk insinyur QA.

Celah antara tes Playwright dan penegasan API

Tes Playwright yang khas adalah masuk, menavigasi ke halaman, dan menegaskan bahwa beberapa elemen UI terlihat. Itu memberi tahu Anda bahwa alur yang terlihat oleh pengguna berfungsi. Itu tidak memberi tahu Anda apa pun tentang API di baliknya. Tiga mode kegagalan yang lolos:

Pertama, regresi bentuk payload. Endpoint mengembalikan 200 dengan bidang yang namanya diubah dari total_count menjadi totalCount. UI mungkin secara diam-diam memaksa atau menampilkan nol. Tes Playwright Anda melihat angka di layar dan lulus.

Kedua, penyimpangan logika bisnis. Endpoint diskon menerapkan potongan harga 10 persen alih-alih 15 persen yang dikontrak. UI menunjukkan apa pun yang dikembalikan API, jadi tes lulus. Hanya tim keuangan yang menyadarinya, berminggu-minggu kemudian.

Ketiga, cakupan jalur error. Tes Playwright hampir selalu menjalankan jalur "happy path". API Anda memiliki lusinan cabang 4xx dan 5xx: batas laju, token kedaluwarsa, kegagalan parsial, konflik idempoten. Tak satu pun dari itu akan diuji kecuali Anda menulis suite tes API terpisah.

Anda dapat menambal sebagian dari ini dengan menambahkan panggilan request.get di dalam spesifikasi Playwright Anda dan menegaskan isi respons. Itu berhasil untuk beberapa endpoint. Itu gagal ketika Anda memiliki 200 endpoint dan ingin skenario berantai seperti “buat pesanan, ambil pesanan, batalkan pesanan, verifikasi webhook pengembalian dana.” Playwright adalah kerangka kerja otomatisasi browser terlebih dahulu; itu tidak dibangun untuk alur kerja API yang stateful atau ergonomi penegasan tingkat skema. Di situlah alat pengujian API khusus mendapatkan nilainya.

Pembagian yang tepat adalah:

• Tes Playwright memverifikasi alur UI, intersepsi jaringan, dan lapisan tipis pemeriksaan API smoke pada batas tindakan pengguna.
• Skenario Apidog memverifikasi kesesuaian skema, alur kerja API berantai, kepatuhan kontrak, dan jalur error secara mendalam.

Kedua suite menggunakan spesifikasi OpenAPI yang sama sehingga Anda tidak pernah memiliki dua versi kebenaran. Untuk pandangan yang lebih mendalam tentang pendekatan contract-first, artikel kami tentang perkakas pengembangan API design-first menjelaskan mengapa spesifikasi harus menjadi yang utama.

Cara berbagi fixture antara Playwright dan Apidog

Satu-satunya sumber kebenaran adalah spesifikasi OpenAPI Anda, biasanya openapi.yaml atau openapi.json di root repo. Playwright membacanya untuk pembantu permintaan yang diketik dan payload contoh; Apidog mengimpornya langsung untuk mengisi langkah-langkah skenario. Kapan pun backend mengirimkan perubahan kontrak, kedua suite akan mengambilnya.

Mulailah dengan folder fixtures/ yang menyimpan data pengujian yang dapat digunakan kembali: pengguna, token, payload sampel. Buat file fixture Playwright yang memuat ini dan mengeksposnya ke tes:

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

Sekarang Anda mengimpor test dari file fixture ini alih-alih @playwright/test di setiap spesifikasi, dan Anda memiliki apiRequest yang diketik, authToken yang baru, dan data sampleOrder yang siap digunakan. File order.json adalah payload yang sama yang digunakan Apidog sebagai contoh body untuk POST /orders dalam skenario Anda. Edit sekali, kedua suite berubah.

Untuk sisi Apidog, buka proyek, klik "Impor", dan arahkan ke openapi.yaml yang sama. Apidog menghasilkan endpoint, contoh permintaan, dan skema parameter dalam hitungan detik. Kemudian simpan payload fixture Anda sebagai "Variabel Lingkungan" atau "Kumpulan Data" Apidog:

// 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);
});

Di dalam Apidog, langkah skenario yang sesuai memposting payload yang sama, lalu menjalankan pemeriksaan Skema JSON bawaan terhadap komponen Order di openapi.yaml. Itu memberi Anda kedalaman: setiap bidang diperiksa tipenya, bidang yang diperlukan diverifikasi, nilai enum diberlakukan. Playwright menangkap penegasan semantik bernilai tinggi (discount_pct: 15); Apidog menangkap setiap bidang yang menyimpang, bahkan yang Anda lupa untuk tegaskan secara manual. Jika Anda baru mengenal pengujian berbasis spesifikasi, panduan kami tentang alur kerja API design-first menunjukkan pola di sekitarnya.

Untuk tim yang sudah menggunakan Postman dan sedang mempertimbangkan untuk beralih, alternatif Postman yang di-host sendiri mencakup mekanisme migrasi.

Menyiapkan alur kerja Apidog + Playwright

Berikut adalah pengaturan yang bersih dan dapat diulang yang akan membawa Anda dari nol ke CI dual-suite dalam waktu sekitar satu jam.

Langkah 1: Satu spesifikasi untuk menguasai semuanya. Tempatkan openapi.yaml di root repo. Perlakukan sebagai kode: diperlukan tinjauan PR, perubahan besar membutuhkan peningkatan versi mayor. Jika Anda belum memilikinya, buat draf dari rute yang ada menggunakan plugin kerangka kerja (FastAPI, NestJS, dan lainnya mengeluarkan OpenAPI secara native), lalu edit secara manual. Apidog juga dapat merekayasa balik spesifikasi dari lalu lintas jika Anda mengimpor file HAR.

Langkah 2: Sambungkan Playwright. Instal Playwright (npm init playwright@latest) dan tambahkan file fixture yang ditunjukkan di atas. Tambahkan skrip npm run test:e2e dan playwright.config.ts yang menunjuk ke lingkungan staging Anda. Jaga agar tes tetap kecil; satu skenario per spesifikasi.

Langkah 3: Tambahkan lapisan skenario Apidog. Di dalam proyek Apidog Anda, impor openapi.yaml, lalu bangun skenario per perjalanan pengguna yang penting: pendaftaran, checkout, pengembalian dana, pengiriman webhook, dan sebagainya. Setiap skenario adalah urutan panggilan API dengan penegasan yang dirangkai. Apidog mendukung variabel lingkungan, skrip pra-permintaan, dan penegasan pasca-respons. Ekspor skenario sebagai JSON yang dapat dijalankan CLI melalui Apidog CLI (apidog-cli run scenario.json).

Langkah 4: Intersepsi jaringan di Playwright. Ketika UI mengambil data yang tidak ingin Anda hubungkan secara langsung, gunakan page.route untuk mencegat dan menstub. Respons yang distub berasal dari file fixture yang sama, sehingga kontrak tetap konsisten:

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

Kemudian di Apidog, jalankan skenario GET /orders yang sama terhadap backend Anda yang sebenarnya atau terhadap server mock Apidog. Fixture yang sama, dua lapisan verifikasi.

Langkah 5: Integrasi CI. Tambahkan alur kerja GitHub Actions yang menjalankan kedua suite secara paralel:

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

Kegagalan salah satu pekerjaan akan memblokir penggabungan. Gunakan --reporters junit agar GitHub menganotasi penegasan yang gagal secara inline pada PR. Dokumentasi GitHub Actions mencakup matrix build dan caching jika Anda ingin meningkatkan skalanya. Untuk tim tanpa fungsi QA khusus, panduan alat pengujian API untuk insinyur QA menjelaskan cara menetapkan kepemilikan setiap suite.

Langkah 6: Deteksi penyimpangan. Jadwalkan pekerjaan harian yang membandingkan openapi.yaml langsung Anda dengan versi yang terakhir kali digunakan untuk tes. Jika ada bidang yang berubah tipe, perbedaan tersebut akan menyebabkan build gagal sebelum tes apa pun dijalankan. Ini menangkap jenis bug "200 OK dengan payload salah" yang kami bahas di awal.

Teknik Lanjutan dan Kiat Profesional

Beberapa langkah yang memberikan hasil setelah pengaturan dasar berjalan.

Sematkan penampil jejak Playwright. Atur trace: 'on-first-retry' di playwright.config.ts. Ketika tes yang tidak stabil gagal di CI, Anda mendapatkan garis waktu lengkap panggilan jaringan, snapshot DOM, dan log konsol. Pasangkan dengan apidog-cli --report html untuk sisi API. Bersama-sama, keduanya menunjukkan apakah UI yang rusak terlebih dahulu atau API yang menyimpang.

Gunakan server mock Apidog untuk menjalankan secara offline. Apidog dapat memutar server mock dari spesifikasi OpenAPI Anda dalam satu klik. Arahkan lingkungan dev lokal Anda ke sana ketika tim backend sedang dalam proses deploy atau basis data staging sedang direset. Suite Playwright Anda berjalan hijau terhadap mock, dan skenario Apidog Anda memverifikasi backend yang sebenarnya secara paralel. Untuk lebih lanjut tentang pola ini, lihat pandangan kami tentang pembuatan tes API yang dibantu AI di mana mock adalah pusatnya.

Batasi jumlah percobaan ulang hingga dua. retries: 2 di playwright.config.ts. Jika sebuah tes membutuhkan tiga percobaan ulang untuk lulus, itu tidak stabil dan Anda memiliki masalah nyata. Jangan menutupi dengan retries: 5. Hal yang sama berlaku untuk skenario Apidog: atur retry: 1 per permintaan, maksimal.

Gagal tertutup pada penyimpangan skema. Ketika Apidog mendeteksi ketidakcocokan skema, keluar non-nol secara default. Jangan biarkan peringatan lolos. Jika Anda harus mengizinkan jendela soft-fail, lindungi dengan variabel lingkungan seperti ALLOW_SCHEMA_DRIFT=true dan minta komentar pada PR yang menjelaskan alasannya.

Beri tag tes berdasarkan prioritas. Gunakan test.describe.configure({ mode: 'serial' }) Playwright untuk alur stateful dan beri tag lainnya dengan @smoke, @regression, @nightly. Jalankan smoke pada setiap push, regression pada PR ke main, nightly di seluruh suite skenario Apidog. Menghemat menit CI tanpa kehilangan cakupan.

Kesalahan umum yang harus dihindari:

• Menegaskan hanya status === 200. Tambahkan setidaknya satu pemeriksaan bidang body.
• Mengodekan token bearer secara langsung dalam fixture. Gunakan beforeAll untuk mengambil token baru.
• Membiarkan Playwright dan Apidog mengimpor file fixture yang berbeda. Satu sumber, titik.
• Melewatkan Apidog CLI di CI karena “alat UI sudah cukup baik.” Tidak; CLI-lah yang menyebabkan build gagal.
• Memperlakukan stub page.route sebagai pengganti tes API yang sebenarnya. Mereka untuk isolasi, bukan cakupan.

Untuk tim yang membuat tes dengan AI, panduan cara menguji API agen AI mencakup kasus non-deterministik yang membutuhkan perhatian ekstra.

Alternatif dan Perbandingan Alat

Beberapa kombinasi alat dapat memvalidasi API bersama dengan tes browser. Berikut adalah bagaimana opsi utama dibandingkan.

Jika Anda berasal dari alat era SOAP yang lebih lama, artikel kami tentang alternatif skrip Groovy SoapUI dan alternatif ReadyAPI mencakup jalur migrasi. Untuk alur kerja local-first, ekstensi VSCode klien REST layak dibaca.

Pasangan Playwright + Apidog unggul untuk tim yang memiliki spesifikasi OpenAPI, mengirimkan beberapa layanan, dan menginginkan satu pipeline CI yang menangkap regresi UI dan API tanpa membayar dua kursi SaaS per insinyur.

Kasus Penggunaan Dunia Nyata

Checkout E-commerce. Tim ritel menjalankan tes Playwright untuk alur dari keranjang hingga konfirmasi dan skenario Apidog untuk rantai API intent pembayaran, pemeriksaan penipuan, dan pengurangan inventaris. Ketika gateway pembayaran mengubah bidang respons dari error_code menjadi errorCode, Apidog menangkapnya dalam 90 detik; Playwright akan menampilkan layar "checkout gagal" generik dan membutuhkan waktu berjam-jam untuk menelusuri masalah.

Dasbor SaaS dengan data grafik. Produk analitik B2B memvalidasi rendering UI dengan snapshot Playwright dan menggunakan Apidog untuk menegaskan bahwa endpoint agregasi mengembalikan jumlah, persentil, dan deret waktu yang benar. Bug di mana endpoint latensi p99 secara diam-diam menghilangkan outlier tertangkap di lapisan API; grafik terlihat baik-baik saja.

Alur kerja berbasis Webhook. Tim fintech menggunakan Playwright untuk portal yang menghadap pengguna dan skenario Apidog untuk pengiriman webhook, logika coba lagi, dan idempoten. Scripting Apidog memverifikasi bahwa ID webhook duplikat ditolak, bahwa tanda tangan valid, dan bahwa jendela konsistensi akhirnya di bawah 30 detik.

Kesimpulan

Playwright sangat baik dalam alur browser. Ini tidak dibangun untuk pengujian API yang mendalam. Memasangkannya dengan Apidog memberi Anda:

• Satu spesifikasi OpenAPI sebagai kontrak antara kedua suite.
• Fixture bersama sehingga data pengujian tidak pernah menyimpang.
• Validasi tingkat skema pada setiap endpoint, di luar kode status saja.
• Server mock untuk pengembangan offline.
• Satu pipeline CI yang gagal pada regresi UI atau API.
• Intersepsi jaringan di Playwright, rantai skenario mendalam di Apidog.
• Kepemilikan yang jelas: insinyur UI memiliki spesifikasi Playwright, insinyur API memiliki skenario Apidog.

Mulailah dengan satu perjalanan kritis, seperti checkout atau pendaftaran. Sambungkan fixture Playwright, bangun skenario Apidog yang sesuai, jalankan keduanya di CI. Kembangkan dari sana. Unduh Apidog, impor spesifikasi OpenAPI Anda, dan Anda dapat menjalankan skenario pertama hari ini.

FAQ

Bisakah saya memvalidasi API dalam tes Playwright tanpa Apidog? Ya, menggunakan fixture request Playwright dan panggilan expect manual. Anda akan mencakup kode status dan beberapa bidang body. Untuk validasi skema, skenario berantai, mock, dan cakupan jalur error pada skala besar, alat khusus seperti Apidog lebih cepat dan menghasilkan lebih sedikit positif palsu. Lihat perbandingan alat pengujian API untuk insinyur QA kami untuk melihat trade-offnya.

Apakah saya memerlukan spesifikasi OpenAPI untuk menggunakan pengaturan ini? Anda memerlukannya untuk mendapatkan manfaat penuh. Tanpa spesifikasi, Anda masih dapat menjalankan Playwright dan Apidog secara berdampingan, tetapi Anda kehilangan sumber kebenaran bersama dan harus memelihara payload contoh di dua tempat. Membuat spesifikasi dari rute yang ada membutuhkan waktu satu atau dua hari.

Bagaimana cara menangani autentikasi di kedua alat? Gunakan langkah beforeAll yang mengambil token baru dari endpoint autentikasi Anda, lalu simpan dalam fixture Playwright dan variabel lingkungan Apidog. Rotasi token per pengujian sehingga token lama tidak menyebabkan ketidakstabilan.

Bisakah skenario Apidog sepenuhnya menggantikan Playwright? Tidak. Apidog sangat baik dalam alur kerja API tetapi tidak merender browser. Untuk penegasan UI (teks yang terlihat, tata letak, alur klik) Anda masih memerlukan Playwright. Kedua alat tersebut mencakup permukaan yang berbeda.

Bagaimana jika backend saya tidak memiliki lingkungan staging yang stabil? Gunakan server mock bawaan Apidog. Ini memutar mock stateful dari spesifikasi OpenAPI Anda dalam satu klik, mengembalikan respons contoh yang ditentukan dalam spesifikasi. Suite Playwright dan skenario Apidog Anda keduanya berjalan hijau terhadap mock, dan Anda beralih kembali ke backend yang sebenarnya ketika staging sehat.

Bagaimana cara menjaga CI tetap cepat saat suite bertambah? Tandai tes berdasarkan prioritas dan jalankan hanya @smoke pada setiap push. Jalankan regresi penuh dan suite skenario Apidog pada PR ke main dan pada jadwal malam. Paralelkan Playwright dengan workers: 4 dan skenario Apidog dengan flag --parallel CLI.

Apakah saya memerlukan paket Apidog berbayar untuk CI? Apidog CLI berjalan secara lokal dan di CI tanpa lisensi kursi untuk eksekusi skenario. Periksa halaman harga saat ini sebelum mengadopsi dalam skala besar. Tingkat gratis mencakup sebagian besar tim kecil.