DEV Community

Cover image for GraphQL APIs in Apidog testen: Queries, Mutations und Automatisierung
Emre Demir
Emre Demir

Posted on • Originally published at apidog.com

GraphQL APIs in Apidog testen: Queries, Mutations und Automatisierung

Sie haben einen GraphQL-Endpunkt und müssen prüfen, ob er wirklich funktioniert: Liefert die user-Abfrage die Felder, die Ihre App verwendet? Erstellt createOrder tatsächlich eine Bestellung? Bleibt die Antwortstruktur korrekt, wenn sich Variablen ändern? Da GraphQL Abfragen per POST an einen zentralen Endpunkt sendet, brauchen Sie einen Client, der GraphQL-Dokumente, Variablen, Schema-Felder und JSON-Antworten versteht.

Apidog heute testen

Apidog unterstützt GraphQL als dedizierten Anfragetyp – neben HTTP, gRPC, WebSocket, SSE und SOAP. In diesem Leitfaden erstellen Sie eine GraphQL-Abfrage, rufen das Schema für die Code-Vervollständigung ab, übergeben Variablen, führen eine Mutation aus und prüfen die Antwort automatisiert. Das Beispiel verwendet eine E-Commerce-API: Sie laden einen Benutzer mit Bestellungen und erstellen anschließend eine neue Bestellung.

Für den konzeptionellen Hintergrund ist die offizielle GraphQL-Dokumentation die maßgebliche Referenz. Für die Entscheidung zwischen API-Stilen hilft auch der Vergleich REST vs. GraphQL.

Was Sie bei GraphQL testen müssen

REST stellt üblicherweise mehrere Endpunkte mit festen Antwortformen bereit. GraphQL verwendet meist einen Endpunkt und lässt den Client die benötigten Felder auswählen.

Das verändert Ihren Testansatz:

  1. Die eigentliche Anfrage ist ein GraphQL-Dokument im Body – nicht nur eine URL mit Pfadparametern.
  2. Ein HTTP-Status 200 OK bedeutet nicht automatisch, dass die GraphQL-Operation erfolgreich war.
  3. GraphQL-Fehler stehen normalerweise im JSON-Feld errors.

Beispiel: Statt eines REST-Aufrufs wie GET /users/42 senden Sie eine Auswahl wie:

user(id: 42) {
  id
  name
}
Enter fullscreen mode Exit fullscreen mode

Eine fachlich oder syntaktisch fehlgeschlagene GraphQL-Operation kann trotzdem mit 200 OK antworten:

{
  "data": null,
  "errors": [
    {
      "message": "User not found"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Prüfen Sie deshalb immer sowohl den HTTP-Status als auch den Response-Body.

Eine GraphQL-Anfrage in Apidog erstellen

Laden Sie zunächst Apidog herunter oder öffnen Sie die Anwendung im Browser. Öffnen oder erstellen Sie anschließend ein Projekt, damit Sie die Anfrage speichern können.

Schritt 1: Neue Anfrage anlegen

  1. Klicken Sie auf +.
  2. Wählen Sie Neue Anfrage.
  3. Setzen Sie die HTTP-Methode auf POST.
  4. Tragen Sie den GraphQL-Endpunkt ein: 
https://api.yourstore.com/graphql
Enter fullscreen mode Exit fullscreen mode
  1. Öffnen Sie Body.
  2. Wählen Sie GraphQL.

Apidog zeigt nun einen GraphQL-Editor mit einem Feld für die Abfrage an.

Benötigt Ihr Endpunkt Authentifizierung, konfigurieren Sie diese im Bereich Autorisierung, beispielsweise als Bearer-Token. Technisch bleibt eine GraphQL-Anfrage ein HTTP-POST, daher funktioniert die Authentifizierung wie bei anderen HTTP-Anfragen.

Schritt 2: Erste Abfrage schreiben

Fügen Sie im Bereich Query eine konkrete Abfrage ein:

query GetUserWithOrders {
  user(id: "usr_1024") {
    id
    name
    email
    orders {
      id
      total
      status
      createdAt
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Die Abfrage lädt einen Benutzer und seine Bestellungen. Alle Feldnamen müssen mit dem GraphQL-Schema Ihres Servers übereinstimmen. Wenn das Schema beispielsweise emailAddress statt email definiert, schlägt die Abfrage fehl.

Schritt 3: Schema abrufen und Code-Vervollständigung aktivieren

Vermeiden Sie das manuelle Erraten von Feldern:

  1. Stellen Sie sicher, dass die Endpunkt-URL korrekt ist.
  2. Klicken Sie im Eingabebereich auf Schema abrufen.
  3. Warten Sie, bis Apidog die Introspektionsabfrage abgeschlossen hat.
  4. Schreiben Sie Ihre Auswahl weiter und nutzen Sie die Feld- und Typvorschläge.

Apidog lädt dabei das Typsystem Ihres GraphQL-Endpunkts. Danach erhalten Sie IntelliSense-ähnliche Vorschläge für gültige Felder des jeweiligen Typs.

Beachten Sie dabei:

  • Die Code-Vervollständigung wird erst nach Schema abrufen aktiviert.
  • Ist die Introspektion im Zielsystem deaktiviert, kann Apidog kein Schema laden.
  • Nach Änderungen am GraphQL-Schema sollten Sie das Schema erneut abrufen.

Schritt 4: Anfrage ausführen und Antwort prüfen

Klicken Sie auf Senden. Eine erfolgreiche Antwort kann so aussehen:

{
  "data": {
    "user": {
      "id": "usr_1024",
      "name": "Dana Whitfield",
      "email": "dana@example.com",
      "orders": [
        {
          "id": "ord_5001",
          "total": 89.9,
          "status": "SHIPPED",
          "createdAt": "2026-07-01T09:14:00Z"
        },
        {
          "id": "ord_5002",
          "total": 12.5,
          "status": "PENDING",
          "createdAt": "2026-07-12T16:03:00Z"
        }
      ]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Wichtig ist die Top-Level-Struktur:

  • data enthält das Ergebnis der Operation.
  • errors enthält Fehler, sofern welche auftreten.

Ihre späteren Assertions müssen deshalb Pfade wie $.data.user.orders prüfen – nicht direkt die JSON-Wurzel.

Variablen verwenden statt Werte zu hardcoden

Die fest codierte ID "usr_1024" ist für einen ersten Test praktisch, aber nicht wiederverwendbar. Verwenden Sie GraphQL-Variablen, wenn Sie dieselbe Abfrage mit unterschiedlichen Nutzern oder Umgebungen ausführen möchten.

Deklarieren Sie die Variable in der Operationssignatur und verwenden Sie sie im Argument:

query GetUserWithOrders($userId: ID!) {
  user(id: $userId) {
    id
    name
    orders {
      id
      total
      status
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Übergeben Sie den Wert im Variablen-JSON:

{
  "userId": "usr_1024"
}
Enter fullscreen mode Exit fullscreen mode

Die Syntax entspricht dem GraphQL-Standard. Details finden Sie in der GraphQL-Dokumentation zu Variablen.

Kombinieren Sie GraphQL-Variablen mit Apidog-Umgebungsvariablen, um dieselbe gespeicherte Anfrage beispielsweise gegen Staging und Produktion auszuführen, ohne das Query-Dokument zu ändern.

Mutation zum Erstellen einer Bestellung ausführen

Mutationen schreiben oder ändern Daten. Sie benötigen dafür keinen separaten Tab: Schreiben Sie die Operation im selben Query-Feld, verwenden Sie aber das Schlüsselwort mutation.

mutation CreateOrder($input: CreateOrderInput!) {
  createOrder(input: $input) {
    id
    total
    status
    createdAt
  }
}
Enter fullscreen mode Exit fullscreen mode

Übergeben Sie die Nutzdaten als Variablen:

{
  "input": {
    "userId": "usr_1024",
    "items": [
      {
        "sku": "TSHIRT-BLK-M",
        "quantity": 2
      },
      {
        "sku": "MUG-CERAMIC",
        "quantity": 1
      }
    ],
    "currency": "USD"
  }
}
Enter fullscreen mode Exit fullscreen mode

Klicken Sie auf Senden. Eine erfolgreiche Mutation kann diese Antwort liefern:

{
  "data": {
    "createOrder": {
      "id": "ord_5003",
      "total": 42.3,
      "status": "PENDING",
      "createdAt": "2026-07-15T10:22:11Z"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Führen Sie schreibende Mutationen in einer Test- oder Staging-Umgebung aus, nicht direkt in der Produktion.

Ein sinnvoller End-to-End-Flow ist:

  1. Benutzer und vorhandene Bestellungen abfragen.
  2. Bestellung per Mutation erstellen.
  3. Die zurückgegebene Bestell-ID speichern.
  4. Benutzer erneut abfragen.
  5. Prüfen, ob die neue Bestellung in der Liste erscheint.

Assertions für GraphQL-Antworten einrichten

Beim Explorieren reicht es, JSON manuell zu lesen. Für wiederholbare Tests benötigen Sie Assertions. In Apidog können Sie diese direkt an einer Anfrage konfigurieren. Weitere Details finden Sie im Beitrag zu API-Assertions.

Für GraphQL sollten Sie mindestens diese drei Prüfungen ergänzen:

  1. HTTP-Status prüfen

    Erwarteter Status: 200.

  2. GraphQL-Fehler prüfen

    Stellen Sie sicher, dass errors nicht vorhanden ist.

  3. Geschäfts- und Strukturwerte prüfen

    Verwenden Sie JSONPath-Ausdrücke für Felder unterhalb von data.

Beispiele:

$.data.createOrder.status == "PENDING"
Enter fullscreen mode Exit fullscreen mode 
$.data.user.orders.length > 0
Enter fullscreen mode Exit fullscreen mode

Der Statuscode allein reicht nicht aus. Eine GraphQL-Antwort mit 200 und einem errors-Array muss als fehlgeschlagener Test bewertet werden.

Den Ablauf als Testszenario speichern

Eine einzelne Anfrage ist ein Smoke Test. Für Regressionstests verketten Sie Query, Mutation und Bestätigungs-Query in einem Testszenario.

Ein typisches Szenario sieht so aus:

  1. GetUserWithOrders ausführen.
  2. CreateOrder ausführen.
  3. Die ID aus $.data.createOrder.id extrahieren und in einer Variablen speichern.
  4. GetUserWithOrders erneut ausführen.
  5. Prüfen, dass die neu erstellte Bestellung vorhanden ist.
  6. Für jeden Schritt Status-, Fehler- und Daten-Assertions hinzufügen.

Eine vollständige Anleitung finden Sie unter Wie man ein Testszenario mit Apidog schreibt.

Damit erhalten Sie einen wiederholbaren GraphQL-Regressionstest, den Sie manuell, zeitgesteuert oder in einer Pipeline ausführen können.

Wenn Sie GraphQL mit anderen API-Stilen vergleichen möchten, lesen Sie REST vs. GraphQL vs. gRPC sowie die Übersicht zu GraphQL-Test- und Mocking-Tools. Für SOAP gilt ein ähnlicher Request-und-Assertion-Workflow, beschrieben in Wie man SOAP-APIs in Apidog testet.

Den Workflow mit der Apidog CLI automatisieren

Wenn Ihre Testszenarien im Projekt gespeichert sind, können Sie sie über Terminal oder CI-Runner mit der Apidog CLI ausführen.

Installieren Sie die CLI und melden Sie sich an:

npm install -g apidog-cli
apidog login --with-token <Ihr-Token>
Enter fullscreen mode Exit fullscreen mode

Führen Sie anschließend ein gespeichertes Szenario mit Szenario- und Umgebungs-ID aus:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <Szenario-ID> -e <Umgebungs-ID> -r cli
Enter fullscreen mode Exit fullscreen mode

Die Optionen bedeuten:

  • -t: Test-Szenario-ID
  • -e: Umgebungs-ID
  • -r: Reporter, etwa cli, html oder junit

Mehrere Reporter können kommagetrennt angegeben werden:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <Szenario-ID> -e <Umgebungs-ID> -r html,cli
Enter fullscreen mode Exit fullscreen mode

Die CLI führt gespeicherte Szenarien und Test-Suites aus dem Cloud-Projekt aus und meldet Erfolg oder Fehlschlag. Damit können Sie Tests in Build-Prozesse integrieren.

Eine Einschränkung bleibt: Die CLI-Dokumentation bestätigt die Ausführung von HTTP-Szenarien, spezifiziert jedoch nicht ausdrücklich, ob Szenarien mit GraphQL-Schritten headless ausgeführt werden. Nutzen Sie die CLI daher für dokumentierte HTTP-Regressionstests und Spezifikationssynchronisierung über import – etwa für OpenAPI, HAR oder Postman. GraphQL-Abfragen, Mutationen und Assertions führen Sie in der App aus.

Weitere Informationen finden Sie im Apidog CLI Installationshandbuch und im Beitrag zu Apidog CLI in einer GitHub-Actions-Pipeline.

FAQ

Benötige ich einen kostenpflichtigen Plan, um GraphQL in Apidog zu testen?

Die GraphQL-Anfragedokumentation beschränkt diese Funktion nicht auf eine bestimmte Planstufe und unterscheidet dabei nicht zwischen Cloud und Self-Hosting. Sie können mit der kostenlosen Stufe beginnen. Aktuelle Plan-Details finden Sie bei Apidog.

Warum liefert meine GraphQL-Anfrage 200, schlägt aber trotzdem fehl?

Das entspricht dem üblichen GraphQL-Verhalten. Die HTTP-Übertragung war erfolgreich, während die Operation selbst einen Geschäfts-, Validierungs- oder Ausführungsfehler erzeugt hat. Prüfen Sie deshalb immer, ob das JSON ein errors-Array enthält – zusätzlich zum Statuscode. Siehe auch API-Assertions.

Wie erhalte ich Feldvorschläge beim Schreiben einer Abfrage?

Klicken Sie auf Schema abrufen. Apidog führt eine Introspektionsabfrage gegen Ihren Endpunkt aus und aktiviert danach die Code-Vervollständigung. Wiederholen Sie den Abruf nach Änderungen am Schema.

Wo finde ich einen separaten Mutation-Tab?

Es gibt keinen separaten Tab. Schreiben Sie die Mutation im selben Query-Feld und verwenden Sie mutation statt query. Die Nutzdaten übergeben Sie als Variablen.

Wie teste ich mehrere Werte, ohne die Abfrage zu ändern?

Verwenden Sie GraphQL-Variablen. Deklarieren Sie sie mit einem $-Präfix in der Operationssignatur und übergeben Sie die Werte als JSON-Objekt. Die Syntax folgt der GraphQL-Spezifikation für Variablen. Kombinieren Sie sie mit Umgebungsvariablen, um dieselbe Anfrage gegen unterschiedliche Systeme auszuführen.

Zusammenfassung

Ein belastbarer GraphQL-Test folgt einem klaren Ablauf:

  1. GraphQL-Endpunkt per POST konfigurieren.
  2. Abfrage oder Mutation im Query-Feld schreiben.
  3. Schema abrufen und Feldvorschläge verwenden.
  4. Feste Werte durch Variablen ersetzen.
  5. HTTP-Status, fehlendes errors-Array und Werte unter data prüfen.
  6. Query-Mutation-Query als Testszenario speichern.

So wird aus einer manuellen GraphQL-Prüfung ein wiederholbarer Regressionstest. Laden Sie Apidog herunter, implementieren Sie den Benutzer-und-Bestellungs-Workflow und führen Sie ihn erneut aus, wenn sich Ihr Schema oder Ihre API-Logik ändert.

Top comments (0)