Cypress API Testing - REST APIs mit cy.request() und cy-api testen

Cypress eignet sich nicht nur für End-to-End-Tests im Browser. Mit cy.request() können wir APIs direkt ansprechen und deren Antworten testen. In diesem Beitrag bauen wir anhand der Open-Meteo-API Schritt für Schritt echte API-Tests mit Cypress auf und schauen uns zusätzlich das Plugin @bahmutov/cy-api an.

Wenn wir mit Cypress arbeiten, denken wir zunächst an Browser-Tests.

Wir öffnen eine Seite:

cy.visit('/weather');

Wir suchen ein Eingabefeld:

cy.get('[data-cy=city]')
    .type('Berlin');

Und anschließend klicken wir auf einen Button:

cy.get('[data-cy=search]')
    .click();

Das ist ein klassischer Cypress-E2E-Test. Aber was passiert eigentlich im Hintergrund? Unsere Wetteranwendung muss irgendwoher ihre Wetterdaten bekommen.

Vielleicht sieht die Architektur ungefähr so aus:

Browser
   │
   │ GET /weather
   ▼
Unsere Wetter-App
   │
   │ API Request
   ▼
Open-Meteo API
   │
   │ JSON
   ▼
Unsere Wetter-App
   │
   ▼
Browser

Wenn wir ausschließlich die Benutzeroberfläche testen, überprüfen wir am Ende vor allem das Ergebnis, das beim Benutzer ankommt.

Wir wissen dann aber nicht unbedingt, ob die API selbst korrekt funktioniert. Genau hier kommt API Testing mit Cypress ins Spiel.

Cypress kann HTTP-Endpunkte direkt ansprechen. Dafür benötigen wir keinen cy.visit(), keine gerenderte Webseite und keinen simulierten Klick. Mit cy.request() senden wir einen echten HTTP-Request und können anschließend Statuscode, Response-Body, Header oder Antwortzeit prüfen.

In diesem Beitrag bauen wir deshalb Schritt für Schritt eine kleine API-Test-Suite für die Open-Meteo API auf.

Dabei betrachten wir:

  • Was ist API Testing?
  • Was ist der Unterschied zwischen UI Testing und API Testing?
  • Wie funktioniert cy.request()?
  • Wie testen wir GET-Requests?
  • Wie prüfen wir Query-Parameter?
  • Wie validieren wir JSON-Responses?
  • Wie testen wir Fehlerfälle?
  • Wie prüfen wir Header und Response-Zeit?
  • Wie können wir mehrere API-Aufrufe kombinieren?
  • Wie können wir API-Tests mit UI-Tests verbinden?
  • Was bietet @bahmutov/cy-api?
  • Wann reicht cy.request() und wann ist cy-api interessant?
  • Wo liegen die Grenzen von Cypress API Testing?

Unser Beispiel: Eine kleine Wetteranwendung

Damit API Testing nicht bei abstrakten Requests bleibt, bauen wir einen roten Faden auf.

Stellen wir uns vor, wir entwickeln eine kleine Wetteranwendung.

Der Benutzer gibt einen Standort ein:

Berlin

Unsere Anwendung ermittelt daraus Koordinaten und ruft anschließend die Open-Meteo API auf.

Die Open-Meteo Forecast API verwendet unter anderem latitude und longitude als erforderliche Parameter. Für Wetterdaten können wir beispielsweise aktuelle Werte wie Temperatur, Luftfeuchtigkeit oder Wettercode anfordern. Die API liefert die Daten als JSON zurück.

Vereinfacht sieht unsere Anwendung so aus:

┌──────────────────────┐
│   Wetter-App         │
│                      │
│ Standort: Berlin     │
│                      │
│ [ Wetter anzeigen ]  │
└──────────┬───────────┘
           │
           │ HTTP
           ▼
┌──────────────────────┐
│    Open-Meteo API    │
│                      │
│ latitude             │
│ longitude            │
│ current              │
└──────────┬───────────┘
           │
           │ JSON
           ▼
┌──────────────────────┐
│ Temperatur           │
│ Wettercode           │
│ Wind                  │
└──────────────────────┘

Unser Ziel ist zunächst nicht, die komplette Wetteranwendung zu testen.

Wir wollen verstehen, wie wir den API-Aufruf unabhängig vom Browser testen können.

Was ist API Testing?

Beim API Testing testen wir nicht die Benutzeroberfläche, sondern die Schnittstelle unserer Anwendung.

Statt:

Browser
   ↓
Button klicken
   ↓
UI prüfen

machen wir:

HTTP Request
   ↓
API
   ↓
HTTP Response
   ↓
Response prüfen

Wir können beispielsweise prüfen:

Status Code
Response Body
Response Header
Response Zeit

Das ist eine andere Testebene als ein klassischer E2E-Test.

Ein UI-Test könnte prüfen:

cy.contains('15 °C').should('be.visible');

Ein API-Test prüft dagegen beispielsweise:

expect(response.status).to.equal(200);
expect(response.body.current.temperature_2m).to.be.a('number');

Der große Vorteil:

Wir müssen keinen Browser bedienen, um die API zu testen.

Cypress führt den Request direkt aus. cy.request() kommuniziert dabei nicht über den normalen Browser-XHR-Mechanismus. Genau deshalb ist beispielsweise auch die klassische Browser-CORS-Grenze für cy.request() nicht das gleiche Problem wie bei einem Request aus der Anwendung selbst.

Unsere erste Open-Meteo-Anfrage

Die Open-Meteo API arbeitet mit geografischen Koordinaten.

Für Berlin können wir beispielsweise folgende Koordinaten verwenden:

Latitude: 52.52
Longitude: 13.41

Eine einfache Anfrage kann so aussehen:

api.open-meteo.com/v1/forecast
    ?latitude=52.52
    &longitude=13.41
    &current=temperature_2m

Wir fragen damit aktuelle Wetterdaten für einen bestimmten Standort ab.

Cypress kann diesen Endpoint direkt aufrufen.

cy.request(
    'https://api.open-meteo.com/v1/forecast?latitude=52.52&longitude=13.41&current=temperature_2m'
);

Das ist bereits ein API-Test.

Aber aktuell prüfen wir noch nichts.

Wir senden lediglich einen Request.

Unser erster API-Test mit cy.request()

Wir machen daraus einen echten Test:

describe('Open-Meteo API', () => {

    it('liefert Wetterdaten für Berlin', () => {

        cy.request(
            'https://api.open-meteo.com/v1/forecast?latitude=52.52&longitude=13.41&current=temperature_2m'
        ).then((response) => {

            expect(response.status).to.equal(200);
            expect(response.body).to.have.property('current');
        });
    });
});

Hier passieren bereits mehrere Dinge.

Cypress führt den HTTP-Request aus.

Anschließend erhalten wir ein response-Objekt.

Dieses enthält unter anderem:

response.status
response.body
response.headers
response.duration

Diese Werte können wir für unsere Assertions verwenden.

Was liefert Open-Meteo zurück?

Die Open-Meteo API liefert bei erfolgreichen Forecast-Anfragen ein JSON-Objekt.

Vereinfacht kann die Struktur so aussehen:

{
  "latitude": 52.52,
  "longitude": 13.419,
  "timezone": "Europe/Berlin",
  "current": {
    "time": "2026-09-20T18:00",
    "temperature_2m": 17.4,
    "wind_speed_10m": 8.2
  }
}

Die tatsächlich zurückgegebenen Werte hängen natürlich vom angefragten Zeitpunkt und den verwendeten Parametern ab.

Für unseren Test sind deshalb weniger die konkreten Wetterwerte interessant.

Wir wollen prüfen, ob die Struktur und fachlich relevanten Eigenschaften stimmen.

Das ist ein wichtiger Unterschied.

Wir sollten nicht testen:

expect(response.body.current.temperature_2m).to.equal(17.4);

wenn wir damit eigentlich nur überprüfen würden, welches Wetter heute gerade in Berlin herrscht.

Morgen wäre dieser Test wahrscheinlich kaputt.

Wir testen stattdessen Eigenschaften, die unabhängig vom konkreten Wetterwert sind:

expect(response.body.current).to.have.property('temperature_2m');

Wetterdaten fachlich prüfen

Wir können unseren Test jetzt erweitern:

describe('Open-Meteo API', () => {

    it('liefert aktuelle Wetterdaten für Berlin', () => {

        cy.request({
            method: 'GET',
            url: 'https://api.open-meteo.com/v1/forecast',
            qs: {
                latitude: 52.52,
                longitude: 13.41,
                current: 'temperature_2m,wind_speed_10m'
            }
        }).then((response) => {

            expect(response.status)
                .to.equal(200);

            expect(response.body)
                .to.have.property('latitude');

            expect(response.body)
                .to.have.property('longitude');

            expect(response.body)
                .to.have.property('current');

            expect(response.body.current)
                .to.have.property('temperature_2m');

            expect(response.body.current)
                .to.have.property('wind_speed_10m');

        });
    });
});

Diese Variante ist wesentlich besser lesbar.

Wir trennen URL und Query-Parameter:

qs: {
    latitude: 52.52,
    longitude: 13.41,
    current: 'temperature_2m,wind_speed_10m'
}

Cypress baut daraus den entsprechenden Request.

Die Open-Meteo-Dokumentation beschreibt latitude und longitude als erforderliche Parameter der Forecast API. Über current können wir aktuelle Wettervariablen auswählen.

Warum qs besser ist als eine lange URL

Natürlich könnten wir auch schreiben:

cy.request(
    'https://api.open-meteo.com/v1/forecast?latitude=52.52&longitude=13.41&current=temperature_2m'
);

Bei komplexeren Requests wird das aber schnell unübersichtlich.

Mit qs sehen wir direkt:

Welche Parameter?
Welche Werte?

Das ist besonders praktisch, wenn wir später verschiedene Szenarien testen wollen.

Beispielsweise:

const location = {
    latitude: 52.52,
    longitude: 13.41
};

und:

cy.request({
    method: 'GET',
    url: 'https://api.open-meteo.com/v1/forecast',
    qs: {
        ...location,
        current: 'temperature_2m'
    }
});

Damit können wir unseren Test leichter erweitern.

cy.request() prüft nicht automatisch alles

Ein wichtiger Punkt bei cy.request():

Cypress erwartet standardmäßig einen erfolgreichen HTTP-Status.

Wenn der Server beispielsweise 400 oder 500 zurückgibt, schlägt der Command normalerweise bereits fehl.

Das Verhalten kann über failOnStatusCode angepasst werden. Auch Redirects, Timeouts und Retry-Verhalten können über die Optionen von cy.request() gesteuert werden.

Für einen positiven Test ist das praktisch:

cy.request({
    method: 'GET',
    url: 'https://api.open-meteo.com/v1/forecast',
    qs: {
        latitude: 52.52,
        longitude: 13.41,
        current: 'temperature_2m'
    }
}).then((response) => {

    expect(response.status).to.equal(200);
});

Der Test schlägt bereits fehl, wenn der Request einen unerwarteten Status liefert.

Trotzdem sollten wir den Statuscode explizit prüfen, wenn er Teil unserer fachlichen Aussage ist.

Fehlerfälle testen

API Testing wird erst richtig interessant, wenn wir nicht nur erfolgreiche Requests testen.

Was passiert beispielsweise, wenn die erforderlichen Koordinaten fehlen?

Die Open-Meteo API dokumentiert, dass bei ungültigen URL-Parametern ein HTTP-400-Fehler mit einem JSON-Fehlerobjekt zurückgegeben werden kann.

Genau diesen Fall wollen wir testen.

Dazu müssen wir Cypress erlauben, dass der Request mit einem Fehlerstatus zurückkommt:

it('liefert einen Fehler bei fehlenden Koordinaten', () => {

    cy.request({
        method: 'GET',
        url: 'https://api.open-meteo.com/v1/forecast',
        failOnStatusCode: false
    }).then((response) => {

        expect(response.status).to.equal(400);
        expect(response.body).to.have.property('error');
        expect(response.body.error).to.equal(true);
    });
});

Jetzt testen wir nicht nur:

Happy Path

sondern auch:

Ungültige Anfrage
       ↓
HTTP 400
       ↓
Fehlerobjekt

Genau solche Fälle sind bei API-Tests besonders wertvoll.

Query-Parameter testen

Wir können nun gezielt prüfen, ob unsere API mit unterschiedlichen Parametern korrekt arbeitet.

Unser Wetterservice könnte beispielsweise folgende Werte anfordern:

const request = {
    latitude: 52.52,
    longitude: 13.41,
    current: 'temperature_2m,relative_humidity_2m'
};

Der Test:

cy.request({
    method: 'GET',
    url: 'https://api.open-meteo.com/v1/forecast',
    qs: request
}).then((response) => {

    expect(response.status).to.equal(200);
    expect(response.body.current).to.have.property('temperature_2m');
    expect(response.body.current) .to.have.property('relative_humidity_2m');
});

Damit können wir testen, dass die API die von uns angeforderten Variablen liefert.

Open-Meteo unterstützt zahlreiche aktuelle und stündliche Wettervariablen, darunter Temperatur, Luftfeuchtigkeit, Niederschlag, Wind und Wettercode.

Nicht nur auf 200 prüfen

Ein häufiger Fehler bei API-Tests ist:

expect(response.status).to.equal(200);

und danach ist der Test fertig.

Das ist zwar besser als gar keine Assertion. Aber ein HTTP-200 bedeutet noch nicht automatisch, dass die API die Daten liefert, die unsere Anwendung benötigt.

Wir sollten deshalb mehrere Ebenen prüfen:

HTTP
 │
 └── Status = 200

Response
 │
 ├── Struktur vorhanden
 ├── Pflichtfelder vorhanden
 └── Datentypen korrekt

Fachlichkeit
 │
 ├── Temperatur ist Zahl
 ├── Luftfeuchtigkeit ist Zahl
 └── Zeitstempel vorhanden

Zum Beispiel:

expect(response.body.current.temperature_2m).to.be.a('number');
expect(response.body.current.relative_humidity_2m).to.be.a('number');
expect(response.body.current.time) .to.be.a('string');

Damit testen wir wesentlich mehr als nur den HTTP-Status.

Response-Header testen

Auch HTTP-Header können Teil unseres Tests sein.

Zum Beispiel:

expect(response.headers).to.have.property('content-type');

Wenn wir eine JSON-Antwort erwarten, können wir den Content-Type prüfen.

expect(response.headers['content-type']).to.include('application/json');

Das ist besonders sinnvoll, wenn wir einen API-Contract testen.

Wir wollen nicht nur:

HTTP 200

sondern:

HTTP 200
Content-Type: JSON
Body: erwartete Struktur

Die Antwortzeit testen

Cypress liefert auch die Dauer des Requests:

response.duration

Damit können wir beispielsweise eine einfache technische Grenze definieren:

expect(response.duration).to.be.lessThan(2000);

Hier sollten wir allerdings vorsichtig sein.

Ein solcher Test ist kein Performance-Test.

Wenn unser Test in CI einmal 2,1 Sekunden benötigt, wissen wir nicht automatisch, dass die API ein Performanceproblem besitzt.

Netzwerk, CI-Auslastung und externe Dienste können die Antwortzeit beeinflussen.

Wir können solche Checks als einfache Regressionserkennung verwenden.

Für echte Last- und Performance-Tests benötigen wir aber spezialisierte Werkzeuge.

Unser Wetterservice bekommt mehrere Orte

Jetzt machen wir aus unserem einfachen Test einen realistischeren Anwendungsfall.

Unsere Wetteranwendung soll mehrere Städte unterstützen:

Berlin
London
Paris
New York

Wir können diese Daten als Testfälle definieren:

const locations = [
    {
        name: 'Berlin',
        latitude: 52.52,
        longitude: 13.41
    },
    {
        name: 'London',
        latitude: 51.50,
        longitude: -0.12
    },
    {
        name: 'Paris',
        latitude: 48.85,
        longitude: 2.35
    }
];

Nun können wir unsere Tests parametrisieren:

locations.forEach((location) => {

    it(`liefert Wetterdaten für ${location.name}`, () => {

        cy.request({
            method: 'GET',
            url: 'https://api.open-meteo.com/v1/forecast',
            qs: {
                latitude: location.latitude,
                longitude: location.longitude,
                current: 'temperature_2m'
            }
        }).then((response) => {

            expect(response.status)
                .to.equal(200);

            expect(response.body.current)
                .to.have.property('temperature_2m');

        });
    });
});

Jetzt haben wir einen wiederverwendbaren Test für mehrere Standorte.

Was testen wir eigentlich?

Hier lohnt sich eine kurze Pause.

Wir testen nicht, ob Berlin heute wirklich 17 Grad hat. Das wäre bei einer Wetter-API ein schlechter Test, weil sich das Wetter ständig verändert.

Wir testen stattdessen:

Standort
   ↓
API Request
   ↓
gültige Antwort
   ↓
aktuelle Wetterstruktur

Unser Test ist also stabiler, weil wir nicht von einem konkreten Wetterwert abhängig sind.

Das ist eine wichtige Regel beim API Testing:

Wir sollten möglichst stabile fachliche Eigenschaften testen und nicht dynamische externe Werte als feste Erwartung behandeln.

cy.request() und cy.intercept() sind nicht dasselbe

Im Cypress-Umfeld werden cy.request() und cy.intercept() häufig miteinander verwechselt.

Sie erfüllen aber unterschiedliche Aufgaben.

cy.request()

Wir senden selbst einen HTTP-Request:

Cypress
   │
   │ GET
   ▼
API

Beispiel:

cy.request('/api/weather');

cy.intercept()

Wir beobachten oder verändern Requests, die unsere Anwendung selbst ausführt:

Browser
   │
   │ GET /api/weather
   ▼
cy.intercept()
   │
   ▼
API

Beispiel:

cy.intercept(
    'GET',
    '/api/weather'
).as('weather');

Dann kann Cypress auf den Request warten oder ihn beispielsweise stubben.

Die Cypress-Dokumentation unterscheidet deshalb klar zwischen cy.request() für direkte Requests und cy.intercept() für Requests, die von der Anwendung ausgeführt werden und die wir beobachten, abfangen oder mocken wollen.

Unser API-Test wird zum UI-Test

Jetzt verbinden wir beide Ebenen.

Unsere Wetteranwendung könnte so funktionieren:

Browser
   │
   │ Standort auswählen
   ▼
Wetter-App
   │
   │ API Request
   ▼
Open-Meteo
   │
   │ JSON
   ▼
Wetter-App
   │
   ▼
Browser

Wir können nun zunächst die API unabhängig testen. Danach testen wir die Benutzeroberfläche.

Zum Beispiel:

it('zeigt das aktuelle Wetter für Berlin', () => {

    cy.visit('/weather');

    cy.get('[data-cy=city]')
        .type('Berlin');

    cy.get('[data-cy=search]')
        .click();

    cy.get('[data-cy=temperature]')
        .should('be.visible');

});

Dieser Test beantwortet eine andere Frage:

Kann der Benutzer die Wetteranwendung verwenden?

Unser API-Test beantwortet:

Liefert der Wetterservice eine gültige Antwort?

Beide Tests ergänzen sich.

API als Setup für UI-Tests

Noch interessanter wird es, wenn unsere eigene Anwendung eine API besitzt.

Nehmen wir an, unsere Wetteranwendung speichert bevorzugte Städte.

Dann könnte ein UI-Test die Daten über API vorbereiten:

API
 │
 └── Berlin als Favorit speichern
          ↓
       Browser
          ↓
       Login
          ↓
    Favoriten anzeigen

Das ist ein großer Vorteil von API Testing.

Wir müssen nicht jeden Ausgangszustand über die Benutzeroberfläche herstellen.

Die Cypress-Dokumentation nennt genau diesen Anwendungsfall: API-Aufrufe können unter anderem dazu verwendet werden, Zustände schneller zu erzeugen, anstatt dafür den kompletten UI-Weg zu durchlaufen.

API Testing mit cy.request() strukturieren

Wenn unsere Test-Suite wächst, wollen wir nicht überall vollständige URLs schreiben.

Wir können beispielsweise eine baseUrl konfigurieren:

import { defineConfig } from 'cypress';

export default defineConfig({
    e2e: {
        baseUrl: 'https://api.open-meteo.com'
    }
});

Dann können wir relative URLs verwenden:

cy.request('/v1/forecast');

Die Cypress-Dokumentation empfiehlt baseUrl als praktische Möglichkeit, URLs zentral zu konfigurieren und Tests einfacher auf unterschiedliche Umgebungen auszurichten.

Bei einer externen API wie Open-Meteo sollten wir allerdings überlegen, ob wir wirklich die komplette Suite direkt gegen den externen Dienst laufen lassen wollen.

Für einen Lernartikel ist das praktisch.

In einem produktiven Projekt ist die Frage nach Verfügbarkeit, Rate Limits, Netzwerkabhängigkeit und Teststabilität wichtig.

cy.request() mit einem Helper kapseln

Wir können unseren Wetter-Request in eine Funktion auslagern:

function getCurrentWeather(latitude, longitude) {

    return cy.request({
        method: 'GET',
        url: 'https://api.open-meteo.com/v1/forecast',
        qs: {
            latitude,
            longitude,
            current: 'temperature_2m'
        }
    });
}

Der Test wird dadurch einfacher:

it('liefert Wetterdaten für Berlin', () => {

    getCurrentWeather(52.52, 13.41)
        .then((response) => {

            expect(response.status)
                .to.equal(200);

            expect(response.body.current)
                .to.have.property('temperature_2m');

        });
});

Das ist besonders sinnvoll, wenn wir denselben API-Endpunkt in vielen Tests verwenden.

Und jetzt: @bahmutov/cy-api

Bis hierhin haben wir ausschließlich Cypress-Bordmittel verwendet.

Für API Testing gibt es aber ein interessantes Plugin von Gleb Bahmutov:

@bahmutov/cy-api.

Das Projekt stellt einen zusätzlichen Cypress-Command namens cy.api() bereit. Das Plugin führt HTTP-Requests gegen externe Server aus und stellt Request und Response zusätzlich im Cypress Test Runner dar.

Installation:

npm install --save-dev @bahmutov/cy-api

Danach importieren wir das Plugin in unsere Cypress-Support-Datei:

import '@bahmutov/cy-api';

Anschließend steht uns cy.api() zur Verfügung.

cy.api() statt cy.request()

Unser bisheriger Request:

cy.request({
    method: 'GET',
    url: 'https://api.open-meteo.com/v1/forecast',
    qs: {
        latitude: 52.52,
        longitude: 13.41,
        current: 'temperature_2m'
    }
});

kann mit dem Plugin beispielsweise so aussehen:

cy.api({
    method: 'GET',
    url: 'https://api.open-meteo.com/v1/forecast',
    qs: {
        latitude: 52.52,
        longitude: 13.41,
        current: 'temperature_2m'
    }
});

Der wesentliche Unterschied ist nicht, dass Cypress plötzlich eine komplett andere Art von API Testing beherrscht.

cy.api() ist ein zusätzlicher Custom Command des Plugins. Der besondere Mehrwert des Plugins liegt vor allem in der Darstellung von Request und Response innerhalb des Cypress Test Runners. Das Projekt beschreibt cy.api() ausdrücklich als Custom Command für End-to-End-API-Testing.

Warum cy-api interessant sein kann

Wenn wir viele API-Tests schreiben, ist die Sichtbarkeit der Requests sehr praktisch.

Statt nur:

GET 200 api.open-meteo.com/...

wollen wir manchmal direkt sehen:

REQUEST

GET /v1/forecast

Query:
latitude=52.52
longitude=13.41
current=temperature_2m


RESPONSE

Status: 200

{
    "latitude": 52.52,
    "longitude": 13.41,
    ...
}

Genau hier setzt cy-api an.

Das Plugin rendert die Ein- und Ausgabe im Cypress Runner dort, wo normalerweise die Webanwendung angezeigt wird.

Das kann beim Entwickeln und Debuggen von API-Tests sehr angenehm sein.

cy.request() oder cy.api()?

Damit kommen wir zu einer wichtigen Frage.

Welche Variante sollten wir verwenden?

Die Antwort ist nicht:

cy-api ist besser als cy.request().

Denn beide verfolgen unterschiedliche Ziele.

Thema cy.request() cy.api()
Bestandteil von Cypress Ja Nein
Installation nötig Nein Ja
Direkte HTTP-Requests Ja Ja
API Testing Ja Ja
Custom Command Nein Ja
Zusätzliche Darstellung Cypress Command Log API-Darstellung im Runner
Request/Response sichtbar Ja Ja
Externe APIs Ja Ja
Plugin-Abhängigkeit Nein Ja

Cypress selbst empfiehlt cy.request() als eingebauten Weg, um APIs direkt zu testen.

cy-api ist deshalb eher eine Erweiterung des Cypress-Erlebnisses als ein Ersatz für die eigentliche API-Testing-Funktionalität.

Ein wichtiger Unterschied: Tool vs. Plugin

Das sollten wir klar auseinanderhalten.

cy.request() gehört zu Cypress.

Das bedeutet:

Cypress
 └── cy.request()

Wir benötigen keine zusätzliche Bibliothek.

cy.api() kommt dagegen aus:

@bahmutov/cy-api
 └── cy.api()

Wir haben also eine zusätzliche Abhängigkeit.

Das ist nicht grundsätzlich schlecht.

Es bedeutet aber, dass wir bei der Architektur unserer Test-Suite bewusst entscheiden sollten, ob wir diese Abhängigkeit benötigen.

Ein kompletter cy-api-Test

Unser Wettertest könnte mit dem Plugin so aussehen:

describe('Open-Meteo API', () => {

    it('liefert aktuelle Wetterdaten für Berlin', () => {

        cy.api({
            method: 'GET',
            url: 'https://api.open-meteo.com/v1/forecast',
            qs: {
                latitude: 52.52,
                longitude: 13.41,
                current: 'temperature_2m'
            }
        }).then((response) => {

            expect(response.status)
                .to.equal(200);

            expect(response.body)
                .to.have.property('current');

            expect(response.body.current)
                .to.have.property('temperature_2m');

        });
    });
});

Der fachliche Test bleibt dabei nahezu identisch.

Wir ändern vor allem das Kommando:

cy.request()

zu:

cy.api()

Der entscheidende Unterschied liegt damit weniger in der HTTP-Funktionalität als in der zusätzlichen Darstellung und den Möglichkeiten des Plugins.

Fehlerfälle mit cy-api

Auch Fehlerfälle können wir mit dem Plugin testen.

Das grundlegende Prinzip bleibt gleich:

cy.api({
    method: 'GET',
    url: 'https://api.open-meteo.com/v1/forecast',
    failOnStatusCode: false
}).then((response) => {

    expect(response.status).to.equal(400);
    expect(response.body.error).to.equal(true);
});

Wichtig ist hier, die konkrete API und das Verhalten des verwendeten Commands zu berücksichtigen.

Bei Cypress selbst ist failOnStatusCode eine Option von cy.request(). Bei einem Plugin sollten wir immer dessen eigene Dokumentation und das tatsächlich unterstützte Optionsverhalten prüfen.

Das ist ein weiterer Grund, warum wir in einer Test-Suite nicht einfach blind jedes Cypress-Kommando durch ein Plugin-Kommando ersetzen sollten.

Was bringt uns das Plugin wirklich?

Wenn wir die Sache auf den Punkt bringen, sieht es so aus:

                API Testing
                     │
          ┌──────────┴──────────┐
          │                     │
          ▼                     ▼
    cy.request()             cy.api()
          │                     │
          │                     │
      Cypress              @bahmutov/
      Bordmittel              cy-api
          │                     │
          └──────────┬──────────┘
                     │
                     ▼
              HTTP Endpoint

cy.request() ist der native Weg innerhalb von Cypress.

cy-api ergänzt Cypress um einen speziellen API-Command und eine zusätzliche Darstellung.

Für viele Projekte reicht deshalb:

cy.request(...)

vollkommen aus.

Wer API Testing stärker in den Cypress Runner integrieren und Request/Response dort besonders sichtbar machen möchte, kann sich cy-api ansehen.

API Testing ist mehr als GET

Bisher haben wir hauptsächlich GET-Requests verwendet.

REST APIs bestehen aber aus unterschiedlichen HTTP-Methoden.

Typischerweise begegnen uns:

GET
POST
PUT
PATCH
DELETE

Mit cy.request() können wir diese Methoden direkt verwenden. Cypress unterstützt neben den klassischen Methoden auch weitere HTTP-Methoden. Für unser Wetterbeispiel ist GET besonders passend, weil wir Daten abrufen.

Bei einer eigenen Wetter-App könnten wir aber beispielsweise einen Benutzerstand speichern:

POST /api/favorites

oder einen gespeicherten Standort entfernen:

DELETE /api/favorites/123

Dann könnten wir einen vollständigen API-Lebenszyklus testen.

Beispiel für einen POST-Request

Angenommen, unsere eigene Anwendung bietet:

POST /api/favorites

mit:

{
    "name": "Berlin",
    "latitude": 52.52,
    "longitude": 13.41
}

Der Test könnte so aussehen:

cy.request({
    method: 'POST',
    url: '/api/favorites',
    body: {
        name: 'Berlin',
        latitude: 52.52,
        longitude: 13.41
    }
}).then((response) => {

    expect(response.status)
        .to.equal(201);

    expect(response.body)
        .to.have.property('id');

    expect(response.body.name)
        .to.equal('Berlin');

});

Cypress serialisiert JavaScript-Objekte im Request-Body bei cy.request() automatisch als JSON und setzt entsprechend den Content-Type.

CRUD mit Cypress API Testing

Damit können wir einen vollständigen CRUD-Test aufbauen:

CREATE
  ↓
READ
  ↓
UPDATE
  ↓
DELETE

Für unsere Favoriten:

POST /favorites
       ↓
GET /favorites/123
       ↓
PATCH /favorites/123
       ↓
DELETE /favorites/123

Das ist ein gutes Beispiel dafür, dass API Tests nicht nur aus einzelnen Requests bestehen müssen.

Wir können komplette fachliche Abläufe testen.

API Testing und Authentifizierung

Viele APIs sind geschützt.

Dann müssen wir beispielsweise einen Token übergeben:

cy.request({
    method: 'GET',
    url: '/api/favorites',
    headers: {
        Authorization: `Bearer ${token}`
    }
});

Oder wir führen vorher einen Login über die API durch.

Cypress kann dabei auch mit Browser-Cookies zusammenspielen. cy.request() verwendet den Cookie-Jar des Browsers: passende Cookies werden für den Request berücksichtigt und Set-Cookie-Antworten können wiederum im Browser-Kontext landen. Dadurch lassen sich hybride Tests aufbauen, bei denen beispielsweise über HTTP eingeloggt und anschließend über die UI weitergetestet wird.

Das ist besonders interessant für unsere Wetteranwendung, wenn Benutzer beispielsweise persönliche Favoriten besitzen.

Ein hybrider Test

Unser Test könnte dann so aussehen:

API
 │
 ├── Benutzer anmelden
 │
 └── Berlin als Favorit speichern
 │
 ▼
Browser
 │
 ├── Wetter-App öffnen
 ├── Login ist bereits vorhanden
 └── Favorit Berlin anzeigen

Damit vermeiden wir, dass jeder Test den kompletten Login über die UI durchführen muss.

Wir testen den Login trotzdem an anderer Stelle vollständig über die Benutzeroberfläche.

Der Unterschied ist:

Login testen
        ↓
UI-Test

Login für Test vorbereiten
        ↓
API

Das ist ein wichtiges Muster für größere Test-Suiten.

Was API Tests schneller macht

API Tests benötigen keine komplette Seitennavigation.

Wir müssen nicht:

HTML laden
CSS laden
JavaScript laden
Bilder laden
DOM rendern
UI bedienen

Wir senden direkt:

HTTP Request

Dadurch sind API Tests typischerweise deutlich fokussierter und schneller als vollständige UI-Flows. Cypress beschreibt API Tests entsprechend als eine Testebene, die schneller als End-to-End-Tests ist, weil keine Seite gerendert und keine Benutzerinteraktion simuliert werden muss.

Das bedeutet aber nicht, dass wir unsere E2E-Tests komplett durch API Tests ersetzen sollten.

Sie beantworten unterschiedliche Fragen.

Was API Tests nicht testen

Unser Open-Meteo-Test kann feststellen:

API antwortet
API liefert JSON
API liefert Temperatur
API liefert Wettercode

Er kann aber nicht feststellen:

Button ist sichtbar
Layout funktioniert
Mobile Menü funktioniert
Temperatur wird korrekt formatiert
Fehlermeldung wird angezeigt
Benutzer kann Standort auswählen

Dafür benötigen wir weiterhin UI-Tests.

Unser gesamtes Testspektrum könnte deshalb so aussehen:

                 Wetteranwendung
                       │
          ┌────────────┼────────────┐
          │            │            │
          ▼            ▼            ▼
       Unit          API          E2E
       Tests         Tests        Tests
          │            │            │
          ▼            ▼            ▼
      Logik        Backend       Browser

Jede Ebene beantwortet eine andere Frage.

Externe APIs sind ein Sonderfall

Unser Beispiel verwendet Open-Meteo.

Das ist für einen Lernartikel ideal, weil wir keine eigene Backend-Anwendung benötigen.

In einem echten Projekt sollten wir aber überlegen, ob wir unsere Tests dauerhaft gegen einen externen Dienst laufen lassen wollen.

Denn dann hängen unsere Tests unter anderem von dessen:

  • Verfügbarkeit
  • Netzwerk
  • Antwortzeiten
  • Änderungen
  • Rate Limits
  • API-Verhalten

ab.

Das kann zu Tests führen, die lokal funktionieren, aber in CI wegen eines externen Problems fehlschlagen.

Für einen echten Vertragstest gegen eine externe API kann das gewollt sein.

Für einen isolierten Test unserer eigenen Wetteranwendung ist es häufig sinnvoller, die externe API zu mocken.

API Test oder Mock?

Hier kommt wieder cy.intercept() ins Spiel.

Wenn wir testen wollen:

Zeigt unsere Anwendung eine Temperatur von 20 °C korrekt an?

müssen wir nicht jedes Mal Open-Meteo aufrufen.

Wir können die API-Antwort simulieren:

cy.intercept(
    'GET',
    '**/v1/forecast*',
    {
        statusCode: 200,
        body: {
            current: {
                temperature_2m: 20
            }
        }
    }
).as('weather');

Dann testen wir die Benutzeroberfläche unabhängig vom externen Wetterdienst.

UI-Test
   │
   ▼
Wetter-App
   │
   ▼
cy.intercept()
   │
   └── simulierte API

Das ist aber kein API-Test.

Wir testen hier die UI und simulieren deren Abhängigkeit.

Der Unterschied ist wichtig:

cy.request()
    ↓
echte API testen

cy.intercept()
    ↓
Verhalten der Anwendung gegenüber API testen

Cypress unterstützt beide Strategien und unterscheidet entsprechend zwischen direkten Requests und dem Beobachten bzw. Stubben von Requests der Anwendung.

Unser Testkonzept für die Wetteranwendung

Damit haben wir mittlerweile drei unterschiedliche Testarten:

API Test

Cypress
   ↓
Open-Meteo
   ↓
Response prüfen

UI Test mit Mock

Cypress
   ↓
Wetter-App
   ↓
cy.intercept()
   ↓
Mock Response

E2E Test

Cypress
   ↓
Wetter-App
   ↓
Open-Meteo
   ↓
echte Response
   ↓
UI

Alle drei Varianten haben ihre Berechtigung.

Ein sinnvoller Aufbau unserer API-Test-Suite

Für unser Beispiel könnten wir die Tests so strukturieren:

cypress/
└── e2e/
    └── api/
        └── open-meteo.cy.js

Darin könnten wir beispielsweise folgende Testgruppen haben:

Open-Meteo API
│
├── aktuelle Wetterdaten
│
├── mehrere Standorte
│
├── verschiedene Wettervariablen
│
├── ungültige Parameter
│
├── fehlende Parameter
│
└── Response-Struktur

Der Vorteil:

Wenn ein Test fehlschlägt, sehen wir bereits am Namen, welche API-Funktion betroffen ist.

Ein vollständiger Open-Meteo-Test

Fassen wir unseren roten Faden noch einmal in einem Test zusammen:

describe('Open-Meteo Forecast API', () => {

    const berlin = {
        latitude: 52.52,
        longitude: 13.41
    };

    it('liefert aktuelle Wetterdaten für Berlin', () => {

        cy.request({
            method: 'GET',
            url: 'https://api.open-meteo.com/v1/forecast',
            qs: {
                ...berlin,
                current: [
                    'temperature_2m',
                    'relative_humidity_2m',
                    'wind_speed_10m'
                ].join(',')
            }
        }).then((response) => {

            // HTTP
            expect(response.status)
                .to.equal(200);

            // Response
            expect(response.body)
                .to.have.property('current');

            // Fachliche Struktur
            expect(response.body.current)
                .to.have.property('temperature_2m');

            expect(response.body.current)
                .to.have.property('relative_humidity_2m');

            expect(response.body.current)
                .to.have.property('wind_speed_10m');

            // Datentypen
            expect(response.body.current.temperature_2m)
                .to.be.a('number');

            expect(response.body.current.relative_humidity_2m)
                .to.be.a('number');

            expect(response.body.current.wind_speed_10m)
                .to.be.a('number');

        });
    });
});

Wir prüfen hier bewusst nicht den konkreten Temperaturwert.

Stattdessen prüfen wir:

Request
   ↓
HTTP 200
   ↓
current vorhanden
   ↓
Temperatur vorhanden
   ↓
Luftfeuchtigkeit vorhanden
   ↓
Wind vorhanden
   ↓
Datentypen korrekt

Das ist wesentlich stabiler.

cy.request() vs. cy.api() - unsere Entscheidung

Für unsere tägliche Arbeit können wir uns eine einfache Regel merken.

Wir verwenden cy.request(), wenn ...

  • wir API-Requests direkt aus Cypress senden wollen
  • wir keine zusätzliche Abhängigkeit benötigen
  • wir API-Tests mit Cypress-Bordmitteln schreiben möchten
  • wir API-Aufrufe für Setup oder Teardown benötigen
  • wir UI- und API-Tests kombinieren möchten

cy.request() ist dafür bereits vollständig in Cypress integriert.

Wir betrachten cy-api, wenn ...

  • wir einen spezialisierten cy.api()-Command möchten
  • Request und Response besonders sichtbar im Cypress Runner dargestellt werden sollen
  • wir die zusätzliche Plugin-Funktionalität für unsere API-Suite hilfreich finden
  • eine zusätzliche Abhängigkeit für unser Projekt akzeptabel ist

@bahmutov/cy-api ist damit keine notwendige Voraussetzung für API Testing mit Cypress. Es ist eine optionale Erweiterung.

Typische Fehler beim Cypress API Testing

Auch bei API Tests gibt es einige typische Fehler.

Nur den Statuscode prüfen

expect(response.status).to.equal(200);

Das ist zu wenig.

Auch der Response-Body sollte geprüft werden.

Dynamische Werte hart codieren

Bei einer Wetter-API wäre das beispielsweise:

expect(temperature).to.equal(18.4);

Das ist kein stabiler Test.

API Tests als UI Tests verwenden

Wenn wir nur die API testen wollen, brauchen wir nicht:

cy.visit('/');

Wir können direkt:

cy.request(...)

verwenden.

Externe APIs ungeprüft als Testabhängigkeit verwenden

Wenn unsere Tests gegen einen externen Dienst laufen, können dessen Probleme unsere Tests beeinflussen.

Wir sollten bewusst entscheiden:

Echte externe API?
oder
Mock?

cy.request() und cy.intercept() verwechseln

Merksatz:

cy.request()
    = Ich sende den Request.

cy.intercept()
    = Ich beobachte oder verändere einen Request
      meiner Anwendung.

cy-api als Pflichtbestandteil betrachten

cy-api ist ein Plugin.

Cypress selbst bietet bereits cy.request() für direkte API-Aufrufe.

Das Plugin ist eine Erweiterung, keine Voraussetzung.

API Testing als Teil einer größeren Teststrategie

Unser Wetterbeispiel zeigt sehr gut, dass API Tests nicht isoliert betrachtet werden sollten.

Eine sinnvolle Teststrategie könnte beispielsweise so aussehen:

                    Wetter-App
                        │
        ┌───────────────┼───────────────┐
        │               │               │
        ▼               ▼               ▼
      Unit             API             E2E
      Tests            Tests           Tests
        │               │               │
        │               │               │
     Funktionen      Backend        Benutzer
     testen          testen         testen

Dazu kommen je nach Anwendung weitere Ebenen:

Integration
Performance
Security
Accessibility
Monitoring

Cypress kann dabei einen wichtigen Teil übernehmen.

Aber Cypress muss nicht alle Testarten ersetzen.

Fazit: Cypress API Testing

API Testing mit Cypress ist deutlich mehr als ein cy.request() mit einem expect().

Wir können mit relativ wenig Code einen kompletten API-Test aufbauen:

Request
   ↓
Status prüfen
   ↓
Response prüfen
   ↓
Struktur prüfen
   ↓
Datentypen prüfen
   ↓
Fachlichkeit prüfen

Unsere Open-Meteo-Beispiele zeigen dabei einen wichtigen Punkt. Wir sollten nicht testen, ob das Wetter heute exakt einen bestimmten Wert hat. Wir testen vielmehr, ob die API auf eine gültige Anfrage mit einer erwarteten Struktur antwortet. Damit bekommen wir stabile und aussagekräftige Tests.

Mit cy.request() bringt Cypress bereits alles mit, was wir für direkte API-Requests benötigen. Requests können GET, POST, PUT, PATCH oder DELETE sein, wir können Query-Parameter und Bodies übergeben und anschließend Status, Body, Header und weitere Response-Eigenschaften prüfen.

Das Plugin @bahmutov/cy-api geht einen Schritt weiter und stellt mit cy.api() einen eigenen Command bereit. Besonders interessant ist die zusätzliche Darstellung von Request und Response innerhalb des Cypress Test Runners.

Damit können wir uns merken:

                    API Testing
                         │
              ┌──────────┴──────────┐
              │                     │
              ▼                     ▼
        cy.request()             cy.api()
              │                     │
        Cypress Core          @bahmutov/cy-api
              │                     │
              └──────────┬──────────┘
                         ▼
                    HTTP API

Für die meisten Projekte ist cy.request() der Ausgangspunkt.

cy-api kann interessant werden, wenn wir eine stärker auf API Testing ausgerichtete Darstellung und den zusätzlichen cy.api()-Command nutzen möchten.

Und unser wichtigster Punkt bleibt:

API Tests testen die API. UI Tests testen die Benutzeroberfläche. E2E Tests testen das Zusammenspiel.

Mit Cypress können wir diese Ebenen in einer gemeinsamen Test-Suite kombinieren.

Genau darin liegt eine der großen Stärken: Wir müssen API und UI nicht künstlich voneinander trennen.

Wir können beispielsweise:

API
 │
 └── Testdaten vorbereiten
          ↓
       Cypress
          │
          ├── UI bedienen
          │
          └── API prüfen

verwenden.

Damit wird Cypress nicht nur zu einem Werkzeug für Browser-Automatisierung, sondern zu einem Baustein für eine umfassendere Teststrategie.

Und genau wie bei UI-Tests gilt auch beim API Testing:

Nicht möglichst viele Requests testen, sondern die richtigen fachlichen Fragen stellen.