GraphQL API Testing: Queries, Mutations, Schema Validation, and Tools

How GraphQL Testing Differs from REST Testing

REST APIs expose multiple endpoints, each returning a predetermined response structure. GET /api/users/1 always returns the same set of user fields. Testing REST is straightforward: send a request to a specific URL and validate the response shape you already know. GraphQL replaces this model with a single endpoint (usually /graphql) that accepts a query language specifying exactly what data the client wants. The same endpoint can return { user { name } } or { user { name email orders { id total items { productName } } } } depending on the query.

This single-endpoint architecture changes how you organize tests. Instead of grouping tests by URL path, GraphQL tests group by schema type (User, Product, Order), by operation type (queries, mutations, subscriptions), or by use case (authentication flow, checkout flow). Each test constructs a specific query or mutation, sends it as a POST request to the /graphql endpoint, and validates the response data against the query's expected results.

Error handling in GraphQL differs fundamentally from REST. REST uses HTTP status codes to indicate success or failure: 200 for success, 404 for not found, 400 for bad input. GraphQL always returns HTTP 200, even when errors occur. Errors appear in an "errors" array in the response body alongside any partial "data" that could be resolved. A single GraphQL response can contain both successful data for some fields and errors for others. Tests must check both the data and errors fields to fully validate a response, because a 200 status code tells you nothing about whether the query succeeded.

Schema introspection provides a machine-readable definition of the API's capabilities. GraphQL servers expose their full schema through introspection queries, listing every type, field, argument, and directive. This schema serves as the authoritative contract between client and server, and testing tools use it for autocomplete, validation, and automatic test generation. Schema-based testing catches changes that break client expectations without requiring hand-written test cases for every field combination.

Testing Queries

Query testing verifies that the GraphQL server returns correct data for requested fields. The simplest query test requests a single field and asserts its value. More complex tests verify nested object resolution, list handling, argument processing, pagination, filtering, and field-level authorization.

Start with basic field resolution. Query a known entity by ID and verify that each requested field returns the expected value. If your schema has a user(id: ID!) query that returns a User type with name, email, and createdAt fields, write a test that creates a user with known values, queries for that user, and asserts each field matches. This catches resolver bugs where fields return null, wrong values, or throw errors.

Nested object testing verifies that relationships resolve correctly. Query a user with their orders, and each order with its items. Verify that the nested data is accurate: the right orders belong to the right user, items are correctly associated with orders, and computed fields (like order totals) calculate correctly. Nested queries stress-test the data layer because each level of nesting typically triggers additional database queries. A resolver bug at any nesting level produces incorrect or missing data.

Argument and variable testing validates that query arguments filter and modify results correctly. If the users query accepts a role argument, test that querying with role: ADMIN returns only admin users. Test with invalid argument values and verify the error response. Test with missing required arguments and verify the appropriate error. GraphQL variables (the $variable syntax) should work identically to inline arguments, so test both approaches to confirm the variable binding works correctly.

Pagination testing in GraphQL typically uses the Relay connection specification with edges, nodes, pageInfo, and cursor-based navigation. Test that requesting the first N items returns exactly N items with correct hasNextPage/hasPreviousPage indicators. Test that navigating with after/before cursors returns the next/previous page without overlapping items. Test that requesting all pages sequentially returns every item exactly once. Test cursor stability: if data changes between page requests, cursor-based pagination should still return consistent results without duplicating or skipping items.

Fragment and inline fragment testing verifies that GraphQL fragments resolve correctly. If your schema uses interfaces or unions (like a SearchResult that can be a User, Product, or Article), test that inline fragments (... on User { name }) return the correct type-specific fields. Test that requesting fields only available on one type correctly returns null or omits the field for other types. Union type testing is particularly important because resolving the wrong type silently returns null for all fields, making the bug difficult to detect without explicit type assertion.

Testing Mutations

Mutation testing validates that write operations correctly create, update, and delete data, enforce validation rules, maintain data integrity, and return accurate results. Mutations are where most GraphQL bugs cause real damage because they modify state.

Create mutation testing mirrors REST POST testing. Send a createUser mutation with valid input, verify the response contains the created user with a server-generated ID, and follow up with a query to confirm the data persisted. Then test with invalid input: missing required fields, invalid data types, values that violate business rules (duplicate email, negative price, future birth date). Verify that invalid mutations return errors in the response's errors array with clear messages identifying the problematic field and the validation rule that failed.

Update mutation testing verifies partial and full updates. GraphQL mutations commonly accept input types with optional fields, where only provided fields are updated and omitted fields remain unchanged. Test that providing a subset of fields updates only those fields. Test that providing null for a nullable field clears the value. Test that providing null for a non-nullable field returns a validation error. Verify optimistic concurrency if the API supports it: update a record, then attempt to update it again with a stale version number and verify the conflict is detected.

Delete mutation testing sends a delete operation and verifies the return value (typically the deleted object or a success boolean), then queries for the deleted entity and confirms it no longer exists. Test cascading deletes: if deleting a user should also delete their orders, verify the orders are gone. Test referential integrity: if deleting a product should fail because active orders reference it, verify the error. Test authorization: verify that users can only delete their own resources and that admin-only deletion endpoints reject non-admin users.

Mutation return type testing validates that mutations return the complete, up-to-date object state. A common bug is a mutation that updates data in the database but returns the pre-update version in the response because the resolver reads the object before the write completes. Test that the mutation response reflects the updated values, not the original values. Also test that related objects returned by the mutation (like the user's updated order count after creating an order) reflect the mutation's side effects.

Schema Validation and Change Detection

Schema validation ensures that the GraphQL schema remains backward compatible as it evolves. Breaking changes to a GraphQL schema, like removing a field, changing a field's type, or making a nullable field non-nullable, can silently break every client that queries the changed field. Unlike REST where each endpoint can be versioned independently, a GraphQL schema is a single contract shared by all clients.

Schema diffing tools compare the current schema against a baseline and report changes categorized as breaking, dangerous, or safe. Breaking changes include removing a type or field, changing a field's type, removing an enum value, and making a nullable argument required. Dangerous changes include adding a required argument to a field, changing a default argument value, and adding a value to an enum (which can break exhaustive switch statements on clients). Safe changes include adding new types, adding new nullable fields, adding new enum values, and deprecating fields. Run schema diffing in CI on every pull request to catch breaking changes before they merge.

graphql-inspector is the most widely used schema validation tool. It compares two schema versions and reports breaking changes, provides a GitHub bot that comments on pull requests with schema change analysis, generates schema documentation, and validates operations against the schema to ensure client queries remain valid. Install it in your CI pipeline and point it at your schema introspection endpoint or schema definition files.

Schema linting enforces naming conventions, documentation requirements, and structural consistency. Tools like graphql-eslint and graphql-schema-linter check that field names follow camelCase convention, that types use PascalCase, that every field has a description (important for auto-generated documentation), that deprecated fields include a deprecation reason, and that input types use the Input suffix. These conventions prevent the schema from becoming inconsistent as multiple developers add to it over time.

Deprecation testing verifies that deprecated fields still work correctly. Marking a field as @deprecated in the schema does not remove it; clients may depend on it for months or years. Tests for deprecated fields ensure they continue to return correct data while the deprecation is active. Track deprecated field usage through query logging to determine when it is safe to remove them. Remove deprecated fields only after query logs confirm zero client usage or after communicating a sunset date to all consumers.

Authorization Testing

GraphQL authorization operates at a finer granularity than REST because clients can request any combination of fields. In REST, you authorize access to an entire endpoint. In GraphQL, you may need to authorize access to individual fields within a type. A regular user might be allowed to query user { name email } but not user { name email socialSecurityNumber }. Field-level authorization testing verifies these granular permissions.

Test that unauthenticated queries to protected fields return errors. Send a query without authentication credentials and verify that the response contains errors for protected fields while returning data for any public fields. The response might include partial data (public fields resolved successfully) alongside errors for the protected fields. This mixed response behavior is correct GraphQL behavior and tests must validate both parts.

Test role-based field access by authenticating as different user roles and requesting the same fields. An admin querying user { name email role lastLoginIP } should get all fields. A regular user querying the same fields should get name and email but receive a null or error for lastLoginIP. This tests that authorization directives on the schema (@auth, @hasRole, or custom directives) correctly restrict field access based on the requesting user's role.

Test object-level authorization to ensure users can only access their own resources. Authenticate as User A and query for User B's data by ID. The query should either return null, return an authorization error, or omit the unauthorized fields depending on the API's authorization strategy. This is the GraphQL equivalent of REST's Broken Object Level Authorization (BOLA) testing and is equally critical for security.

Test mutation authorization to ensure that create, update, and delete operations are restricted to authorized users. An admin mutation to change user roles should reject requests from non-admin users. A user should not be able to update another user's profile through a mutation, even if they know the target user's ID. Test that authorization checks run before any data modification, not after, so that unauthorized mutations do not partially modify data before failing.

Performance and Security Testing

GraphQL's query flexibility creates unique performance and security concerns that do not exist in REST. Because clients control the query shape, a malicious or poorly written client can construct queries that consume enormous server resources. Testing must verify that the server protects itself against these abuse patterns.

Query depth limiting prevents deeply nested queries that cause exponential database load. A query like { users { orders { items { product { reviews { author { orders { items } } } } } } } } nests seven levels deep, potentially triggering millions of database rows to be loaded. Test that the server rejects queries exceeding the configured depth limit with a clear error message. Typical depth limits range from 5 to 10 levels depending on the schema structure.

Query complexity analysis assigns a cost to each field based on how expensive it is to resolve. A simple scalar field (name) might cost 1, while a list field (orders) might cost 10 times the estimated list size. The server calculates total query complexity before execution and rejects queries that exceed the complexity budget. Test that complex queries are rejected and that the error message includes the query's calculated complexity and the maximum allowed, so clients can optimize their queries.

N+1 query detection tests for the most common GraphQL performance problem. When a resolver for a list type makes one database query per item instead of batching, it creates an N+1 pattern that degrades linearly with collection size. Request a list of 100 items with nested relationships and measure the response time. If it takes significantly longer than querying a single item with the same nesting, the resolver likely has an N+1 problem. DataLoader (or equivalent batching mechanisms) should eliminate this, and tests should verify the fix by comparing response times for different collection sizes.

Introspection control testing verifies that production environments disable or restrict schema introspection. While introspection is essential during development, exposing the full schema in production reveals every field, type, argument, and relationship to potential attackers. Test that introspection queries return an error or empty result in production while working correctly in development and staging environments.

GraphQL Testing Tools

Insomnia provides the best visual GraphQL testing experience among GUI clients. Its GraphQL editor offers schema-aware autocomplete, inline documentation, query validation, and a schema browser that lets you explore types and fields before constructing queries. For teams that prefer visual tools, Insomnia is the strongest choice for GraphQL specifically.

Hoppscotch includes a dedicated GraphQL section with a query editor, variable input, headers configuration, and response viewer. Being browser-based and open-source, it is the fastest way to test a GraphQL endpoint without installing anything.

Apollo Client DevTools (for Apollo-based clients) provides query inspection, cache visualization, and mutation tracking in the browser's developer tools. While not a testing tool per se, it helps debug query behavior during development and understand cache interactions that affect test outcomes.

For automated testing, the same code-based frameworks used for REST apply to GraphQL with minor adaptations. Playwright, Supertest, requests, and REST Assured all send POST requests to the /graphql endpoint with a query body. The difference is in the assertion logic: instead of checking the HTTP status code (which is always 200), you check the data and errors fields in the response body. Some teams build thin wrapper functions that send a GraphQL operation and return either the data or throw an error, simplifying test code.

Schemathesis generates GraphQL test cases automatically from schema introspection. It creates valid and boundary-case queries for every type and field in the schema, sends them to the server, and reports any crashes, errors, or unexpected responses. This property-based testing approach is particularly valuable for GraphQL because the combinatorial explosion of possible query shapes makes exhaustive manual test writing impractical. Schemathesis can find edge cases that hand-written tests would never cover.