GraphQL Testing Pyramid: Combining Unit, Integration, and E2E Tests

1. Why the classic testing pyramid needs adjusting

The classic testing pyramid, lots of unit tests, fewer integration tests, few E2E tests, was designed for systems with clear functional boundaries. GraphQL partly breaks that assumption: a single resolver is rarely interesting in isolation, its real value only emerges together with the schema, linked types, and the resolution of nested fields. A GraphQL testing pyramid therefore has to deliberately put more weight on the middle integration layer than a classic REST API would.

The reason lies in the nature of the GraphQL execution model: errors frequently arise not inside a single resolver but at the seams, a parent field returns an unexpected null value, but a child resolver expects an object and throws an exception that destroys the entire query branch. Pure unit tests of individual resolver functions never catch such errors, because they never traverse the full execution graph. A balanced GraphQL testing pyramid accounts for this by treating integration tests against the real, composed schema as an explicit, well-populated layer, not just a thin transition between unit and E2E tests.

At the same time, E2E tests remain indispensable, because they are the only layer covering authentication, network latency, caching headers, and the interplay with the actual frontend. The art lies in deliberately assigning each layer the error class it catches most cheaply and reliably, instead of producing redundancy across layers.

2. Unit tests for isolated resolvers

The bottom layer of the GraphQL testing pyramid tests individual resolver functions without a GraphQL executor, without a network, and with fully mocked data sources. These tests are extremely fast, usually in the millisecond range per test, and are ideal for business logic inside a resolver, for instance price calculations, validation rules, or formatting logic.

// 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);
  });
});

The most important rule at this layer: a unit test must never call a real database or a real HTTP client. Every dependency gets replaced through dependency injection or mocking libraries. This isolation is why this layer of the GraphQL testing pyramid can be written in large numbers without noticeably slowing down CI runtime.

3. Integration tests against the full schema

Integration tests execute real GraphQL queries against the fully composed schema graph, usually with mocked or in-memory data sources instead of a real production database. This layer covers exactly the class of error that unit tests systematically miss: mis-wired resolvers, incorrect type resolution for interfaces and unions, and unexpected null propagation behavior across several field levels.

// 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("Shoes");
  });
});

In the GraphQL testing pyramid, this layer is deliberately wider than in a classic pyramid, because at reasonable cost, no network, no real database, but the real GraphQL executor runs, it covers most practically relevant errors. Many teams write at least one happy path test and one failure case test here for every publicly exposed query and mutation type.

4. Snapshot testing for queries

Snapshot tests capture the full response structure of a query on the first test run and compare every subsequent run against that stored reference value. For the GraphQL testing pyramid, snapshots are especially valuable for catching unintended structural changes in nested responses without having to write a separate assertion for every field.

// 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();
  });
});

The downside of snapshot tests: they quickly become routine rubber-stamping without real verification when developers reflexively update snapshots with --update instead of reviewing every change's substance. In the GraphQL testing pyramid, snapshot tests should therefore be used deliberately for stable, rarely-changed core queries, not blanketed across every query in the system.

5. Contract testing between schema and client

Contract tests check whether the queries and fragments actually used by the frontend remain compatible with the server schema, independent of whether the server itself works correctly. The tool for this is usually a schema validator that checks every GraphQL operation found in the frontend code against the current schema definition, without ever executing a real server request.

# 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 the GraphQL testing pyramid, contract testing closes the gap between backend integration tests and frontend E2E tests: it finds incompatible changes in milliseconds, without a browser or a real server instance ever starting, considerably faster than a full E2E run for the same class of error.

6. E2E tests against real staging environments

End-to-end tests run real browser interactions against a live staging environment, making them the only layer in the GraphQL testing pyramid that covers the full interplay: the authentication flow, actual network latency, browser caching behavior, and the correct wiring between frontend state management and 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

Because E2E tests are slow and prone to flakiness from network variance, this layer of the GraphQL testing pyramid should be kept deliberately lean: only business-critical core flows, checkout, login, cart, not every possible query combination. An E2E test that checks whether a single optional field renders correctly belongs at the integration layer, not in the E2E suite.

7. Mocking strategies: MSW and schema mocking

For frontend tests that need GraphQL responses without starting a real server, two complementary mocking approaches have become standard. Mock Service Worker (MSW) intercepts network requests at the HTTP level and works well for component and integration tests on the frontend. Schema mocking, in contrast, automatically generates plausible sample data directly from the GraphQL schema definition, ideal during early development before the real resolver is implemented.

// 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: "Running Shoe Model X",
          price: { amount: 89.99, currency: "EUR" },
        },
      },
    });
  }),
];

In the GraphQL testing pyramid, mocking replaces none of the three main layers, it accelerates them: MSW makes frontend integration tests independent of the backend deployment status, schema mocking lets frontend and backend teams work in parallel as long as both use the same schema as a contractual foundation.

8. A CI pipeline with all three layers

In practice, the three layers of the GraphQL testing pyramid run as staged CI jobs, ordered by execution speed, so a developer gets feedback on a simple error within seconds, not only after the full E2E run completes.

# .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

This staging is not merely organizational, it saves substantial CI time in practice: an error already visible in a unit test doesn't need to run through a multi-minute E2E suite to surface. A well-staged GraphQL testing pyramid delivers fast feedback for common errors and reserves the expensive E2E layer for the error classes it uniquely catches.

9. The test layers head to head

The table below summarizes which layer catches which error class most efficiently.

10. Summary

A working GraphQL testing pyramid differs from the classic REST testing pyramid mainly through a noticeably wider integration layer, because GraphQL errors frequently arise at the seams between resolvers, not inside individual functions. Unit tests cover isolated business logic, integration tests validate the real interplay in the composed schema, contract tests secure compatibility between frontend queries and the server schema, and a lean E2E layer covers exactly the error classes only visible in the complete system.

The key mistake many teams make is trying to test every error class at every layer. A balanced GraphQL testing pyramid instead assigns each error class exactly one primary layer, which reduces redundancy, keeps CI runtime low, and makes failing tests more meaningful, since a failed contract test signals something different than a failed E2E test.

11. FAQ: GraphQL Testing Pyramid