GraphQL API Testing: Queries, Mutations, Errors and Security

GraphQL APIs look simple from the outside, with one URL and one POST, but they hide a surprising number of testing traps. Errors come back with HTTP 200, “not found” is a null instead of a 404, and a single query can ask for so much nested data that it slows the whole server down. In this lesson you’ll test a real public GraphQL API with Postman, cURL and Playwright, and learn the checklist that catches GraphQL-specific bugs.

GraphQL in 2 Minutes

• One endpoint, usually POST /graphql.
• Schema with types and fields defines what can be asked (strongly typed).
• Query reads, mutation writes, subscription streams updates (usually over WebSocket).
• Response is JSON with data and/or errors.

Comparison with REST and SOAP: REST vs SOAP vs GraphQL.

The Public API We’ll Test

We’ll use the free public Countries GraphQL API at https://countries.trevorblades.com/. It needs no key and returns country data. (It’s a third-party demo service; be gentle with it and don’t load test it.)

query {
  country(code: "IN") {
    name
    capital
    currency
    languages { name }
  }
}

Real response (HTTP 200):

{
  "data": {
    "country": {
      "name": "India",
      "capital": "New Delhi",
      "currency": "INR",
      "languages": [ { "name": "Hindi" }, { "name": "English" } ]
    }
  }
}

Sending GraphQL Requests: cURL and Postman

cURL

curl -s https://countries.trevorblades.com/ \
  -H "Content-Type: application/json" \
  -d '{"query":"{ country(code: \"IN\") { name capital currency } }"}'

With variables (the right way)

Never build queries by gluing strings together; pass values as variables. It’s cleaner and avoids injection.

{
  "query": "query GetCountry($code: ID!) { country(code: $code) { name emoji } }",
  "variables": { "code": "JP" },
  "operationName": "GetCountry"
}

Response: {"data":{"country":{"emoji":"🇯🇵","name":"Japan"}}}

Postman

1. New HTTP request, method POST, URL https://countries.trevorblades.com/.
2. Body → GraphQL. Postman fetches the schema and gives autocomplete.
3. Write the query in the QUERY box and variables in the GRAPHQL VARIABLES box. Send.

The Biggest Trap: HTTP 200 Doesn’t Mean Success

We sent three “wrong” requests to the real API. Look at the status codes:

Status code behaviour varies by server (some return 400 for validation errors when using the newer “GraphQL over HTTP” conventions), so check your API’s documented behaviour and test it explicitly.

What to Test in a GraphQL API

GraphQL Security Checks

• Introspection: { __schema { types { name } } } reveals the whole schema. Often disabled in production for internal APIs.
• Field suggestions: “Did you mean …?” messages (like the one above) can leak hidden field names; some teams disable them in production.
• Authorization per resolver: every field that returns sensitive data needs its own check.
• Injection: arguments still reach databases; test them like REST inputs.
• Batching / alias abuse: 1,000 login attempts in one request via aliases can bypass rate limiting.

Automating GraphQL Tests with Playwright

Playwright’s request fixture is all you need. A small helper keeps tests readable:

import { test, expect, APIRequestContext } from '@playwright/test';

const GQL = 'https://countries.trevorblades.com/';

async function gql(request: APIRequestContext, query: string, variables?: Record<string, unknown>) {
  const res = await request.post(GQL, { data: { query, variables } });
  return { status: res.status(), body: await res.json() };
}

test('query with variables returns the right country', async ({ request }) => {
  const { status, body } = await gql(request,
    'query GetCountry($code: ID!) { country(code: $code) { name capital currency } }',
    { code: 'IN' });

  expect(status).toBe(200);
  expect(body.errors).toBeUndefined();                 // the essential GraphQL check
  expect(body.data.country).toEqual({ name: 'India', capital: 'New Delhi', currency: 'INR' });
});

test('unknown record returns null, not an error', async ({ request }) => {
  const { status, body } = await gql(request, '{ country(code: "ZZ") { name } }');
  expect(status).toBe(200);
  expect(body.errors).toBeUndefined();
  expect(body.data.country).toBeNull();
});

test('invalid field returns 200 with a validation error', async ({ request }) => {
  const { status, body } = await gql(request, '{ country(code: "IN") { nam } }');
  expect(status).toBe(200);
  expect(body.data).toBeUndefined();
  expect(body.errors[0].extensions.code).toBe('GRAPHQL_VALIDATION_FAILED');
  expect(body.errors[0].message).toContain('Cannot query field "nam"');
});

test('aliases fetch two records in one request', async ({ request }) => {
  const { body } = await gql(request, '{ in: country(code: "IN") { name } jp: country(code: "JP") { name } }');
  expect(body.data).toEqual({ in: { name: 'India' }, jp: { name: 'Japan' } });
});

These tests ran green against the live API while this lesson was written. For your own APIs, also add schema validation of data (next module) and auth tests per field.

GraphQL Tools for Testers

• Postman / Insomnia: GraphQL body type with schema autocomplete.
• GraphiQL / Apollo Sandbox: in-browser explorer with docs from introspection.
• Playwright, REST Assured, pytest: GraphQL is just HTTP POST, so any API framework works.
• GraphQL Inspector: detects breaking schema changes in CI.
• k6: load testing GraphQL operations.

Mutations: Testing Writes

The countries API is read-only, so here is a typical mutation shape you’ll see in real projects:

mutation AddToCart($input: AddToCartInput!) {
  addToCart(input: $input) {
    cart { id itemCount total }
    errors { field message }         # some APIs return business errors as data
  }
}
# variables: { "input": { "productId": "101", "quantity": 2 } }

Test cases: valid input updates the cart (verify with a follow-up query); quantity 0 / -1 / 1000 returns an error in errors or the typed errors field; unknown product; another user’s cart id (authorization); running the same mutation twice (idempotency where expected).

Common Mistakes When Testing GraphQL

• Asserting only status 200.
• Building queries with string concatenation instead of variables.
• Testing only the fields the UI uses; other clients may request more.
• Ignoring null in nested data (partial failures).
• Not testing depth/complexity limits and introspection settings.

Interview Questions: GraphQL Testing