@arcadialdev/arcality 2.2.0

package/.agents/skills/playwright-best-practices/testing-patterns/graphql-testing.md

@@ -0,0 +1,331 @@
+# GraphQL Testing
+
+## Table of Contents
+
+1. [Patterns](#patterns)
+2. [Anti-Patterns](#anti-patterns)
+3. [Troubleshooting](#troubleshooting)
+
+> **When to use**: Testing GraphQL APIs — queries, mutations, variables, and error handling.
+
+## Patterns
+
+### Basic Query with Variables
+
+All GraphQL requests go through `POST` to a single endpoint. Send `query`, `variables`, and optionally `operationName` in the JSON body.
+
+```typescript
+import { test, expect } from "@playwright/test";
+
+const GQL_ENDPOINT = "/graphql";
+
+test("query with variables", async ({ request }) => {
+  const resp = await request.post(GQL_ENDPOINT, {
+    data: {
+      query: `
+        query FetchItem($id: ID!) {
+          item(id: $id) {
+            id
+            title
+            price
+            reviews { id rating }
+          }
+        }
+      `,
+      variables: { id: "101" },
+    },
+  });
+
+  expect(resp.ok()).toBeTruthy();
+  const { data, errors } = await resp.json();
+
+  // GraphQL returns 200 even on errors — always check both
+  expect(errors).toBeUndefined();
+  expect(data.item).toMatchObject({
+    id: "101",
+    title: expect.any(String),
+    price: expect.any(Number),
+  });
+  expect(data.item.reviews).toEqual(
+    expect.arrayContaining([
+      expect.objectContaining({
+        id: expect.any(String),
+        rating: expect.any(Number),
+      }),
+    ])
+  );
+});
+```
+
+### Mutations
+
+```typescript
+import { test, expect } from "@playwright/test";
+
+const GQL_ENDPOINT = "/graphql";
+
+test("mutation creates resource", async ({ request }) => {
+  const resp = await request.post(GQL_ENDPOINT, {
+    data: {
+      query: `
+        mutation AddItem($input: ItemInput!) {
+          addItem(input: $input) {
+            id
+            title
+            status
+          }
+        }
+      `,
+      variables: {
+        input: {
+          title: "New Widget",
+          price: 15.0,
+          status: "DRAFT",
+        },
+      },
+    },
+  });
+
+  const { data, errors } = await resp.json();
+  expect(errors).toBeUndefined();
+  expect(data.addItem).toMatchObject({
+    id: expect.any(String),
+    title: "New Widget",
+    status: "DRAFT",
+  });
+});
+```
+
+### Validation Errors
+
+```typescript
+import { test, expect } from "@playwright/test";
+
+const GQL_ENDPOINT = "/graphql";
+
+test("handles validation errors", async ({ request }) => {
+  const resp = await request.post(GQL_ENDPOINT, {
+    data: {
+      query: `
+        mutation AddItem($input: ItemInput!) {
+          addItem(input: $input) { id }
+        }
+      `,
+      variables: { input: { title: "" } },
+    },
+  });
+
+  const { data, errors } = await resp.json();
+  expect(errors).toBeDefined();
+  expect(errors.length).toBeGreaterThan(0);
+  expect(errors[0].message).toContain("title");
+  expect(errors[0].extensions?.code).toBe("BAD_USER_INPUT");
+});
+```
+
+### Authorization Errors
+
+```typescript
+import { test, expect } from "@playwright/test";
+
+const GQL_ENDPOINT = "/graphql";
+
+test("handles authorization errors", async ({ request }) => {
+  const resp = await request.post(GQL_ENDPOINT, {
+    data: {
+      query: `
+        query AdminDashboard {
+          adminMetrics { revenue activeUsers }
+        }
+      `,
+    },
+  });
+
+  const { data, errors } = await resp.json();
+  expect(errors).toBeDefined();
+  expect(errors[0].extensions?.code).toBe("UNAUTHORIZED");
+  expect(data?.adminMetrics).toBeNull();
+});
+```
+
+### Authenticated GraphQL Fixture
+
+```typescript
+// fixtures/graphql-fixtures.ts
+import { test as base, expect, APIRequestContext } from "@playwright/test";
+
+type GraphQLFixtures = {
+  gqlClient: APIRequestContext;
+  adminGqlClient: APIRequestContext;
+};
+
+export const test = base.extend<GraphQLFixtures>({
+  gqlClient: async ({ playwright }, use) => {
+    const ctx = await playwright.request.newContext({
+      baseURL: "https://api.myapp.io",
+      extraHTTPHeaders: {
+        Authorization: `Bearer ${process.env.API_TOKEN}`,
+        "Content-Type": "application/json",
+      },
+    });
+    await use(ctx);
+    await ctx.dispose();
+  },
+
+  adminGqlClient: async ({ playwright }, use) => {
+    const loginCtx = await playwright.request.newContext({
+      baseURL: "https://api.myapp.io",
+    });
+    const loginResp = await loginCtx.post("/graphql", {
+      data: {
+        query: `
+          mutation Login($email: String!, $password: String!) {
+            login(email: $email, password: $password) { token }
+          }
+        `,
+        variables: {
+          email: process.env.ADMIN_EMAIL,
+          password: process.env.ADMIN_PASSWORD,
+        },
+      },
+    });
+    const { data } = await loginResp.json();
+    
+    if (!data?.login?.token) {
+      throw new Error(`Admin login failed: status ${loginResp.status()}, response: ${JSON.stringify(data)}`);
+    }
+    
+    await loginCtx.dispose();
+
+    const ctx = await playwright.request.newContext({
+      baseURL: "https://api.myapp.io",
+      extraHTTPHeaders: {
+        Authorization: `Bearer ${data.login.token}`,
+        "Content-Type": "application/json",
+      },
+    });
+    await use(ctx);
+    await ctx.dispose();
+  },
+});
+
+export { expect };
+```
+
+### GraphQL Helper Function
+
+```typescript
+// utils/graphql.ts
+import { APIRequestContext, expect } from "@playwright/test";
+
+export async function gqlQuery<T = any>(
+  request: APIRequestContext,
+  query: string,
+  variables?: Record<string, any>
+): Promise<{ data: T; errors?: any[] }> {
+  const resp = await request.post("/graphql", {
+    data: { query, variables },
+  });
+  expect(resp.ok()).toBeTruthy();
+  return resp.json();
+}
+
+export async function gqlMutation<T = any>(
+  request: APIRequestContext,
+  mutation: string,
+  variables?: Record<string, any>
+): Promise<{ data: T; errors?: any[] }> {
+  return gqlQuery<T>(request, mutation, variables);
+}
+```
+
+```typescript
+// tests/api/items.spec.ts
+import { test, expect } from "@playwright/test";
+import { gqlQuery, gqlMutation } from "../../utils/graphql";
+
+test("fetch and update item", async ({ request }) => {
+  const { data: fetchData } = await gqlQuery(
+    request,
+    `query GetItem($id: ID!) { item(id: $id) { id title } }`,
+    { id: "101" }
+  );
+  expect(fetchData.item.title).toBeDefined();
+
+  const { data: updateData, errors } = await gqlMutation(
+    request,
+    `mutation UpdateItem($id: ID!, $title: String!) {
+      updateItem(id: $id, title: $title) { id title }
+    }`,
+    { id: "101", title: "Updated Title" }
+  );
+  expect(errors).toBeUndefined();
+  expect(updateData.updateItem.title).toBe("Updated Title");
+});
+```
+
+## Anti-Patterns
+
+| Don't Do This | Problem | Do This Instead |
+| --- | --- | --- |
+| 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 |
+| Ignore `errors` array | Validation and auth errors appear in `errors`, not HTTP status | Destructure and assert: `expect(errors).toBeUndefined()` |
+| Hardcode query strings inline everywhere | Duplicated queries are hard to maintain | Extract queries to constants or use a helper function |
+| Skip variable validation | Invalid variables cause cryptic server errors | Validate input shape before sending |
+
+## Troubleshooting
+
+### GraphQL returns 200 but data is null
+
+**Cause**: GraphQL servers return HTTP 200 even when the query has errors. The actual error is in the `errors` array.
+
+**Fix**: Always destructure and check both `data` and `errors`.
+
+```typescript
+const { data, errors } = await resp.json();
+if (errors) {
+  console.error("GraphQL errors:", JSON.stringify(errors, null, 2));
+}
+expect(errors).toBeUndefined();
+expect(data.item).toBeDefined();
+```
+
+### "Cannot query field X on type Y"
+
+**Cause**: The field doesn't exist in the schema, or you're querying the wrong type.
+
+**Fix**: Verify the schema. Use introspection or check your GraphQL IDE for available fields.
+
+```typescript
+// Introspection query to debug schema
+const { data } = await request.post("/graphql", {
+  data: {
+    query: `{ __type(name: "Item") { fields { name type { name } } } }`,
+  },
+});
+console.log(data.__type.fields);
+```
+
+### Variables not being applied
+
+**Cause**: Variable names in the query don't match the `variables` object keys, or types don't match.
+
+**Fix**: Ensure variable names match exactly (case-sensitive) and types align with the schema.
+
+```typescript
+// Wrong: variable name mismatch
+const resp = await request.post("/graphql", {
+  data: {
+    query: `query GetItem($itemId: ID!) { item(id: $itemId) { id } }`,
+    variables: { id: "101" }, // Should be { itemId: "101" }
+  },
+});
+
+// Correct
+const resp = await request.post("/graphql", {
+  data: {
+    query: `query GetItem($itemId: ID!) { item(id: $itemId) { id } }`,
+    variables: { itemId: "101" },
+  },
+});
+```