# Test Data Management

> **When to use**: Every test that interacts with data — user accounts, form inputs, entities, or any state that must exist before assertions run.

## Quick Reference

| Strategy            | Speed   | Isolation | Complexity | Best For                                  |
| ------------------- | ------- | --------- | ---------- | ----------------------------------------- |
| Inline data         | Instant | Perfect   | None       | Simple value checks, form inputs          |
| Factory functions   | Instant | Perfect   | Low        | Unique identifiers, consistent shapes     |
| Faker/random data   | Instant | Perfect   | Low        | Realistic fields, edge-case discovery     |
| Builder pattern     | Instant | Perfect   | Medium     | Complex objects with many optional fields |
| API seeding         | Fast    | Perfect   | Medium     | Creating entities the app depends on      |
| Database seeding    | Fast    | Good      | High       | Complex relational data, bulk setup       |
| Storage state       | Fast    | Good      | Low        | Reusing authenticated sessions            |
| Fixture-based setup | Fast    | Perfect   | Medium     | Encapsulating setup + guaranteed teardown |

**Core principle**: Every test creates its own data and cleans up after itself. No test should depend on data left behind by another test or pre-existing in the environment.

## Patterns

### Inline Test Data

**Use when**: The data is simple, unique to one test, and essential for understanding the assertion.

**Avoid when**: The same data shape repeats across many tests — extract a factory instead.

Inline data makes tests self-documenting. The reader sees exactly what matters without chasing imports.

**TypeScript**

```typescript
// tests/contact-form.spec.ts
import { test, expect } from "@playwright/test"

test("submits contact form with valid data", async ({ page }) => {
  const name = "Ada Lovelace"
  const email = `ada-${Date.now()}@example.com`
  const message = "Inquiry about analytics engine"

  await page.goto("/contact")
  await page.getByLabel("Name").fill(name)
  await page.getByLabel("Email").fill(email)
  await page.getByLabel("Message").fill(message)
  await page.getByRole("button", { name: "Send" }).click()

  await expect(page.getByText("Thank you, Ada Lovelace")).toBeVisible()
})
```

**JavaScript**

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

test("submits contact form with valid data", async ({ page }) => {
  const name = "Ada Lovelace"
  const email = `ada-${Date.now()}@example.com`
  const message = "Inquiry about analytics engine"

  await page.goto("/contact")
  await page.getByLabel("Name").fill(name)
  await page.getByLabel("Email").fill(email)
  await page.getByLabel("Message").fill(message)
  await page.getByRole("button", { name: "Send" }).click()

  await expect(page.getByText("Thank you, Ada Lovelace")).toBeVisible()
})
```

Use `Date.now()` or `crypto.randomUUID()` for fields that must be unique (emails, usernames). This prevents collisions during parallel execution.

---

### Factory Functions

**Use when**: Multiple tests need the same data shape with different values, or you need guaranteed uniqueness.

**Avoid when**: The data is trivial and only used once — inline it instead.

Factories centralize data creation logic. When the data shape changes, you update one function, not dozens of tests.

**TypeScript**

```typescript
// tests/factories/user.factory.ts
export interface UserData {
  firstName: string
  lastName: string
  email: string
  password: string
}

let counter = 0

export function createUserData(overrides: Partial<UserData> = {}): UserData {
  counter++
  const id = `${Date.now()}-${counter}`
  return {
    firstName: `Test`,
    lastName: `User${id}`,
    email: `testuser-${id}@example.com`,
    password: "SecureP@ss123!",
    ...overrides,
  }
}
```

```typescript
// tests/registration.spec.ts
import { test, expect } from "@playwright/test"
import { createUserData } from "./factories/user.factory"

test("registers a new user", async ({ page }) => {
  const user = createUserData()

  await page.goto("/register")
  await page.getByLabel("First name").fill(user.firstName)
  await page.getByLabel("Last name").fill(user.lastName)
  await page.getByLabel("Email").fill(user.email)
  await page.getByLabel("Password").fill(user.password)
  await page.getByRole("button", { name: "Create account" }).click()

  await expect(page.getByText(`Welcome, ${user.firstName}`)).toBeVisible()
})

test("rejects duplicate email", async ({ page }) => {
  const user = createUserData({ email: "duplicate@example.com" })

  await page.goto("/register")
  await page.getByLabel("Email").fill(user.email)
  await page.getByLabel("Password").fill(user.password)
  await page.getByRole("button", { name: "Create account" }).click()

  await expect(page.getByText("Email already registered")).toBeVisible()
})
```

**JavaScript**

```javascript
// tests/factories/user.factory.js
let counter = 0

function createUserData(overrides = {}) {
  counter++
  const id = `${Date.now()}-${counter}`
  return {
    firstName: "Test",
    lastName: `User${id}`,
    email: `testuser-${id}@example.com`,
    password: "SecureP@ss123!",
    ...overrides,
  }
}

module.exports = { createUserData }
```

```javascript
// tests/registration.spec.js
const { test, expect } = require("@playwright/test")
const { createUserData } = require("./factories/user.factory")

test("registers a new user", async ({ page }) => {
  const user = createUserData()

  await page.goto("/register")
  await page.getByLabel("First name").fill(user.firstName)
  await page.getByLabel("Last name").fill(user.lastName)
  await page.getByLabel("Email").fill(user.email)
  await page.getByLabel("Password").fill(user.password)
  await page.getByRole("button", { name: "Create account" }).click()

  await expect(page.getByText(`Welcome, ${user.firstName}`)).toBeVisible()
})
```

---

### Faker / Random Data

**Use when**: You need realistic-looking data (names, addresses, phone numbers) or want to discover edge cases through randomness.

**Avoid when**: Debugging a failure — use a fixed seed to make it reproducible.

Always seed faker so failures are reproducible. Use `testInfo.testId` or a fixed seed per test file.

**TypeScript**

```typescript
// tests/factories/faker-user.factory.ts
import { faker } from "@faker-js/faker"

export function createFakerUser(seed?: number) {
  if (seed !== undefined) {
    faker.seed(seed)
  }
  return {
    firstName: faker.person.firstName(),
    lastName: faker.person.lastName(),
    email: faker.internet.email({ provider: "testmail.example.com" }),
    phone: faker.phone.number(),
    address: {
      street: faker.location.streetAddress(),
      city: faker.location.city(),
      state: faker.location.state({ abbreviated: true }),
      zip: faker.location.zipCode(),
    },
  }
}
```

```typescript
// tests/checkout.spec.ts
import { test, expect } from "@playwright/test"
import { createFakerUser } from "./factories/faker-user.factory"

test("completes checkout with shipping address", async ({ page }, testInfo) => {
  // Seed with a stable value so re-runs produce the same data
  const user = createFakerUser(testInfo.workerIndex)

  await page.goto("/checkout")
  await page.getByLabel("Street address").fill(user.address.street)
  await page.getByLabel("City").fill(user.address.city)
  await page.getByLabel("State").fill(user.address.state)
  await page.getByLabel("ZIP code").fill(user.address.zip)
  await page.getByRole("button", { name: "Place order" }).click()

  await expect(page.getByText("Order confirmed")).toBeVisible()
})
```

**JavaScript**

```javascript
// tests/factories/faker-user.factory.js
const { faker } = require("@faker-js/faker")

function createFakerUser(seed) {
  if (seed !== undefined) {
    faker.seed(seed)
  }
  return {
    firstName: faker.person.firstName(),
    lastName: faker.person.lastName(),
    email: faker.internet.email({ provider: "testmail.example.com" }),
    phone: faker.phone.number(),
    address: {
      street: faker.location.streetAddress(),
      city: faker.location.city(),
      state: faker.location.state({ abbreviated: true }),
      zip: faker.location.zipCode(),
    },
  }
}

module.exports = { createFakerUser }
```

```javascript
// tests/checkout.spec.js
const { test, expect } = require("@playwright/test")
const { createFakerUser } = require("./factories/faker-user.factory")

test("completes checkout with shipping address", async ({ page }, testInfo) => {
  const user = createFakerUser(testInfo.workerIndex)

  await page.goto("/checkout")
  await page.getByLabel("Street address").fill(user.address.street)
  await page.getByLabel("City").fill(user.address.city)
  await page.getByLabel("State").fill(user.address.state)
  await page.getByLabel("ZIP code").fill(user.address.zip)
  await page.getByRole("button", { name: "Place order" }).click()

  await expect(page.getByText("Order confirmed")).toBeVisible()
})
```

Always use a test-specific email domain (e.g., `testmail.example.com`) so faker-generated emails never hit real inboxes. The `example.com` domain is reserved by RFC 2606 and is safe for testing.

---

### Builder Pattern

**Use when**: Objects have many optional fields, conditional logic, or multiple valid configurations. Common for product listings, user profiles, or form payloads with nested data.

**Avoid when**: The object has fewer than 5 fields — a factory with overrides is simpler.

**TypeScript**

```typescript
// tests/builders/product.builder.ts
export interface Product {
  name: string
  price: number
  currency: string
  category: string
  description: string
  inStock: boolean
  tags: string[]
  variants: { size: string; color: string }[]
}

export class ProductBuilder {
  private product: Product = {
    name: `Product-${Date.now()}`,
    price: 29.99,
    currency: "USD",
    category: "Electronics",
    description: "A test product",
    inStock: true,
    tags: [],
    variants: [],
  }

  withName(name: string): this {
    this.product.name = name
    return this
  }

  withPrice(price: number, currency = "USD"): this {
    this.product.price = price
    this.product.currency = currency
    return this
  }

  withCategory(category: string): this {
    this.product.category = category
    return this
  }

  outOfStock(): this {
    this.product.inStock = false
    return this
  }

  withTags(...tags: string[]): this {
    this.product.tags = tags
    return this
  }

  withVariant(size: string, color: string): this {
    this.product.variants.push({ size, color })
    return this
  }

  build(): Product {
    return { ...this.product }
  }
}
```

```typescript
// tests/product-catalog.spec.ts
import { test, expect } from "@playwright/test"
import { ProductBuilder } from "./builders/product.builder"

test("displays out-of-stock badge for unavailable products", async ({ page, request }) => {
  const product = new ProductBuilder()
    .withName("Wireless Keyboard")
    .withCategory("Accessories")
    .outOfStock()
    .build()

  // Seed via API (see API Seeding pattern below)
  await request.post("/api/products", { data: product })

  await page.goto("/products")
  const card = page.getByRole("listitem").filter({ hasText: product.name })
  await expect(card.getByText("Out of Stock")).toBeVisible()
})
```

**JavaScript**

```javascript
// tests/builders/product.builder.js
class ProductBuilder {
  constructor() {
    this.product = {
      name: `Product-${Date.now()}`,
      price: 29.99,
      currency: "USD",
      category: "Electronics",
      description: "A test product",
      inStock: true,
      tags: [],
      variants: [],
    }
  }

  withName(name) {
    this.product.name = name
    return this
  }

  withPrice(price, currency = "USD") {
    this.product.price = price
    this.product.currency = currency
    return this
  }

  withCategory(category) {
    this.product.category = category
    return this
  }

  outOfStock() {
    this.product.inStock = false
    return this
  }

  withTags(...tags) {
    this.product.tags = tags
    return this
  }

  withVariant(size, color) {
    this.product.variants.push({ size, color })
    return this
  }

  build() {
    return { ...this.product }
  }
}

module.exports = { ProductBuilder }
```

```javascript
// tests/product-catalog.spec.js
const { test, expect } = require("@playwright/test")
const { ProductBuilder } = require("./builders/product.builder")

test("displays out-of-stock badge for unavailable products", async ({ page, request }) => {
  const product = new ProductBuilder()
    .withName("Wireless Keyboard")
    .withCategory("Accessories")
    .outOfStock()
    .build()

  await request.post("/api/products", { data: product })

  await page.goto("/products")
  const card = page.getByRole("listitem").filter({ hasText: product.name })
  await expect(card.getByText("Out of Stock")).toBeVisible()
})
```

---

### API Seeding

**Use when**: Tests need entities to already exist (users, products, orders) and the app exposes APIs to create them. This is the default strategy for test data setup.

**Avoid when**: No API exists for the entity, or the API itself is what you are testing (use the UI or database instead).

API seeding is faster than UI-based setup, more maintainable than database seeding, and exercises real application logic. Prefer it over all other approaches when an API is available.

**TypeScript**

```typescript
// tests/fixtures/api-data.fixture.ts
import { test as base, APIRequestContext } from "@playwright/test"
import { createUserData, UserData } from "../factories/user.factory"

type ApiDataFixtures = {
  apiUser: UserData & { id: string }
}

export const test = base.extend<ApiDataFixtures>({
  apiUser: async ({ request }, use) => {
    const userData = createUserData()

    // Create
    const response = await request.post("/api/users", { data: userData })
    const created = await response.json()
    const user = { ...userData, id: created.id }

    // Provide to test
    await use(user)

    // Cleanup — runs even if test fails
    await request.delete(`/api/users/${user.id}`)
  },
})

export { expect } from "@playwright/test"
```

```typescript
// tests/user-profile.spec.ts
import { test, expect } from "./fixtures/api-data.fixture"

test("edits user profile name", async ({ page, apiUser }) => {
  await page.goto(`/users/${apiUser.id}/profile`)
  await page.getByLabel("First name").fill("Updated")
  await page.getByRole("button", { name: "Save" }).click()

  await expect(page.getByText("Profile updated")).toBeVisible()
})
```

**JavaScript**

```javascript
// tests/fixtures/api-data.fixture.js
const { test: base } = require("@playwright/test")
const { createUserData } = require("../factories/user.factory")

const test = base.extend({
  apiUser: async ({ request }, use) => {
    const userData = createUserData()

    const response = await request.post("/api/users", { data: userData })
    const created = await response.json()
    const user = { ...userData, id: created.id }

    await use(user)

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

module.exports = { test, expect: require("@playwright/test").expect }
```

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

test("edits user profile name", async ({ page, apiUser }) => {
  await page.goto(`/users/${apiUser.id}/profile`)
  await page.getByLabel("First name").fill("Updated")
  await page.getByRole("button", { name: "Save" }).click()

  await expect(page.getByText("Profile updated")).toBeVisible()
})
```

For multi-entity seeding, compose fixtures:

**TypeScript**

```typescript
// tests/fixtures/order-data.fixture.ts
import { test as base } from "./api-data.fixture"

export const test = base.extend({
  apiOrder: async ({ request, apiUser }, use) => {
    const orderResponse = await request.post("/api/orders", {
      data: { userId: apiUser.id, items: [{ sku: "WIDGET-001", qty: 2 }] },
    })
    const order = await orderResponse.json()

    await use(order)

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

---

### Database Seeding

**Use when**: No API exists for the data you need, you need bulk data, or you need to set up complex relational state that is cumbersome via API calls.

**Avoid when**: An API exists — API seeding is more maintainable and exercises real application logic. Database seeding couples tests to schema details.

**TypeScript**

```typescript
// tests/fixtures/db.fixture.ts
import { test as base } from "@playwright/test"
import { Pool } from "pg"

type DbFixtures = {
  db: Pool
  seededOrg: { id: string; name: string }
}

export const test = base.extend<DbFixtures>({
  db: async ({}, use) => {
    const pool = new Pool({
      connectionString: process.env.TEST_DATABASE_URL,
    })
    await use(pool)
    await pool.end()
  },

  seededOrg: async ({ db }, use) => {
    const orgName = `TestOrg-${Date.now()}`
    const result = await db.query(
      "INSERT INTO organizations (name, plan) VALUES ($1, $2) RETURNING id",
      [orgName, "enterprise"]
    )
    const orgId = result.rows[0].id

    await use({ id: orgId, name: orgName })

    // Cascade delete cleans up related data
    await db.query("DELETE FROM organizations WHERE id = $1", [orgId])
  },
})

export { expect } from "@playwright/test"
```

**JavaScript**

```javascript
// tests/fixtures/db.fixture.js
const { test: base } = require("@playwright/test")
const { Pool } = require("pg")

const test = base.extend({
  db: async ({}, use) => {
    const pool = new Pool({
      connectionString: process.env.TEST_DATABASE_URL,
    })
    await use(pool)
    await pool.end()
  },

  seededOrg: async ({ db }, use) => {
    const orgName = `TestOrg-${Date.now()}`
    const result = await db.query(
      "INSERT INTO organizations (name, plan) VALUES ($1, $2) RETURNING id",
      [orgName, "enterprise"]
    )
    const orgId = result.rows[0].id

    await use({ id: orgId, name: orgName })

    await db.query("DELETE FROM organizations WHERE id = $1", [orgId])
  },
})

module.exports = { test, expect: require("@playwright/test").expect }
```

Always use parameterized queries (`$1`, `$2`) to prevent SQL injection — even in tests. It is a good habit and prevents breakage from special characters in generated data.

---

### Storage State

**Use when**: Multiple tests need an authenticated session and you want to avoid logging in via the UI in every test.

**Avoid when**: The test is specifically testing the login flow itself.

Generate storage state once in a setup project, then reuse it across all tests that need authentication.

**TypeScript**

```typescript
// playwright.config.ts
import { defineConfig } from "@playwright/test"

export default defineConfig({
  projects: [
    {
      name: "auth-setup",
      testMatch: /auth\.setup\.ts/,
    },
    {
      name: "authenticated-tests",
      dependencies: ["auth-setup"],
      use: {
        storageState: ".auth/user.json",
      },
    },
  ],
})
```

```typescript
// tests/auth.setup.ts
import { test as setup, expect } from "@playwright/test"
import path from "node:path"

const authFile = path.join(__dirname, "..", ".auth", "user.json")

setup("authenticate as standard user", async ({ page }) => {
  await page.goto("/login")
  await page.getByLabel("Email").fill(process.env.TEST_USER_EMAIL!)
  await page.getByLabel("Password").fill(process.env.TEST_USER_PASSWORD!)
  await page.getByRole("button", { name: "Sign in" }).click()

  await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible()

  await page.context().storageState({ path: authFile })
})
```

**JavaScript**

```javascript
// playwright.config.js
const { defineConfig } = require("@playwright/test")

module.exports = defineConfig({
  projects: [
    {
      name: "auth-setup",
      testMatch: /auth\.setup\.js/,
    },
    {
      name: "authenticated-tests",
      dependencies: ["auth-setup"],
      use: {
        storageState: ".auth/user.json",
      },
    },
  ],
})
```

```javascript
// tests/auth.setup.js
const { test: setup, expect } = require("@playwright/test")
const path = require("node:path")

const authFile = path.join(__dirname, "..", ".auth", "user.json")

setup("authenticate as standard user", async ({ page }) => {
  await page.goto("/login")
  await page.getByLabel("Email").fill(process.env.TEST_USER_EMAIL)
  await page.getByLabel("Password").fill(process.env.TEST_USER_PASSWORD)
  await page.getByRole("button", { name: "Sign in" }).click()

  await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible()

  await page.context().storageState({ path: authFile })
})
```

For multiple roles, create separate setup files and storage state files:

```typescript
// tests/admin-auth.setup.ts
import { test as setup } from "@playwright/test"
import path from "node:path"

const adminAuthFile = path.join(__dirname, "..", ".auth", "admin.json")

setup("authenticate as admin", async ({ page }) => {
  await page.goto("/login")
  await page.getByLabel("Email").fill(process.env.ADMIN_EMAIL!)
  await page.getByLabel("Password").fill(process.env.ADMIN_PASSWORD!)
  await page.getByRole("button", { name: "Sign in" }).click()
  await page.context().storageState({ path: adminAuthFile })
})
```

Add `.auth/` to `.gitignore` — storage state files contain session tokens.

---

### Test Data Cleanup

**Use when**: Always. Every test that creates data must clean it up.

**Avoid when**: Never. Skipping cleanup causes cascading failures in subsequent runs.

**Strategy 1: Fixture teardown (preferred)**

Put cleanup in the fixture's teardown block. Runs even if the test throws.

```typescript
// Already shown in API Seeding — the cleanup runs after `use()`
apiUser: async ({ request }, use) => {
  const user = await createViaApi(request);
  await use(user);
  // This ALWAYS runs — even on test failure
  await request.delete(`/api/users/${user.id}`);
},
```

**Strategy 2: Batch cleanup by timestamp prefix**

Tag all test-created data with a recognizable prefix, then sweep it in global teardown.

**TypeScript**

```typescript
// global-teardown.ts
import { request } from "@playwright/test"

export default async function globalTeardown() {
  const context = await request.newContext({
    baseURL: process.env.BASE_URL,
  })

  // Delete all test entities created in this run
  // Assumes entities created with the "test-" prefix
  const response = await context.delete("/api/test-data/cleanup", {
    data: { prefix: "test-", olderThanMinutes: 60 },
  })

  if (!response.ok()) {
    console.warn(`Cleanup returned ${response.status()}`)
  }

  await context.dispose()
}
```

**JavaScript**

```javascript
// global-teardown.js
const { request } = require("@playwright/test")

module.exports = async function globalTeardown() {
  const context = await request.newContext({
    baseURL: process.env.BASE_URL,
  })

  const response = await context.delete("/api/test-data/cleanup", {
    data: { prefix: "test-", olderThanMinutes: 60 },
  })

  if (!response.ok()) {
    console.warn(`Cleanup returned ${response.status()}`)
  }

  await context.dispose()
}
```

**Strategy 3: Isolated tenant per worker**

Each Playwright worker gets its own tenant/organization. All data is scoped to that tenant. Teardown deletes the entire tenant.

```typescript
// tests/fixtures/tenant.fixture.ts
import { test as base } from "@playwright/test"

export const test = base.extend<{}, { workerTenant: { id: string; apiKey: string } }>({
  workerTenant: [
    async ({ request }, use) => {
      const res = await request.post("/api/tenants", {
        data: { name: `test-worker-${Date.now()}` },
      })
      const tenant = await res.json()

      await use(tenant)

      await request.delete(`/api/tenants/${tenant.id}`)
    },
    { scope: "worker" },
  ],
})
```

---

### Environment-Specific Data

**Use when**: Tests run against multiple environments (dev, staging, production-mirror) with different base URLs, credentials, or data constraints.

**Avoid when**: You only have one test environment.

Never hardcode environment-specific values in test files. Use `.env` files and `playwright.config` to inject them.

**TypeScript**

```typescript
// playwright.config.ts
import { defineConfig } from "@playwright/test"
import dotenv from "dotenv"
import path from "node:path"

// Load environment-specific .env file
const envFile = process.env.TEST_ENV || "local"
dotenv.config({ path: path.resolve(__dirname, `.env.${envFile}`) })

export default defineConfig({
  use: {
    baseURL: process.env.BASE_URL,
  },
})
```

```
# .env.local
BASE_URL=http://localhost:3000
TEST_USER_EMAIL=testuser@localhost.test
TEST_USER_PASSWORD=localpassword123

# .env.staging
BASE_URL=https://staging.example.com
TEST_USER_EMAIL=e2e-bot@staging.example.com
TEST_USER_PASSWORD=staging-secret-from-vault
```

```typescript
// tests/fixtures/env-data.fixture.ts
import { test as base } from "@playwright/test"

type EnvConfig = {
  testCredentials: { email: string; password: string }
}

export const test = base.extend<EnvConfig>({
  testCredentials: async ({}, use) => {
    const email = process.env.TEST_USER_EMAIL
    const password = process.env.TEST_USER_PASSWORD
    if (!email || !password) {
      throw new Error("TEST_USER_EMAIL and TEST_USER_PASSWORD must be set")
    }
    await use({ email, password })
  },
})

export { expect } from "@playwright/test"
```

**JavaScript**

```javascript
// playwright.config.js
const { defineConfig } = require("@playwright/test")
const dotenv = require("dotenv")
const path = require("node:path")

const envFile = process.env.TEST_ENV || "local"
dotenv.config({ path: path.resolve(__dirname, `.env.${envFile}`) })

module.exports = defineConfig({
  use: {
    baseURL: process.env.BASE_URL,
  },
})
```

Run against a specific environment:

```bash
TEST_ENV=staging npx playwright test
```

---

### Fixtures for Test Data

**Use when**: Test data setup and teardown should be encapsulated, reusable, and guaranteed to clean up. This is the recommended pattern for all non-trivial test data.

**Avoid when**: The data is a simple inline value that does not require cleanup.

Fixtures are the backbone of reliable test data management in Playwright. They compose, they guarantee teardown, and they make tests declarative.

**TypeScript**

```typescript
// tests/fixtures/index.ts
import { test as base, expect } from "@playwright/test"
import { createUserData, UserData } from "../factories/user.factory"

type TestFixtures = {
  seedUser: UserData & { id: string }
  seedProduct: { id: string; name: string; price: number }
}

export const test = base.extend<TestFixtures>({
  seedUser: async ({ request }, use) => {
    const data = createUserData()
    const res = await request.post("/api/users", { data })
    expect(res.ok()).toBeTruthy()
    const user = { ...data, id: (await res.json()).id }

    await use(user)

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

  seedProduct: async ({ request }, use) => {
    const data = {
      name: `Product-${Date.now()}`,
      price: 49.99,
      category: "Testing",
    }
    const res = await request.post("/api/products", { data })
    expect(res.ok()).toBeTruthy()
    const product = { ...data, id: (await res.json()).id }

    await use(product)

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

export { expect }
```

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

test("adds product to cart", async ({ page, seedUser, seedProduct }) => {
  // seedUser and seedProduct are already created and will be cleaned up automatically
  await page.goto(`/products/${seedProduct.id}`)
  await page.getByRole("button", { name: "Add to cart" }).click()

  await page.goto("/cart")
  await expect(page.getByText(seedProduct.name)).toBeVisible()
  await expect(page.getByText("$49.99")).toBeVisible()
})
```

**JavaScript**

```javascript
// tests/fixtures/index.js
const { test: base, expect } = require("@playwright/test")
const { createUserData } = require("../factories/user.factory")

const test = base.extend({
  seedUser: async ({ request }, use) => {
    const data = createUserData()
    const res = await request.post("/api/users", { data })
    expect(res.ok()).toBeTruthy()
    const user = { ...data, id: (await res.json()).id }

    await use(user)

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

  seedProduct: async ({ request }, use) => {
    const data = {
      name: `Product-${Date.now()}`,
      price: 49.99,
      category: "Testing",
    }
    const res = await request.post("/api/products", { data })
    expect(res.ok()).toBeTruthy()
    const product = { ...data, id: (await res.json()).id }

    await use(product)

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

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

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

test("adds product to cart", async ({ page, seedUser, seedProduct }) => {
  await page.goto(`/products/${seedProduct.id}`)
  await page.getByRole("button", { name: "Add to cart" }).click()

  await page.goto("/cart")
  await expect(page.getByText(seedProduct.name)).toBeVisible()
  await expect(page.getByText("$49.99")).toBeVisible()
})
```

Fixtures only run when a test requests them by name. If a test does not use `seedProduct`, the product is never created — no wasted setup, no unnecessary cleanup.

## Decision Guide

```
What data does your test need?
│
├── Simple values (strings, numbers for form fields)?
│   └── Use INLINE DATA — keep it in the test
│
├── Same shape used across many tests?
│   ├── < 5 fields? → Use a FACTORY FUNCTION
│   └── >= 5 fields with optional/conditional fields? → Use a BUILDER
│
├── Need realistic-looking data (names, addresses)?
│   └── Use FAKER with a fixed seed
│
├── Entities that must exist before the test starts?
│   ├── App has an API for this entity?
│   │   └── Use API SEEDING in a fixture (preferred)
│   ├── No API, but have database access?
│   │   └── Use DATABASE SEEDING in a fixture
│   └── No API, no DB access?
│       └── Use UI setup in a beforeEach (slowest — avoid if possible)
│
├── Need an authenticated session?
│   └── Use STORAGE STATE via setup project
│
└── Need data isolated per worker?
    └── Use WORKER-SCOPED FIXTURES with tenant isolation
```

### Speed ranking (fastest to slowest)

1. Inline data / factories / faker — no I/O, instant
2. API seeding — one HTTP call per entity
3. Database seeding — direct DB call, skips app logic
4. Storage state — one-time login, reused across tests
5. UI-based setup — full browser interaction per test (avoid)

### Isolation ranking (most to least isolated)

1. Test-scoped fixtures with API teardown — each test gets fresh data, cleaned up after
2. Worker-scoped tenant isolation — tests in a worker share a tenant, cleaned up when worker exits
3. Timestamp-prefixed batch cleanup — catches orphaned data, runs in global teardown
4. Shared database state — fragile, prone to ordering bugs (avoid)

## Anti-Patterns

### Shared mutable data across tests

```typescript
// BAD — tests share the same user object and depend on execution order
let sharedUser: UserData

test.beforeAll(async ({ request }) => {
  sharedUser = await createUser(request)
})

test("updates user name", async ({ page }) => {
  // Mutates sharedUser — other tests see the changed state
})

test("checks original name", async ({ page }) => {
  // Fails because the previous test changed the name
})
```

Fix: Use test-scoped fixtures. Each test gets its own instance.

### Hardcoded IDs

```typescript
// BAD — this ID only exists in your local database
test("edits product", async ({ page }) => {
  await page.goto("/products/507f1f77bcf86cd799439011/edit")
})
```

Fix: Create the product in a fixture and use the returned ID.

### No cleanup

```typescript
// BAD — creates data but never deletes it
test.beforeEach(async ({ request }) => {
  await request.post("/api/products", { data: { name: "Leaked Product" } })
})
// Over time, the database fills with test debris causing slowdowns and false positives
```

Fix: Always pair creation with deletion in a fixture teardown.

### Relying on pre-existing database state

```typescript
// BAD — assumes "Premium Plan" already exists in the database
test("subscribes to premium", async ({ page }) => {
  await page.goto("/pricing")
  await page.getByRole("button", { name: "Premium Plan" }).click()
  // Breaks on a fresh database or different environment
})
```

Fix: Seed the plan via API or database fixture before the test.

### Using production data in tests

```typescript
// BAD — tests against real customer data
test("views customer orders", async ({ page }) => {
  await page.goto("/admin/customers/real-customer-id/orders")
})
```

Fix: Create synthetic test data. Never point test suites at production databases or use real customer identifiers.

### Over-engineering data setup

```typescript
// BAD — abstraction for its own sake
const data = new TestDataOrchestrator()
  .withStrategy("api")
  .withRetry(3)
  .withCleanupPolicy("deferred")
  .withEnvironment("staging")
  .build()
```

Fix: A factory function and a fixture cover 95% of cases. Add complexity only when you have a proven need.

## Troubleshooting

| Problem                                 | Cause                                                 | Fix                                                                                                        |
| --------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Tests fail with "duplicate key" errors  | Data from previous runs was not cleaned up            | Add fixture teardown; run batch cleanup in `globalTeardown`                                                |
| Tests pass alone but fail in parallel   | Tests share mutable state or collide on unique fields | Use `Date.now()` or `crypto.randomUUID()` in factory output; use test-scoped fixtures                      |
| Faker produces different data on retry  | Faker was not seeded, or seed changes between runs    | Seed with `testInfo.workerIndex` or a fixed value                                                          |
| Storage state expired / session invalid | Auth tokens have a short TTL                          | Re-run auth setup before each suite; set `fullyParallel: false` on auth-dependent project if needed        |
| Cleanup fails and blocks other tests    | Teardown makes network calls that can timeout         | Wrap cleanup in `try/catch`; log failures but do not throw; rely on batch cleanup as a safety net          |
| Database seeding is slow                | Too many individual INSERT statements                 | Batch inserts; use transactions; consider API seeding instead                                              |
| Tests break when run against staging    | Hardcoded values that only exist locally              | Use environment variables for all environment-specific data; validate in fixture with clear error messages |

### Making cleanup resilient

```typescript
// Wrap fixture teardown in try/catch so a cleanup failure does not mask the real test failure
seedUser: async ({ request }, use) => {
  const user = await createViaApi(request);
  await use(user);

  try {
    await request.delete(`/api/users/${user.id}`);
  } catch (error) {
    console.warn(`Failed to clean up user ${user.id}:`, error);
  }
},
```

## Related

- [core/fixtures-and-hooks.md](fixtures-and-hooks.md) — fixture mechanics, scoping, composition
- [core/authentication.md](authentication.md) — storage state setup, multi-role auth patterns
- [core/api-testing.md](api-testing.md) — API request context, response validation
- [ci/global-setup-teardown.md](../ci/global-setup-teardown.md) — global setup/teardown for batch operations
- [pom/pom-vs-fixtures-vs-helpers.md](../pom/pom-vs-fixtures-vs-helpers.md) — when to use fixtures vs page objects vs helpers