GraphQL API Testing Guide: Complete 2026 Handbook

This guide covers everything you need to test GraphQL APIs in 2026: schema validation, queries, mutations, security, and tooling. For the broader picture, see our API Testing Tutorial, Microservices Testing Strategy, and Postman API Testing Tutorial.

GraphQL is a query language for APIs that lets clients request exactly the data they need. Developed by Facebook in 2012 and open-sourced in 2015, it's now the default choice for many product teams alongside REST.

• Single endpoint — every request goes to /graphql.
• POST method — all queries are POSTs.
• Query in body — GraphQL operations travel in the request body.
• Schema-driven — tests can introspect the schema.
• Variable support — operations accept typed variables.
• Subscriptions — real-time data over WebSocket.

Simple query

query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    email
  }
}

const query = `
  query GetUser($id: ID!) {
    user(id: $id) { id name email }
  }
`;
const variables = { id: '123' };

const response = await fetch('https://api.example.com/graphql', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ query, variables }),
});

const json = await response.json();
expect(json.data.user.id).toBe('123');

Query with variables

query SearchUsers($term: String!, $limit: Int = 10) {
  searchUsers(term: $term, limit: $limit) { id name }
}

Create

mutation CreateUser($input: CreateUserInput!) {
  createUser(input: $input) { id name email }
}

const variables = {
  input: { name: 'Alice', email: 'alice@example.com', role: 'admin' }
};

Update

mutation UpdateUser($id: ID!, $input: UpdateUserInput!) {
  updateUser(id: $id, input: $input) { id name email }
}

Validate with graphql-js

import { buildSchema, validate, parse } from 'graphql';

const schema = buildSchema(`
  type Query { user(id: ID!): User }
  type User { id: ID! name: String! email: String! }
`);

const query = `query { user(id: "123") { id name email } }`;
const errors = validate(schema, parse(query));
expect(errors).toHaveLength(0);

Detect breaking changes with graphql-inspector

const inspector = new GraphQLInspector();
const changes = inspector.diff(oldSchema, newSchema);
// breaking, dangerous, and safe changes

const query = `query { user(id: "invalid") { id } }`;
const response = await graphqlCall(query);
expect(response.errors).toBeDefined();
expect(response.errors[0].message).toContain('Invalid ID');

1. Introspection disabled in production

const query = `{ __schema { types { name } } }`;
const response = await graphqlCall(query);
expect(response.errors[0].message).toContain('not allowed');

2. Query depth limit

const deep = `query { user { friends { friends { friends { friends { name } } } } } }`;
// expect depth limit error

3. Query complexity limit

const expensive = `query { users(first: 10000) { id name posts { title } comments { text } } }`;
// expect complexity error

4. SQL injection in GraphQL

query { user(id: "1' OR '1'='1") { id name } }

Expected: validation error or sanitized response.

5. Auth required for sensitive fields

const response = await graphqlCall(`{ adminUsers { id email } }`);
expect(response.errors[0].message).toContain('Unauthorized');

Postman

Native GraphQL support: POST to your endpoint, JSON body with query + variables, write assertions in the Tests tab. See the Postman API Testing Tutorial.

Jest + graphql-request

import { request } from 'graphql-request';

const endpoint = 'https://api.example.com/graphql';

test('returns user by id', async () => {
  const query = `query GetUser($id: ID!) { user(id: $id) { id name } }`;
  const data = await request(endpoint, query, { id: '123' });
  expect(data.user.id).toBe('123');
});

Karate DSL

Feature: User API

Scenario: Get user
  Given path '/graphql'
  And request { query: 'query { user(id: "123") { id name } }' }
  When method POST
  Then status 200
  And match $.data.user.id == '123'

Apollo Studio

Visual GraphQL explorer for running queries, browsing the schema, and generating tests. See official Apollo Studio docs and graphql.org learn.

Unit

• Schema validation.
• Single-field queries.
• Edge cases (null, empty, max values).

Integration

• Full query chains.
• Mutations.
• Authentication and authorization.

E2E

• Full user journeys.
• Subscription delivery.
• Real backend, real database.

For the broader pyramid, see Test Pyramid Explained.

1. Testing only the happy path — add error, security, and edge cases.
2. Leaving introspection enabled in production — disable it.
3. No query depth/complexity limits — use graphql-depth-limit:

   const depthLimit = require('graphql-depth-limit');
   const server = new ApolloServer({ validationRules: [depthLimit(7)] });

4. Not testing subscriptions — verify real-time events actually deliver.
5. Ignoring N+1 query problems — assert query count, not just response.
6. Not validating input data — use the type system and @constraint directives.
7. No rate limiting — protect the single endpoint.
8. Trusting client-side validation — always re-validate on the server.

Step 1 — Install tools

npm install --save-dev graphql graphql-request jest

Step 2 — Write your first test

test('user query returns expected fields', async () => {
  const query = `{ user(id: "1") { id name email } }`;
  const response = await graphqlCall(query);
  expect(response.data.user.id).toBe('1');
});

Step 3 — Add error tests

test('invalid id returns error', async () => {
  const response = await graphqlCall(`{ user(id: "invalid") { id } }`);
  expect(response.errors).toBeDefined();
});

Step 4 — Add security tests

test('introspection is disabled in production', async () => {
  const response = await graphqlCall(`{ __schema { types { name } } }`);
  expect(response.errors[0].message).toContain('not allowed');
});

Step 5 — Wire into CI/CD

Run on every PR. See the GitHub Actions Automation Testing guide.

Continue your API testing journey: API Testing Tutorial · Microservices Testing Strategy · Postman API Testing · API testing interview questions · AI mock interview.

Original SoftwareTestPilot research relevant to API testing:

• Shift-left benchmarks (2026) — where API contract tests move the defect-cost needle.
• Test pyramid benchmarks (2026) — the API layer has grown from 20% (Cohn) to 26% median in 2026.
• Enterprise automation tool benchmarks (2026) — flake and cost data.
• API testing interview questions with senior-SDET answers.