1# API Testing
2 
3## Table of Contents
4 
51. [Patterns](#patterns)
62. [Decision Guide](#decision-guide)
73. [Anti-Patterns](#anti-patterns)
84. [Troubleshooting](#troubleshooting)
9 
10> **When to use**: Testing REST APIs directly — validating endpoints, seeding test data, or verifying backend behavior without browser overhead.
11> **See also**: [graphql-testing.md](graphql-testing.md) for GraphQL-specific patterns.
12 
13## Patterns
14 
15### Request Fixtures for Authenticated Clients
16 
17**Use when**: Multiple tests need an authenticated API client with shared configuration.
18**Avoid when**: A single test makes one-off API calls — use the built-in `request` fixture directly.
19 
20```typescript
21// fixtures/api-fixtures.ts
22import { test as base, expect, APIRequestContext } from "@playwright/test";
23 
24type ApiFixtures = {
25  authApi: APIRequestContext;
26  adminApi: APIRequestContext;
27};
28 
29export const test = base.extend<ApiFixtures>({
30  authApi: async ({ playwright }, use) => {
31    const ctx = await playwright.request.newContext({
32      baseURL: "https://api.myapp.io",
33      extraHTTPHeaders: {
34        Authorization: `Bearer ${process.env.API_TOKEN}`,
35        Accept: "application/json",
36      },
37    });
38    await use(ctx);
39    await ctx.dispose();
40  },
41 
42  adminApi: async ({ playwright }, use) => {
43    const loginCtx = await playwright.request.newContext({
44      baseURL: "https://api.myapp.io",
45    });
46    const loginResp = await loginCtx.post("/auth/login", {
47      data: {
48        email: process.env.ADMIN_EMAIL,
49        password: process.env.ADMIN_PASSWORD,
50      },
51    });
52    expect(loginResp.ok()).toBeTruthy();
53    const { token } = await loginResp.json();
54    await loginCtx.dispose();
55 
56    const ctx = await playwright.request.newContext({
57      baseURL: "https://api.myapp.io",
58      extraHTTPHeaders: {
59        Authorization: `Bearer ${token}`,
60        Accept: "application/json",
61      },
62    });
63    await use(ctx);
64    await ctx.dispose();
65  },
66});
67 
68export { expect };
69```
70 
71```typescript
72// tests/api/admin.spec.ts
73import { test, expect } from "../../fixtures/api-fixtures";
74 
75test("admin retrieves all accounts", async ({ adminApi }) => {
76  const resp = await adminApi.get("/admin/accounts");
77  expect(resp.status()).toBe(200);
78  const body = await resp.json();
79  expect(body.accounts.length).toBeGreaterThan(0);
80});
81```
82 
83### CRUD Operations
84 
85**Use when**: Making HTTP requests — GET, POST, PUT, PATCH, DELETE with headers, query params, and bodies.
86**Avoid when**: You need to test browser-rendered responses (redirects, cookies with `HttpOnly`).
87 
88```typescript
89import { test, expect } from "@playwright/test";
90 
91test("full CRUD cycle", async ({ request }) => {
92  // GET with query params
93  const listResp = await request.get("/api/items", {
94    params: { page: 1, limit: 10, category: "tools" },
95  });
96  expect(listResp.ok()).toBeTruthy();
97 
98  // POST with JSON body
99  const createResp = await request.post("/api/items", {
100    data: {
101      title: "Hammer",
102      price: 19.99,
103      category: "tools",
104    },
105  });
106  expect(createResp.status()).toBe(201);
107  const created = await createResp.json();
108 
109  // PUT — full replacement
110  const putResp = await request.put(`/api/items/${created.id}`, {
111    data: {
112      title: "Claw Hammer",
113      price: 24.99,
114      category: "tools",
115    },
116  });
117  expect(putResp.ok()).toBeTruthy();
118 
119  // PATCH — partial update
120  const patchResp = await request.patch(`/api/items/${created.id}`, {
121    data: { price: 22.5 },
122  });
123  expect(patchResp.ok()).toBeTruthy();
124  const patched = await patchResp.json();
125  expect(patched.price).toBe(22.5);
126 
127  // DELETE
128  const delResp = await request.delete(`/api/items/${created.id}`);
129  expect(delResp.status()).toBe(204);
130 
131  // Verify deletion
132  const getDeleted = await request.get(`/api/items/${created.id}`);
133  expect(getDeleted.status()).toBe(404);
134});
135 
136test("form-urlencoded body", async ({ request }) => {
137  const resp = await request.post("/oauth/token", {
138    form: {
139      grant_type: "client_credentials",
140      client_id: "my-client",
141      client_secret: "secret-value",
142    },
143  });
144  expect(resp.ok()).toBeTruthy();
145  const token = await resp.json();
146  expect(token).toHaveProperty("access_token");
147});
148```
149 
150### Dedicated API Project Configuration
151 
152**Use when**: Writing dedicated API test suites that do not need a browser.
153 
154```typescript
155// playwright.config.ts
156import { defineConfig } from "@playwright/test";
157 
158export default defineConfig({
159  projects: [
160    {
161      name: "api",
162      testDir: "./tests/api",
163      use: {
164        baseURL: "https://api.myapp.io",
165        extraHTTPHeaders: { Accept: "application/json" },
166      },
167    },
168    {
169      name: "e2e",
170      testDir: "./tests/e2e",
171      use: {
172        baseURL: "https://myapp.io",
173        browserName: "chromium",
174      },
175    },
176  ],
177});
178```
179 
180### Response Assertions
181 
182**Use when**: Validating response status, headers, and body structure.
183**Avoid when**: Never skip these — every API test should assert on status and body.
184 
185```typescript
186import { test, expect } from "@playwright/test";
187 
188test("comprehensive response validation", async ({ request }) => {
189  const resp = await request.get("/api/items/101");
190 
191  // Status code — always check first
192  expect(resp.status()).toBe(200);
193  expect(resp.ok()).toBeTruthy();
194 
195  // Headers
196  expect(resp.headers()["content-type"]).toContain("application/json");
197  expect(resp.headers()["cache-control"]).toMatch(/max-age=\d+/);
198 
199  const item = await resp.json();
200 
201  // Exact match on known fields
202  expect(item.id).toBe(101);
203  expect(item.title).toBe("Widget");
204 
205  // Partial match — ignore fields you don't care about
206  expect(item).toMatchObject({
207    id: 101,
208    title: "Widget",
209    status: expect.stringMatching(/^(active|inactive|archived)$/),
210  });
211 
212  // Type checks
213  expect(item).toMatchObject({
214    id: expect.any(Number),
215    title: expect.any(String),
216    createdAt: expect.any(String),
217    tags: expect.any(Array),
218  });
219 
220  // Array content
221  expect(item.tags).toEqual(expect.arrayContaining(["featured"]));
222  expect(item.tags).not.toContain("deprecated");
223 
224  // Nested object
225  expect(item.metadata).toMatchObject({
226    views: expect.any(Number),
227    rating: expect.any(Number),
228  });
229 
230  // Date format
231  expect(new Date(item.createdAt).toISOString()).toBe(item.createdAt);
232});
233 
234test("list response structure", async ({ request }) => {
235  const resp = await request.get("/api/items");
236  const body = await resp.json();
237 
238  expect(body.items).toHaveLength(10);
239 
240  for (const item of body.items) {
241    expect(item).toMatchObject({
242      id: expect.any(Number),
243      title: expect.any(String),
244      price: expect.any(Number),
245    });
246  }
247 
248  expect(body.pagination).toEqual({
249    page: 1,
250    limit: 10,
251    total: expect.any(Number),
252    totalPages: expect.any(Number),
253  });
254});
255```
256 
257### API Data Seeding
258 
259**Use when**: E2E tests need specific data to exist before running. API seeding is 10-100x faster than UI-based setup.
260**Avoid when**: The test specifically validates the creation flow through the UI.
261 
262```typescript
263import { test as base, expect } from "@playwright/test";
264 
265type SeedFixtures = {
266  seedAccount: { id: number; email: string; password: string };
267  seedWorkspace: { id: number; name: string };
268};
269 
270export const test = base.extend<SeedFixtures>({
271  seedAccount: async ({ request }, use) => {
272    const email = `account-${Date.now()}@test.io`;
273    const password = "SecurePass123!";
274 
275    const resp = await request.post("/api/accounts", {
276      data: { name: "Test Account", email, password },
277    });
278    expect(resp.ok()).toBeTruthy();
279    const account = await resp.json();
280 
281    await use({ id: account.id, email, password });
282 
283    // Cleanup
284    await request.delete(`/api/accounts/${account.id}`);
285  },
286 
287  seedWorkspace: async ({ request, seedAccount }, use) => {
288    const resp = await request.post("/api/workspaces", {
289      data: { name: `Workspace ${Date.now()}`, ownerId: seedAccount.id },
290    });
291    expect(resp.ok()).toBeTruthy();
292    const workspace = await resp.json();
293 
294    await use({ id: workspace.id, name: workspace.name });
295 
296    await request.delete(`/api/workspaces/${workspace.id}`);
297  },
298});
299 
300export { expect };
301```
302 
303```typescript
304// tests/e2e/workspace-dashboard.spec.ts
305import { test, expect } from "../../fixtures/seed-fixtures";
306 
307test("user sees workspace on dashboard", async ({
308  page,
309  seedAccount,
310  seedWorkspace,
311}) => {
312  await page.goto("/login");
313  await page.getByLabel("Email").fill(seedAccount.email);
314  await page.getByLabel("Password").fill(seedAccount.password);
315  await page.getByRole("button", { name: "Sign in" }).click();
316 
317  await page.waitForURL("/dashboard");
318  await expect(
319    page.getByRole("heading", { name: seedWorkspace.name })
320  ).toBeVisible();
321});
322```
323 
324### Error Response Testing
325 
326**Use when**: Every API has error paths — test them. A missing 401 test today is a security hole tomorrow.
327 
328```typescript
329import { test, expect } from "@playwright/test";
330 
331test.describe("Error responses", () => {
332  test("400 — validation error with details", async ({ request }) => {
333    const resp = await request.post("/api/items", {
334      data: { title: "", price: -5 },
335    });
336    expect(resp.status()).toBe(400);
337 
338    const body = await resp.json();
339    expect(body).toMatchObject({
340      error: "Validation Error",
341      details: expect.any(Array),
342    });
343    expect(body.details).toEqual(
344      expect.arrayContaining([
345        expect.objectContaining({
346          field: "title",
347          message: expect.any(String),
348        }),
349        expect.objectContaining({
350          field: "price",
351          message: expect.any(String),
352        }),
353      ])
354    );
355  });
356 
357  test("401 — missing authentication", async ({ request }) => {
358    const resp = await request.get("/api/protected/resource", {
359      headers: { Authorization: "" },
360    });
361    expect(resp.status()).toBe(401);
362    const body = await resp.json();
363    expect(body.error).toMatch(/unauthorized|unauthenticated/i);
364  });
365 
366  test("403 — insufficient permissions", async ({ request }) => {
367    const resp = await request.delete("/api/admin/items/1");
368    expect(resp.status()).toBe(403);
369    const body = await resp.json();
370    expect(body.error).toMatch(/forbidden|insufficient permissions/i);
371  });
372 
373  test("404 — resource not found", async ({ request }) => {
374    const resp = await request.get("/api/items/999999");
375    expect(resp.status()).toBe(404);
376    const body = await resp.json();
377    expect(body).toMatchObject({ error: expect.stringMatching(/not found/i) });
378  });
379 
380  test("409 — conflict on duplicate", async ({ request }) => {
381    const sku = `SKU-${Date.now()}`;
382    await request.post("/api/items", { data: { title: "First", sku } });
383 
384    const resp = await request.post("/api/items", {
385      data: { title: "Duplicate", sku },
386    });
387    expect(resp.status()).toBe(409);
388  });
389 
390  test("422 — unprocessable entity", async ({ request }) => {
391    const resp = await request.post("/api/orders", {
392      data: { items: [] },
393    });
394    expect(resp.status()).toBe(422);
395    const body = await resp.json();
396    expect(body.error).toContain("at least one item");
397  });
398 
399  test("429 — rate limiting", async ({ request }) => {
400    const responses = await Promise.all(
401      Array.from({ length: 50 }, () =>
402        request.get("/api/search", { params: { q: "test" } })
403      )
404    );
405    const rateLimited = responses.filter((r) => r.status() === 429);
406    expect(rateLimited.length).toBeGreaterThan(0);
407    expect(rateLimited[0].headers()["retry-after"]).toBeDefined();
408  });
409});
410```
411 
412### File Upload via API
413 
414**Use when**: Testing file upload endpoints with multipart form data.
415**Avoid when**: You need to test the browser file picker dialog — use `page.setInputFiles()` instead.
416 
417```typescript
418import { test, expect } from "@playwright/test";
419import path from "path";
420import fs from "fs";
421 
422test("upload file via multipart", async ({ request }) => {
423  const filePath = path.resolve("tests/fixtures/report.pdf");
424 
425  const resp = await request.post("/api/documents/upload", {
426    multipart: {
427      file: {
428        name: "report.pdf",
429        mimeType: "application/pdf",
430        buffer: fs.readFileSync(filePath),
431      },
432      description: "Monthly report",
433      category: "reports",
434    },
435  });
436 
437  expect(resp.status()).toBe(201);
438  const body = await resp.json();
439  expect(body).toMatchObject({
440    id: expect.any(String),
441    filename: "report.pdf",
442    mimeType: "application/pdf",
443    size: expect.any(Number),
444    url: expect.stringMatching(/^https:\/\//),
445  });
446});
447 
448test("rejects oversized files", async ({ request }) => {
449  const largeBuffer = Buffer.alloc(11 * 1024 * 1024); // 11MB
450 
451  const resp = await request.post("/api/documents/upload", {
452    multipart: {
453      file: {
454        name: "large-file.bin",
455        mimeType: "application/octet-stream",
456        buffer: largeBuffer,
457      },
458    },
459  });
460 
461  expect(resp.status()).toBe(413);
462});
463```
464 
465### Chained API Calls
466 
467**Use when**: Testing multi-step workflows — create, read, update, delete sequences; order flows; state machine transitions.
468**Avoid when**: You can test each endpoint in isolation and the interactions are trivial.
469 
470```typescript
471import { test, expect } from "@playwright/test";
472 
473test("complete order workflow", async ({ request }) => {
474  // Step 1: Create a product
475  const productResp = await request.post("/api/products", {
476    data: { name: "Gadget", price: 49.99, stock: 50 },
477  });
478  expect(productResp.status()).toBe(201);
479  const product = await productResp.json();
480 
481  // Step 2: Create a cart
482  const cartResp = await request.post("/api/carts", {
483    data: { items: [{ productId: product.id, quantity: 3 }] },
484  });
485  expect(cartResp.status()).toBe(201);
486  const cart = await cartResp.json();
487  expect(cart.total).toBe(149.97);
488 
489  // Step 3: Checkout
490  const orderResp = await request.post("/api/orders", {
491    data: {
492      cartId: cart.id,
493      shippingAddress: {
494        street: "456 Main Ave",
495        city: "Metropolis",
496        zip: "54321",
497      },
498    },
499  });
500  expect(orderResp.status()).toBe(201);
501  const order = await orderResp.json();
502  expect(order.status).toBe("pending");
503  expect(order.items).toHaveLength(1);
504 
505  // Step 4: Verify order in list
506  const ordersResp = await request.get("/api/orders");
507  const orders = await ordersResp.json();
508  expect(orders.items.map((o: any) => o.id)).toContain(order.id);
509 
510  // Step 5: Verify stock decreased
511  const updatedProduct = await (
512    await request.get(`/api/products/${product.id}`)
513  ).json();
514  expect(updatedProduct.stock).toBe(47);
515 
516  // Cleanup
517  await request.delete(`/api/orders/${order.id}`);
518  await request.delete(`/api/products/${product.id}`);
519});
520 
521test("state machine transitions — publish workflow", async ({ request }) => {
522  const createResp = await request.post("/api/articles", {
523    data: { title: "Draft Article", body: "Content here." },
524  });
525  const article = await createResp.json();
526  expect(article.status).toBe("draft");
527 
528  // Submit for review
529  const reviewResp = await request.patch(`/api/articles/${article.id}/status`, {
530    data: { status: "in_review" },
531  });
532  expect(reviewResp.ok()).toBeTruthy();
533  expect((await reviewResp.json()).status).toBe("in_review");
534 
535  // Approve
536  const approveResp = await request.patch(
537    `/api/articles/${article.id}/status`,
538    {
539      data: { status: "published" },
540    }
541  );
542  expect(approveResp.ok()).toBeTruthy();
543  expect((await approveResp.json()).status).toBe("published");
544 
545  // Cannot revert to draft from published
546  const revertResp = await request.patch(`/api/articles/${article.id}/status`, {
547    data: { status: "draft" },
548  });
549  expect(revertResp.status()).toBe(422);
550 
551  await request.delete(`/api/articles/${article.id}`);
552});
553 
554test("API + E2E hybrid — seed via API, verify in browser", async ({
555  request,
556  page,
557}) => {
558  const resp = await request.post("/api/products", {
559    data: {
560      name: `Hybrid Product ${Date.now()}`,
561      price: 35.0,
562      published: true,
563    },
564  });
565  const product = await resp.json();
566 
567  await page.goto("/products");
568  await expect(page.getByRole("heading", { name: product.name })).toBeVisible();
569  await expect(page.getByText("$35.00")).toBeVisible();
570 
571  await request.delete(`/api/products/${product.id}`);
572});
573```
574 
575### Schema Validation with Zod
576 
577**Use when**: Verifying API responses match a contract — field types, required fields, value constraints.
578**Avoid when**: You only need to check one or two specific fields — use `toMatchObject` instead.
579 
580```typescript
581import { test, expect } from "@playwright/test";
582import { z } from "zod";
583 
584const ItemSchema = z.object({
585  id: z.number().positive(),
586  title: z.string().min(1),
587  price: z.number().nonnegative(),
588  status: z.enum(["active", "inactive", "archived"]),
589  createdAt: z.string().datetime(),
590  metadata: z.object({
591    views: z.number().int().nonnegative(),
592    rating: z.number().min(0).max(5).nullable(),
593  }),
594});
595 
596const PaginatedItemsSchema = z.object({
597  items: z.array(ItemSchema),
598  pagination: z.object({
599    page: z.number().int().positive(),
600    limit: z.number().int().positive(),
601    total: z.number().int().nonnegative(),
602  }),
603});
604 
605test("GET /api/items matches schema", async ({ request }) => {
606  const resp = await request.get("/api/items");
607  expect(resp.ok()).toBeTruthy();
608 
609  const body = await resp.json();
610  const result = PaginatedItemsSchema.safeParse(body);
611 
612  if (!result.success) {
613    throw new Error(
614      `Schema validation failed:\n${result.error.issues
615        .map((i) => `  ${i.path.join(".")}: ${i.message}`)
616        .join("\n")}`
617    );
618  }
619});
620```
621 
622## Decision Guide
623 
624| Scenario                                         | Use API Tests               | Use E2E Tests                  | Why                                                                |
625| ------------------------------------------------ | --------------------------- | ------------------------------ | ------------------------------------------------------------------ |
626| Validate response status/body/headers            | Yes                         | No                             | No browser needed; 10-100x faster                                  |
627| Test business logic (calculations, rules)        | Yes                         | No                             | API tests isolate backend logic from UI                            |
628| Verify form submission creates correct data      | Seed via API, submit via UI | Yes                            | UI test validates the form; API check confirms persistence         |
629| Test error messages shown to user                | No                          | Yes                            | Error rendering is a UI concern                                    |
630| Validate pagination, filtering, sorting          | Yes                         | Maybe both                     | API test for correctness; E2E test only if the UI logic is complex |
631| Seed test data for E2E tests                     | Yes (fixture)               | No                             | API seeding is fast and reliable                                   |
632| Test auth flows (login/logout/RBAC)              | Yes for token/session logic | Yes for UI flow                | Both matter: API protects resources, UI guides users               |
633| Verify file upload processing                    | Yes                         | Only if testing file picker UI | API test validates backend processing                              |
634| Contract/schema regression testing               | Yes                         | No                             | Schema tests run in milliseconds                                   |
635| Test third-party webhook handling                | Yes                         | No                             | Webhooks are API-to-API; no UI involved                            |
636| Verify redirect behavior after action            | No                          | Yes                            | Redirects are browser/navigation concerns                          |
637| Test real-time updates (WebSocket + API trigger) | API triggers                | E2E verifies                   | Seed via API, observe in browser                                   |
638 
639## Anti-Patterns
640 
641| Don't Do This                                        | Problem                                                                                | Do This Instead                                                   |
642| ---------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
643| Use E2E tests to validate pure API responses         | Slow, flaky, launches a browser for no reason                                          | Use `request` fixture — no browser, direct HTTP                   |
644| Ignore `response.status()`                           | A 500 with a fallback body can pass all body assertions                                | Always assert status first: `expect(response.status()).toBe(200)` |
645| Skip response header checks                          | Missing `Content-Type`, `Cache-Control`, CORS headers cause production bugs            | Assert critical headers                                           |
646| Only test the happy path                             | Real users trigger 400, 401, 403, 404, 409, 422 — every one needs a test               | Dedicate a `describe` block to error responses                    |
647| Hardcode IDs in API tests                            | Tests break when database is reset or IDs are reassigned                               | Create resources in the test, use returned IDs                    |
648| Share mutable state between tests                    | Tests that depend on execution order are flaky and cannot run in parallel              | Each test creates and cleans up its own data                      |
649| Parse `response.text()` then `JSON.parse()` manually | Playwright's `response.json()` handles this and throws clear errors on non-JSON        | Use `await response.json()`                                       |
650| Forget cleanup after creating resources              | Test pollution: subsequent tests may see stale data or hit unique constraints          | Use fixtures with teardown or explicit `delete` calls             |
651| Use `page.request` when you don't need a page        | `page.request` shares cookies with the browser context, which may cause auth confusion | Use the standalone `request` fixture for pure API tests           |
652 
653## Troubleshooting
654 
655### "Request failed: connect ECONNREFUSED 127.0.0.1:3000"
656 
657**Cause**: The API server is not running, or `baseURL` points to the wrong host/port.
658 
659**Fix**: Verify the server is running before tests. Use `webServer` in config to start it automatically.
660 
661```typescript
662// playwright.config.ts
663export default defineConfig({
664  webServer: {
665    command: "npm run start:api",
666    url: "http://localhost:3000/api/health",
667    reuseExistingServer: !process.env.CI,
668  },
669  use: { baseURL: "http://localhost:3000" },
670});
671```
672 
673### "response.json() failed — body is not valid JSON"
674 
675**Cause**: The endpoint returned HTML (error page), plain text, or an empty body instead of JSON.
676 
677**Fix**: Check `response.status()` first — a 500 or 302 often returns HTML. Log `await response.text()` to see the actual body. Verify the `Accept: application/json` header is set.
678 
679```typescript
680const resp = await request.get("/api/endpoint");
681if (!resp.ok()) {
682  console.error(`Status: ${resp.status()}, Body: ${await resp.text()}`);
683}
684const body = await resp.json();
685```
686 
687### "401 Unauthorized" when using `request` fixture
688 
689**Cause**: The built-in `request` fixture does not carry browser cookies or auth tokens automatically.
690 
691**Fix**: Set `extraHTTPHeaders` in config or create a custom authenticated fixture. If you need cookies from a browser login, use `page.request` instead.
692 
693```typescript
694// Option A: config-level headers
695export default defineConfig({
696  use: {
697    extraHTTPHeaders: { Authorization: `Bearer ${process.env.API_TOKEN}` },
698  },
699});
700 
701// Option B: per-request headers
702const resp = await request.get("/api/resource", {
703  headers: { Authorization: `Bearer ${token}` },
704});
705 
706// Option C: use page.request to inherit browser cookies
707test("API call with browser auth", async ({ page }) => {
708  await page.goto("/login");
709  // ... login via UI ...
710  const resp = await page.request.get("/api/profile");
711  expect(resp.ok()).toBeTruthy();
712});
713```
714 
715### Tests pass locally but fail in CI
716 
717**Cause**: Different environments, database state, or missing environment variables.
718 
719**Fix**: Use `process.env` for secrets and base URLs. Run database seeds or migrations in `globalSetup`. Use unique identifiers (timestamps, UUIDs) for test data. Check that the CI `baseURL` matches the deployed service.
720