GraphQL Testing: Queries, Snapshots und Contract-Tests

1. Warum GraphQL Testing mehr ist als eine Query ausprobieren

Wer eine GraphQL-Query einmal manuell in GraphiQL ausgeführt hat und das Ergebnis korrekt aussah, hat noch keinen Test. Das ist Exploration, nicht Qualitätssicherung. Der Unterschied wird spürbar, wenn drei Monate später ein anderes Team-Mitglied einen Resolver umschreibt, ein Feld umbenennt oder die Paginierungsstruktur ändert – und das Frontend still Fehler produziert, weil niemand eine automatisierte Prüfung kannte.

GraphQL Testing umfasst mehrere Ebenen: Query-Tests prüfen, ob eine bekannte Anfrage das erwartete Ergebnis liefert. Snapshot-Tests vergleichen die aktuelle Response-Struktur mit einem gespeicherten Referenz-Ergebnis und schlagen Alarm bei unerwarteten Änderungen. Contract-Tests gehen weiter und definieren formale Verträge zwischen dem Frontend-Team, das Queries schreibt, und dem Backend-Team, das das Schema pflegt. Alle drei Ansätze zusammen bilden eine Testschicht, die Schema-Evolution kontrollierbar macht und Überraschungen im Produktivbetrieb reduziert.

2. Query-Tests: Der erste Schritt zur stabilen API

Ein Query-Test schickt eine definierte GraphQL-Anfrage an die API und prüft die Antwort gegen bekannte Erwartungen. In Node.js-Projekten nutzt man dafür typischerweise Jest oder Vitest zusammen mit einer HTTP-Client-Library. Die Anfrage wird als Fixture-Datei abgelegt, damit sie versioniert werden kann und im Code-Review sichtbar ist. Das Wichtigste beim Aufbau von Query-Tests ist die Trennung zwischen dem Testaufruf und der Assertion: zuerst die Response speichern, dann spezifische Felder prüfen, anstatt die gesamte Response als String zu vergleichen.

In Magento-Projekten existiert dafür eine eigene Basis-Klasse für Integrationstests. Die Klasse GraphQlQueryTest stellt eine graphQlQuery()-Methode bereit, die intern einen vollständigen HTTP-Request gegen den laufenden Shop abfeuert. Das macht Magento-GraphQL-Tests zu echten Integrationstests – kein Mocking, kein in-memory-Schema, sondern der echte Resolver-Stack mit Datenbank. Das ist langsamer, aber wesentlich aussagekräftiger als Unit-Tests gegen isolierte Resolver-Klassen.

# Query fixture: category-products.graphql
# Tests product listing for a specific category page

query CategoryProducts($categoryId: String!, $pageSize: Int!) {
  products(
    filter: { category_id: { eq: $categoryId } }
    pageSize: $pageSize
    currentPage: 1
    sort: { position: ASC }
  ) {
    total_count
    page_info {
      current_page
      page_size
      total_pages
    }
    items {
      sku
      name
      url_key
      price_range {
        minimum_price {
          regular_price {
            value
            currency
          }
        }
      }
    }
  }
}

3. Snapshot-Tests: Regressionssicherung für Response-Strukturen

Snapshot-Tests lösen ein konkretes Problem: Man möchte sicherstellen, dass eine Response-Struktur nach einer Schema-Änderung noch dieselbe Form hat, ohne jedes einzelne Feld manuell assertieren zu müssen. Beim ersten Durchlauf wird die aktuelle Response als JSON-Datei gespeichert – der Snapshot. Bei jedem weiteren Test-Durchlauf wird die aktuelle Response mit dem gespeicherten Snapshot verglichen. Abweichungen führen zum Test-Fehler und müssen explizit bestätigt werden.

Der häufigste Einwand gegen Snapshot-Tests lautet: "Die Snapshots veralten doch sowieso schnell." Das stimmt – aber genau das ist der Punkt. Wenn ein Snapshot veraltet, ist eine bewusste Entscheidung nötig: Ist die Änderung gewollt? Dann wird der Snapshot aktualisiert. Ist sie ungewollt? Dann ist der Snapshot-Test der einzige Mechanismus, der die Regression sichtbar gemacht hat. Der Schlüssel liegt darin, die Snapshots als Quellcode zu behandeln und sie im Review-Prozess einzubeziehen – nicht als nervige Artefakte, die man blindlings mit --updateSnapshot aktualisiert.

# Snapshot test: validates that the product type structure
# has not changed between deployments

query ProductSnapshotTest {
  products(search: "testproduct-snapshot") {
    items {
      __typename
      sku
      name
      url_key
      meta_title
      meta_description
      price_range {
        minimum_price {
          regular_price { value currency }
          final_price { value currency }
          discount { amount_off percent_off }
        }
      }
      media_gallery {
        url
        label
        disabled
      }
    }
  }
}

4. Contract-Tests: Stabile Verträge zwischen Frontend und Backend

Contract-Tests sind die nächste Ausbaustufe über Snapshot-Tests hinaus. Statt nur die aktuelle Response zu snapshotten, definieren beide Seiten – Frontend und Backend – explizit, welche Felder das Frontend braucht und welche das Backend liefern muss. Diese Vereinbarung wird in einer Datei festgehalten und in der CI-Pipeline geprüft. GraphQL Inspector ist das gängigste Tool für diesen Zweck: Es prüft, ob alle im "Consumer"-Dokument verwendeten Felder im Schema vorhanden sind, ob ihre Typen übereinstimmen und ob deprecierte Felder noch genutzt werden.

In der Praxis funktioniert das am besten, wenn das Frontend-Team ihre Queries als Fragment-Definitionen in einem gemeinsamen Repository ablegt. Das Backend-Team überprüft bei Schema-Änderungen automatisch, ob vorhandene Consumer-Queries noch valide sind. Diese Workflow-Kombination macht Breaking Changes sichtbar, bevor sie deployt werden. Pact ist eine Alternative für REST-APIs, bei GraphQL ist GraphQL Inspector die natürlichere Wahl, weil es das Schema als Vertragsgrundlage direkt nutzt.

5. Schema-Validierung in der CI-Pipeline

Schema-Validierung in der CI-Pipeline bedeutet, dass bei jedem Merge-Request automatisch geprüft wird, ob Schema-Änderungen Breaking Changes einführen. Breaking Changes sind alle Änderungen, die vorhandene Queries ungültig machen: das Entfernen von Feldern, das Ändern von Argument-Typen auf nicht-kompatible Typen oder das Entfernen von Typen aus Unions. GraphQL Inspector kann in wenigen Zeilen Konfiguration in eine GitHub Actions oder GitLab CI Pipeline integriert werden und produziert einen klaren Bericht über Art und Schwere der Änderungen.

Ein pragmatischer Ansatz für Teams, die noch kein vollständiges Contract-Testing-Setup haben: Die SDL des aktuellen produktiven Schemas als Datei im Repository versionieren. Bei jedem Deployment wird die neue SDL mit der alten verglichen. Das ist keine perfekte Lösung, aber sie deckt die häufigsten Fälle ab und erfordert keinen externen Service. In Magento generiert man die SDL über bin/magento dev:graphql:schema und legt sie als Fixture im Testrepositorium ab.

# Consumer query document — used by the frontend product listing page
# Contract: Backend must provide all these fields

fragment ProductListItem on ProductInterface {
  sku
  name
  url_key
  small_image { url label }
  price_range {
    minimum_price {
      final_price { value currency }
      discount { percent_off }
    }
  }
  rating_summary
  review_count
}

query CategoryListing(
  $filter: ProductAttributeFilterInput!
  $pageSize: Int!
  $currentPage: Int!
) {
  products(filter: $filter, pageSize: $pageSize, currentPage: $currentPage) {
    total_count
    items { ...ProductListItem }
    page_info { current_page total_pages }
    aggregations {
      attribute_code
      label
      count
      options { label value count }
    }
  }
}

6. GraphQL Testing in Magento: Integration und PHPUnit

Magento liefert eine vollständige Infrastruktur für GraphQL-Integrationstests. Die Basis ist die abstrakte Klasse Magento\TestFramework\TestCase\GraphQlAbstract, die Methoden wie graphQlQuery(), graphQlMutation() und graphQlQueryWithResponseHeaders() bereitstellt. Diese Tests laufen gegen eine laufende Magento-Instanz mit Testdaten aus Fixtures und prüfen echte Resolver-Pfade inklusive Datenbankzugriffe, Caching und Plugin-Ketten.

Das Magento-Testing-Setup hat Stärken und Schwächen. Die Stärke: Tests sind realistisch und decken auch Datenbankprobleme, fehlende Indexer-Einträge und Resolver-Bugs auf. Die Schwäche: Die Tests sind langsam und erfordern eine laufende Umgebung. Für schnelle Feedback-Schleifen während der Entwicklung empfiehlt es sich, die langsamen Integrationstests in der CI laufen zu lassen und lokal mit Altair oder GraphiQL gegen eine laufende Dev-Instanz zu explorieren. Unit-Tests für Resolver-Klassen sind möglich, aber nur sinnvoll für Resolver, die komplexe Logik kapseln – einfache Resolver-Weiterleitung braucht keinen Mocking-Test.

7. Tools im Überblick: Jest, Vitest, Inspector und mehr

Die Werkzeuglandschaft für GraphQL Testing ist überschaubar, wenn man sie nach Aufgaben ordnet. Für Query-Tests und Snapshot-Tests auf Node.js-Seite sind Jest und Vitest die gängigen Test-Runner. Beide unterstützen Snapshots nativ. Für reine API-Tests ohne Frontend-Code ist Hurl eine schlanke Alternative: HTTP-Requests als Textdatei mit eingebetteten Assertions, versionierbar und lesbar ohne JavaScript-Kenntnisse.

Für Schema-Validierung und Contract-Prüfungen ist GraphQL Inspector das ausgereifteste Tool. Es bietet Kommandozeilen-Tools, einen GitHub-Check und eine Web-UI. Rover CLI von Apollo ist eine Alternative, die eng mit Apollo Studio integriert ist und Schema-Checks als Teil des Apollo-Ökosystems abdeckt. Für Teams ohne Apollo-Stack ist GraphQL Inspector die neutralere Wahl. Ein oft übersehenes Tool ist graphql-tag in Kombination mit TypeScript: Wenn Queries typsicher kompiliert werden, fängt der Compiler viele breaking changes bereits zur Build-Zeit ab, bevor Tests überhaupt laufen.

8. Typische Fehler und wie man sie erkennt

Der häufigste Fehler beim Aufbau von GraphQL-Tests ist, nur den "Happy Path" zu testen: Die Query gibt Daten zurück, alles sieht gut aus. Was fehlt: Tests für Fehlerfälle. Was passiert, wenn ein Produkt nicht existiert? Liefert die API einen leeren Array oder ein null? Liefert sie einen Fehler im errors-Array oder im data-Feld? In GraphQL ist beides gültig, je nach Implementierung. Contract-Tests müssen auch die Fehlerstruktur definieren, nicht nur die Erfolgsstruktur.

Ein zweites typisches Problem: Tests, die gegen Produktionsdaten laufen. Produktionsdaten ändern sich, und Tests, die davon abhängen, sind instabil. Die Lösung ist eine saubere Test-Fixture-Strategie: Testdaten werden vor dem Test eingespielt und danach gelöscht. Magento bietet dafür den @magentoDataFixture-Annotationsmechanismus. Ein dritter Fehler ist das Fehlen von Tests für Auth-Fälle: Welche Felder sind nur für eingeloggte Kunden sichtbar? Contract-Tests sollten explizit prüfen, dass geschützte Felder ohne Token keinen Wert zurückliefern, sondern einen Fehler.

9. Testing-Ansätze im direkten Vergleich

Die häufigste Frage beim Aufbau einer GraphQL-Teststrategie lautet: "Brauchen wir wirklich alle drei Schichten?" Die Antwort hängt vom Team und vom API-Reifegrad ab. Ein einzelner Entwickler, der eine interne API pflegt, kommt lange mit einfachen Query-Tests aus. Ein Team mit mehreren Frontend-Konsumenten, das das Schema unabhängig weiterentwickelt, braucht Contract-Tests, weil sonst koordinierte Deployments zur einzigen Schutzmaßnahme werden.

Der wichtigste Praxishinweis: GraphQL Testing ist kein einmaliges Setup, sondern ein Prozess. Tests veralten, wenn das Schema wächst und niemand die Fixtures aktualisiert. Die Teststrategie muss im Team explizit vereinbart werden – wer ist verantwortlich für welche Test-Schicht? Das klingt nach Overhead, verhindert aber die häufigste Situation in der Praxis: niemand hat Tests geschrieben, weil jeder davon ausgegangen ist, jemand anderes würde es tun.

10. Zusammenfassung

GraphQL Testing ist ein Thema, das in vielen Projekten zu spät angegangen wird. Solange die API klein und das Team überschaubar ist, reicht explorative Nutzung von GraphiQL. Sobald mehrere Teams an verschiedenen Konsumenten arbeiten oder das Schema regelmäßig weiterentwickelt wird, sind Query-Tests, Snapshot-Tests und Contract-Tests keine Optionen, sondern Notwendigkeiten. Der Unterschied zwischen einem Schema, das jederzeit geändert werden kann, und einem, das Frontends stabil hält, liegt fast immer in der Testabdeckung.

In Magento-Projekten bietet die eingebaute Test-Infrastruktur einen soliden Ausgangspunkt. Die Kombination aus Magento-Integrationstests für Resolver-Korrektheit, GraphQL Inspector für Schema-Evolution und Snapshot-Tests für Response-Stabilität deckt die wichtigsten Risiken ab. Der nächste Schritt nach diesem Artikel: Eine einzelne kritische Query auswählen, einen Snapshot-Test schreiben und in die CI-Pipeline integrieren – das ist der erste konkrete Schritt zu einer stabilen GraphQL-Teststrategie.

11. FAQ: GraphQL Testing – Queries, Snapshots und Contract-Tests