Guide
GraphQL API Testing Handbook
Design GraphQL tests across syntax, operation selection, variables, fragments, errors, authorization, and runtime limits.
Dated source and synthetic-example checks; no target schema or service was executed.
Related tools
Understand the document before execution
Parse the document and inventory named operations, variables, fragments, and root fields. Duplicate names and anonymous operations complicate client selection and test reports.
Test schema and runtime separately
A parsed operation may still request an unknown field or pass the wrong argument type. Schema-aware validation needs a local authoritative schema. Runtime tests then verify resolver behavior, state, authorization, and performance.
Variables and fixtures
Keep query text stable and supply synthetic variables separately. Test required, omitted, null, wrong-type, boundary, and unexpected values according to the target schema. Avoid storing real tokens in examples.
Read partial failures
Inspect both data and errors. A field error may leave partial data, make a parent null, or produce no data depending on type nullability and execution stage. Assert expected paths and values, not only HTTP status.
Authorization and complexity
Check object-level and field-level permissions with synthetic identities. Review depth, breadth, pagination, batching, and cost controls in the service; local syntax analysis cannot prove safe resource use.
Network evidence
When a browser call fails, inspect its HTTP request, response, cookies, CORS, and Content-Type as well as the GraphQL payload. A network failure may occur before GraphQL parsing begins.
Limits
DevPouch never fetches a schema or executes operations. Its analyzer reports document structure, not server conformance or security.
Worked synthetic operation and response
The document query Order($id: ID!) { order(id: $id) { id status } } parses with one named operation and one variable. Variables {"id":"SYNTHETIC-7"} supply a value at execution. A response {"data":{"order":null},"errors":[{"message":"Not found","path":["order"]]} requires an assertion on data and errors together. Local syntax parsing cannot establish whether order exists in the target schema, whether the resolver ran, or whether authorization was correct. HTTP status interpretation also depends on the server's GraphQL-over-HTTP transport behavior.
- Parse the document before schema validation.
- Validate against the owning schema before execution tests.
- Assert response data, errors, and transport metadata separately.
References
FAQ
Does this handbook replace testing the actual service?
No. It organizes local inspection and test design; runtime behavior requires controlled tests against the owning system.