From qa-graphql
Wraps GraphQL Yoga testing patterns: `yoga.fetch()` for in-process HTTP-conformant request simulation (no network), `@graphql-tools/executor-http` for subscription + incremental-delivery testing, and the request-builder pattern for queries/mutations/subscriptions. Includes Yoga-specific config gates - `@graphql-yoga/plugin-disable-introspection`, `@graphql-yoga/plugin-persisted-operations` - testable through this skill. Use when writing tests for a GraphQL Yoga server (the-guild.dev's runtime, common in non-Apollo deployments). Composes introspection-attack-surface-reference + persisted-query-strategy-reference.
How this skill is triggered — by the user, by Claude, or both
Slash command
/qa-graphql:graphql-yoga-testThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Per
Per
the-guild.dev/graphql/yoga-server/docs/features/testing:
"Calling the yoga.fetch method does not send an actual HTTP
request. It simulates the HTTP request which 100% conforms with
how Request/Response work."
Structurally different from Apollo's executeOperation - Yoga's
testing path goes through the HTTP transport layer including
middleware, headers, and response codes. There is no separate
"in-process" vs "HTTP-layer" choice.
npm install --save-dev graphql-yoga @graphql-tools/executor-http
Per Yoga docs:
import { createYoga, createSchema } from 'graphql-yoga';
const yoga = createYoga({
schema: createSchema({
typeDefs: /* GraphQL */ `
type Query { greetings: String }
`,
resolvers: { Query: { greetings: () => 'Hello' } },
}),
});
test('greetings', async () => {
const response = await yoga.fetch('http://yoga/graphql', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ query: '{ greetings }' }),
});
const result = await response.json();
expect(result.data.greetings).toBe('Hello');
});
The URL http://yoga/graphql is a placeholder - yoga.fetch
doesn't make a network call, but the URL must parse.
Per Yoga docs:
import { buildHTTPExecutor } from '@graphql-tools/executor-http';
import { parse } from 'graphql';
const executor = buildHTTPExecutor({ fetch: yoga.fetch });
const result = await executor({ document: parse(`{ greetings }`) });
expect(result.data.greetings).toBe('Hello');
For subscriptions (SSE):
const stream = await executor({ document: parse(subscriptionQuery) });
if (Symbol.asyncIterator in stream) {
for await (const event of stream) {
expect(event.data).toBeDefined();
if (allEventsReceived) break;
}
}
const response = await yoga.fetch('http://yoga/graphql', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${testToken}`,
},
body: JSON.stringify({ query: '{ me { id } }' }),
});
Yoga's context-builder runs against the simulated request, so auth middleware is exercised.
npm test
Per
introspection-attack-surface-reference:
import { useDisableIntrospection } from '@graphql-yoga/plugin-disable-introspection';
test('introspection disabled', async () => {
const yoga = createYoga({
schema,
plugins: [useDisableIntrospection()],
});
const resp = await yoga.fetch('http://yoga/graphql', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ query: '{ __schema { types { name } } }' }),
});
const result = await resp.json();
expect(result.errors).toBeDefined();
expect(result.errors[0].message).toMatch(/introspection/i);
});
Per
persisted-query-strategy-reference
Mode 2:
import { usePersistedOperations } from '@graphql-yoga/plugin-persisted-operations';
const operations = {
'abcdef': '{ greetings }',
};
test('rejects unregistered hash in strict mode', async () => {
const yoga = createYoga({
schema,
plugins: [
usePersistedOperations({
getPersistedOperation: (key) => operations[key],
}),
],
});
const resp = await yoga.fetch('http://yoga/graphql', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
extensions: {
persistedQuery: { version: 1, sha256Hash: 'unknown' },
},
}),
});
expect(resp.status).toBe(404); // Yoga's default for unknown
});
yoga.fetch returns a standard Response. Parse with .json()
for non-streaming queries; iterate with the async-iterator for
subscriptions.
The response shape:
{
"data": { "greetings": "Hello" },
"errors": [
{
"message": "...",
"path": ["greetings"],
"extensions": { "code": "..." }
}
]
}
Yoga uses useMaskedErrors by default (per Yoga docs) - error
messages are masked to "Unexpected error" in production unless
the error has been marked safe. Test against this:
const resp = await yoga.fetch(/* ... */);
const result = await resp.json();
// Production: error message is "Unexpected error", original
// hidden in extensions if at all
expect(result.errors[0].message).toBe('Unexpected error.');
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- uses: actions/setup-node@v4
with: { node-version: '20' }
- run: npm ci
- run: npm test
- name: Production-mode tests
env: { NODE_ENV: production }
run: npx jest tests/production-config/
| Anti-pattern | Why it fails | Fix |
|---|---|---|
Skipping yoga.fetch and using HTTP server directly | Slower; same coverage | yoga.fetch is purpose-built |
Asserting on Yoga's default error string "Unexpected error." everywhere | Misses real errors that aren't masked | Use useMaskedErrors({ errorMessage: 'Sanitised' }) and assert per-test |
Skipping useDisableIntrospection in prod tests | Production introspection silently enabled | Mirror prod plugin set in test |
Persisted-operations plugin without explicit allowArbitraryOperations: false | Auto-bypass on unrecognised hash | Use strict mode |
Subscription tests with await response.json() | SSE/multipart streams aren't JSON | Use buildHTTPExecutor + async iterator |
| Stale schema in test | Schema drifts; tests pass against old shape | Rebuild schema per test file or use beforeAll |
http quirks, h2-upgrade
scenarios) need a real server with node-fetch or supertest.graphql-ws integration with its
own test harness.useMaskedErrors interacts with
every test that asserts on errors; understand the project's
configuration.FormData not JSON.introspection-attack-surface-reference,
persisted-query-strategy-reference.apollo-server-test,
mercurius-test,
pothos-builder-tests.n-plus-one-query-detector.npx claudepluginhub testland/qa --plugin qa-graphqlProvides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.