Sie haben einen GraphQL-Endpunkt und müssen wissen, ob er funktioniert. Nicht „der Server ist oben“, sondern das Echte: Liefert die `user`-Abfrage die Felder, die Ihre App liest, speichert eine `createOrder`-Mutation tatsächlich eine Bestellung, und bleiben die Formen erhalten, wenn Sie eine Variable ändern? Ein REST-Tool, das nur Pfad-und-Verb-Aufrufe kennt, macht dies umständlich. GraphQL sendet alles an eine URL als POST-Body, daher benötigen Sie einen Client, der die Abfragesprache selbst versteht, Ihnen Feldvorschläge macht und Sie JSON überprüfen lässt, das zurückkommt.
Apidog behandelt GraphQL als erstklassigen Anfragetyp, neben HTTP, gRPC, WebSocket, SSE und SOAP. Dieser Leitfaden führt Sie durch den Aufbau einer GraphQL-Anfrage von Grund auf: Schreiben einer Abfrage, Abrufen des Schemas für die Code-Vervollständigung, Übergeben von Variablen, Ausführen einer Mutation und Überprüfen der Antwort. Das laufende Beispiel ist eine E-Commerce-API, bei der Sie einen Benutzer und seine Bestellungen abfragen und dann eine neue Bestellung erstellen. Wenn Sie den konzeptionellen Hintergrund wissen möchten, warum GraphQL eine einzige typisierte Abfrage anstelle vieler Endpunkte sendet, ist die offizielle GraphQL-Dokumentation die kanonische Referenz, und unser Vergleich von REST vs GraphQL behandelt, wann welches passt.
Was Sie testen und warum GraphQL anders ist
REST bietet Ihnen viele Endpunkte, von denen jeder eine feste Form zurückgibt. GraphQL bietet Ihnen einen Endpunkt und lässt den Aufrufer genau die gewünschten Felder anfordern. Diese Flexibilität ist der Kernpunkt, und sie macht auch das Testen anders.
Zwei Dinge ändern sich. Erstens ist die Anfrage ein Abfragedokument im Body, nicht eine URL, die Sie variieren. Ein `GET /users/42` wird zu einer `user(id: 42) { ... }`-Auswahl, die per POST gesendet wird. Zweitens gibt GraphQL bei einem Geschäftsfehler fast nie einen Nicht-200-Status zurück. Eine fehlgeschlagene Abfrage kommt immer noch als `200 OK` mit einem `errors`-Array im JSON zurück. Das Überprüfen des Statuscodes reicht also nicht aus. Sie müssen den Body lesen. Diese einzige Tatsache prägt, wie Sie später in diesem Leitfaden Behauptungen aufstellen werden.
Apidog bietet Ihnen einen dedizierten GraphQL-Body-Typ, schema-bewusste Code-Vervollständigung, Variablen für wiederverwendbare Abfragen und dieselben Assertions- und Testszenario-Tools, die Sie auch für REST verwenden würden. Sie entwerfen und führen die Anfrage in der App aus, speichern sie dann in einem Szenario, das Sie erneut ausführen können. Lassen Sie uns eines erstellen.
Eine GraphQL-Anfrage in Apidog erstellen
Zuerst laden Sie Apidog herunter oder öffnen Sie es in Ihrem Browser, dann öffnen Sie Ihr Projekt. Wenn Sie neu beginnen, erstellen Sie ein Projekt, damit die Anfrage einen Speicherort hat.
Schritt 1: Eine neue Anfrage erstellen und den Body auf GraphQL umstellen
Klicken Sie auf die Schaltfläche `+` und wählen Sie `Neue Anfrage`. Dies öffnet den Standard-Anfrage-Builder, denselben, den Sie für einen REST-Aufruf verwenden würden: Methode, URL, Parameter und `Autorisierung`.
Stellen Sie die Methode auf `POST` ein und fügen Sie Ihren GraphQL-Endpunkt in die URL-Leiste ein. Ein typischer sieht so aus:
https://api.yourstore.com/graphql
Teilen Sie Apidog nun mit, dass dies eine GraphQL-Anfrage ist. Klicken Sie im Bereich des Anfragetextes auf `Body` und wählen Sie dann `GraphQL`. Der Body-Editor wechselt zu einer GraphQL-fähigen Ansicht mit einem `Query`-Feld, in dem die Abfragesprache enthalten ist.
Wenn Ihr Endpunkt ein Token benötigt, öffnen Sie den Abschnitt `Autorisierung` und fügen Sie es dort hinzu, zum Beispiel ein Bearer-Token. Die Authentifizierung bei einer GraphQL-Anfrage funktioniert genauso wie bei jeder anderen HTTP-Anfrage in Apidog, da es sich im Grunde immer noch um einen HTTP-POST handelt.
Schritt 2: Ihre erste Abfrage schreiben
Geben Sie auf der Registerkarte `Ausführen` Ihre Abfrage in das Feld `Abfrage` ein. Beginnen Sie mit etwas Konkretem. Hier möchten Sie einen Benutzer und die ihm zugeordneten Bestellungen:
query GetUserWithOrders {
user(id: "usr_1024") {
id
name
email
orders {
id
total
status
createdAt
}
}
}
Dies fragt nach einem Benutzer und einer verschachtelten Liste seiner Bestellungen. Die Feldnamen müssen exakt mit dem Schema Ihres Servers übereinstimmen. Wenn Ihr Schema es `emailAddress` statt `email` nennt, schlägt diese Abfrage fehl. Das ist die Aufgabe des nächsten Schritts, dies zu verhindern.
Schritt 3: Das Schema für die Code-Vervollständigung abrufen
Das Erraten von Feldnamen ist der Punkt, an dem GraphQL-Tests langsam werden. Apidog kann Ihr Schema lesen, sodass der Editor gültige Felder und Typen vorschlägt, während Sie tippen, anstatt dass Sie ein Dokument in einem anderen Tab gegenprüfen müssen.
Dies ist eine manuelle, bei Bedarf auszuführende Aktion. Klicken Sie auf die Schaltfläche `Schema abrufen` im Eingabefeld. Apidog führt eine Introspektionsabfrage gegen Ihren Endpunkt aus und zieht das Typsystem. Sobald dies erfolgreich ist, wird die Code-Vervollständigung aktiviert: Beginnen Sie, ein Feld innerhalb einer Auswahl zu tippen, und Sie erhalten IntelliSense-ähnliche Vorschläge für das, was tatsächlich auf diesem Typ verfügbar ist.
Zwei Dinge, die Sie wissen sollten. Die Code-Vervollständigung ist nicht automatisch; sie wird erst aktiviert, nachdem Sie auf `Schema abrufen` geklickt haben. Und wenn Ihr Endpunkt die Introspektion deaktiviert hat (einige Produktionsserver tun dies aus Sicherheitsgründen), liefert der Abruf kein Schema zurück, sodass Sie Felder manuell anhand Ihrer eigenen Dokumentation schreiben müssen. Wenn der Abruf funktioniert, rufen Sie ihn nach jeder Schemaänderung erneut ab, damit die Vorschläge aktuell bleiben.
Schritt 4: Ausführen und die Antwort lesen
Klicken Sie auf `Senden`. Die Antwort erscheint in der unteren Hälfte der Oberfläche. Ein gesundes Ergebnis sieht so aus:
{
"data": {
"user": {
"id": "usr_1024",
"name": "Dana Whitfield",
"email": "dana@example.com",
"orders": [
{ "id": "ord_5001", "total": 89.90, "status": "SHIPPED", "createdAt": "2026-07-01T09:14:00Z" },
{ "id": "ord_5002", "total": 12.50, "status": "PENDING", "createdAt": "2026-07-12T16:03:00Z" }
]
}
}
}
Beachten Sie den Top-Level-Schlüssel `data`. Jede GraphQL-Antwort schachtelt Ihr Ergebnis unter `data`, und alle Probleme erscheinen in einem Geschwister-`errors`-Array. Beachten Sie diese Struktur, denn Ihre Assertions werden auf `data.user...` zeigen, nicht auf die Wurzel.
Variablen übergeben, um die Anfrage wiederverwendbar zu machen
Das Hardcodieren von `"usr_1024"` in die Abfrage funktioniert einmal. Für eine Anfrage, die Sie über Benutzer und Umgebungen hinweg erneut ausführen werden, verschieben Sie diesen Wert in eine Variable. GraphQL verfügt über eine erstklassige Variablensyntax dafür, und Apidog unterstützt diese. Die Syntax selbst ist Standard-GraphQL und keine Erfindung von Apidog, daher sind die offiziellen GraphQL-Dokumente zu Variablen die maßgebliche Quelle.
Deklarieren Sie die Variable in der Abfragesignatur mit einem `$`-Präfix und einem Typ, und verwenden Sie sie dann in den Argumenten:
query GetUserWithOrders($userId: ID!) {
user(id: $userId) {
id
name
orders {
id
total
status
}
}
}
Geben Sie dann den Wert als kleines JSON-Objekt von Variablen an:
{
"userId": "usr_1024"
}
Nun läuft dieselbe Abfrage für jeden Benutzer, indem ein JSON-Wert geändert wird. Kombinieren Sie dies mit Apidog-Umgebungsvariablen und Sie können die identische Anfrage auf Staging- und Produktionsumgebungen richten, ohne die Abfrage bearbeiten zu müssen. Dies verwandelt einen einmaligen Aufruf in etwas, das Sie speichern, teilen und in einer Suite ausführen können.
Eine Mutation zum Erstellen einer Bestellung schreiben
Eine Mutation ändert Daten. In GraphQL gibt es kein separates Protokoll oder UI dafür; eine Mutation wird als GraphQL im selben `Query`-Feld geschrieben, mit dem Schlüsselwort `mutation` anstelle von `query`. Der Workflow, den Sie bereits kennen, lässt sich also direkt übertragen.
Hier erstellen Sie eine Bestellung für den Benutzer, den Sie zuvor abgefragt haben:
mutation CreateOrder($input: CreateOrderInput!) {
createOrder(input: $input) {
id
total
status
createdAt
}
}
Die Variablen tragen die Nutzdaten:
{
"input": {
"userId": "usr_1024",
"items": [
{ "sku": "TSHIRT-BLK-M", "quantity": 2 },
{ "sku": "MUG-CERAMIC", "quantity": 1 }
],
"currency": "USD"
}
}
Klicken Sie auf `Senden`. Eine gute Antwort spiegelt die erstellte Bestellung wider:
{
"data": {
"createOrder": {
"id": "ord_5003",
"total": 42.30,
"status": "PENDING",
"createdAt": "2026-07-15T10:22:11Z"
}
}
}
Da Mutationen echte Daten schreiben, führen Sie sie in einer Test- oder Staging-Umgebung aus, nicht in der Produktion. Ein gängiges Muster ist es, die Mutation auszuführen, die zurückgegebene `id` zu erfassen und dann Ihre `GetUserWithOrders`-Abfrage erneut auszuführen und zu bestätigen, dass die neue Bestellung in der Liste erscheint. Dieser Query-Mutation-Query-Loop ist eine realistische End-to-End-Prüfung, und genau die Art von Sache, die Sie im nächsten Abschnitt als Szenario speichern möchten.
Auf die Antwort prüfen, anstatt sie nur zu betrachten
Das manuelle Lesen von JSON ist in Ordnung, solange Sie explorieren. Für einen Test, der unbeaufsichtigt läuft, benötigen Sie Assertions, die von selbst bestehen oder fehlschlagen. Apidog ermöglicht es Ihnen, Assertions zu einer Anfrage hinzuzufügen, sodass ein Lauf automatisch bewertet wird, was Sie in den API-Assertions einrichten.
Für GraphQL decken drei Prüfungen die meisten Fälle ab:
- Bestätigen Sie, dass der HTTP-Status `200` ist. Notwendig, aber nicht ausreichend, da GraphQL auch bei Geschäftsfehlern 200 zurückgibt.
- Bestätigen Sie, dass das Feld `errors` nicht vorhanden ist. Dies ist das eigentliche GraphQL-Pass- oder Fail-Tor. Wenn `errors` existiert, ist der Vorgang fehlgeschlagen, egal was der Status sagt.
- Prüfen Sie bestimmte Werte innerhalb von `data` mithilfe eines JSONPath wie `$.data.createOrder.status` gleich `PENDING` oder `$.data.user.orders` hat eine Länge größer als null.
Diese Kombination fängt die Fehlerfälle ab, die eine reine Statusprüfung übersehen würde: eine Abfrage, die 200 mit einem `errors`-Array zurückgibt, oder eine, die erfolgreich ist, aber die falsche Form zurückgibt. Richten Sie Ihre Wertprüfungen auf den verschachtelten Pfad unter `data` aus, passend zur zuvor gesehenen Antwortstruktur.
In einem Testszenario speichern
Eine einzelne bestätigte Anfrage ist ein guter Smoke Test. Der wahre Nutzen liegt darin, Anfragen zu einem Szenario zu verketten: den Benutzer abfragen, eine Bestellung erstellen und dann erneut abfragen, um zu bestätigen, dass sie gespeichert wurde. Apidog-Testszenarien ermöglichen es Ihnen, diese Schritte zu sequenzieren, Daten zwischen ihnen zu übergeben (die `id` aus der Mutation erfassen, sie in die Bestätigungsabfrage einspeisen) und den gesamten Fluss mit einem Klick auszuführen. Die vollständige Anleitung finden Sie unter Wie man ein Testszenario mit Apidog schreibt.
Im Großen und Ganzen: Erstellen Sie ein neues Testszenario, fügen Sie Ihre GraphQL-Abfrage und -Mutation als Schritte in der richtigen Reihenfolge hinzu, extrahieren Sie die Bestell-`id` aus der Mutationsantwort in eine Variable und referenzieren Sie diese Variable im letzten Abfrageschritt. Fügen Sie die Assertions aus dem vorherigen Abschnitt zu jedem Schritt hinzu. Jetzt haben Sie einen wiederholbaren Regressionstest für Ihre GraphQL-API, den ein Mensch, ein Zeitplan oder eine Pipeline ausführen kann.
Für Teams, die GraphQL vor einer Entscheidung mit anderen Stilen vergleichen, helfen unser Vergleich von REST vs GraphQL vs gRPC und die Übersicht über GraphQL-Test- und Mocking-Tools, diesen Workflow einzuordnen. Und wenn Ihr Stack auch SOAP spricht, gilt dasselbe Anfrage-und-Assert-Muster in Wie man SOAP-APIs in Apidog testet.
Den Workflow mit der Apidog CLI automatisieren
Sobald Ihre GraphQL-Szenarien im Projekt leben, können Sie die gespeicherten Testszenarien des Projekts von einem Terminal oder CI-Runner mit der Apidog CLI ausführen. Installieren Sie sie und melden Sie sich an:
npm install -g apidog-cli
apidog login --with-token <Ihr-Token>
Dann führen Sie ein gespeichertes Szenario nach ID aus, das auf eine Umgebung zeigt:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <Szenario-ID> -e <Umgebungs-ID> -r cli
Hier ist `-t` die Test-Szenario-ID, `-e` die Umgebungs-ID und `-r` der Reporter (`cli`, `html` oder `junit`; kommagetrennt, wie `–r html,cli`, für mehr als einen). Die CLI führt gespeicherte Szenarien und Test-Suites aus Ihrem Cloud-Projekt aus und meldet Erfolg oder Misserfolg, was Apidog in einen Build integriert. Eine ehrliche Einschränkung: Die CLI-Dokumentation bestätigt die Ausführung von HTTP-Szenarien, und es wird nicht angegeben, ob Szenarien, die GraphQL-Schritte enthalten, headless ausgeführt werden. Betrachten Sie die CLI als Ihre Engine für HTTP-Regressionstests und zur Synchronisierung von Spezifikationen über ihren `import`-Befehl (OpenAPI, HAR, Postman und mehr), und führen Sie Ihre GraphQL-Abfragen, Mutationen und Assertions in der App durch. Eine Anleitung zur Token-Einrichtung finden Sie im Apidog CLI Installationshandbuch und Informationen zur Integration in CI unter Apidog CLI in einer GitHub Actions Pipeline.
FAQ
Benötige ich einen kostenpflichtigen Plan, um GraphQL in Apidog zu testen? Die GraphQL-Anfragedokumentation schränkt diese Funktion nicht hinter einer Planstufe ein und zieht auch keine Linie zwischen Cloud und Self-Hosting. Sie können mit der kostenlosen Stufe beginnen: Kostenlos ausprobieren, keine Kreditkarte erforderlich, und unter Apidog finden Sie aktuelle Plan-Details.
Warum gibt meine GraphQL-Anfrage 200 zurück, schlägt aber trotzdem fehl? Das ist normales GraphQL-Verhalten. Die Übertragung war erfolgreich, daher ist der HTTP-Status 200, aber der Vorgang traf auf einen Geschäfts- oder Validierungsfehler, der im `errors`-Array des JSON-Bodys landet. Bestätigen Sie immer, dass `errors` nicht vorhanden ist, zusätzlich zur Überprüfung des Status, wie in den API-Assertions beschrieben.
Wie erhalte ich Feldvorschläge beim Schreiben einer Abfrage? Klicken Sie auf die Schaltfläche `Schema abrufen` im Eingabefeld. Apidog introspektiert Ihren Endpunkt und aktiviert die Code-Vervollständigung, sodass der Editor gültige Felder und Typen vorschlägt. Es ist ein manueller Schritt, nicht automatisch, also klicken Sie darauf, sobald Ihre Endpunkt-URL festgelegt ist, und rufen Sie es nach jeder Schemaänderung erneut ab.
Wo sind Mutationen? Ich sehe keinen separaten Mutations-Tab. Es gibt keinen. Eine Mutation wird als GraphQL im selben `Query`-Feld geschrieben, wobei das Schlüsselwort `mutation` anstelle von `query` verwendet wird. Übergeben Sie die Nutzdaten über Variablen und klicken Sie dann auf `Senden`, genau wie bei einer Abfrage.
Wie übergebe ich verschiedene Werte, ohne die Abfrage neu zu schreiben? Verwenden Sie GraphQL-Variablen. Deklarieren Sie diese in der Operationssignatur mit einem `$`-Präfix und liefern Sie ein JSON-Objekt mit Werten. Die Syntax folgt der Standard-GraphQL-Spezifikation, und die Variablenunterstützung von Apidog lässt sich mit Umgebungsvariablen kombinieren, sodass eine Anfrage über Staging und Produktion hinweg ausgeführt werden kann.
Zusammenfassung
Das Testen von GraphQL läuft auf ein paar ehrliche Gewohnheiten hinaus: Schreiben Sie die Abfrage in das `Query`-Feld, rufen Sie das Schema ab, damit der Editor Ihnen hilft, verschieben Sie feste Werte in Variablen und bestätigen Sie den Body, anstatt dem Statuscode zu vertrauen. Führen Sie eine Mutation auf dieselbe Weise aus, wie Sie eine Abfrage ausführen, und verketten Sie dann beide zu einem gespeicherten Szenario, damit die Prüfung sich wiederholt. Laden Sie Apidog herunter, um mitzumachen, bauen Sie den oben beschriebenen Benutzer-und-Bestellungs-Workflow auf, und Sie haben einen GraphQL-Regressionstest, den Sie jederzeit wiederholen können, wenn sich Ihr Schema ändert.