Stop 08 · API TestingTopics · 8/9

GraphQL Testing Basics

In short

GraphQL APIs have one endpoint and let the client choose exactly which fields it wants. That flexibility changes how you test, starting with errors that arrive as 200 OK.

Testing GraphQL APIs, which differ from REST — a single endpoint, client-specified queries, and different error handling conventions requiring adapted testing approaches.

The purple blob points at three chosen fillings at a sandwich counter.

Think of it like this

The build-your-own sandwich counter

At a fixed-menu stall you get the whole sandwich, onions and all. At a build-your-own counter you point: cheese, tomato, cucumber, done. REST serves fixed plates. GraphQL lets you name exactly the fields you want, in one order.

Watch it happen

REST vs GraphQL, for testers

REST

Many URLs, one per resource
Server decides the fields returned
Errors use HTTP status codes

GraphQL

One URL, usually /graphql
Client picks exact fields
Errors often in an errors array

For GraphQL, always check the errors array as well as the status code, and test that unrequested fields never leak.

The big ideas

What you need to know

Queries read

A query asks for data and lists the exact fields: country { name capital }.

Mutations write

Mutations create, update or delete, like createUser(input: {...}). Test them like POSTs.

200 can be a failure

Many GraphQL servers return 200 with an errors array. A status check alone misses it.

Deep queries

Nested queries can get very heavy. Teams often add depth or cost limits, so test those too.

See it in code

Walk through the code

python

1import requests2 3URL = "https://countries.trevorblades.com/graphql"4query = """5query ($code: ID!) {6  country(code: $code) { name capital currency }7}8"""9 10r = requests.post(URL, json={"query": query, "variables": {"code": "IN"}}, timeout=10)11body = r.json()12 13assert r.status_code == 20014assert "errors" not in body          # GraphQL errors can arrive with 20015assert body["data"]["country"]["capital"] == "New Delhi"

1/4The query names exactly three fields. Nothing else will come back.

A query against a free public GraphQL API for country data. Every GraphQL call is a POST with a query.

Save yourself the pain

Common mistakes

Oops

Asserting only status_code == 200 on GraphQL responses.

Do this instead

Also assert that errors is absent, or contains the error you expected.

Oops

Testing only the queries the front end uses today.

Do this instead

Try missing variables, wrong types and fields you shouldn't see, like other users' emails.

Your mission

Explore a GraphQL API

~25 min

Quick check

A GraphQL response has status 200 and an errors array. Did the request succeed?

Go deeper

1Explore a sample GraphQL API using a GraphQL client tool.
2Learn the basic differences between testing REST and GraphQL APIs.
3Practice writing a query and verifying the returned data structure matches expectations.