1# GraphQL Testing
2 
3## Table of Contents
4 
51. [Patterns](#patterns)
62. [Anti-Patterns](#anti-patterns)
73. [Troubleshooting](#troubleshooting)
8 
9> **When to use**: Testing GraphQL APIs — queries, mutations, variables, and error handling.
10 
11## Patterns
12 
13### Basic Query with Variables
14 
15All GraphQL requests go through `POST` to a single endpoint. Send `query`, `variables`, and optionally `operationName` in the JSON body.
16 
17```typescript
18import { test, expect } from "@playwright/test";
19 
20const GQL_ENDPOINT = "/graphql";
21 
22test("query with variables", async ({ request }) => {
23  const resp = await request.post(GQL_ENDPOINT, {
24    data: {
25      query: `
26        query FetchItem($id: ID!) {
27          item(id: $id) {
28            id
29            title
30            price
31            reviews { id rating }
32          }
33        }
34      `,
35      variables: { id: "101" },
36    },
37  });
38 
39  expect(resp.ok()).toBeTruthy();
40  const { data, errors } = await resp.json();
41 
42  // GraphQL returns 200 even on errors — always check both
43  expect(errors).toBeUndefined();
44  expect(data.item).toMatchObject({
45    id: "101",
46    title: expect.any(String),
47    price: expect.any(Number),
48  });
49  expect(data.item.reviews).toEqual(
50    expect.arrayContaining([
51      expect.objectContaining({
52        id: expect.any(String),
53        rating: expect.any(Number),
54      }),
55    ])
56  );
57});
58```
59 
60### Mutations
61 
62```typescript
63import { test, expect } from "@playwright/test";
64 
65const GQL_ENDPOINT = "/graphql";
66 
67test("mutation creates resource", async ({ request }) => {
68  const resp = await request.post(GQL_ENDPOINT, {
69    data: {
70      query: `
71        mutation AddItem($input: ItemInput!) {
72          addItem(input: $input) {
73            id
74            title
75            status
76          }
77        }
78      `,
79      variables: {
80        input: {
81          title: "New Widget",
82          price: 15.0,
83          status: "DRAFT",
84        },
85      },
86    },
87  });
88 
89  const { data, errors } = await resp.json();
90  expect(errors).toBeUndefined();
91  expect(data.addItem).toMatchObject({
92    id: expect.any(String),
93    title: "New Widget",
94    status: "DRAFT",
95  });
96});
97```
98 
99### Validation Errors
100 
101```typescript
102import { test, expect } from "@playwright/test";
103 
104const GQL_ENDPOINT = "/graphql";
105 
106test("handles validation errors", async ({ request }) => {
107  const resp = await request.post(GQL_ENDPOINT, {
108    data: {
109      query: `
110        mutation AddItem($input: ItemInput!) {
111          addItem(input: $input) { id }
112        }
113      `,
114      variables: { input: { title: "" } },
115    },
116  });
117 
118  const { data, errors } = await resp.json();
119  expect(errors).toBeDefined();
120  expect(errors.length).toBeGreaterThan(0);
121  expect(errors[0].message).toContain("title");
122  expect(errors[0].extensions?.code).toBe("BAD_USER_INPUT");
123});
124```
125 
126### Authorization Errors
127 
128```typescript
129import { test, expect } from "@playwright/test";
130 
131const GQL_ENDPOINT = "/graphql";
132 
133test("handles authorization errors", async ({ request }) => {
134  const resp = await request.post(GQL_ENDPOINT, {
135    data: {
136      query: `
137        query AdminDashboard {
138          adminMetrics { revenue activeUsers }
139        }
140      `,
141    },
142  });
143 
144  const { data, errors } = await resp.json();
145  expect(errors).toBeDefined();
146  expect(errors[0].extensions?.code).toBe("UNAUTHORIZED");
147  expect(data?.adminMetrics).toBeNull();
148});
149```
150 
151### Authenticated GraphQL Fixture
152 
153```typescript
154// fixtures/graphql-fixtures.ts
155import { test as base, expect, APIRequestContext } from "@playwright/test";
156 
157type GraphQLFixtures = {
158  gqlClient: APIRequestContext;
159  adminGqlClient: APIRequestContext;
160};
161 
162export const test = base.extend<GraphQLFixtures>({
163  gqlClient: async ({ playwright }, use) => {
164    const ctx = await playwright.request.newContext({
165      baseURL: "https://api.myapp.io",
166      extraHTTPHeaders: {
167        Authorization: `Bearer ${process.env.API_TOKEN}`,
168        "Content-Type": "application/json",
169      },
170    });
171    await use(ctx);
172    await ctx.dispose();
173  },
174 
175  adminGqlClient: async ({ playwright }, use) => {
176    const loginCtx = await playwright.request.newContext({
177      baseURL: "https://api.myapp.io",
178    });
179    const loginResp = await loginCtx.post("/graphql", {
180      data: {
181        query: `
182          mutation Login($email: String!, $password: String!) {
183            login(email: $email, password: $password) { token }
184          }
185        `,
186        variables: {
187          email: process.env.ADMIN_EMAIL,
188          password: process.env.ADMIN_PASSWORD,
189        },
190      },
191    });
192    const { data } = await loginResp.json();
193    
194    if (!data?.login?.token) {
195      throw new Error(`Admin login failed: status ${loginResp.status()}, response: ${JSON.stringify(data)}`);
196    }
197    
198    await loginCtx.dispose();
199 
200    const ctx = await playwright.request.newContext({
201      baseURL: "https://api.myapp.io",
202      extraHTTPHeaders: {
203        Authorization: `Bearer ${data.login.token}`,
204        "Content-Type": "application/json",
205      },
206    });
207    await use(ctx);
208    await ctx.dispose();
209  },
210});
211 
212export { expect };
213```
214 
215### GraphQL Helper Function
216 
217```typescript
218// utils/graphql.ts
219import { APIRequestContext, expect } from "@playwright/test";
220 
221export async function gqlQuery<T = any>(
222  request: APIRequestContext,
223  query: string,
224  variables?: Record<string, any>
225): Promise<{ data: T; errors?: any[] }> {
226  const resp = await request.post("/graphql", {
227    data: { query, variables },
228  });
229  expect(resp.ok()).toBeTruthy();
230  return resp.json();
231}
232 
233export async function gqlMutation<T = any>(
234  request: APIRequestContext,
235  mutation: string,
236  variables?: Record<string, any>
237): Promise<{ data: T; errors?: any[] }> {
238  return gqlQuery<T>(request, mutation, variables);
239}
240```
241 
242```typescript
243// tests/api/items.spec.ts
244import { test, expect } from "@playwright/test";
245import { gqlQuery, gqlMutation } from "../../utils/graphql";
246 
247test("fetch and update item", async ({ request }) => {
248  const { data: fetchData } = await gqlQuery(
249    request,
250    `query GetItem($id: ID!) { item(id: $id) { id title } }`,
251    { id: "101" }
252  );
253  expect(fetchData.item.title).toBeDefined();
254 
255  const { data: updateData, errors } = await gqlMutation(
256    request,
257    `mutation UpdateItem($id: ID!, $title: String!) {
258      updateItem(id: $id, title: $title) { id title }
259    }`,
260    { id: "101", title: "Updated Title" }
261  );
262  expect(errors).toBeUndefined();
263  expect(updateData.updateItem.title).toBe("Updated Title");
264});
265```
266 
267## Anti-Patterns
268 
269| Don't Do This | Problem | Do This Instead |
270| --- | --- | --- |
271| Check only `response.ok()` | GraphQL returns 200 even on errors — `errors` array is the real signal | Always check both `data` and `errors` in the response body |
272| Ignore `errors` array | Validation and auth errors appear in `errors`, not HTTP status | Destructure and assert: `expect(errors).toBeUndefined()` |
273| Hardcode query strings inline everywhere | Duplicated queries are hard to maintain | Extract queries to constants or use a helper function |
274| Skip variable validation | Invalid variables cause cryptic server errors | Validate input shape before sending |
275 
276## Troubleshooting
277 
278### GraphQL returns 200 but data is null
279 
280**Cause**: GraphQL servers return HTTP 200 even when the query has errors. The actual error is in the `errors` array.
281 
282**Fix**: Always destructure and check both `data` and `errors`.
283 
284```typescript
285const { data, errors } = await resp.json();
286if (errors) {
287  console.error("GraphQL errors:", JSON.stringify(errors, null, 2));
288}
289expect(errors).toBeUndefined();
290expect(data.item).toBeDefined();
291```
292 
293### "Cannot query field X on type Y"
294 
295**Cause**: The field doesn't exist in the schema, or you're querying the wrong type.
296 
297**Fix**: Verify the schema. Use introspection or check your GraphQL IDE for available fields.
298 
299```typescript
300// Introspection query to debug schema
301const { data } = await request.post("/graphql", {
302  data: {
303    query: `{ __type(name: "Item") { fields { name type { name } } } }`,
304  },
305});
306console.log(data.__type.fields);
307```
308 
309### Variables not being applied
310 
311**Cause**: Variable names in the query don't match the `variables` object keys, or types don't match.
312 
313**Fix**: Ensure variable names match exactly (case-sensitive) and types align with the schema.
314 
315```typescript
316// Wrong: variable name mismatch
317const resp = await request.post("/graphql", {
318  data: {
319    query: `query GetItem($itemId: ID!) { item(id: $itemId) { id } }`,
320    variables: { id: "101" }, // Should be { itemId: "101" }
321  },
322});
323 
324// Correct
325const resp = await request.post("/graphql", {
326  data: {
327    query: `query GetItem($itemId: ID!) { item(id: $itemId) { id } }`,
328    variables: { itemId: "101" },
329  },
330});
331```
332