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
│
▼
BrowserWenn 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:
BerlinUnsere 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üfenmachen wir:
HTTP Request
↓
API
↓
HTTP Response
↓
Response prüfenWir können beispielsweise prüfen:
Status Code
Response Body
Response Header
Response ZeitDas 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.41Eine einfache Anfrage kann so aussehen:
api.open-meteo.com/v1/forecast
?latitude=52.52
&longitude=13.41
¤t=temperature_2mWir 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¤t=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¤t=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.durationDiese 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¤t=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 Pathsondern auch:
Ungültige Anfrage
↓
HTTP 400
↓
FehlerobjektGenau 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 vorhandenZum 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 200sondern:
HTTP 200
Content-Type: JSON
Body: erwartete StrukturDie Antwortzeit testen
Cypress liefert auch die Dauer des Requests:
response.durationDamit 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 YorkWir 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 WetterstrukturUnser 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
▼
APIBeispiel:
cy.request('/api/weather');cy.intercept()
Wir beobachten oder verändern Requests, die unsere Anwendung selbst ausführt:
Browser
│
│ GET /api/weather
▼
cy.intercept()
│
▼
APIBeispiel:
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
│
▼
BrowserWir 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 anzeigenDas 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-apiDanach 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 Endpointcy.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
DELETEMit 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/favoritesoder einen gespeicherten Standort entfernen:
DELETE /api/favorites/123Dann könnten wir einen vollständigen API-Lebenszyklus testen.
Beispiel für einen POST-Request
Angenommen, unsere eigene Anwendung bietet:
POST /api/favoritesmit:
{
"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
↓
DELETEFür unsere Favoriten:
POST /favorites
↓
GET /favorites/123
↓
PATCH /favorites/123
↓
DELETE /favorites/123Das 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 anzeigenDamit 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 bedienenWir senden direkt:
HTTP RequestDadurch 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 WettercodeEr kann aber nicht feststellen:
Button ist sichtbar
Layout funktioniert
Mobile Menü funktioniert
Temperatur wird korrekt formatiert
Fehlermeldung wird angezeigt
Benutzer kann Standort auswählenDafü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 APIDas 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 testenCypress 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
↓
UIAlle 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-StrukturDer 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 korrektDas 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 testenDazu kommen je nach Anwendung weitere Ebenen:
Integration
Performance
Security
Accessibility
MonitoringCypress 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üfenUnsere 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 APIFü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üfenverwenden.
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.