# API Testing

> **When to use**: Testing REST or GraphQL APIs directly — validating endpoints, seeding test data, or verifying backend behavior without browser overhead.
> **Prerequisites**: [core/configuration.md](configuration.md) for `baseURL` setup, [core/fixtures-and-hooks.md](fixtures-and-hooks.md) for custom fixture patterns.

## Quick Reference

```typescript
// Standalone API test — no browser launched
import { test, expect } from "@playwright/test"

test("GET /api/users returns user list", async ({ request }) => {
  const response = await request.get("/api/users")
  expect(response.status()).toBe(200)
  expect(response.headers()["content-type"]).toContain("application/json")
  const body = await response.json()
  expect(body.users).toHaveLength(3)
  expect(body.users[0]).toMatchObject({ id: expect.any(Number), email: expect.any(String) })
})
```

## Patterns

### APIRequestContext Basics

**Use when**: Making HTTP requests in any test — GET, POST, PUT, PATCH, DELETE with headers, query params, and request bodies.
**Avoid when**: You need to test browser-rendered responses (redirects, cookies set via `Set-Cookie` with `HttpOnly`). Use a browser test instead.

The `request` fixture provides a pre-configured `APIRequestContext` that inherits `baseURL` from your config. No browser is launched.

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"

test("CRUD operations via API", async ({ request }) => {
  // GET with query parameters
  const listResponse = await request.get("/api/users", {
    params: { page: 1, limit: 10, role: "admin" },
  })
  expect(listResponse.ok()).toBeTruthy()

  // POST with JSON body
  const createResponse = await request.post("/api/users", {
    data: {
      name: "Jane Doe",
      email: "jane@example.com",
      role: "editor",
    },
  })
  expect(createResponse.status()).toBe(201)
  const created = await createResponse.json()

  // PUT — full replacement
  const updateResponse = await request.put(`/api/users/${created.id}`, {
    data: {
      name: "Jane Smith",
      email: "jane.smith@example.com",
      role: "editor",
    },
  })
  expect(updateResponse.ok()).toBeTruthy()

  // PATCH — partial update
  const patchResponse = await request.patch(`/api/users/${created.id}`, {
    data: { role: "admin" },
  })
  expect(patchResponse.ok()).toBeTruthy()
  const patched = await patchResponse.json()
  expect(patched.role).toBe("admin")

  // DELETE
  const deleteResponse = await request.delete(`/api/users/${created.id}`)
  expect(deleteResponse.status()).toBe(204)

  // Verify deletion
  const getDeleted = await request.get(`/api/users/${created.id}`)
  expect(getDeleted.status()).toBe(404)
})

test("custom headers and auth tokens", async ({ request }) => {
  const response = await request.get("/api/protected/resource", {
    headers: {
      Authorization: "Bearer eyJhbGciOiJIUzI1NiIs...",
      "X-Request-ID": "test-correlation-id-123",
      Accept: "application/json",
    },
  })
  expect(response.ok()).toBeTruthy()
})

test("form-urlencoded body", async ({ request }) => {
  const response = await request.post("/api/oauth/token", {
    form: {
      grant_type: "client_credentials",
      client_id: "my-app",
      client_secret: "secret-value",
    },
  })
  expect(response.ok()).toBeTruthy()
  const token = await response.json()
  expect(token).toHaveProperty("access_token")
})
```

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

test("CRUD operations via API", async ({ request }) => {
  const listResponse = await request.get("/api/users", {
    params: { page: 1, limit: 10, role: "admin" },
  })
  expect(listResponse.ok()).toBeTruthy()

  const createResponse = await request.post("/api/users", {
    data: {
      name: "Jane Doe",
      email: "jane@example.com",
      role: "editor",
    },
  })
  expect(createResponse.status()).toBe(201)
  const created = await createResponse.json()

  const updateResponse = await request.put(`/api/users/${created.id}`, {
    data: {
      name: "Jane Smith",
      email: "jane.smith@example.com",
      role: "editor",
    },
  })
  expect(updateResponse.ok()).toBeTruthy()

  const patchResponse = await request.patch(`/api/users/${created.id}`, {
    data: { role: "admin" },
  })
  expect(patchResponse.ok()).toBeTruthy()

  const deleteResponse = await request.delete(`/api/users/${created.id}`)
  expect(deleteResponse.status()).toBe(204)
})

test("form-urlencoded body", async ({ request }) => {
  const response = await request.post("/api/oauth/token", {
    form: {
      grant_type: "client_credentials",
      client_id: "my-app",
      client_secret: "secret-value",
    },
  })
  expect(response.ok()).toBeTruthy()
  const token = await response.json()
  expect(token).toHaveProperty("access_token")
})
```

### API Test Structure

**Use when**: Writing dedicated API test suites that do not need a browser.
**Avoid when**: You need to assert on UI state after an API call — use a combined test with `page` and `request` fixtures.

Structure API tests in their own directory with descriptive `describe` blocks per resource or domain.

**TypeScript**

```typescript
// tests/api/users.spec.ts
import { test, expect } from "@playwright/test"

// No browser is launched — these tests use only the request fixture
test.describe("Users API", () => {
  test.describe("GET /api/users", () => {
    test("returns paginated user list", async ({ request }) => {
      const response = await request.get("/api/users", {
        params: { page: 1, limit: 5 },
      })
      expect(response.status()).toBe(200)
      const body = await response.json()
      expect(body.users.length).toBeLessThanOrEqual(5)
      expect(body.pagination).toMatchObject({
        page: 1,
        limit: 5,
        total: expect.any(Number),
      })
    })

    test("filters by role", async ({ request }) => {
      const response = await request.get("/api/users", {
        params: { role: "admin" },
      })
      const body = await response.json()
      for (const user of body.users) {
        expect(user.role).toBe("admin")
      }
    })
  })

  test.describe("POST /api/users", () => {
    test("creates a new user with valid data", async ({ request }) => {
      const response = await request.post("/api/users", {
        data: { name: "Test User", email: `test-${Date.now()}@example.com` },
      })
      expect(response.status()).toBe(201)
      const user = await response.json()
      expect(user).toMatchObject({
        id: expect.any(Number),
        name: "Test User",
      })
    })

    test("rejects duplicate email", async ({ request }) => {
      const email = `dupe-${Date.now()}@example.com`
      await request.post("/api/users", { data: { name: "First", email } })

      const response = await request.post("/api/users", {
        data: { name: "Second", email },
      })
      expect(response.status()).toBe(409)
      const body = await response.json()
      expect(body.error).toContain("already exists")
    })
  })
})
```

**JavaScript**

```javascript
// tests/api/users.spec.js
const { test, expect } = require("@playwright/test")

test.describe("Users API", () => {
  test.describe("GET /api/users", () => {
    test("returns paginated user list", async ({ request }) => {
      const response = await request.get("/api/users", {
        params: { page: 1, limit: 5 },
      })
      expect(response.status()).toBe(200)
      const body = await response.json()
      expect(body.users.length).toBeLessThanOrEqual(5)
      expect(body.pagination).toMatchObject({
        page: 1,
        limit: 5,
        total: expect.any(Number),
      })
    })
  })

  test.describe("POST /api/users", () => {
    test("creates a new user with valid data", async ({ request }) => {
      const response = await request.post("/api/users", {
        data: { name: "Test User", email: `test-${Date.now()}@example.com` },
      })
      expect(response.status()).toBe(201)
      const user = await response.json()
      expect(user).toMatchObject({
        id: expect.any(Number),
        name: "Test User",
      })
    })
  })
})
```

**Config tip**: Use a dedicated project for API tests to avoid launching browsers.

```typescript
// playwright.config.ts — API project runs without a browser
import { defineConfig } from "@playwright/test"

export default defineConfig({
  projects: [
    {
      name: "api",
      testDir: "./tests/api",
      use: {
        baseURL: "https://api.example.com",
        extraHTTPHeaders: {
          Accept: "application/json",
        },
      },
    },
    {
      name: "e2e",
      testDir: "./tests/e2e",
      use: {
        baseURL: "https://app.example.com",
        browserName: "chromium",
      },
    },
  ],
})
```

### Request Fixtures

**Use when**: Multiple tests need an authenticated API client, or you want to share request configuration (headers, base URL, auth tokens) across a test suite.
**Avoid when**: A single test makes one-off API calls. Use the built-in `request` fixture directly.

**TypeScript**

```typescript
// fixtures/api-fixtures.ts
import { test as base, expect, APIRequestContext } from "@playwright/test"

type ApiFixtures = {
  authenticatedRequest: APIRequestContext
  adminRequest: APIRequestContext
}

export const test = base.extend<ApiFixtures>({
  authenticatedRequest: async ({ playwright }, use) => {
    // Create a fresh context with auth headers
    const context = await playwright.request.newContext({
      baseURL: "https://api.example.com",
      extraHTTPHeaders: {
        Authorization: `Bearer ${process.env.API_TOKEN}`,
        Accept: "application/json",
      },
    })
    await use(context)
    await context.dispose()
  },

  adminRequest: async ({ playwright }, use) => {
    // Login via API to get a token, then create authenticated context
    const loginContext = await playwright.request.newContext({
      baseURL: "https://api.example.com",
    })
    const loginResponse = await loginContext.post("/api/auth/login", {
      data: {
        email: process.env.ADMIN_EMAIL,
        password: process.env.ADMIN_PASSWORD,
      },
    })
    expect(loginResponse.ok()).toBeTruthy()
    const { token } = await loginResponse.json()
    await loginContext.dispose()

    const context = await playwright.request.newContext({
      baseURL: "https://api.example.com",
      extraHTTPHeaders: {
        Authorization: `Bearer ${token}`,
        Accept: "application/json",
      },
    })
    await use(context)
    await context.dispose()
  },
})

export { expect }
```

```typescript
// tests/api/admin.spec.ts
import { test, expect } from "../../fixtures/api-fixtures"

test("admin can list all users", async ({ adminRequest }) => {
  const response = await adminRequest.get("/api/admin/users")
  expect(response.status()).toBe(200)
  const body = await response.json()
  expect(body.users.length).toBeGreaterThan(0)
})

test("admin can delete a user", async ({ adminRequest }) => {
  // Create then delete
  const createResp = await adminRequest.post("/api/users", {
    data: { name: "To Delete", email: `del-${Date.now()}@example.com` },
  })
  const { id } = await createResp.json()

  const deleteResp = await adminRequest.delete(`/api/users/${id}`)
  expect(deleteResp.status()).toBe(204)
})
```

**JavaScript**

```javascript
// fixtures/api-fixtures.js
const { test: base, expect } = require("@playwright/test")

const test = base.extend({
  authenticatedRequest: async ({ playwright }, use) => {
    const context = await playwright.request.newContext({
      baseURL: "https://api.example.com",
      extraHTTPHeaders: {
        Authorization: `Bearer ${process.env.API_TOKEN}`,
        Accept: "application/json",
      },
    })
    await use(context)
    await context.dispose()
  },

  adminRequest: async ({ playwright }, use) => {
    const loginContext = await playwright.request.newContext({
      baseURL: "https://api.example.com",
    })
    const loginResponse = await loginContext.post("/api/auth/login", {
      data: {
        email: process.env.ADMIN_EMAIL,
        password: process.env.ADMIN_PASSWORD,
      },
    })
    expect(loginResponse.ok()).toBeTruthy()
    const { token } = await loginResponse.json()
    await loginContext.dispose()

    const context = await playwright.request.newContext({
      baseURL: "https://api.example.com",
      extraHTTPHeaders: {
        Authorization: `Bearer ${token}`,
        Accept: "application/json",
      },
    })
    await use(context)
    await context.dispose()
  },
})

module.exports = { test, expect }
```

```javascript
// tests/api/admin.spec.js
const { test, expect } = require("../../fixtures/api-fixtures")

test("admin can list all users", async ({ adminRequest }) => {
  const response = await adminRequest.get("/api/admin/users")
  expect(response.status()).toBe(200)
  const body = await response.json()
  expect(body.users.length).toBeGreaterThan(0)
})
```

### JSON Response Assertions

**Use when**: Validating response status, headers, and body structure after every API call.
**Avoid when**: Never skip these. Every API test should assert on status and body.

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"

test("thorough response validation", async ({ request }) => {
  const response = await request.get("/api/users/42")

  // Status code — always check first
  expect(response.status()).toBe(200)

  // Status category — ok() checks 200-299 range
  expect(response.ok()).toBeTruthy()

  // Response headers
  expect(response.headers()["content-type"]).toContain("application/json")
  expect(response.headers()["x-request-id"]).toBeDefined()
  expect(response.headers()["cache-control"]).toMatch(/max-age=\d+/)

  // Full body parse and deep assertion
  const user = await response.json()

  // Exact match on known fields
  expect(user.id).toBe(42)
  expect(user.name).toBe("Jane Doe")
  expect(user.email).toBe("jane@example.com")

  // Partial match — ignore fields you don't care about
  expect(user).toMatchObject({
    id: 42,
    name: "Jane Doe",
    role: expect.stringMatching(/^(admin|editor|viewer)$/),
  })

  // Type checks with expect.any()
  expect(user).toMatchObject({
    id: expect.any(Number),
    name: expect.any(String),
    createdAt: expect.any(String),
    permissions: expect.any(Array),
  })

  // Array content
  expect(user.permissions).toEqual(expect.arrayContaining(["read", "write"]))
  expect(user.permissions).not.toContain("delete")

  // Nested object assertions
  expect(user.profile).toMatchObject({
    avatar: expect.stringMatching(/^https:\/\//),
    bio: expect.any(String),
  })

  // Date format validation
  expect(new Date(user.createdAt).toISOString()).toBe(user.createdAt)
})

test("list response structure", async ({ request }) => {
  const response = await request.get("/api/users")
  const body = await response.json()

  // Array length
  expect(body.users).toHaveLength(10)

  // Every item in array matches shape
  for (const user of body.users) {
    expect(user).toMatchObject({
      id: expect.any(Number),
      name: expect.any(String),
      email: expect.stringContaining("@"),
    })
  }

  // Pagination metadata
  expect(body.pagination).toEqual({
    page: 1,
    limit: 10,
    total: expect.any(Number),
    totalPages: expect.any(Number),
  })
})
```

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

test("thorough response validation", async ({ request }) => {
  const response = await request.get("/api/users/42")

  expect(response.status()).toBe(200)
  expect(response.ok()).toBeTruthy()
  expect(response.headers()["content-type"]).toContain("application/json")

  const user = await response.json()

  expect(user).toMatchObject({
    id: 42,
    name: "Jane Doe",
    role: expect.stringMatching(/^(admin|editor|viewer)$/),
  })

  expect(user).toMatchObject({
    id: expect.any(Number),
    name: expect.any(String),
    createdAt: expect.any(String),
    permissions: expect.any(Array),
  })

  expect(user.permissions).toEqual(expect.arrayContaining(["read", "write"]))
})

test("list response structure", async ({ request }) => {
  const response = await request.get("/api/users")
  const body = await response.json()

  expect(body.users).toHaveLength(10)
  for (const user of body.users) {
    expect(user).toMatchObject({
      id: expect.any(Number),
      name: expect.any(String),
      email: expect.stringContaining("@"),
    })
  }
})
```

### GraphQL Testing

**Use when**: Your backend exposes a GraphQL API and you want to test queries, mutations, variables, and error handling.
**Avoid when**: Your API is purely REST. Use the standard HTTP methods instead.

All GraphQL requests go through `POST` to a single endpoint. Send `query`, `variables`, and optionally `operationName` in the JSON body.

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"

const GRAPHQL_ENDPOINT = "/graphql"

test.describe("GraphQL API", () => {
  test("query with variables", async ({ request }) => {
    const response = await request.post(GRAPHQL_ENDPOINT, {
      data: {
        query: `
          query GetUser($id: ID!) {
            user(id: $id) {
              id
              name
              email
              posts {
                id
                title
              }
            }
          }
        `,
        variables: { id: "42" },
      },
    })

    expect(response.ok()).toBeTruthy()
    const { data, errors } = await response.json()

    // GraphQL returns 200 even on errors — always check both
    expect(errors).toBeUndefined()
    expect(data.user).toMatchObject({
      id: "42",
      name: expect.any(String),
      email: expect.stringContaining("@"),
    })
    expect(data.user.posts).toEqual(
      expect.arrayContaining([
        expect.objectContaining({ id: expect.any(String), title: expect.any(String) }),
      ])
    )
  })

  test("mutation creates a resource", async ({ request }) => {
    const response = await request.post(GRAPHQL_ENDPOINT, {
      data: {
        query: `
          mutation CreatePost($input: CreatePostInput!) {
            createPost(input: $input) {
              id
              title
              status
              author {
                id
              }
            }
          }
        `,
        variables: {
          input: {
            title: "API Testing with Playwright",
            body: "A comprehensive guide...",
            status: "DRAFT",
          },
        },
      },
    })

    const { data, errors } = await response.json()
    expect(errors).toBeUndefined()
    expect(data.createPost).toMatchObject({
      id: expect.any(String),
      title: "API Testing with Playwright",
      status: "DRAFT",
    })
  })

  test("handles GraphQL validation errors", async ({ request }) => {
    const response = await request.post(GRAPHQL_ENDPOINT, {
      data: {
        query: `
          mutation CreatePost($input: CreatePostInput!) {
            createPost(input: $input) {
              id
            }
          }
        `,
        variables: {
          input: { title: "" }, // invalid: empty title
        },
      },
    })

    // GraphQL often returns 200 even for validation errors
    const { data, errors } = await response.json()
    expect(errors).toBeDefined()
    expect(errors.length).toBeGreaterThan(0)
    expect(errors[0].message).toContain("title")
    expect(errors[0].extensions?.code).toBe("BAD_USER_INPUT")
  })

  test("handles authorization errors", async ({ request }) => {
    const response = await request.post(GRAPHQL_ENDPOINT, {
      data: {
        query: `
          query AdminDashboard {
            adminStats {
              totalRevenue
              activeUsers
            }
          }
        `,
      },
      // No auth header
    })

    const { data, errors } = await response.json()
    expect(errors).toBeDefined()
    expect(errors[0].extensions?.code).toBe("UNAUTHORIZED")
    expect(data?.adminStats).toBeNull()
  })
})
```

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

const GRAPHQL_ENDPOINT = "/graphql"

test.describe("GraphQL API", () => {
  test("query with variables", async ({ request }) => {
    const response = await request.post(GRAPHQL_ENDPOINT, {
      data: {
        query: `
          query GetUser($id: ID!) {
            user(id: $id) {
              id
              name
              email
            }
          }
        `,
        variables: { id: "42" },
      },
    })

    const { data, errors } = await response.json()
    expect(errors).toBeUndefined()
    expect(data.user).toMatchObject({
      id: "42",
      name: expect.any(String),
      email: expect.stringContaining("@"),
    })
  })

  test("mutation creates a resource", async ({ request }) => {
    const response = await request.post(GRAPHQL_ENDPOINT, {
      data: {
        query: `
          mutation CreatePost($input: CreatePostInput!) {
            createPost(input: $input) {
              id
              title
              status
            }
          }
        `,
        variables: {
          input: {
            title: "API Testing with Playwright",
            body: "A comprehensive guide...",
            status: "DRAFT",
          },
        },
      },
    })

    const { data, errors } = await response.json()
    expect(errors).toBeUndefined()
    expect(data.createPost).toMatchObject({
      id: expect.any(String),
      title: "API Testing with Playwright",
      status: "DRAFT",
    })
  })

  test("handles GraphQL validation errors", async ({ request }) => {
    const response = await request.post(GRAPHQL_ENDPOINT, {
      data: {
        query: `
          mutation CreatePost($input: CreatePostInput!) {
            createPost(input: $input) { id }
          }
        `,
        variables: { input: { title: "" } },
      },
    })

    const { data, errors } = await response.json()
    expect(errors).toBeDefined()
    expect(errors.length).toBeGreaterThan(0)
    expect(errors[0].message).toContain("title")
  })
})
```

### API Data Seeding

**Use when**: E2E tests need specific data to exist before running. API seeding is 10-100x faster than UI-based setup.
**Avoid when**: The test specifically validates the creation flow through the UI. Seed everything _except_ what you are testing.

**TypeScript**

```typescript
import { test as base, expect, APIRequestContext } from "@playwright/test"

// Fixture that seeds data via API before each test
type SeedFixtures = {
  seedUser: { id: number; email: string; password: string }
  seedProject: { id: number; name: string }
}

export const test = base.extend<SeedFixtures>({
  seedUser: async ({ request }, use) => {
    const email = `user-${Date.now()}@example.com`
    const password = "TestPass123!"

    // Create via API
    const response = await request.post("/api/users", {
      data: { name: "Test User", email, password },
    })
    expect(response.ok()).toBeTruthy()
    const user = await response.json()

    // Pass to test
    await use({ id: user.id, email, password })

    // Cleanup after test — always delete what you created
    await request.delete(`/api/users/${user.id}`)
  },

  seedProject: async ({ request, seedUser }, use) => {
    const response = await request.post("/api/projects", {
      data: { name: `Test Project ${Date.now()}`, ownerId: seedUser.id },
    })
    expect(response.ok()).toBeTruthy()
    const project = await response.json()

    await use({ id: project.id, name: project.name })

    await request.delete(`/api/projects/${project.id}`)
  },
})

export { expect }
```

```typescript
// tests/e2e/project-dashboard.spec.ts
import { test, expect } from "../../fixtures/seed-fixtures"

test("user sees their project on dashboard", async ({ page, seedUser, seedProject }) => {
  // Login via UI (or use storageState for speed)
  await page.goto("/login")
  await page.getByLabel("Email").fill(seedUser.email)
  await page.getByLabel("Password").fill(seedUser.password)
  await page.getByRole("button", { name: "Sign in" }).click()

  // Data already exists — go straight to assertion
  await page.waitForURL("/dashboard")
  await expect(page.getByRole("heading", { name: seedProject.name })).toBeVisible()
})
```

**JavaScript**

```javascript
// fixtures/seed-fixtures.js
const { test: base, expect } = require("@playwright/test")

const test = base.extend({
  seedUser: async ({ request }, use) => {
    const email = `user-${Date.now()}@example.com`
    const password = "TestPass123!"

    const response = await request.post("/api/users", {
      data: { name: "Test User", email, password },
    })
    expect(response.ok()).toBeTruthy()
    const user = await response.json()

    await use({ id: user.id, email, password })

    await request.delete(`/api/users/${user.id}`)
  },

  seedProject: async ({ request, seedUser }, use) => {
    const response = await request.post("/api/projects", {
      data: { name: `Test Project ${Date.now()}`, ownerId: seedUser.id },
    })
    expect(response.ok()).toBeTruthy()
    const project = await response.json()

    await use({ id: project.id, name: project.name })

    await request.delete(`/api/projects/${project.id}`)
  },
})

module.exports = { test, expect }
```

```javascript
// tests/e2e/project-dashboard.spec.js
const { test, expect } = require("../../fixtures/seed-fixtures")

test("user sees their project on dashboard", async ({ page, seedUser, seedProject }) => {
  await page.goto("/login")
  await page.getByLabel("Email").fill(seedUser.email)
  await page.getByLabel("Password").fill(seedUser.password)
  await page.getByRole("button", { name: "Sign in" }).click()

  await page.waitForURL("/dashboard")
  await expect(page.getByRole("heading", { name: seedProject.name })).toBeVisible()
})
```

### Schema Validation

**Use when**: Verifying that API responses match a contract — field types, required fields, value constraints. Catches backend regressions early.
**Avoid when**: You only need to check one or two specific fields. Use `toMatchObject` instead.

#### Option A: Zod (recommended for TypeScript projects)

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"
import { z } from "zod"

// Define schemas once, reuse across tests
const UserSchema = z.object({
  id: z.number().positive(),
  name: z.string().min(1),
  email: z.string().email(),
  role: z.enum(["admin", "editor", "viewer"]),
  createdAt: z.string().datetime(),
  profile: z.object({
    avatar: z.string().url().nullable(),
    bio: z.string().max(500),
  }),
})

const PaginatedUsersSchema = z.object({
  users: z.array(UserSchema),
  pagination: z.object({
    page: z.number().int().positive(),
    limit: z.number().int().positive(),
    total: z.number().int().nonnegative(),
  }),
})

test("GET /api/users matches schema", async ({ request }) => {
  const response = await request.get("/api/users")
  expect(response.ok()).toBeTruthy()

  const body = await response.json()
  const result = PaginatedUsersSchema.safeParse(body)

  if (!result.success) {
    // Detailed error output showing exactly which fields failed
    throw new Error(
      `Schema validation failed:\n${result.error.issues
        .map((i) => `  ${i.path.join(".")}: ${i.message}`)
        .join("\n")}`
    )
  }
})

test("POST /api/users returns valid user", async ({ request }) => {
  const response = await request.post("/api/users", {
    data: { name: "Schema Test", email: `schema-${Date.now()}@example.com` },
  })

  const body = await response.json()
  // Throws with detailed path info if validation fails
  UserSchema.parse(body)
})
```

#### Option B: Manual type checks (no dependencies)

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"

function assertUserShape(user: unknown): void {
  expect(user).toBeDefined()
  expect(user).toMatchObject({
    id: expect.any(Number),
    name: expect.any(String),
    email: expect.any(String),
    role: expect.any(String),
    createdAt: expect.any(String),
  })

  const u = user as Record<string, unknown>
  // Value constraints
  expect(["admin", "editor", "viewer"]).toContain(u.role)
  expect(typeof u.email === "string" && u.email.includes("@")).toBe(true)
  expect(new Date(u.createdAt as string).toString()).not.toBe("Invalid Date")
}

test("response matches expected shape", async ({ request }) => {
  const response = await request.get("/api/users/1")
  expect(response.ok()).toBeTruthy()

  const body = await response.json()
  assertUserShape(body)
})
```

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

function assertUserShape(user) {
  expect(user).toBeDefined()
  expect(user).toMatchObject({
    id: expect.any(Number),
    name: expect.any(String),
    email: expect.any(String),
    role: expect.any(String),
    createdAt: expect.any(String),
  })
  expect(["admin", "editor", "viewer"]).toContain(user.role)
  expect(user.email).toContain("@")
  expect(new Date(user.createdAt).toString()).not.toBe("Invalid Date")
}

test("response matches expected shape", async ({ request }) => {
  const response = await request.get("/api/users/1")
  expect(response.ok()).toBeTruthy()

  const body = await response.json()
  assertUserShape(body)
})
```

### Error Response Testing

**Use when**: Every API has error paths. Test them. A missing 401 test today is a security hole tomorrow.
**Avoid when**: Never skip error testing.

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"

test.describe("Error responses", () => {
  test("400 — validation error with details", async ({ request }) => {
    const response = await request.post("/api/users", {
      data: { name: "", email: "not-an-email" }, // invalid
    })
    expect(response.status()).toBe(400)

    const body = await response.json()
    expect(body).toMatchObject({
      error: "Validation Error",
      details: expect.any(Array),
    })
    // Check individual field errors
    expect(body.details).toEqual(
      expect.arrayContaining([
        expect.objectContaining({ field: "name", message: expect.any(String) }),
        expect.objectContaining({ field: "email", message: expect.any(String) }),
      ])
    )
  })

  test("401 — missing authentication", async ({ request }) => {
    // Create a fresh context with NO auth headers
    const response = await request.get("/api/protected/resource", {
      headers: { Authorization: "" }, // explicitly clear
    })
    expect(response.status()).toBe(401)

    const body = await response.json()
    expect(body.error).toMatch(/unauthorized|unauthenticated/i)
  })

  test("403 — insufficient permissions", async ({ request }) => {
    // Assuming `request` is authenticated as a viewer
    const response = await request.delete("/api/admin/users/1")
    expect(response.status()).toBe(403)

    const body = await response.json()
    expect(body.error).toMatch(/forbidden|insufficient permissions/i)
  })

  test("404 — resource not found", async ({ request }) => {
    const response = await request.get("/api/users/999999")
    expect(response.status()).toBe(404)

    const body = await response.json()
    expect(body).toMatchObject({
      error: expect.stringMatching(/not found/i),
    })
  })

  test("409 — conflict on duplicate resource", async ({ request }) => {
    const email = `conflict-${Date.now()}@example.com`
    await request.post("/api/users", {
      data: { name: "First", email },
    })

    const response = await request.post("/api/users", {
      data: { name: "Duplicate", email },
    })
    expect(response.status()).toBe(409)
  })

  test("422 — unprocessable entity", async ({ request }) => {
    const response = await request.post("/api/orders", {
      data: { items: [] }, // empty cart
    })
    expect(response.status()).toBe(422)
    const body = await response.json()
    expect(body.error).toContain("at least one item")
  })

  test("429 — rate limiting", async ({ request }) => {
    // Send rapid requests to trigger rate limit
    const responses = await Promise.all(
      Array.from({ length: 50 }, () => request.get("/api/search", { params: { q: "test" } }))
    )
    const rateLimited = responses.filter((r) => r.status() === 429)
    expect(rateLimited.length).toBeGreaterThan(0)

    // Verify rate limit headers
    const limited = rateLimited[0]
    expect(limited.headers()["retry-after"]).toBeDefined()
  })
})
```

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

test.describe("Error responses", () => {
  test("400 — validation error with details", async ({ request }) => {
    const response = await request.post("/api/users", {
      data: { name: "", email: "not-an-email" },
    })
    expect(response.status()).toBe(400)

    const body = await response.json()
    expect(body).toMatchObject({
      error: "Validation Error",
      details: expect.any(Array),
    })
    expect(body.details).toEqual(
      expect.arrayContaining([
        expect.objectContaining({ field: "name", message: expect.any(String) }),
        expect.objectContaining({ field: "email", message: expect.any(String) }),
      ])
    )
  })

  test("401 — missing authentication", async ({ request }) => {
    const response = await request.get("/api/protected/resource", {
      headers: { Authorization: "" },
    })
    expect(response.status()).toBe(401)
  })

  test("404 — resource not found", async ({ request }) => {
    const response = await request.get("/api/users/999999")
    expect(response.status()).toBe(404)
  })

  test("409 — conflict on duplicate resource", async ({ request }) => {
    const email = `conflict-${Date.now()}@example.com`
    await request.post("/api/users", { data: { name: "First", email } })

    const response = await request.post("/api/users", {
      data: { name: "Duplicate", email },
    })
    expect(response.status()).toBe(409)
  })
})
```

### File Upload via API

**Use when**: Testing file upload endpoints with multipart form data — document uploads, image processing, CSV imports.
**Avoid when**: You need to test the browser file picker dialog. Use `page.setInputFiles()` in an E2E test instead.

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"
import path from "path"
import fs from "fs"

test("upload a file via multipart form data", async ({ request }) => {
  const filePath = path.resolve("tests/fixtures/test-document.pdf")

  const response = await request.post("/api/documents/upload", {
    multipart: {
      file: {
        name: "test-document.pdf",
        mimeType: "application/pdf",
        buffer: fs.readFileSync(filePath),
      },
      description: "Quarterly report",
      category: "reports",
    },
  })

  expect(response.status()).toBe(201)
  const body = await response.json()
  expect(body).toMatchObject({
    id: expect.any(String),
    filename: "test-document.pdf",
    mimeType: "application/pdf",
    size: expect.any(Number),
    url: expect.stringMatching(/^https:\/\//),
  })
})

test("upload an image with metadata", async ({ request }) => {
  const imagePath = path.resolve("tests/fixtures/avatar.png")

  const response = await request.post("/api/users/42/avatar", {
    multipart: {
      image: {
        name: "avatar.png",
        mimeType: "image/png",
        buffer: fs.readFileSync(imagePath),
      },
      crop: JSON.stringify({ x: 0, y: 0, width: 200, height: 200 }),
    },
  })

  expect(response.ok()).toBeTruthy()
  const body = await response.json()
  expect(body.avatarUrl).toMatch(/\.png$/)
})

test("upload multiple files", async ({ request }) => {
  const files = ["report-q1.csv", "report-q2.csv"].map((name) => ({
    name,
    mimeType: "text/csv",
    buffer: fs.readFileSync(path.resolve(`tests/fixtures/${name}`)),
  }))

  // Send sequential uploads when the API does not support batch
  const results = []
  for (const file of files) {
    const response = await request.post("/api/imports/csv", {
      multipart: { file },
    })
    expect(response.ok()).toBeTruthy()
    results.push(await response.json())
  }
  expect(results).toHaveLength(2)
})

test("rejects oversized files", async ({ request }) => {
  // Create a buffer that exceeds the server limit
  const largeBuffer = Buffer.alloc(11 * 1024 * 1024) // 11MB

  const response = await request.post("/api/documents/upload", {
    multipart: {
      file: {
        name: "large-file.bin",
        mimeType: "application/octet-stream",
        buffer: largeBuffer,
      },
    },
  })

  expect(response.status()).toBe(413) // Payload Too Large
})
```

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")
const path = require("path")
const fs = require("fs")

test("upload a file via multipart form data", async ({ request }) => {
  const filePath = path.resolve("tests/fixtures/test-document.pdf")

  const response = await request.post("/api/documents/upload", {
    multipart: {
      file: {
        name: "test-document.pdf",
        mimeType: "application/pdf",
        buffer: fs.readFileSync(filePath),
      },
      description: "Quarterly report",
      category: "reports",
    },
  })

  expect(response.status()).toBe(201)
  const body = await response.json()
  expect(body).toMatchObject({
    id: expect.any(String),
    filename: "test-document.pdf",
    mimeType: "application/pdf",
    size: expect.any(Number),
  })
})

test("rejects oversized files", async ({ request }) => {
  const largeBuffer = Buffer.alloc(11 * 1024 * 1024)

  const response = await request.post("/api/documents/upload", {
    multipart: {
      file: {
        name: "large-file.bin",
        mimeType: "application/octet-stream",
        buffer: largeBuffer,
      },
    },
  })

  expect(response.status()).toBe(413)
})
```

### Chained API Calls

**Use when**: Testing multi-step workflows — create, read, update, delete sequences; order flows; state machine transitions. This verifies the API's behavior as an integrated system, not just isolated endpoints.
**Avoid when**: You can test each endpoint in isolation and the interactions are trivial.

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"

test("complete order workflow", async ({ request }) => {
  // Step 1: Create a product
  const productResp = await request.post("/api/products", {
    data: { name: "Widget", price: 29.99, stock: 100 },
  })
  expect(productResp.status()).toBe(201)
  const product = await productResp.json()

  // Step 2: Create a cart
  const cartResp = await request.post("/api/carts", {
    data: { items: [{ productId: product.id, quantity: 2 }] },
  })
  expect(cartResp.status()).toBe(201)
  const cart = await cartResp.json()
  expect(cart.total).toBe(59.98)

  // Step 3: Checkout — create an order from the cart
  const orderResp = await request.post("/api/orders", {
    data: {
      cartId: cart.id,
      shippingAddress: {
        street: "123 Test St",
        city: "Testville",
        zip: "12345",
      },
    },
  })
  expect(orderResp.status()).toBe(201)
  const order = await orderResp.json()
  expect(order.status).toBe("pending")
  expect(order.items).toHaveLength(1)
  expect(order.total).toBe(59.98)

  // Step 4: Verify order appears in user's order list
  const ordersResp = await request.get("/api/orders")
  const orders = await ordersResp.json()
  expect(orders.items.map((o: any) => o.id)).toContain(order.id)

  // Step 5: Verify product stock decreased
  const updatedProduct = await (await request.get(`/api/products/${product.id}`)).json()
  expect(updatedProduct.stock).toBe(98) // 100 - 2

  // Cleanup
  await request.delete(`/api/orders/${order.id}`)
  await request.delete(`/api/products/${product.id}`)
})

test("state machine transitions — publish workflow", async ({ request }) => {
  // Create a draft post
  const createResp = await request.post("/api/posts", {
    data: { title: "Draft Post", body: "Content here." },
  })
  const post = await createResp.json()
  expect(post.status).toBe("draft")

  // Submit for review
  const reviewResp = await request.patch(`/api/posts/${post.id}/status`, {
    data: { status: "in_review" },
  })
  expect(reviewResp.ok()).toBeTruthy()
  expect((await reviewResp.json()).status).toBe("in_review")

  // Approve (requires admin — use appropriate fixture in real tests)
  const approveResp = await request.patch(`/api/posts/${post.id}/status`, {
    data: { status: "published" },
  })
  expect(approveResp.ok()).toBeTruthy()
  expect((await approveResp.json()).status).toBe("published")

  // Verify: cannot go back to draft from published
  const revertResp = await request.patch(`/api/posts/${post.id}/status`, {
    data: { status: "draft" },
  })
  expect(revertResp.status()).toBe(422)

  // Cleanup
  await request.delete(`/api/posts/${post.id}`)
})

test("API + E2E hybrid — seed via API, verify in browser", async ({ request, page }) => {
  // Seed test data via API
  const resp = await request.post("/api/products", {
    data: {
      name: `Hybrid Test Product ${Date.now()}`,
      price: 42.0,
      published: true,
    },
  })
  const product = await resp.json()

  // Verify via browser
  await page.goto("/products")
  await expect(page.getByRole("heading", { name: product.name })).toBeVisible()
  await expect(page.getByText("$42.00")).toBeVisible()

  // Cleanup via API
  await request.delete(`/api/products/${product.id}`)
})
```

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

test("complete order workflow", async ({ request }) => {
  const productResp = await request.post("/api/products", {
    data: { name: "Widget", price: 29.99, stock: 100 },
  })
  expect(productResp.status()).toBe(201)
  const product = await productResp.json()

  const cartResp = await request.post("/api/carts", {
    data: { items: [{ productId: product.id, quantity: 2 }] },
  })
  expect(cartResp.status()).toBe(201)
  const cart = await cartResp.json()
  expect(cart.total).toBe(59.98)

  const orderResp = await request.post("/api/orders", {
    data: {
      cartId: cart.id,
      shippingAddress: {
        street: "123 Test St",
        city: "Testville",
        zip: "12345",
      },
    },
  })
  expect(orderResp.status()).toBe(201)
  const order = await orderResp.json()
  expect(order.status).toBe("pending")

  const ordersResp = await request.get("/api/orders")
  const orders = await ordersResp.json()
  expect(orders.items.map((o) => o.id)).toContain(order.id)

  await request.delete(`/api/orders/${order.id}`)
  await request.delete(`/api/products/${product.id}`)
})

test("API + E2E hybrid — seed via API, verify in browser", async ({ request, page }) => {
  const resp = await request.post("/api/products", {
    data: {
      name: `Hybrid Test Product ${Date.now()}`,
      price: 42.0,
      published: true,
    },
  })
  const product = await resp.json()

  await page.goto("/products")
  await expect(page.getByRole("heading", { name: product.name })).toBeVisible()

  await request.delete(`/api/products/${product.id}`)
})
```

## Decision Guide

| Scenario                                         | Use API Tests               | Use E2E Tests                  | Why                                                                |
| ------------------------------------------------ | --------------------------- | ------------------------------ | ------------------------------------------------------------------ |
| Validate response status/body/headers            | Yes                         | No                             | No browser needed; 10-100x faster                                  |
| Test business logic (calculations, rules)        | Yes                         | No                             | API tests isolate backend logic from UI                            |
| Verify form submission creates correct data      | Seed via API, submit via UI | Yes                            | UI test validates the form; API check confirms persistence         |
| Test error messages shown to user                | No                          | Yes                            | Error rendering is a UI concern                                    |
| Validate pagination, filtering, sorting          | Yes                         | Maybe both                     | API test for correctness; E2E test only if the UI logic is complex |
| Seed test data for E2E tests                     | Yes (fixture)               | No                             | API seeding is fast and reliable                                   |
| Test auth flows (login/logout/RBAC)              | Yes for token/session logic | Yes for UI flow                | Both matter: API protects resources, UI guides users               |
| Verify file upload processing                    | Yes                         | Only if testing file picker UI | API test validates backend processing                              |
| Contract/schema regression testing               | Yes                         | No                             | Schema tests run in milliseconds                                   |
| Test third-party webhook handling                | Yes                         | No                             | Webhooks are API-to-API; no UI involved                            |
| Verify redirect behavior after action            | No                          | Yes                            | Redirects are browser/navigation concerns                          |
| Test real-time updates (WebSocket + API trigger) | API triggers                | E2E verifies                   | Seed via API, observe in browser                                   |

## Anti-Patterns

| Don't Do This                                        | Problem                                                                                | Do This Instead                                                                                     |
| ---------------------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Use E2E tests to validate pure API responses         | Slow, flaky, launches a browser for no reason                                          | Use `request` fixture — no browser, direct HTTP                                                     |
| Ignore `response.status()`                           | A 500 with a fallback body can pass all body assertions                                | Always assert status first: `expect(response.status()).toBe(200)`                                   |
| Skip response header checks                          | Missing `Content-Type`, `Cache-Control`, CORS headers cause production bugs            | Assert critical headers: `expect(response.headers()['content-type']).toContain('application/json')` |
| 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                                                      |
| Hardcode IDs in API tests                            | Tests break when database is reset or IDs are reassigned                               | Create resources in the test, use returned IDs                                                      |
| 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                                                        |
| Parse `response.text()` then `JSON.parse()` manually | Playwright's `response.json()` handles this and throws clear errors on non-JSON        | Use `await response.json()`                                                                         |
| 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                                               |
| Test GraphQL by checking 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                                          |
| 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                                             |

## Troubleshooting

### "Request failed: connect ECONNREFUSED 127.0.0.1:3000"

**Cause**: The API server is not running, or `baseURL` points to the wrong host/port.

**Fix**:

- Verify the server is running before tests: use `webServer` in `playwright.config.ts` to start it automatically.
- Check `baseURL` in your config matches the actual server address.

```typescript
// playwright.config.ts
export default defineConfig({
  webServer: {
    command: "npm run start:api",
    url: "http://localhost:3000/api/health",
    reuseExistingServer: !process.env.CI,
  },
  use: {
    baseURL: "http://localhost:3000",
  },
})
```

### "response.json() failed — body is not valid JSON"

**Cause**: The endpoint returned HTML (error page), plain text, or an empty body instead of JSON.

**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.

```typescript
const response = await request.get("/api/endpoint")
if (!response.ok()) {
  console.error(`Status: ${response.status()}, Body: ${await response.text()}`)
}
const body = await response.json() // now you know what failed
```

### "401 Unauthorized" when using `request` fixture

**Cause**: The built-in `request` fixture does not carry browser cookies or auth tokens automatically. It starts with a clean slate.

**Fix**:

- Set `extraHTTPHeaders` in your config or create a custom authenticated fixture.
- If you need cookies from a browser login, use `page.request` (which shares the browser context's cookies) instead of the standalone `request` fixture.

```typescript
// Option A: config-level headers
export default defineConfig({
  use: {
    extraHTTPHeaders: {
      Authorization: `Bearer ${process.env.API_TOKEN}`,
    },
  },
})

// Option B: per-request headers
const response = await request.get("/api/resource", {
  headers: { Authorization: `Bearer ${token}` },
})

// Option C: use page.request to inherit browser cookies
test("API call with browser auth", async ({ page }) => {
  await page.goto("/login")
  // ... login via UI ...
  const response = await page.request.get("/api/profile")
  expect(response.ok()).toBeTruthy()
})
```

### 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 response.json()
if (errors) {
  console.error("GraphQL errors:", JSON.stringify(errors, null, 2))
}
expect(errors).toBeUndefined()
expect(data.user).toBeDefined()
```

### Tests pass locally but fail in CI

**Cause**: Different environments, database state, or missing environment variables.

**Fix**:

- Use `process.env` for secrets and base URLs — never hardcode them.
- Run database seeds or migrations in `globalSetup`.
- Use unique identifiers (timestamps, UUIDs) for test data to avoid collisions in parallel runs.
- Check that the CI `baseURL` matches the deployed or containerized service.

## Related

- [core/configuration.md](configuration.md) — `baseURL`, `extraHTTPHeaders`, and `webServer` config
- [core/fixtures-and-hooks.md](fixtures-and-hooks.md) — custom fixture patterns for reusable API clients
- [core/authentication.md](authentication.md) — auth patterns including token-based API auth
- [core/network-mocking.md](network-mocking.md) — mocking API responses in E2E tests (opposite of this guide)
- [core/test-architecture.md](test-architecture.md) — when to use API tests vs E2E vs component tests
- [core/when-to-mock.md](when-to-mock.md) — when to hit real APIs vs mock them