Walse

Posted on May 12 • Originally published at apidog.com

Cara Memvalidasi Respons API dalam Pengujian Playwright

Tes Playwright Anda bisa lulus sementara API tetap salah. Contohnya: tombol login berhasil diklik, dashboard tampil, grafik dirender, tetapi pelanggan melaporkan angka grafik keliru. Setelah ditelusuri, API mengembalikan 200 OK dengan payload yang formatnya salah. Tes browser tidak menangkapnya karena hanya memeriksa UI. Untuk menutup celah ini, tambahkan penegasan API berbasis kontrak. Alat seperti Apidog membantu memvalidasi kontrak API, skema, dan semantik respons, lalu menjalankannya bersama suite Playwright di CI.

Coba Apidog hari ini

TL;DR

Gunakan kombinasi:

fixture request Playwright untuk pemeriksaan API ringan di dekat alur UI,
page.route untuk stub/mocking data UI,
skenario Apidog untuk validasi skema, kontrak, workflow API berantai, dan jalur error,
satu spesifikasi OpenAPI sebagai sumber kebenaran,
satu pipeline CI yang menjalankan Playwright dan Apidog secara paralel.

Hasilnya: perubahan kontrak API cepat gagal, baik di lapisan UI maupun API.

Pendahuluan

Playwright adalah kerangka kerja otomatisasi browser yang banyak digunakan, dan dokumentasi Playwright membuat pengujian API terlihat sederhana:

const response = await request.get('/api/orders');
expect(response.status()).toBe(200);

Masalahnya muncul saat suite membesar. Banyak tim berakhir dengan ratusan tes yang hanya memeriksa status code, tanpa validasi bentuk respons, tanpa sumber kebenaran bersama, dan tanpa cara menjalankan UI secara offline saat backend lambat atau rusak.

Pola yang lebih aman:

Jadikan openapi.yaml atau openapi.json sebagai kontrak.
Gunakan kontrak itu untuk fixture Playwright dan skenario Apidog.
Validasi respons di dua lapisan:
- Playwright untuk smoke check di sekitar aksi pengguna.
- Apidog untuk validasi skema dan workflow API yang lebih dalam.
Jalankan keduanya di CI.

Jika belum memasang alatnya, Unduh Apidog, lalu ikuti langkah implementasi di bawah.

Untuk konteks pemilihan alat, lihat juga alat pengujian API untuk insinyur QA.

Celah antara tes Playwright dan penegasan API

Tes Playwright biasanya melakukan hal berikut:

Login.
Navigasi ke halaman.
Pastikan elemen UI terlihat.
Pastikan teks, tombol, atau grafik muncul.

Itu cukup untuk memverifikasi alur pengguna, tetapi belum cukup untuk memverifikasi API di baliknya.

Tiga kegagalan umum yang sering lolos:

1. Regresi bentuk payload

Endpoint mengembalikan 200 OK, tetapi field berubah:

{
  "totalCount": 10
}

Padahal kontrak mengharapkan:

{
  "total_count": 10
}

UI mungkin tetap menampilkan angka default atau nilai kosong. Playwright bisa tetap lulus jika hanya memeriksa elemen terlihat.

2. Penyimpangan logika bisnis

Endpoint diskon seharusnya menerapkan diskon 15%, tetapi backend hanya mengembalikan 10%.

UI tetap menampilkan apa pun yang diberikan API. Jika tes hanya memeriksa “harga muncul”, bug ini bisa lolos.

3. Jalur error tidak diuji

Tes browser sering fokus pada happy path. Sementara API memiliki banyak cabang:

token kedaluwarsa,
rate limit,
konflik idempotensi,
validasi input gagal,
kegagalan parsial,
respons 4xx dan 5xx.

Cabang-cabang ini lebih cocok diuji di suite API khusus.

Pembagian tanggung jawab yang praktis:

Playwright: validasi alur UI, intersepsi jaringan, smoke check API di sekitar aksi pengguna.
Apidog: validasi skema, kontrak OpenAPI, workflow API berantai, jalur error, dan mock server.

Keduanya memakai spesifikasi OpenAPI yang sama. Untuk pendekatan contract-first, baca perkakas pengembangan API design-first.

Cara berbagi fixture antara Playwright dan Apidog

Mulai dari satu sumber kebenaran:

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

openapi.yaml mendefinisikan kontrak API. Folder fixtures/ menyimpan data uji yang digunakan oleh Playwright dan Apidog.

1. Buat fixture Playwright untuk API

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

Setelah itu, impor test dari file fixture ini, bukan langsung dari @playwright/test.

2. Gunakan fixture di spesifikasi Playwright

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

Playwright menangkap assertion semantik penting seperti:

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

Namun Playwright tidak ideal untuk validasi skema mendalam pada banyak endpoint. Di sinilah Apidog melengkapi.

3. Impor OpenAPI yang sama ke Apidog

Di Apidog:

Buka proyek.
Klik Import.
Pilih openapi.yaml.
Gunakan endpoint, schema, parameter, dan contoh request yang dihasilkan.
Simpan payload seperti fixtures/order.json sebagai variabel lingkungan atau dataset.

Skenario Apidog untuk POST /orders dapat menggunakan payload yang sama, lalu memvalidasi respons terhadap komponen Order di OpenAPI.

Contoh manfaatnya:

Playwright memastikan discount_pct benar.
Apidog memastikan semua field sesuai tipe.
Apidog memastikan enum valid.
Apidog memastikan required field tidak hilang.
Apidog menangkap field yang berubah nama atau berubah tipe.

Jika baru mulai dengan pengujian berbasis spesifikasi, lihat alur kerja API design-first.

Untuk tim yang masih memakai Postman, baca juga alternatif Postman yang di-host sendiri.

Menyiapkan alur kerja Apidog + Playwright

Berikut setup implementasi dari nol hingga CI.

Langkah 1: Simpan satu spesifikasi OpenAPI di repo

Letakkan file di root:

openapi.yaml

Perlakukan seperti kode:

wajib review PR,
breaking change perlu penanda versi,
schema harus diperbarui bersama perubahan endpoint,
contoh request/response harus realistis.

Jika belum punya OpenAPI, buat dari framework backend yang digunakan. Banyak framework seperti FastAPI dan NestJS bisa menghasilkan OpenAPI secara native. Apidog juga dapat membantu merekayasa balik spesifikasi dari traffic jika Anda mengimpor file HAR.

Langkah 2: Sambungkan Playwright

Instal Playwright:

npm init playwright@latest

Tambahkan script:

{
  "scripts": {
    "test:e2e": "playwright test"
  }
}

Contoh konfigurasi dasar:

// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  retries: 2,
  use: {
    baseURL: process.env.WEB_BASE_URL ?? 'http://localhost:3000',
    trace: 'on-first-retry',
  },
});

Prinsipnya:

satu skenario per file atau per blok test,
jangan membuat test terlalu panjang,
validasi API di Playwright hanya untuk smoke check penting,
validasi kontrak lengkap tetap di Apidog.

Langkah 3: Tambahkan skenario Apidog

Di Apidog:

Impor openapi.yaml.
Buat skenario untuk perjalanan pengguna penting:
- registrasi,
- login,
- checkout,
- refund,
- webhook,
- pembatalan order.
Rangkai response dari satu request menjadi input request berikutnya.
Tambahkan assertion pasca-respons.
Ekspor skenario agar bisa dijalankan via CLI.

Contoh eksekusi:

apidog-cli run ./apidog/scenarios/checkout.json

Langkah 4: Gunakan `page.route` untuk isolasi UI

Saat backend lambat atau Anda ingin menguji kondisi tertentu, stub respons jaringan di Playwright.

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

Catatan penting: stub page.route bukan pengganti tes API. Stub dipakai untuk isolasi UI. Validasi API tetap dijalankan di Apidog terhadap backend asli atau mock server.

Langkah 5: Jalankan Playwright dan Apidog di CI

Contoh GitHub Actions:

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

Jika salah satu job gagal, PR diblokir.

Gunakan reporter JUnit agar hasil bisa dianotasi di CI:

apidog-cli run ./apidog/scenarios/checkout.json --reporters cli,junit

Untuk optimasi workflow, lihat Dokumentasi GitHub Actions.

Untuk pembagian kepemilikan antara developer dan QA, lihat alat pengujian API untuk insinyur QA.

Langkah 6: Tambahkan deteksi schema drift

Tambahkan job harian yang membandingkan schema saat ini dengan schema yang dipakai di test.

Tujuannya: menangkap perubahan seperti:

- total_count: integer
+ totalCount: integer

atau:

- discount_pct: number
+ discount_pct: string

Jika schema berubah tanpa pembaruan test dan review, build harus gagal sebelum regresi masuk ke production.

Teknik lanjutan dan kiat profesional

Aktifkan Playwright trace

Di playwright.config.ts:

use: {
  trace: 'on-first-retry',
}

Saat test gagal di CI, Anda bisa melihat:

timeline aksi,
network request,
snapshot DOM,
console log.

Pasangkan dengan report HTML dari Apidog untuk melihat apakah sumber masalah ada di UI atau API.

Gunakan mock server Apidog untuk mode offline

Apidog dapat menjalankan mock server dari spesifikasi OpenAPI. Ini berguna saat:

backend sedang deploy,
database staging di-reset,
service dependency lambat,
developer frontend butuh data stabil.

Pola yang disarankan:

Playwright diarahkan ke mock saat menguji UI secara lokal.
Skenario Apidog tetap dijalankan terhadap backend asli di CI.
Kontrak tetap berasal dari OpenAPI yang sama.

Untuk pola yang berhubungan dengan pembuatan test, baca pembuatan tes API yang dibantu AI.

Batasi retry

Contoh konfigurasi Playwright:

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

Jika test butuh lebih dari dua retry untuk lulus, kemungkinan ada masalah stabilitas.

Prinsip yang sama berlaku untuk skenario API. Jangan menyembunyikan endpoint flaky dengan retry berlebihan.

Gagal tertutup pada schema drift

Jika Apidog menemukan ketidakcocokan schema, biarkan job keluar dengan status non-zero.

Hindari pola seperti:

apidog-cli run scenario.json || true

Jika benar-benar perlu soft-fail sementara, buat eksplisit:

ALLOW_SCHEMA_DRIFT=true

Dan minta komentar di PR yang menjelaskan alasannya.

Tag test berdasarkan prioritas

Gunakan tag untuk mengontrol durasi CI:

test('checkout happy path @smoke', async ({ page }) => {
  // ...
});

test('refund with expired token @regression', async ({ page }) => {
  // ...
});

Strategi umum:

@smoke: setiap push,
@regression: PR ke main,
@nightly: seluruh suite,
skenario Apidog lengkap: PR penting dan jadwal malam.

Kesalahan umum yang harus dihindari

Hanya memeriksa status === 200.
Tidak memvalidasi field body.
Hardcode bearer token di fixture.
Memakai fixture berbeda antara Playwright dan Apidog.
Tidak menjalankan Apidog CLI di CI.
Menganggap stub page.route sebagai pengganti tes API.
Menyimpan OpenAPI tetapi tidak menjadikannya bagian dari review PR.

Untuk kasus API yang non-deterministik, lihat cara menguji API agen AI.

Alternatif dan perbandingan alat

Stack	Kekuatan	Kelemahan	Terbaik untuk
Playwright saja dengan fixture `request`	Satu alat, cepat, native ke suite	Validasi skema dangkal, skenario berantai terbatas, cakupan error lemah	Tim kecil, API sederhana
Playwright + Postman	Ekosistem Postman matang, Newman CLI	Potensi dua sumber kebenaran, koleksi bisa menyimpang dari OpenAPI	Tim yang sudah memakai Postman
Playwright + Apidog	Satu sumber OpenAPI, validasi skema, mock, CLI untuk CI, workflow design-first	Dua alat untuk dipelajari, butuh disiplin spesifikasi	Tim yang ingin pengujian berbasis kontrak
Cypress + plugin cy-api	Akrab bagi pengguna Cypress	Pengujian API terbatas, bergantung plugin	Basis kode Cypress yang sudah ada
Pact	Kontrak kuat antar layanan	Kurva belajar lebih curam, butuh broker, tidak fokus UI	Organisasi microservice dengan banyak consumer internal

Jika Anda berasal dari alat lama seperti SoapUI atau ReadyAPI, lihat:

Pasangan Playwright + Apidog paling cocok untuk tim yang sudah memiliki OpenAPI, mengirimkan beberapa layanan, dan ingin satu pipeline CI yang menangkap regresi UI dan API.

Kasus penggunaan dunia nyata

Checkout e-commerce

Playwright menguji alur:

tambah produk ke keranjang,
isi alamat,
pilih metode pembayaran,
klik checkout,
lihat halaman konfirmasi.

Apidog menguji rantai API:

buat payment intent,
jalankan pemeriksaan fraud,
kurangi inventaris,
verifikasi order,
validasi respons error dari gateway pembayaran.

Jika payment gateway mengubah error_code menjadi errorCode, Apidog menangkapnya di lapisan kontrak. Playwright mungkin hanya melihat layar “checkout gagal”.

Dashboard SaaS dengan data grafik

Playwright memastikan grafik dirender dan filter UI bekerja.

Apidog memastikan endpoint agregasi mengembalikan:

total,
percentile,
time series,
jumlah data,
tipe field,
nilai enum.

Jika endpoint p99 latency menghilangkan outlier, grafik bisa tetap terlihat normal. Validasi API lebih mungkin menangkap kesalahan tersebut.

Workflow berbasis webhook

Playwright menguji portal pengguna.

Apidog menguji:

pengiriman webhook,
retry,
idempotensi,
signature,
duplicate event ID,
eventual consistency.

Contoh assertion yang relevan:

expect(response.status()).toBe(409);
expect(body.code).toBe('DUPLICATE_WEBHOOK');

Kesimpulan

Playwright sangat kuat untuk alur browser, tetapi bukan alat utama untuk pengujian API mendalam.

Gabungkan dengan Apidog untuk mendapatkan:

satu spesifikasi OpenAPI sebagai kontrak,
fixture bersama,
validasi skema di setiap endpoint,
mock server untuk pengembangan offline,
pipeline CI yang gagal pada regresi UI atau API,
page.route untuk isolasi UI,
skenario API berantai untuk validasi backend,
kepemilikan yang jelas antara frontend dan backend.

Mulai dari satu perjalanan kritis seperti checkout atau registrasi:

Tambahkan fixture Playwright.
Impor OpenAPI ke Apidog.
Buat skenario API yang sesuai.
Jalankan keduanya di CI.
Perluas cakupan secara bertahap.

Unduh Apidog, impor spesifikasi OpenAPI Anda, lalu jalankan skenario pertama.

FAQ

Bisakah saya memvalidasi API dalam tes Playwright tanpa Apidog?

Ya. Gunakan fixture request Playwright dan assertion manual:

const res = await request.get('/orders');
expect(res.status()).toBe(200);

const body = await res.json();
expect(body.orders).toBeDefined();

Namun untuk validasi skema, skenario berantai, mock, dan cakupan jalur error pada skala besar, alat khusus seperti Apidog lebih praktis. Lihat juga perbandingan alat pengujian API untuk insinyur QA.

Apakah saya memerlukan spesifikasi OpenAPI?

Untuk manfaat penuh, ya.

Tanpa OpenAPI, Anda masih bisa menjalankan Playwright dan Apidog berdampingan, tetapi akan kehilangan sumber kebenaran bersama. Akibatnya, payload contoh dan schema bisa menyimpang.

Bagaimana cara menangani autentikasi di kedua alat?

Ambil token baru dari endpoint autentikasi, lalu simpan di fixture Playwright dan variabel lingkungan Apidog.

Di Playwright:

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

  const body = await res.json();
  await use(body.access_token);
}

Jangan hardcode token di repo.

Bisakah skenario Apidog menggantikan Playwright?

Tidak.

Apidog menguji API. Playwright menguji browser. Untuk validasi UI seperti teks terlihat, klik, layout, form, dan navigasi, Anda tetap membutuhkan Playwright.

Bagaimana jika staging backend tidak stabil?

Gunakan mock server Apidog dari spesifikasi OpenAPI.

Pola praktis:

lokal: Playwright diarahkan ke mock,
CI: Apidog menguji backend asli,
fallback: jika staging rusak, jalankan smoke UI terhadap mock agar developer tetap bisa bekerja.

Bagaimana menjaga CI tetap cepat?

Gunakan strategi bertingkat:

smoke test pada setiap push,
regression test pada PR ke main,
full suite pada jadwal malam,
parallel worker untuk Playwright,
parallel execution untuk skenario Apidog jika tersedia.

Contoh Playwright:

export default defineConfig({
  workers: 4,
});

Apakah saya memerlukan paket Apidog berbayar untuk CI?

Apidog CLI dapat dijalankan secara lokal dan di CI untuk eksekusi skenario. Periksa halaman harga terbaru sebelum mengadopsi dalam skala besar, terutama jika tim membutuhkan fitur kolaborasi tambahan.