API-Testing mit Cypress und Playwright statt separatem Tool

1. Warum API-Tests im E2E-Framework Sinn ergeben

Viele Teams pflegen zwei getrennte Test-Ökosysteme: eine Postman- oder Insomnia-Collection für API-Tests und eine separate Cypress- oder Playwright-Suite für den Browser. Das Problem dabei ist selten das Tool selbst, sondern die Redundanz: Login-Logik, Umgebungsvariablen, Basis-URLs und Testdaten-Fixtures existieren doppelt und laufen bei jeder Änderung an der API auseinander. Ein API-Test in Cypress oder Playwright nutzt dieselbe Konfiguration, dieselben Umgebungsvariablen und denselben CI-Job wie die UI-Tests, wodurch ein einziger Wartungspfad übrig bleibt.

Der zweite Grund ist funktional: Sowohl cy.request() als auch Playwrights APIRequestContext laufen im selben Testkontext wie die Browser-Interaktion. Das bedeutet, ein Test kann per API einen Benutzer anlegen, sich per API einloggen, den Browser mit derselben Session öffnen und direkt auf der Checkout-Seite weiterarbeiten, ohne Registrierungsformular und Login-Maske durchklicken zu müssen. Diese Kombination aus API-Setup und UI-Verifikation ist der eigentliche Mehrwert, nicht der Ersatz von Postman durch ein neues Tool. Wo API-Test-Logik ohnehin schon in Cypress oder Playwright existiert, sinkt zudem die Einstiegshürde für Entwickler, die neue Tests schreiben, weil sie nur eine Sprache und ein Framework beherrschen müssen.

2. cy.request() in Cypress: direkte HTTP-Aufrufe ohne Browser-Overhead

cy.request() sendet einen HTTP-Request direkt aus dem Node-Prozess, der Cypress steuert, nicht aus dem gerenderten Browser-Fenster. Dadurch entfällt jeglicher Rendering-, Layout- und JavaScript-Ausführungs-Overhead: Ein Request, der im Browser über XHR mehrere hundert Millisekunden für DOM-Updates und Reflows braucht, ist als cy.request()-Aufruf oft in unter 50 Millisekunden erledigt. Cypress wartet automatisch auf die Antwort, prüft den Status-Code standardmäßig auf 2xx und liefert Body, Header und Status als reguläres, chainbares Objekt zurück.

Ein wichtiger Unterschied zu Fetch- oder Axios-Aufrufen im Testcode: cy.request() ist Teil der Cypress-Command-Queue und damit automatisch retry-fähig, wenn es mit Assertions kombiniert wird. Außerdem umgeht cy.request() standardmäßig Same-Origin-Beschränkungen und CORS-Prüfungen, weil der Request nicht aus dem Browser-Kontext kommt, praktisch für Backend-Aufrufe gegen eine andere Domain als die getestete Anwendung. Für Assertions auf JSON-Antworten reicht cy.request(...).its('body').should(...), ganz ohne cy.wait() auf ein Intercept-Alias.

// cypress/e2e/api/product-creation.cy.js
describe('Product API', () => {
  it('creates a product via REST API without touching the browser', () => {
    cy.request({
      method: 'POST',
      url: `${Cypress.env('apiUrl')}/rest/V1/products`,
      headers: { Authorization: `Bearer ${Cypress.env('adminToken')}` },
      body: {
        product: {
          sku: 'test-sku-001',
          name: 'Cypress Test Product',
          price: 19.99,
          status: 1,
          type_id: 'simple',
          attribute_set_id: 4
        }
      }
    }).then((response) => {
      expect(response.status).to.eq(200)
      expect(response.body.sku).to.eq('test-sku-001')
      // Store the id for cleanup in an after() hook
      Cypress.env('createdProductId', response.body.id)
    })
  })
})

3. Playwright APIRequestContext: eigener HTTP-Client neben der Page

Playwright trennt die API-Testing-Fähigkeiten klarer vom Browser als Cypress: Über request.newContext() oder den in Fixtures verfügbaren request-Parameter entsteht ein eigenständiger APIRequestContext, der unabhängig von einer Page existiert. Das erlaubt reine API-Testdateien ganz ohne Browser-Start, was sowohl Testlaufzeit als auch Ressourcenverbrauch in der CI reduziert. Playwright nutzt für APIRequestContext denselben Netzwerk-Stack wie für Browser-Requests, inklusive automatischer Cookie-Verwaltung, wenn Context und Page denselben storageState teilen.

Ein zentrales Feature ist die native expect(response).toBeOK()-Assertion sowie response.json() als Promise für den geparsten Body. Playwright unterstützt zudem request.newContext({ extraHTTPHeaders }) für global gültige Header wie Auth-Tokens, was das wiederholte Setzen von Headern in jedem einzelnen Request erspart. Da APIRequestContext-Aufrufe genau wie Page-Aktionen awaitbar sind, lassen sich API- und UI-Schritte im selben Test linear mischen, ohne Callback-Verschachtelung wie bei Cypress' Command-Queue-Modell.

// tests/api/cart-seeding.spec.ts
import { test, expect } from '@playwright/test'

test('seeds a cart via API then verifies totals in the UI', async ({ page, request }) => {
  // Step 1: seed cart data directly through the REST API
  const cartResponse = await request.post('/rest/V1/carts/mine/items', {
    headers: { Authorization: `Bearer ${process.env.CUSTOMER_TOKEN}` },
    data: { cartItem: { sku: 'test-sku-001', qty: 2, quote_id: process.env.QUOTE_ID } }
  })
  expect(cartResponse.ok()).toBeTruthy()
  const item = await cartResponse.json()
  expect(item.qty).toBe(2)

  // Step 2: switch to the browser and verify the same state visually
  await page.goto('/checkout/cart')
  await expect(page.getByTestId('cart-item-qty')).toHaveValue('2')
  await expect(page.getByTestId('cart-subtotal')).toContainText('39.98')
})

4. Setup via API, Verifikation über die UI

Der größte praktische Nutzen von API-Testing innerhalb der E2E-Suite liegt im Testdaten-Setup. Statt sich durch ein Registrierungsformular, einen Produktkatalog und ein Adressformular zu klicken, um einen Test-Checkout vorzubereiten, erledigt ein einziger cy.request()- oder APIRequestContext-Aufruf Kundenanlage, Produktanlage und Warenkorb-Befüllung in wenigen hundert Millisekunden. Der eigentliche Test beginnt dann genau an der Stelle, die tatsächlich geprüft werden soll, etwa dem Checkout-Formular oder der Bestellbestätigung, statt Vorbedingungen zu simulieren, die selbst fehleranfällig und langsam sind.

Diese Trennung erhöht auch die Testzuverlässigkeit: Ein UI-Setup-Schritt, der ein Formularfeld verändert, weil ein Kollege das Markup angepasst hat, lässt Dutzende nachgelagerte Tests fehlschlagen, obwohl die eigentlich zu testende Funktionalität unverändert ist. Ein API-Setup ist gegen kosmetische UI-Änderungen immun, solange der REST- oder GraphQL-Endpunkt stabil bleibt. In der Praxis empfiehlt sich ein klares Muster: alles, was nicht Gegenstand des Tests ist, per API vorbereiten; alles, was tatsächlich geprüft werden soll, über die UI ausführen und verifizieren. Ein beforeEach-Hook mit API-Setup ist damit oft der wirkungsvollste Hebel, um eine langsame Suite spürbar zu beschleunigen.

5. Authentifizierung und Session-Handling zwischen API und UI

Die naheliegende, aber langsame Variante ist, für jeden Test das Login-Formular auszufüllen. Schneller und robuster ist es, sich per API ein Token oder Session-Cookie zu holen und dieses direkt in den Browser-Kontext zu injizieren. In Cypress geschieht das über cy.session() in Kombination mit einem cy.request()-Login: Das Ergebnis wird über die Testläufe hinweg gecacht, sodass nur der erste Test tatsächlich einen Login-Request auslöst. In Playwright übernimmt storageState dieselbe Rolle, ein einmal per API oder UI erzeugter Zustand mit Cookies und localStorage wird als JSON-Datei gespeichert und von allen folgenden Tests wiederverwendet.

Für Token-basierte APIs wie die Magento REST API reicht ein POST auf /rest/V1/integration/customer/token oder /rest/V1/integration/admin/token, um ein Bearer-Token zu erhalten, das anschließend sowohl für weitere API-Aufrufe als auch, über einen injizierten localStorage-Eintrag oder ein Cookie, für die authentifizierte Browser-Session verwendet wird. Wichtig ist, Tokens pro Test-Worker zu isolieren, wenn Tests parallel laufen, damit sich zwei parallele Testläufe nicht gegenseitig ausloggen. Abgelaufene Tokens sollten in einer zentralen Fixture erneuert werden, statt in jedem einzelnen Test einen neuen Login-Call zu duplizieren.

// cypress/support/e2e.js: reuse an API-issued token as a cached UI session
Cypress.Commands.add('loginByApi', (email, password) => {
  cy.session([email, password], () => {
    cy.request('POST', `${Cypress.env('apiUrl')}/rest/V1/integration/customer/token`, {
      username: email,
      password: password
    }).then((response) => {
      const token = response.body
      window.localStorage.setItem('mage-customer-token', token)
      cy.setCookie('mironsoft_customer_logged_in', '1')
    })
  }, {
    validate: () => {
      cy.window().its('localStorage.mage-customer-token').should('exist')
    }
  })
})

// Usage in a spec: skip the login form entirely
beforeEach(() => {
  cy.loginByApi('customer@mironsoft.de', 'Test1234!')
  cy.visit('/checkout')
})

6. Performance: API-Tests vs. vollständige Browser-E2E-Tests

Der Geschwindigkeitsunterschied zwischen einem reinen API-Test und einem vollständigen Browser-E2E-Test ist in der Praxis eine Größenordnung. Ein Browser-Test, der eine Produktseite lädt, Bilder und Fonts rendert, Alpine.js oder React initialisiert und auf sichtbare DOM-Elemente wartet, braucht typischerweise zwei bis acht Sekunden pro Testschritt. Derselbe Zustand über cy.request() oder APIRequestContext hergestellt, läuft in 50 bis 300 Millisekunden, abhängig von Netzwerk-Latenz und Server-Antwortzeit, ganz ohne Rendering-Kosten.

In einer Suite mit 200 E2E-Tests, von denen jeder im Schnitt drei bis fünf UI-Setup-Schritte durch API-Aufrufe ersetzt, summiert sich das schnell auf mehrere Minuten eingesparte Laufzeit pro vollständigem Testlauf. Wichtig ist die Unterscheidung: Ein reiner API-Test prüft nicht, ob die UI die Daten korrekt darstellt, nur ob das Backend korrekt antwortet. Wer API-Tests als Ersatz für UI-Tests missversteht, verliert Testabdeckung für Rendering-Bugs, CSS-Regressionen und JavaScript-Fehler. Der Performance-Gewinn entsteht nicht durch weniger Testabdeckung, sondern durch das Verschieben von reinem Setup-Aufwand aus dem Browser in die API-Schicht, während die eigentliche UI-Prüfung weiterhin im Browser stattfindet.

7. Testdaten-Management und Cleanup

API-generierte Testdaten müssen genauso konsequent aufgeräumt werden wie UI-generierte, sonst füllt sich die Testumgebung mit verwaisten Produkten, Bestellungen und Kundenkonten, die spätere Tests durch Namenskollisionen oder falsche Zählwerte stören. Ein robustes Muster: Jeder Testlauf erzeugt Entitäten mit einem eindeutigen Präfix, etwa einem Zeitstempel oder einer Test-Run-ID im SKU oder E-Mail-Feld, und ein after()- oder afterAll()-Hook löscht alle in diesem Lauf erzeugten IDs wieder über die API.

Für Magento-Projekte bewährt sich zusätzlich ein separater Datenbank-Snapshot oder ein bin/magento-Reset-Skript, das vor jedem CI-Lauf eine saubere Basis wiederherstellt, statt sich vollständig auf Test-eigenes Cleanup zu verlassen. So bleiben fehlgeschlagene Cleanup-Läufe, etwa durch einen abgebrochenen Testprozess, ohne Langzeitfolgen für die Umgebung. API-Cleanup direkt im Test ist trotzdem sinnvoll, weil es schneller ist als ein voller Datenbank-Reset und lokale Testläufe während der Entwicklung nicht ausbremst. Ein zentrales cleanupRegistry-Fixture-Objekt, das erzeugte IDs sammelt und am Testende iteriert, verhindert vergessene Löschaufrufe in einzelnen Testdateien.

// tests/fixtures/cleanup.ts: Playwright fixture that tracks and deletes created entities
import { test as base } from '@playwright/test'

type CleanupFixture = {
  registerForCleanup: (endpoint: string, id: string | number) => void
}

export const test = base.extend<CleanupFixture>({
  registerForCleanup: async ({ request }, use) => {
    const created: Array<{ endpoint: string; id: string | number }> = []
    await use((endpoint, id) => created.push({ endpoint, id }))

    // Runs after the test, regardless of pass/fail
    for (const entry of created.reverse()) {
      await request.delete(`${entry.endpoint}/${entry.id}`).catch(() => {
        // Cleanup failures are logged, not fatal, snapshot reset is the safety net
        console.warn(`Cleanup failed for ${entry.endpoint}/${entry.id}`)
      })
    }
  }
})

8. CI/CD-Integrationsmuster für API-lastige Suiten

Weil API-Tests keinen Browser benötigen, lassen sie sich in der CI als eigene, deutlich schnellere Job-Stufe vor den vollständigen Browser-E2E-Tests ausführen. Ein typisches Pipeline-Muster: Ein schneller API-Smoke-Test-Job läuft bei jedem Commit und prüft innerhalb von unter einer Minute, ob zentrale Endpunkte erreichbar sind und erwartete Antwortstrukturen liefern. Erst danach startet der langsamere, ressourcenintensivere Browser-E2E-Job, oft nur bei Pull Requests oder vor einem Deployment, um Rechenzeit zu sparen.

Für parallele Ausführung ist wichtig, dass API-Setup-Aufrufe pro Worker isoliert laufen. Cypress' --parallel-Flag mit dem Dashboard-Service und Playwrights --shard-Option verteilen Tests auf mehrere Maschinen, wodurch geteilte Testdaten wie ein global wiederverwendeter Kundenaccount zu Race Conditions führen können. Die Lösung ist, Testdaten pro Worker-Index oder Shard-ID zu parametrisieren. Secrets für API-Zugriffe, etwa Admin-Tokens oder Integrationsschlüssel, gehören in CI-Secrets-Manager statt in Testcode, und ein separates, isoliertes Testsystem statt der Produktions-API verhindert versehentliche Seiteneffekte auf echte Daten.

# .github/workflows/e2e.yml: fast API smoke stage before the full browser suite
name: E2E Tests
on: [pull_request]

jobs:
  api-smoke:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm ci
      - run: npx playwright test tests/api --project=api
        env:
          API_BASE_URL: ${{ secrets.STAGING_API_URL }}
          ADMIN_TOKEN: ${{ secrets.STAGING_ADMIN_TOKEN }}

  browser-e2e:
    needs: api-smoke
    runs-on: ubuntu-latest
    strategy:
      matrix:
        shard: [1, 2, 3, 4]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npx playwright test --shard=${{ matrix.shard }}/4
        env:
          API_BASE_URL: ${{ secrets.STAGING_API_URL }}

9. Wann ein dediziertes API-Tool trotzdem sinnvoll bleibt

Trotz aller Vorteile ersetzt cy.request() oder APIRequestContext ein dediziertes API-Tool wie Postman oder Insomnia nicht vollständig. Für explorative API-Arbeit, bei der ein Entwickler schnell verschiedene Parameter-Kombinationen ausprobiert, bevor überhaupt ein Test geschrieben wird, ist eine grafische Oberfläche mit Request-Historie oft produktiver als ein Testskript, das erst geschrieben und ausgeführt werden muss. Auch die Zusammenarbeit im Team profitiert von geteilten Collections: Postman-Workspaces erlauben es, API-Dokumentation, Beispiel-Requests und Umgebungsvariablen mit nicht-technischen Stakeholdern wie Produktmanagern oder QA-Testern zu teilen, die keinen Zugriff auf den Testcode-Repository haben oder keine Testsuite lokal ausführen können.

Die pragmatische Antwort ist meist eine Kombination: Postman oder Insomnia für schnelles, exploratives Testen neuer Endpunkte und für die Dokumentation der API gegenüber dem Team, cy.request() oder APIRequestContext für automatisierte, versionierte Tests, die in der CI laufen und Regressionen zuverlässig erkennen. Wer eine Postman-Collection ohnehin pflegt, kann sie über den Postman-zu-OpenAPI-Export oder direkte JSON-Exporte teilweise in Playwright- oder Cypress-Testfälle überführen, um Doppelarbeit zu vermeiden.

Die Tabelle zeigt: Keines der drei Werkzeuge ersetzt die beiden anderen vollständig. Die stärkste Testarchitektur kombiniert alle drei gezielt, API-Tests im E2E-Framework für schnelles, automatisiertes Setup und Regressionsschutz, ein dediziertes Tool für explorative Arbeit und Teamkommunikation, und Browser-E2E-Tests dort, wo tatsächlich die sichtbare Nutzererfahrung geprüft werden muss.

10. Zusammenfassung

Die Kombination aus cy.request() in Cypress und APIRequestContext in Playwright löst ein konkretes Problem: langsames, fehleranfälliges UI-Setup, das echte Testzeit von der eigentlichen Prüfung abzieht. API-Aufrufe direkt aus dem E2E-Framework bauen Testdaten in Millisekunden statt Sekunden auf, teilen Auth-Sessions zwischen API und Browser über cy.session() oder storageState, und laufen im selben CI-Job wie die UI-Tests, ohne doppelte Konfiguration. Der Performance-Gewinn ist real und in Suiten mit hunderten Tests spürbar in Minuten, nicht nur Millisekunden.

Ein dediziertes API-Tool wie Postman verliert dadurch nicht seine Daseinsberechtigung, es verschiebt sich in eine andere Rolle: explorative Arbeit, API-Dokumentation und Zusammenarbeit mit nicht-technischen Stakeholdern bleiben Domänen, in denen eine grafische Oberfläche mit geteilten Collections überlegen ist. Die robusteste Strategie trennt bewusst, was automatisiert und versioniert in der Testsuite laufen soll, von dem, was manuell und explorativ im Team besprochen wird, statt eines pauschalen Ersatzes in eine der beiden Richtungen.

11. FAQ: API-Testing mit Cypress und Playwright