Cypress API-Tests: APIs mit cy.request() testen

Sie verwenden bereits Cypress für End-to-End-Tests. Nun möchten Sie eine API direkt ansprechen, den Statuscode überprüfen und eine Assertion für den JSON-Body durchführen, ohne durch die Benutzeroberfläche zu klicken. Cypress kann das. Der Befehl cy.request() sendet echte HTTP-Anfragen von Node aus, außerhalb des Browsers, sodass Sie einen Endpunkt eigenständig testen oder den Zustand vor einem UI-Test einrichten können.

Dieser Leitfaden zeigt Ihnen, wie Sie APIs mit Cypress testen: die Grundlagen von cy.request(), das Überprüfen von Antworten, das Verketten von Anfragen zur Wiederverwendung eines Authentifizierungstokens und das Stubben von Browser-Traffic mit cy.intercept(). Sie werden auch sehen, wo Cypress für API-Tests gut geeignet ist und wo ein API-natives Tool besser passt.

Warum APIs mit Cypress testen

Die meisten Cypress-Suiten steuern einen Browser. Doch ein Großteil dessen, was Sie in der Benutzeroberfläche überprüfen, ist die zugrunde liegende API: Gibt /login ein Token zurück, liefert /users die richtige Struktur, erstellt ein POST den erwarteten Datensatz?

Das direkte Testen dieser Endpunkte bietet zwei Vorteile. Erstens laufen API-Prüfungen schneller als UI-Abläufe, da es kein Rendering und kein Warten auf Elemente gibt. Zweitens können Sie cy.request() verwenden, um Testdaten einzurichten. Anstatt sich durch ein Anmeldeformular zu klicken, um einen Benutzer zu erstellen, senden Sie ein POST und fahren mit der Assertion fort, die Ihnen tatsächlich wichtig ist.

Wenn Cypress bereits in Ihrem Stack ist, bedeutet das Hinzufügen von API-Tests, dass kein neues Tool installiert werden muss. Sie schreiben sie in denselben Spec-Dateien, mit denselben expect-Assertions, im selben CI-Lauf.

cy.request()-Grundlagen

cy.request() stellt eine HTTP-Anfrage und liefert die Antwort. Es läuft vom Cypress Node-Prozess aus, nicht vom Browser, sodass es weder CORS- noch Same-Origin-Regeln unterliegt.

Der Befehl akzeptiert verschiedene Formen:

cy.request(url)
cy.request(url, body)
cy.request(method, url)
cy.request(method, url, body)
cy.request(options)

Der einfachste Aufruf übergibt eine URL. Ohne Methode wählt Cypress standardmäßig GET:

cy.request('https://jsonplaceholder.typicode.com/users')

Für alles, was über ein einfaches GET hinausgeht, übergeben Sie ein Options-Objekt. Dies gibt Ihnen die volle Kontrolle über Methode, Body und Header:

cy.request({
  method: 'POST',
  url: 'https://jsonplaceholder.typicode.com/posts',
  headers: {
    'Content-Type': 'application/json'
  },
  body: {
    title: 'API test',
    body: 'created from Cypress',
    userId: 1
  }
})

Nützliche Optionen für dieses Objekt:

• method: das HTTP-Verb (GET, POST, PUT, PATCH, DELETE und andere). Standardmäßig GET.
• url: der Endpunkt. Erforderlich.
• body: die Anforderungsnutzlast (Request Payload). Cypress serialisiert Objekte in JSON.
• headers: ein Objekt von Anforderungsheadern.
• auth: Anmeldeinformationen für die HTTP Basic Authentication.
• qs: Query-String-Parameter als Objekt.
• failOnStatusCode: auf false setzen, wenn Sie eine Assertion für eine 4xx- oder 5xx-Antwort durchführen möchten, anstatt den Test fehlschlagen zu lassen.

Diese letzte Option ist wichtig für negative Tests. Standardmäßig lässt cy.request() den Test bei jedem Status, der nicht 2xx oder 3xx ist, fehlschlagen. Wenn Sie überprüfen möchten, ob eine fehlerhafte Anfrage 400 zurückgibt, müssen Sie dies explizit deaktivieren:

cy.request({
  method: 'GET',
  url: 'https://jsonplaceholder.typicode.com/users/99999',
  failOnStatusCode: false
}).then((response) => {
  expect(response.status).to.eq(404)
})

Assertions für Status und Body

cy.request() liefert ein Antwortobjekt (Response Object). Verketten Sie .then(), um es zu lesen. Die Antwort hat vier Eigenschaften, die Sie am häufigsten verwenden werden:

• status: der HTTP-Statuscode.
• body: die Antwortnutzlast (Response Payload). Cypress parst sie in ein JavaScript-Objekt, wenn der Content-Type auf json endet.
• headers: die Antwortheader.
• duration: die Dauer der Anfrage in Millisekunden.

Hier ist ein vollständiger Test, der den Status, die Body-Struktur und ein spezifisches Feld überprüft:

describe('Users API', () => {
  it('returns a list of users', () => {
    cy.request('https://jsonplaceholder.typicode.com/users').then((response) => {
      expect(response.status).to.eq(200)
      expect(response.body).to.be.an('array')
      expect(response.body).to.have.length(10)
      expect(response.body[0]).to.have.property('email')
    })
  })
})

Da response.body bereits ein geparstes Objekt ist, können Sie es mit Standard-Chai überprüfen. Sie können den Typ, die Länge, verschachtelte Eigenschaften oder genaue Werte überprüfen. Dies ist dieselbe Assertions-Syntax, die Sie auch für UI-Tests verwenden, sodass Sie nichts Neues lernen müssen.

Sie können auch Assertions für Antwortheader durchführen, was praktisch ist, um den Content-Type oder das Caching zu überprüfen:

cy.request('https://jsonplaceholder.typicode.com/users').then((response) => {
  expect(response.headers['content-type']).to.include('application/json')
})

Für einen tieferen Einblick in die Strukturierung dieser Prüfungen, lesen Sie unseren Leitfaden zu API-Assertions und die umfassenderen Best Practices für API-Tests.

Anfragen verketten und ein Authentifizierungstoken wiederverwenden

Echte APIs benötigen Authentifizierung. Das gängige Muster ist, sich einmal anzumelden, das Token zu erfassen und es dann bei jeder folgenden Anfrage mitzusenden. cy.request() lässt sich hierfür sauber verketten.

Senden Sie die Anmeldeanfrage, lesen Sie das Token aus dem Antwort-Body und verwenden Sie es dann im nächsten Aufruf:

describe('Authenticated API flow', () => {
  it('logs in and fetches a protected resource', () => {
    cy.request({
      method: 'POST',
      url: 'https://api.example.com/login',
      body: {
        email: 'user@example.com',
        password: 'secret'
      }
    }).then((loginResponse) => {
      expect(loginResponse.status).to.eq(200)
      const token = loginResponse.body.token

      cy.request({
        method: 'GET',
        url: 'https://api.example.com/profile',
        headers: {
          Authorization: `Bearer ${token}`
        }
      }).then((profileResponse) => {
        expect(profileResponse.status).to.eq(200)
        expect(profileResponse.body).to.have.property('email', 'user@example.com')
      })
    })
  })
})

Wenn mehrere Tests dasselbe Token benötigen, verschieben Sie die Anmeldung in einen beforeEach-Hook und speichern Sie das Token mit Cypress.env() oder einem gewrappten Alias, damit jeder Test es übernehmen kann. Das hält die Authentifizierungseinrichtung an einem Ort, anstatt sie in jedem Spec zu wiederholen.

Dieses Login-und-dann-Verwenden-Muster entspricht dem, was Sie in jedem API-Integrationstest-Ablauf schreiben würden, bei dem ein Aufruf Daten in den nächsten einspeist.

cy.intercept() zum Stubbing

cy.request() spricht die echte API an. Manchmal möchten Sie das Gegenteil: die Anfragen Ihrer Frontend-Anwendung abfangen und eine gefälschte Antwort zurückgeben. Dafür ist cy.intercept() da.

Hier gibt es einen wichtigen Unterschied. cy.intercept() fängt nur Anfragen ab, die von Ihrer Frontend-Anwendung im Browser gestellt werden. Es fängt cy.request() nicht ab, da cy.request() den Browser vollständig umgeht. Verwenden Sie cy.intercept(), wenn Sie testen, wie Ihre Benutzeroberfläche auf eine bestimmte API-Antwort reagiert, und nicht, wenn Sie die API selbst testen.

Sie können eine Anfrage überwachen, sie mit einer statischen Antwort stubben oder darauf warten. Zum Stubben übergeben Sie ein Antwortobjekt:

cy.intercept('GET', '/api/users', {
  statusCode: 200,
  body: [{ id: 1, name: 'Ada' }]
})

Nun gibt jede Browser-Anfrage an /api/users diese feste Nutzlast zurück. Dies ermöglicht es Ihnen, Randfälle zu testen, die schwer gegen ein Live-Backend auszulösen sind, wie eine leere Liste, einen 500-Fehler oder eine langsame Antwort.

Um zu überprüfen, ob die Anfrage stattgefunden hat, vergeben Sie ihr einen Alias mit .as() und warten Sie darauf:

it('shows an error banner when the API fails', () => {
  cy.intercept('GET', '/api/users', {
    statusCode: 500,
    body: { message: 'Server error' }
  }).as('getUsers')

  cy.visit('/dashboard')
  cy.wait('@getUsers').its('response.statusCode').should('eq', 500)
  cy.contains('Something went wrong').should('be.visible')
})

Die Zeile cy.wait('@getUsers') pausiert den Test, bis die abgefangene Anfrage abgeschlossen ist, und übergibt Ihnen dann die Anfrage und Antwort zur Überprüfung. Richten Sie den Intercept ein, bevor die Aktion stattfindet, die die Anfrage auslöst, sonst wird nichts abgefangen. Wenn Sie abwägen, wann Sie eine Antwort fälschen oder einen ganzen Dienst mocken sollten, erläutern unsere Beiträge zu API-Mocking und API-Stubbing vs. API-Mocking die Kompromisse.

Wann Cypress für API-Tests sinnvoll ist und wann nicht

Cypress eignet sich hervorragend für API-Prüfungen, die Teil einer UI-Testsuite sind. Wenn Sie bereits E2E-Tests schreiben und Daten vorbereiten, einen Endpunkt überprüfen, von dem Ihre UI abhängt, oder eine Antwort stubben müssen, um die Fehlerbehandlung zu testen, halten cy.request() und cy.intercept() alles an einem Ort. Kein Kontextwechsel, kein zweites Tool.

Es ist auch gut geeignet für eine Handvoll eigenständiger API-Smoke-Tests, wenn Cypress Ihr einziger Test-Runner ist und Sie keine weitere Abhängigkeit hinzufügen möchten.

Schwierig wird es bei einer großen, eigenständigen API-Testsuite. Cypress wurde für den Browser entwickelt, daher ist API-Testing eine zusätzlich aufgesetzte Funktion und nicht das Kerndesign. Einige Lücken zeigen sich, wenn die Suite wächst:

• Kein visueller Request Builder. Jede Anfrage ist Code. Das manuelle Zusammenstellen von Headern, Bodys und Query-Parametern wird langsam, wenn Sie Hunderte von Endpunkten haben.
• Weniger geeignet für eine reine API-Pipeline in CI. Cypress startet einen Browser-Kontext auch für reine API-Läufe, was ein unnötiger Overhead ist.
• Keine gemeinsame API-Definition. Die Anfragestrukturen befinden sich in Ihren Testdateien, nicht in einer Spezifikation, die Ihr Team über Design, Dokumentation und Tests hinweg wiederverwenden kann.

Hier passt ein API-natives Tool besser. Apidog ist um die API selbst herum aufgebaut: Sie entwerfen einen Endpunkt einmal und erstellen dann Testszenarien dafür mit einem visuellen Request Builder und visuellen Assertions, ohne Code für die gängigen Fälle. Anfragen, Umgebungen und Authentifizierung leben in einem gemeinsamen Arbeitsbereich, sodass Ihr Team sie nicht erneut aus Testdateien ableiten muss.

Für CI führt die Apidog CLI Ihre gespeicherten Testszenarien headless in jedem Schritt aus, der Node ausführen kann:

npm install -g apidog-cli

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t <scenarioOrSuiteId> \
  -e <environmentId> \
  -r cli,html,junit

Das Flag -t zielt auf ein gespeichertes Szenario oder eine Suite ab, -e wählt eine Umgebung aus und -r wählt die Berichtsformate (cli, html, json, junit). Die JUnit-Ausgabe lässt sich direkt in die meisten CI-Dashboards integrieren. Fügen Sie -d oder --iteration-data hinzu, um einen Test aus einer Datendatei zu steuern, und --upload-report, um die Ergebnisse in Ihren Arbeitsbereich zurückzusenden. Die CLI führt gespeicherte Szenarien aus; sie ist kein interaktiver Request-Sender.

Eine nützliche Denkweise: Verwenden Sie cy.request() für API-Prüfungen, die Ihre Browser-Tests unterstützen, und greifen Sie zu einem API-nativen Tool, wenn API-Tests die Hauptaufgabe sind. Wenn Sie Optionen vergleichen, decken unsere Übersichten der API-Testautomatisierungstools, die in CI/CD laufen, und die umfassenderen 30 besten API-Testtools das gesamte Spektrum ab.

Häufig gestellte Fragen (FAQ)

Läuft cy.request() im Browser?

Nein. cy.request() läuft vom Cypress Node-Prozess aus, außerhalb des Browsers. Deshalb wird es nicht durch CORS oder die Same-Origin-Policy blockiert, und deshalb kann cy.intercept() es nicht abfangen. Wenn Sie eine Anfrage benötigen, die der Browser stellt, lösen Sie diese über Ihre App aus und fangen Sie sie mit cy.intercept() ab.

Wie teste ich eine 400- oder 404-Antwort, ohne den Test fehlschlagen zu lassen?

Standardmäßig schlägt cy.request() bei jedem Status fehl, der nicht 2xx oder 3xx ist. Setzen Sie failOnStatusCode: false im Options-Objekt und überprüfen Sie dann den Status selbst mit expect(response.status).to.eq(404).

Kann ich cy.request() verwenden, um mich vor einem UI-Test anzumelden?

Ja, und das ist ein gängiges Muster. Senden Sie eine POST-Anfrage an Ihren Login-Endpunkt mit cy.request(), lesen Sie das Token aus response.body und speichern Sie es (in Cypress.env(), localStorage oder einem Cookie), damit Ihr UI-Test bereits authentifiziert beginnt. Dies überspringt das Login-Formular und beschleunigt die Suite.

Was ist der Unterschied zwischen cy.request() und cy.intercept()?

cy.request() sendet eine echte HTTP-Anfrage und gibt die tatsächliche Antwort zurück, daher verwenden Sie es, um eine API zu testen. cy.intercept() überwacht oder fälscht die Anfragen, die Ihr Frontend im Browser stellt, daher verwenden Sie es, um zu steuern, was Ihre Benutzeroberfläche empfängt. Eines sendet an das Netzwerk; das andere formt es.

Sollte ich Cypress oder ein dediziertes Tool für API-Tests verwenden?

Verwenden Sie Cypress, wenn API-Prüfungen eine Browser-Testsuite unterstützen, die Sie bereits ausführen. Für eine große eigenständige API-Suite, reine API-Pipelines in CI oder eine gemeinsame API-Definition, mit der Ihr gesamtes Team arbeitet, passt ein API-natives Tool wie Apidog besser. Unsere Best Practices für API-Tests zeigen Ihnen, wie Sie sich entscheiden können.