DEV Community

Cover image for API Response Validierung in Playwright Tests
Emre Demir
Emre Demir

Posted on • Originally published at apidog.com

API Response Validierung in Playwright Tests

Ihre Playwright-Tests sind grün: Login klickbar, Dashboard sichtbar, Diagramm gerendert. Trotzdem meldet ein Kunde falsche Diagrammwerte. Die Ursache: Die API hat 200 OK mit fehlerhafter Nutzlast geliefert. Ihre E2E-Suite hat nur geprüft, ob UI-Elemente erscheinen, nicht ob die API semantisch korrekt antwortet. Diese Lücke schließen API-Zusicherungen. Tools wie Apidog helfen dabei, API-Verträge, Schemata und Antwortlogik genauso systematisch zu validieren wie UI-Flows — und beides gemeinsam in CI auszuführen.

Testen Sie Apidog noch heute

TL;DR

Kombinieren Sie Playwrights request-Fixture und page.route mit Apidog-Szenarien, die dieselbe OpenAPI-Spezifikation verwenden. So validieren Sie APIs auf zwei Ebenen:

  • Playwright prüft UI-nahe API-Smoke-Checks.
  • Apidog prüft Schema-Konformität, verkettete Workflows und Fehlerpfade.
  • Beide Suiten laufen in CI gegen denselben Vertrag.

Einführung

Playwright ist für viele Teams das Standard-Framework für Browser-Automatisierung. Die Playwright-Dokumentation zeigt, wie einfach API-Tests aussehen können:

const response = await request.get('/users');
expect(response.status()).toBe(200);
Enter fullscreen mode Exit fullscreen mode

Das skaliert aber nur begrenzt. In größeren Projekten entstehen schnell Tests, die Statuscodes prüfen, aber keine Antwortstruktur. Dazu kommen doppelte Testdaten, fehlende Mocks und keine gemeinsame Quelle der Wahrheit zwischen Browser- und API-Tests.

Die robustere Lösung:

  1. Behandeln Sie Ihre OpenAPI-Spezifikation als Vertrag.
  2. Nutzen Sie sie für Playwright-Fixtures und Testdaten.
  3. Importieren Sie dieselbe Spezifikation in Apidog.
  4. Führen Sie Playwright- und Apidog-Suites gemeinsam in CI aus.

Wenn Sie Apidog lokal installieren möchten, laden Sie Apidog herunter und fahren Sie dann mit den folgenden Schritten fort.

In diesem Beitrag bauen Sie ein Setup mit:

  • gemeinsam genutzten Fixtures,
  • API-Assertions in Playwright,
  • Apidog-Szenarien für Schema- und Workflow-Validierung,
  • page.route-Mocks,
  • CI-Integration,
  • Drift-Erkennung.

Für mehr Kontext zu API-Test-Tools siehe auch API-Test-Tools für QA-Ingenieure.

Die Lücke zwischen Playwright-Tests und API-Zusicherungen

Ein typischer Playwright-Test macht Folgendes:

  1. Benutzer anmelden.
  2. Seite öffnen.
  3. UI-Element sichtbar prüfen.

Das validiert den Benutzerfluss, aber nicht zwingend die zugrunde liegende API.

Typische Fehler, die dadurch durchrutschen:

1. Payload-Regressionen

Ein Endpoint gibt weiterhin 200 OK zurück, aber ein Feld wurde geändert:

{
  "totalCount": 42
}
Enter fullscreen mode Exit fullscreen mode

statt:

{
  "total_count": 42
}
Enter fullscreen mode Exit fullscreen mode

Die UI zeigt vielleicht trotzdem irgendeinen Wert an. Der Playwright-Test bleibt grün.

2. Drift in der Geschäftslogik

Ein Rabatt-Endpunkt gibt 10 % statt 15 % Rabatt zurück. Die UI rendert korrekt, aber die Berechnung ist falsch.

3. Fehlende Fehlerpfad-Abdeckung

E2E-Tests laufen meist über den Happy Path. APIs haben aber viele Fehlerfälle:

  • 401 Unauthorized
  • 403 Forbidden
  • 409 Conflict
  • 429 Too Many Requests
  • 500 Internal Server Error
  • abgelaufene Tokens
  • Idempotenzkonflikte
  • Teilfehler

Diese Fälle gehören in eine API-Test-Suite.

Die sinnvolle Aufteilung:

  • Playwright: UI-Flows, Netzwerk-Interception, API-Smoke-Checks an Benutzeraktionen.
  • Apidog: Schema-Validierung, verkettete API-Workflows, Vertrags-Compliance, Fehlerpfade.

Beide Suiten verwenden dieselbe OpenAPI-Spezifikation. Damit vermeiden Sie zwei Versionen der Wahrheit. Mehr zum Contract-First-Ansatz finden Sie unter Design-First-API-Workflows.

Wenn Sie von Postman migrieren möchten, lesen Sie auch selbst gehostete Postman-Alternativen.

Fixtures zwischen Playwright und Apidog teilen

Legen Sie Ihre OpenAPI-Spezifikation im Repository-Root ab:

openapi.yaml
Enter fullscreen mode Exit fullscreen mode

oder:

openapi.json
Enter fullscreen mode Exit fullscreen mode

Diese Datei ist die Quelle der Wahrheit.

Playwright nutzt sie indirekt über Fixtures und Beispiel-Payloads. Apidog importiert sie direkt, um Szenarien, Requests und Schema-Checks zu erzeugen.

Beispielstruktur:

.
├── openapi.yaml
├── fixtures
│   └── order.json
├── tests
│   ├── fixtures
│   │   └── api.ts
│   └── orders.spec.ts
└── apidog
    └── scenarios
        └── checkout.json
Enter fullscreen mode Exit fullscreen mode

Playwright-Fixture anlegen 

// 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 };
Enter fullscreen mode Exit fullscreen mode

Ab jetzt importieren Sie test nicht mehr direkt aus @playwright/test, sondern aus Ihrer Fixture-Datei.

API-Assertion in Playwright schreiben 

// 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);
});
Enter fullscreen mode Exit fullscreen mode

Playwright prüft hier gezielt die geschäftlich relevante Assertion:

discount_pct: 15
Enter fullscreen mode Exit fullscreen mode

Apidog prüft zusätzlich das vollständige JSON-Schema gegen die Order-Komponente in openapi.yaml:

  • Feldtypen,
  • Pflichtfelder,
  • Enums,
  • verschachtelte Objekte,
  • fehlende oder unerwartete Felder.

So ergänzen sich beide Ebenen.

Mehr zum spezifikationsgetriebenen Testen finden Sie unter Design-First-API-Workflows.

Apidog + Playwright Workflow einrichten

Schritt 1: OpenAPI-Spezifikation zentral ablegen

Legen Sie openapi.yaml im Repository-Root ab.

Behandeln Sie die Datei wie Code:

  • Änderungen nur per Pull Request.
  • Breaking Changes explizit markieren.
  • Review durch Backend- und Frontend-Team.
  • Beispiel-Payloads aktuell halten.

Wenn Sie noch keine Spezifikation haben, generieren Sie einen Entwurf aus Ihrem Framework. Viele Frameworks können OpenAPI nativ ausgeben, z. B. FastAPI oder NestJS. Alternativ kann Apidog aus importiertem Traffic bzw. HAR-Dateien eine Spezifikation ableiten.

Schritt 2: Playwright verdrahten

Installieren Sie Playwright:

npm init playwright@latest
Enter fullscreen mode Exit fullscreen mode

Fügen Sie ein Testskript hinzu:

{
  "scripts": {
    "test:e2e": "playwright test"
  }
}
Enter fullscreen mode Exit fullscreen mode

Beispiel für 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',
  },
});
Enter fullscreen mode Exit fullscreen mode

Schritt 3: Apidog-Szenarien erstellen

In Apidog:

  1. Projekt öffnen.
  2. openapi.yaml importieren.
  3. Szenario pro kritischem Pfad erstellen, z. B.:
    • Registrierung,
    • Login,
    • Checkout,
    • Rückerstattung,
    • Webhook-Zustellung.
  4. Requests verketten.
  5. Variablen aus vorherigen Antworten extrahieren.
  6. Schema-Validierung aktivieren.
  7. Szenario für CI exportieren.

Beispielausführung per CLI:

apidog-cli run ./apidog/scenarios/checkout.json
Enter fullscreen mode Exit fullscreen mode

Schritt 4: Netzwerk-Interception in Playwright nutzen

Wenn die UI nicht gegen ein Live-Backend laufen soll, stubben Sie API-Antworten mit page.route.

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);
});
Enter fullscreen mode Exit fullscreen mode

Wichtig: page.route ersetzt keine API-Tests. Es isoliert die UI. Die echte API validieren Sie weiterhin mit Apidog-Szenarien.

Schritt 5: CI-Workflow hinzufügen

Beispiel mit 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
Enter fullscreen mode Exit fullscreen mode

Ein Fehler in Playwright oder Apidog blockiert den Merge.

Nutzen Sie JUnit-Reports, damit CI-Tools fehlgeschlagene Assertions direkt anzeigen:

apidog-cli run ./apidog/scenarios/checkout.json --reporters cli,junit
Enter fullscreen mode Exit fullscreen mode

Die GitHub Actions-Dokumentation zeigt, wie Sie Matrix-Builds, Caching und parallele Jobs ergänzen.

Für Teams ohne dedizierte QA-Rolle hilft API-Test-Tool für QA-Ingenieure bei der Aufteilung der Verantwortlichkeiten.

Schritt 6: Schema-Drift erkennen

Planen Sie einen täglichen CI-Job, der die aktuelle openapi.yaml gegen die zuletzt getestete Version vergleicht.

Ziel:

  • geänderte Feldtypen erkennen,
  • entfernte Pflichtfelder erkennen,
  • neue Pflichtfelder erkennen,
  • geänderte Enums erkennen,
  • Build vor der Ausführung teurer Tests abbrechen.

Damit fangen Sie genau die Fehlerklasse ab, die sonst als 200 OK mit falscher Nutzlast durchläuft.

Fortgeschrittene Techniken und Profi-Tipps

Playwright Trace Viewer aktivieren

Setzen Sie in playwright.config.ts:

trace: 'on-first-retry'
Enter fullscreen mode Exit fullscreen mode

Bei einem fehlgeschlagenen Retry erhalten Sie:

  • DOM-Snapshots,
  • Netzwerkaufrufe,
  • Screenshots,
  • Konsolenlogs,
  • Timeline des Tests.

Kombinieren Sie das mit Apidog-Reports:

apidog-cli run ./apidog/scenarios/checkout.json --report html
Enter fullscreen mode Exit fullscreen mode

So erkennen Sie schneller, ob zuerst die UI oder die API gebrochen ist.

Apidog Mock-Server für lokale Entwicklung nutzen

Apidog kann aus Ihrer OpenAPI-Spezifikation einen Mock-Server starten. Verwenden Sie ihn, wenn:

  • Staging instabil ist,
  • das Backend gerade deployed wird,
  • Testdaten zurückgesetzt wurden,
  • Frontend-Entwicklung nicht blockieren soll.

Playwright läuft gegen den Mock. Apidog-Szenarien validieren zusätzlich das echte Backend, sobald es verfügbar ist.

Mehr zu Mocks und generierten Tests finden Sie unter KI-gestützter API-Testgenerierung.

Retries begrenzen

Empfehlung für Playwright:

retries: 2
Enter fullscreen mode Exit fullscreen mode

Wenn ein Test erst nach mehreren Versuchen grün wird, ist er instabil. Erhöhen Sie Retries nicht dauerhaft, sondern beheben Sie die Ursache.

Für API-Szenarien gilt dasselbe: maximal ein Retry pro Request, wenn Netzwerkflakiness realistisch ist.

Schema-Drift als Build-Fehler behandeln

Wenn Apidog eine Schema-Abweichung erkennt, sollte der CI-Job fehlschlagen.

Falls Sie temporär Soft-Fails benötigen, kapseln Sie das explizit:

ALLOW_SCHEMA_DRIFT=true
Enter fullscreen mode Exit fullscreen mode

Und verlangen Sie im Pull Request eine Begründung.

Tests nach Priorität taggen

In Playwright können Sie Tags im Testnamen nutzen:

test('@smoke user can log in', async ({ page }) => {
  // ...
});
Enter fullscreen mode Exit fullscreen mode

Dann gezielt ausführen:

npx playwright test --grep @smoke
Enter fullscreen mode Exit fullscreen mode

Praktische Aufteilung:

  • @smoke: bei jedem Push.
  • @regression: bei Pull Requests zum Main-Branch.
  • @nightly: vollständige Suite inklusive aller Apidog-Szenarien.

Häufige Fehler vermeiden

Vermeiden Sie diese Muster:

  • Nur status === 200 prüfen.
  • Bearer-Tokens hartcodieren.
  • Unterschiedliche Fixture-Dateien für Playwright und Apidog verwenden.
  • Apidog CLI in CI überspringen.
  • page.route-Stubs als Ersatz für echte API-Tests behandeln.
  • OpenAPI-Spezifikation nur nachträglich aktualisieren.
  • Fehlerpfade nicht testen.

Für KI-basierte Workflows siehe auch wie man KI-Agenten-APIs testet.

Alternativen und Tool-Vergleich

Stack Stärken Schwächen Am besten geeignet für
Playwright allein (request-Fixture) Ein Tool, schnell, nativ in der Suite Oberflächliche Schema-Validierung, keine verketteten Szenarien, schwache Fehlerpfad-Abdeckung Kleine Teams, einfache APIs
Playwright + Postman Reifes Postman-Ökosystem, Newman CLI Zwei Quellen der Wahrheit, Postman-Sammlungen können von OpenAPI abweichen, Zusammenarbeit je nach Setup kostenpflichtig Teams, die bereits tief in Postman arbeiten
Playwright + Apidog Eine OpenAPI-Quelle, Schema-Validierung, Mocks, CLI für CI, Design-First-Workflow Zwei Tools zum Erlernen, erfordert Spezifikationsdisziplin Teams, die spezifikationsgetriebenes API- und UI-Testing wollen
Cypress + cy-api Plugin Vertraut für Cypress-Nutzer API-Tests sind eingeschränkter, Plugins weniger ausgereift Bestehende Cypress-Codebasen
Pact Starke Consumer-Driven Contracts zwischen Services Hohe Lernkurve, Broker-Infrastruktur, nicht UI-fokussiert Microservice-Organisationen mit vielen internen API-Konsumenten

Wenn Sie von älteren SOAP-Tools kommen, helfen diese Migrationsartikel:

Für lokale API-Workflows siehe auch REST-Client VSCode-Erweiterungen.

Die Kombination aus Playwright und Apidog passt besonders gut, wenn Ihr Team:

  • eine OpenAPI-Spezifikation pflegt,
  • mehrere Services bereitstellt,
  • UI- und API-Regressionen in einer Pipeline erkennen möchte,
  • Mocking für lokale Entwicklung benötigt,
  • API-Verträge explizit testen will.

Praktische Anwendungsfälle

E-Commerce-Checkout

Ein Handelsteam testet den Warenkorb-zu-Bestätigung-Flow mit Playwright. Apidog validiert zusätzlich:

  • Zahlungsabsicht,
  • Betrugsprüfung,
  • Bestandsreduzierung,
  • Rückerstattungs-API.

Als ein Payment-Gateway ein Feld von error_code zu errorCode änderte, erkannte Apidog die Schema-Abweichung früh. Playwright hätte nur einen generischen Checkout-Fehler gezeigt.

SaaS-Dashboard mit Diagrammdaten

Ein Analyseprodukt validiert die UI mit Playwright-Snapshots. Apidog prüft die Aggregationsendpunkte:

  • Summen,
  • Perzentile,
  • Zeitreihen,
  • Grenzwerte.

Ein Fehler im p99-Latenz-Endpunkt wurde auf API-Ebene entdeckt, obwohl das Diagramm optisch korrekt aussah.

Webhook-gesteuerter Workflow

Ein Fintech-Team nutzt Playwright für das Portal und Apidog für:

  • Webhook-Zustellung,
  • Wiederholungslogik,
  • Signaturprüfung,
  • Idempotenz,
  • Eventual Consistency.

Apidog-Skripte prüfen, ob doppelte Webhook-IDs abgelehnt werden und Signaturen korrekt validiert werden.

Fazit

Playwright ist stark für Browser-Flows. Für tiefgehende API-Validierung brauchen Sie eine zusätzliche API-Testschicht.

Mit Playwright + Apidog erhalten Sie:

  • eine OpenAPI-Spezifikation als gemeinsamen Vertrag,
  • geteilte Fixtures,
  • Schema-Validierung über Statuscodes hinaus,
  • Mock-Server für lokale Entwicklung,
  • CI-Fehler bei UI- oder API-Regressionen,
  • Netzwerk-Interception in Playwright,
  • verkettete API-Szenarien in Apidog,
  • klare Zuständigkeiten zwischen UI- und API-Tests.

Starten Sie klein:

  1. Wählen Sie einen kritischen Pfad, z. B. Checkout oder Registrierung.
  2. Legen Sie gemeinsame Fixtures an.
  3. Schreiben Sie einen Playwright-Test mit API-Assertion.
  4. Erstellen Sie das passende Apidog-Szenario.
  5. Führen Sie beides in CI aus.

Danach erweitern Sie Endpoint für Endpoint.

Häufig gestellte Fragen

Kann ich APIs in Playwright-Tests ohne Apidog validieren?

Ja. Verwenden Sie Playwrights request-Fixture und manuelle expect-Assertions. Das reicht für Statuscodes und einzelne Body-Felder. Für Schema-Validierung, verkettete Szenarien, Mocks und Fehlerpfade im größeren Maßstab ist ein dediziertes Tool wie Apidog effizienter. Siehe auch API-Test-Tools für QA-Ingenieure.

Benötige ich eine OpenAPI-Spezifikation?

Für den vollen Nutzen: ja. Ohne Spezifikation können Playwright und Apidog zwar nebeneinander laufen, aber Sie verlieren die gemeinsame Quelle der Wahrheit und müssen Payloads doppelt pflegen.

Wie gehe ich mit Authentifizierung um?

Rufen Sie pro Testlauf ein frisches Token vom Auth-Endpunkt ab.

In Playwright:

  • Token in einer Fixture speichern.
  • Per Header in Requests verwenden.

In Apidog:

  • Token in einer Umgebungsvariable speichern.
  • In nachfolgenden Requests referenzieren.

Vermeiden Sie hartcodierte Tokens.

Können Apidog-Szenarien Playwright ersetzen?

Nein. Apidog testet API-Workflows, rendert aber keinen Browser. Für sichtbare UI, Klickpfade, Layout und Frontend-Interaktionen brauchen Sie weiterhin Playwright.

Was mache ich bei instabilem Staging?

Nutzen Sie den Apidog Mock-Server. Er erzeugt Antworten aus der OpenAPI-Spezifikation. Playwright kann gegen den Mock laufen, während Apidog-Szenarien später wieder gegen das echte Backend ausgeführt werden.

Wie halte ich CI schnell?

Nutzen Sie Prioritäten:

  • @smoke bei jedem Push,
  • Regression bei Pull Requests,
  • vollständige Apidog-Suite nightly.

Parallelisieren Sie Playwright über Worker:

workers: 4
Enter fullscreen mode Exit fullscreen mode

Und führen Sie Apidog-Szenarien parallel aus, falls Ihre CLI-Konfiguration das vorsieht.

Benötige ich einen kostenpflichtigen Apidog-Plan für CI?

Prüfen Sie vor der Einführung die aktuelle Preisseite und Lizenzbedingungen. Für kleinere Teams kann die kostenlose Stufe ausreichen; für größere Setups sollten Sie die CI- und Kollaborationsanforderungen vorher validieren.

Top comments (0)