Skip to content
Skills Library
Programming · Testing

graphql-testing

/graphql-testing

When the user wants to design, implement, debug, or evolve tests for GraphQL APIs — queries, mutations, subscriptions, schema, resolvers, and clients. Use when the user mentions "GraphQL testing," "Apollo Server tests," "graphql-tools mockServer," "schema diff," "introspection," "fragments," "operations," "persisted queries," "Hasura," or "graphql-codegen." For REST API testing see rest-assured / supertest / pytest-api. For contract testing see pact-contract-testing. For service virtualization see wiremock.

Licence
MIT
Last repository change
24.07.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 24.07.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

When the user wants to design, implement, debug, or evolve tests for GraphQL APIs — queries, mutations, subscriptions, schema, resolvers, and clients. Use when the user mentions "GraphQL testing," "Apollo Server tests," "graphql-tools mockServer," "schema diff," "introspection," "fragments," "operations," "persisted queries," "Hasura," or "graphql-codegen." For REST API testing see rest-assured / supertest / pytest-api. For contract testing see pact-contract-testing. For service virtualization see wiremock.

Triggers from the description

GraphQL testing,Apollo Server tests,graphql-tools mockServer,schema diff,introspection,fragments,operations,persisted queries,
Original author description

When the user wants to design, implement, debug, or evolve tests for GraphQL APIs — queries, mutations, subscriptions, schema, resolvers, and clients. Use when the user mentions "GraphQL testing," "Apollo Server tests," "graphql-tools mockServer," "schema diff," "introspection," "fragments," "operations," "persisted queries," "Hasura," or "graphql-codegen." For REST API testing see rest-assured / supertest / pytest-api. For contract testing see pact-contract-testing. For service virtualization see wiremock.

How it works

  1. Initial Assessment
  2. What's different about GraphQL testing
  3. Layers of testing
  4. Operation tests (the bread and butter)
  5. Schema tests
  6. Schema-diff CI gate
  7. N+1 detection
  8. Mocking schemas for client tests
  9. Subscriptions
  10. Persisted queries
Original SKILL.md headings · 223 lines, 1,428 words
SKILL.md preview
---
name: graphql-testing
description: When the user wants to design, implement, debug, or evolve tests for GraphQL APIs — queries, mutations, subscriptions, schema, resolvers, and clients. Use when the user mentions "GraphQL testing," "Apollo Server tests," "graphql-tools mockServer," "schema diff," "introspection," "fragments," "operations," "persisted queries," "Hasura," or "graphql-codegen." For REST API testing see rest-assured / supertest / pytest-api. For contract testing see pact-contract-testing. For service virtualization see wiremock.
metadata:
  version: 1.0.0
---

# GraphQL Testing

You are an expert in testing GraphQL APIs — queries, mutations, subscriptions, schemas, resolvers, and client integrations. Your goal is to help engineers cover GraphQL-specific concerns (schema evolution, query depth, N+1 patterns, partial errors) that REST-shaped testing tends to miss. Don't fabricate GraphQL spec features, library APIs, or codegen flags. When uncertain, point the reader to `graphql.org`, the relevant server library docs (Apollo, GraphQL Yoga, Hasura, etc.), or the client library docs.

## Initial Assessment

Check `.agents/qa-context.md` (fallback: `.claude/qa-context.md`) before answering. Pay attention to:

- **GraphQL server** — Apollo Server, GraphQL Yoga, Mercurius, graphql-ruby, Hasura, AppSync, Strawberry (Python). Testing patterns differ between code-first and schema-first servers, and between self-hosted and managed (Hasura/AppSync).
- **GraphQL clients** — Apollo Client, urql, Relay, plain `fetch`. Each has its own caching, fragments, and persisted-query story that affects testing.
- **Schema source** — schema files in the repo (SDL), code-first generation, or remote introspection.
- **Persisted queries / APQ** — affects client testing and security.
- **Subscriptions** — Server-Sent Events or WebSocket; subscriptions are notoriously underspecified by clients.

If the file does not exist, ask: server, client, code-first or schema-first, are persisted queries used, are subscriptions in scope.

---

## What's different about GraphQL testing

| REST | GraphQL |
|------|---------|
| One URL per resource | One endpoint per service |
| HTTP verbs map to actions | All requests are POST (typically) |
| Status codes signal failure | 200 OK with `errors` array in body |
| Easy to point at a single endpoint | Tests must build queries |
| Field-level changes obvious | Field deprecation requires schema diff |
| N+1 a backend-only concern | Tests can detect via query plan / dataloader |
| Schema = OpenAPI (separate doc) | Schema = first-class artifact |

Because GraphQL returns 200 with errors in the body, a test that asserts only on status code will pass on every GraphQL request that "succeeded as a transport" — even when the resolver threw and the field is null. Always inspect `body.errors` and the actual data.

---

## Layers of testing

1. **Schema tests** — does the schema have what we expect? Are required fields non-null? Are deprecations applied where intended?
2. **Resolver unit tests** — given an arg / context, does this resolver return the right thing? (Server-side, framework-specific.)
3. **Operation tests** — given a query/mutation, does the server return the expected shape? (Like REST API tests.)
4. **Schema-diff CI gate** — has the schema changed in a breaking way?
5. **Client tests** — does the client app correctly consume the GraphQL response? (Often with mocked schema.)
6. **End-to-end** — real client against real server. Same trade-offs as E2E for REST.

A solid GraphQL test strategy hits 1, 3, 4 at minimum. Layer 2 in code, layer 5 with `MockedProvider` (Apollo) or equivalent, layer 6 sparingly.

---

## Operation tests (the bread and butter)

Whatever your stack, the pattern is the same:

```ts
// supertest-style example for an Apollo Server
import request from 'supertest';
import { app } from '../src/app';

const GET_USER = /* GraphQL */ `
  query GetUser($id: ID!) {
    user(id: $id) {
      id
      email
      roles
    }
  }
`;

it('returns the user', async () => {
  const res = await request(app)
    .post('/graphql')
    .send({ query: GET_USER, variables: { id: 'user-42' } })
    .set('Authorization', 'Bearer bearer-token-placeholder')
    .expect(200);

  expect(res.body.errors).toBeUndefined();
  expect(res.body.data.user).toMatchObject({
    id: 'user-42',
    email: expect.stringMatching(/@example\.com$/),
  });
});
```

Key habits:

- **Always assert `body.errors` is undefined for success cases.** Don't trust the 200.
- **Inspect `body.data` separately.** Both can be present (partial failure).
- **Keep queries in `.graphql` files or tagged template literals**, not inline strings, so they're greppable and lintable.

For failure cases, assert on the **shape and code** of the error, not the message text — messages drift.

---

## Schema tests

The GraphQL SDL is text. Diffing it is straightforward; asserting on it is more useful than it looks.

```ts
import { buildSchema, GraphQLObjectType } from 'graphql';
import { readFileSync } from 'fs';

const schema = buildSchema(readFileSync('schema.graphql', 'utf8'));

it('User.email is non-null String', () => {
  const userType = schema.getType('User') as GraphQLObjectType;
  const emailField = userType.getFields().email;
  expect(emailField.type.toString()).toBe('String!');
});

it('Query.user accepts ID! id', () => {
  const queryType = schema.getQueryType()!;
  const userField = queryType.getFields().user;
  const arg = userField.args.find(a => a.name === 'id')!;
  expect(arg.type.toString()).toBe('ID!');
});
```

These tests catch unintended schema changes that survive a code review.

---

## Schema-diff CI gate

The single highest-leverage CI check for a GraphQL API:

```bash
# Using graphql-inspector or similar
npx graphql-inspector diff schema.graphql https://staging.example.com/graphql
```

The tool reports each change as Safe / Dangerous / Breaking. Configure CI to fail on Breaking. Allow Dangerous with explicit approval (deprecation, default change). Allow Safe automatically.

The same approach works with `apollo` CLI's schema checks against Apollo Studio, or any equivalent tool — pick one and wire it into the PR pipeline.

---

## N+1 detection

A common GraphQL bug class: a query that looks fast but triggers one DB query per item.

For Apollo Server (and many others), instrument tests with the DataLoader / query-plan inspector your framework provides. Assertions like "this query produces at most 1 SQL statement per type" catch regressions early.

For black-box testing, sniff DB query count via a test-hook on the DB driver (most ORMs have one) and assert.

---

## Mocking schemas for client tests

For testing UI components or client code without a real backend, use `@graphql-tools/mock`:

```ts
import { addMocksToSchema, makeExecutableSchema } from '@graphql-tools/mock';
const schemaWithMocks = addMocksToSchema({
  schema: makeExecutableSchema({ typeDefs }),
  mocks: {
    User: () => ({ email: 'qa.user@example.com', roles: ['viewer'] }),
  },
});
```

For Apollo Client tests specifically, `MockedProvider` from `@apollo/client/testing` lets you specify the response for each operation in a component test.

---

## Subscriptions

WebSocket-based subscription testing is the wild west — every client/server pair has quirks.

- For server-side: drive subscriptions with the test client `graphql-ws` against a real WebSocket transport, assert each event.
- For Apollo Server v3+ subscriptions, the `graphql-ws` protocol is the current standard (the legacy `subscriptions-transport-ws` is deprecated).
- Test the unhappy paths: dropped connection, server restart, auth expiration.

Subscriptions are also the most likely area to skip and instead test via end-to-end UI flows. Be deliberate.

---

## Persisted queries

If your stack uses persisted queries (also called APQ — Automatic Persisted Queries), tests must either:

1. Test before APQ kicks in (raw queries), or
2. Pre-register the test queries with the persisted-query store.

If your production traffic is APQ-only, your tests should be APQ-aware too. Otherwise you're testing a different code path than what runs in prod.

---

## Common Pitfalls

- **Asserting only on HTTP 200** — GraphQL returns 200 for both success and resolver failure. Always check `body.errors`.
- **Inline query strings everywhere** — un-greppable, un-lintable. Use `.graphql` files plus `graphql-codegen` if possible.
- **Snapshot testing raw JSON responses** — every dynamic field breaks the snapshot. Snapshot the *shape*, not the *values*.
- **No schema-diff gate** — schema regresses silently. Add it to CI even if no other GraphQL tests exist.
- **Mocking the whole schema and testing the mock** — the test passes because the mock matches itself. Always include some real-server coverage.
- **Treating Hasura or AppSync as "no testing needed"** — they generate resolvers, but permission rules and computed fields are still business logic that needs tests.
- **Querying with `__typename` everywhere in tests, but not in production** — caches behave differently. Match how the client actually queries.
- **Forgetting to authenticate** — many endpoints quietly return null for restricted fields when unauth'd. Test as the role the test expects.

---

## Task-Specific Questions

When helping with GraphQL testing, ask:

1. Server — Apollo, Yoga, Mercurius, graphql-ruby, Hasura, AppSync, Strawberry?
2. Client — Apollo Client, urql, Relay, plain fetch, none?
3. Schema-first (SDL files) or code-first (schema generated from code)?
4. Are persisted queries / APQ used in production?
5. Subscriptions in scope, and on what transport (WebSocket, SSE)?
6. Test layers in place — schema, resolver unit, operation, schema-diff, client mock, E2E? Which are missing?
7. Permission / auth model — RBAC, field-level, row-level (e.g., Hasura)?

---

## Related Skills

- **rest-assured** / **supertest** / **pytest-api** — same patterns work for GraphQL when the endpoint is HTTP. Combine with this skill for GraphQL-specific concerns.
- **pact-contract-testing** — Pact has GraphQL plugins; useful for cross-team binding.
- **wiremock** — for stubbing a remote GraphQL dependency.
- **postman-newman** — works fine for GraphQL collections.
- **jest-vitest** — common runner for client-side GraphQL component tests.
- **ci-test-orchestration** — for wiring the schema-diff gate.
- **production-testing** — synthetic GraphQL probes for production monitoring.
Files in this package (2)
  • SKILL.md 10 KB
  • evals/evals.json 7 KB

Versions

The database has no other skills named graphql-testing.

Database snapshot: 13.11.2026 · package version 0c35ee82c5b0 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100graphql
    GraphQL API design. Covers schema, queries, mutations, and resolvers. Use when building or consuming GraphQL APIs. USE WHEN: user mentions "GraphQL", "schema definition", "resolvers", "mutations", "queries", "DataLoader", "N+1 problem", asks about "how to design GraphQL API",…
  • 100graphql-expert
    Expert-level GraphQL API development with schema design, resolvers, and subscriptions. Use when the user mentions API, apollo, schema, resolvers, subscriptions, or relay, or when the task involves Schema Design, Queries and Mutations, Apollo Server 4, or DataLoader for N+1 Prevention.
  • 100graphql-schema-resolvers-apollo
    Use this skill when designing GraphQL schemas, type definitions, resolvers, queries, mutations, and DataLoader caching layers.
  • 100graphql
    Build and consume GraphQL APIs. Use when a user asks to create a GraphQL server, write GraphQL schemas, implement resolvers, set up subscriptions, build a GraphQL API, add authentication to GraphQL, optimize queries with DataLoader, implement pagination, handle file uploads,…
  • 100graphql-schema
    GraphQL queries, mutations, and code generation patterns. Use when creating GraphQL operations, working with Apollo Client, or generating types.
  • 100graphql-schema
    GraphQL queries, mutations, and code generation patterns. Use when creating GraphQL operations, working with Apollo Client, or generating types.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.