GraphQL Testing Pyramide: Unit, Integration und E2E Tests kombinieren

1. Warum die klassische Testpyramide angepasst werden muss

Die klassische Testpyramide, viele Unit-Tests, weniger Integrationstests, wenige E2E-Tests, entstand für Systeme mit klaren Funktionsgrenzen. GraphQL bricht diese Annahme teilweise: Ein einzelner Resolver ist selten isoliert interessant, sein eigentlicher Wert entsteht erst im Zusammenspiel mit dem Schema, mit verknüpften Typen und mit der Auflösung verschachtelter Felder. Eine GraphQL Testing Pyramide muss deshalb bewusst mehr Gewicht auf die mittlere Integrationsebene legen, als es bei einer klassischen REST-API der Fall wäre.

Der Grund liegt in der Natur des GraphQL-Ausführungsmodells: Fehler entstehen häufig nicht innerhalb eines einzelnen Resolvers, sondern an den Nahtstellen, ein Elternfeld liefert einen unerwarteten Null-Wert, ein Kind-Resolver erwartet aber ein Objekt und wirft eine Exception, die den gesamten Query-Zweig zerstört. Reine Unit-Tests einzelner Resolver-Funktionen finden solche Fehler nicht, weil sie den vollständigen Ausführungsgraphen nie durchlaufen. Eine ausgewogene GraphQL Testing Pyramide berücksichtigt das, indem sie Integrationstests gegen das echte, komponierte Schema explizit als eigene, gut besetzte Ebene führt, nicht nur als schmalen Übergang zwischen Unit- und E2E-Tests.

Gleichzeitig bleiben E2E-Tests unverzichtbar, weil sie als einzige Ebene Authentifizierung, Netzwerklatenz, Caching-Header und das Zusammenspiel mit dem tatsächlichen Frontend abdecken. Die Kunst liegt darin, jede Ebene bewusst für die Fehlerklasse einzusetzen, die sie am günstigsten und zuverlässigsten findet, statt Redundanz zwischen den Ebenen zu produzieren.

2. Unit-Tests für isolierte Resolver

Die unterste Ebene der GraphQL Testing Pyramide testet einzelne Resolver-Funktionen ohne GraphQL-Executor, ohne Netzwerk und mit vollständig gemockten Datenquellen. Diese Tests sind extrem schnell, meist im Millisekundenbereich pro Test, und eignen sich perfekt für Business-Logik innerhalb eines Resolvers, etwa Preisberechnungen, Validierungsregeln oder Formatierungslogik.

// resolvers/product.test.js — pure unit test, no GraphQL execution involved
import { describe, it, expect, vi } from "vitest";
import { resolveDiscountedPrice } from "./product.js";

describe("resolveDiscountedPrice", () => {
  it("applies a 10% discount for loyalty tier gold", () => {
    const product = { basePrice: 100 };
    const context = { customer: { loyaltyTier: "gold" } };

    const result = resolveDiscountedPrice(product, {}, context);

    expect(result).toBe(90);
  });

  it("returns base price for customers without a loyalty tier", () => {
    const product = { basePrice: 100 };
    const context = { customer: null };

    expect(resolveDiscountedPrice(product, {}, context)).toBe(100);
  });
});

Der wichtigste Grundsatz auf dieser Ebene: Ein Unit-Test darf niemals eine echte Datenbank oder einen echten HTTP-Client aufrufen. Sämtliche Abhängigkeiten werden über Dependency Injection oder Mocking-Bibliotheken ersetzt. Diese Isolation ist der Grund, warum diese Ebene der GraphQL Testing Pyramide in großer Zahl geschrieben werden kann, ohne die CI-Laufzeit spürbar zu belasten.

3. Integrationstests gegen das komplette Schema

Integrationstests führen echte GraphQL-Queries gegen den vollständig komponierten Schema-Graphen aus, meist mit gemockten oder In-Memory-Datenquellen statt einer echten Produktionsdatenbank. Diese Ebene deckt genau die Fehlerklasse ab, die Unit-Tests systematisch übersehen: falsch verdrahtete Resolver, fehlerhafte Typauflösung bei Interfaces und Unions, und unerwartetes Null-Propagation-Verhalten über mehrere Feld-Ebenen hinweg.

// integration/product-query.test.js — executes against the real schema
import { describe, it, expect } from "vitest";
import { executeOperation } from "../test-utils/apollo-test-server.js";

describe("Product query integration", () => {
  it("resolves nested category and price fields correctly", async () => {
    const response = await executeOperation({
      query: `
        query {
          product(id: "42") {
            name
            category { name slug }
            price { amount currency }
          }
        }
      `,
      contextValue: { dataSources: mockDataSources() },
    });

    expect(response.body.singleResult.errors).toBeUndefined();
    expect(response.body.singleResult.data.product.category.name).toBe("Schuhe");
  });
});

In der GraphQL Testing Pyramide ist diese Ebene bewusst breiter angelegt als bei einer klassischen Pyramide, weil sie mit vertretbarem Aufwand, kein Netzwerk, keine echte Datenbank, aber der reale GraphQL-Executor läuft, die meisten praxisrelevanten Fehler abdeckt. Viele Teams schreiben hier für jeden öffentlich exponierten Query- und Mutation-Typ mindestens einen Happy-Path-Test und einen Fehlerfall-Test.

4. Snapshot-Testing von Queries

Snapshot-Tests erfassen die vollständige Response-Struktur einer Query beim ersten Testlauf und vergleichen jeden weiteren Lauf gegen diesen gespeicherten Referenzwert. Für die GraphQL Testing Pyramide sind Snapshots besonders wertvoll, um unbeabsichtigte Strukturänderungen in verschachtelten Responses zu erkennen, ohne für jedes Feld einzeln eine Assertion schreiben zu müssen.

// snapshot/product-detail.test.js
import { describe, it, expect } from "vitest";
import { executeOperation } from "../test-utils/apollo-test-server.js";

describe("Product detail snapshot", () => {
  it("matches the expected response shape", async () => {
    const response = await executeOperation({
      query: `
        query ProductDetail($id: ID!) {
          product(id: $id) {
            name
            variants { sku attributes { name value } }
          }
        }
      `,
      variables: { id: "42" },
    });

    // Fails if the response shape changes unexpectedly (new/removed/renamed fields)
    expect(response.body.singleResult.data).toMatchSnapshot();
  });
});

Der Nachteil von Snapshot-Tests: Sie werden bei absichtlichen Schema-Änderungen schnell zur Routine-Bestätigung ohne echte Prüfung, wenn Entwickler Snapshots reflexartig mit --update aktualisieren, statt jede Änderung inhaltlich zu prüfen. In der GraphQL Testing Pyramide sollten Snapshot-Tests deshalb gezielt für stabile, selten geänderte Kern-Queries eingesetzt werden, nicht flächendeckend für jede Query im System.

5. Contract-Testing zwischen Schema und Client

Contract-Tests prüfen, ob die vom Frontend tatsächlich verwendeten Queries und Fragmente weiterhin mit dem Server-Schema kompatibel sind, unabhängig davon, ob der Server selbst korrekt funktioniert. Das Werkzeug dafür ist meist ein Schema-Validator, der jede im Frontend-Code gefundene GraphQL-Operation gegen die aktuelle Schema-Definition validiert, ohne einen echten Server-Request auszuführen.

# frontend/queries/ProductCard.graphql — validated against the schema in CI
query ProductCard($id: ID!) {
  product(id: $id) {
    name
    thumbnailUrl
    price { amount currency }
    # This field must exist in the current schema, or the contract test fails
    availabilityStatus
  }
}

{
  "contractCheck": {
    "operation": "ProductCard",
    "status": "FAILED",
    "reason": "Field 'availabilityStatus' does not exist on type 'Product'",
    "suggestedFix": "Did you mean 'stockStatus'?"
  }
}

In der GraphQL Testing Pyramide schließt Contract-Testing die Lücke zwischen Backend-Integrationstests und Frontend-E2E-Tests: Es findet inkompatible Änderungen in Millisekunden, ohne dass ein Browser oder eine echte Server-Instanz gestartet werden muss, deutlich schneller als ein vollständiger E2E-Testlauf für dieselbe Klasse von Fehlern.

6. E2E-Tests gegen echte Staging-Umgebungen

End-to-End-Tests führen echte Browser-Interaktionen gegen eine laufende Staging-Umgebung aus und decken damit als einzige Ebene der GraphQL Testing Pyramide das vollständige Zusammenspiel ab: Authentifizierungsfluss, tatsächliche Netzwerklatenz, Caching-Verhalten des Browsers und die korrekte Verdrahtung zwischen Frontend-State-Management und GraphQL-Responses.

#!/usr/bin/env bash
set -euo pipefail

# Run Playwright E2E suite against the staging environment
export STAGING_URL="https://staging.mironsoft.de"
export PLAYWRIGHT_TEST_TIMEOUT=30000

npx playwright test e2e/checkout-flow.spec.ts --project=chromium

Weil E2E-Tests langsam und anfällig für Flakiness durch Netzwerkschwankungen sind, sollte diese Ebene in der GraphQL Testing Pyramide bewusst schlank gehalten werden: nur die geschäftskritischen Kernflüsse, Checkout, Login, Warenkorb, nicht jede mögliche Query-Kombination. Ein E2E-Test, der prüft, ob ein einzelnes optionales Feld korrekt gerendert wird, gehört auf die Integrationsebene, nicht in die E2E-Suite.

7. Mocking-Strategien: MSW und Schema-Mocking

Für Frontend-Tests, die GraphQL-Responses benötigen, ohne einen echten Server zu starten, haben sich zwei komplementäre Mocking-Ansätze etabliert. Mock Service Worker (MSW) fängt Netzwerk-Requests auf HTTP-Ebene ab und eignet sich für Komponenten- und Integrationstests im Frontend. Schema-Mocking hingegen generiert automatisch plausible Beispieldaten direkt aus der GraphQL-Schema-Definition, ideal für frühe Entwicklungsphasen, bevor der echte Resolver fertig implementiert ist.

// mocks/handlers.js — MSW intercepts GraphQL requests at the network level
import { graphql, HttpResponse } from "msw";

export const handlers = [
  graphql.query("ProductCard", ({ variables }) => {
    return HttpResponse.json({
      data: {
        product: {
          id: variables.id,
          name: "Laufschuh Modell X",
          price: { amount: 89.99, currency: "EUR" },
        },
      },
    });
  }),
];

In der GraphQL Testing Pyramide ersetzt Mocking keine der drei Hauptebenen, sondern beschleunigt sie: MSW macht Frontend-Integrationstests unabhängig vom Backend-Deployment-Status, Schema-Mocking erlaubt paralleles Arbeiten von Frontend- und Backend-Teams, solange beide dasselbe Schema als vertragliche Grundlage nutzen.

8. Eine CI-Pipeline mit allen drei Ebenen

Die drei Ebenen der GraphQL Testing Pyramide laufen in der Praxis als gestaffelte CI-Jobs, sortiert nach Ausführungsgeschwindigkeit, sodass ein Entwickler bei einem einfachen Fehler bereits nach wenigen Sekunden Feedback bekommt, nicht erst nach dem vollständigen E2E-Durchlauf.

# .github/workflows/graphql-tests.yml
name: GraphQL Test Pyramid
on: [pull_request]

jobs:
  unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run test:unit          # seconds, runs on every push

  integration:
    needs: unit
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run test:integration   # tens of seconds, real schema execution

  contract:
    needs: unit
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run test:contract      # schema compatibility check

  e2e:
    needs: [integration, contract]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npm run test:e2e           # minutes, only after cheaper checks pass

Diese Staffelung ist keine reine Organisationsfrage, sie spart in der Praxis erhebliche CI-Zeit: Ein Fehler, der bereits im Unit-Test auffällt, muss nicht erst durch eine mehrminütige E2E-Suite laufen, um sichtbar zu werden. Eine gut gestaffelte GraphQL Testing Pyramide gibt schnelles Feedback bei häufigen Fehlern und reserviert die teure E2E-Ebene für die Fehlerklassen, die sie exklusiv findet.

9. Die Testebenen im direkten Vergleich

Die folgende Tabelle fasst zusammen, welche Ebene welche Fehlerklasse am effizientesten findet.

10. Zusammenfassung

Eine funktionierende GraphQL Testing Pyramide unterscheidet sich von der klassischen REST-Testpyramide vor allem durch eine deutlich breitere Integrationsebene, weil GraphQL-Fehler häufig an den Nahtstellen zwischen Resolvern entstehen, nicht innerhalb einzelner Funktionen. Unit-Tests decken isolierte Business-Logik ab, Integrationstests prüfen das reale Zusammenspiel im komponierten Schema, Contract-Tests sichern die Kompatibilität zwischen Frontend-Queries und Server-Schema, und eine schlanke E2E-Ebene deckt genau die Fehlerklassen ab, die nur im vollständigen System sichtbar werden.

Der entscheidende Denkfehler bei vielen Teams ist, jede Fehlerklasse auf jeder Ebene testen zu wollen. Eine ausgewogene GraphQL Testing Pyramide ordnet stattdessen jeder Fehlerklasse genau eine primäre Ebene zu, das reduziert Redundanz, hält die CI-Laufzeit niedrig und macht fehlschlagende Tests aussagekräftiger, weil ein fehlgeschlagener Contract-Test etwas anderes bedeutet als ein fehlgeschlagener E2E-Test.

11. FAQ: GraphQL Testing Pyramide