Fixtures Pattern | Bootspring Docs

Create and manage test data with factory functions, builder patterns, database seeding, and Playwright fixtures.

Overview#

Test fixtures provide consistent, reusable test data. Good fixtures make tests more readable, maintainable, and reliable by ensuring predictable test scenarios.

When to use:

Creating consistent test data across tests
Setting up complex object structures
Seeding test databases
Sharing setup between tests

Key features:

Factory functions for object creation
Builder pattern for complex objects
Database fixtures for integration tests
Playwright fixtures for E2E tests

Code Example#

Factory Functions#

// tests/factories/user.ts
import { faker } from '@faker-js/faker'

interface UserInput {
  id?: string
  email?: string
  name?: string
  role?: 'USER' | 'ADMIN'
  createdAt?: Date
}

export function createUser(overrides: UserInput = {}) {
  return {
    id: faker.string.uuid(),
    email: faker.internet.email(),
    name: faker.person.fullName(),
    role: 'USER' as const,
    createdAt: faker.date.past(),
    ...overrides
  }
}

// Usage
const user = createUser({ role: 'ADMIN' })
const users = Array.from({ length: 5 }, () => createUser())

// Factory with relations
export function createUserWithPosts(overrides: UserInput = {}) {
  const user = createUser(overrides)
  return {
    ...user,
    posts: Array.from({ length: 3 }, () => createPost({ authorId: user.id }))
  }
}

Builder Pattern#

// tests/factories/post.ts
import { faker } from '@faker-js/faker'

class PostBuilder {
  private data = {
    id: faker.string.uuid(),
    title: faker.lorem.sentence(),
    content: faker.lorem.paragraphs(3),
    published: false,
    authorId: faker.string.uuid(),
    createdAt: new Date(),
    tags: [] as string[]
  }

  withTitle(title: string) {
    this.data.title = title
    return this
  }

  withContent(content: string) {
    this.data.content = content
    return this
  }

  published() {
    this.data.published = true
    return this
  }

  draft() {
    this.data.published = false
    return this
  }

  byAuthor(authorId: string) {
    this.data.authorId = authorId
    return this
  }

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

  createdAt(date: Date) {
    this.data.createdAt = date
    return this
  }

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

export const postBuilder = () => new PostBuilder()

// Usage
const post = postBuilder()
  .withTitle('My Post')
  .published()
  .byAuthor('user-123')
  .withTags('tech', 'tutorial')
  .build()

Database Fixtures#

// tests/fixtures/database.ts
import { prisma } from '@/lib/db'
import { createUser } from '../factories/user'
import { createPost } from '../factories/post'

export async function seedUser(overrides = {}) {
  const data = createUser(overrides)
  return prisma.user.create({ data })
}

export async function seedUsers(count: number) {
  const users = Array.from({ length: count }, () => createUser())
  return prisma.user.createMany({ data: users })
}

export async function seedUserWithPosts(userOverrides = {}, postCount = 3) {
  const user = await seedUser(userOverrides)
  const posts = await Promise.all(
    Array.from({ length: postCount }, () =>
      prisma.post.create({
        data: createPost({ authorId: user.id })
      })
    )
  )
  return { user, posts }
}

export async function cleanDatabase() {
  const tables = ['Comment', 'Post', 'User']

  for (const table of tables) {
    await prisma.$executeRawUnsafe(`TRUNCATE TABLE "${table}" CASCADE`)
  }
}

// Test setup
beforeEach(async () => {
  await cleanDatabase()
})

afterAll(async () => {
  await prisma.$disconnect()
})

Fixture Files#

// tests/fixtures/products.json
[
  {
    "id": "prod_1",
    "name": "Basic Plan",
    "price": 999,
    "currency": "usd"
  },
  {
    "id": "prod_2",
    "name": "Pro Plan",
    "price": 2999,
    "currency": "usd"
  }
]

// tests/fixtures/index.ts
import products from './products.json'

export const fixtures = {
  products,
  users: [
    { id: 'user_1', email: 'admin@test.com', role: 'ADMIN' },
    { id: 'user_2', email: 'user@test.com', role: 'USER' }
  ],
  categories: [
    { id: 'cat_1', name: 'Electronics' },
    { id: 'cat_2', name: 'Clothing' }
  ]
}

// Usage
import { fixtures } from '../fixtures'

it('displays products', () => {
  render(<ProductList products={fixtures.products} />)
  expect(screen.getByText('Basic Plan')).toBeInTheDocument()
})

Scenario Fixtures#

// tests/fixtures/scenarios.ts
import { prisma } from '@/lib/db'
import { seedUser } from './database'

export async function setupTeamWithMembers() {
  const owner = await seedUser({ role: 'ADMIN' })
  const team = await prisma.team.create({
    data: {
      name: 'Test Team',
      ownerId: owner.id
    }
  })

  const members = await Promise.all([
    seedUser(),
    seedUser(),
    seedUser()
  ])

  await prisma.teamMember.createMany({
    data: members.map(m => ({
      userId: m.id,
      teamId: team.id,
      role: 'MEMBER'
    }))
  })

  return { owner, team, members }
}

export async function setupSubscriptionScenario() {
  const user = await seedUser()
  const subscription = await prisma.subscription.create({
    data: {
      userId: user.id,
      planId: 'pro',
      status: 'active',
      currentPeriodStart: new Date(),
      currentPeriodEnd: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000)
    }
  })

  return { user, subscription }
}

export async function setupExpiredSubscription() {
  const user = await seedUser()
  const subscription = await prisma.subscription.create({
    data: {
      userId: user.id,
      planId: 'pro',
      status: 'past_due',
      currentPeriodEnd: new Date(Date.now() - 1000) // Expired
    }
  })

  return { user, subscription }
}

// Usage in test
it('lists team members', async () => {
  const { team, members } = await setupTeamWithMembers()

  const result = await getTeamMembers(team.id)
  expect(result).toHaveLength(members.length)
})

Playwright Fixtures#

// tests/e2e/fixtures.ts
import { test as base, expect } from '@playwright/test'
import { LoginPage } from './pages/login.page'
import { DashboardPage } from './pages/dashboard.page'

type Fixtures = {
  loginPage: LoginPage
  dashboardPage: DashboardPage
  authenticatedPage: void
  testUser: { email: string; password: string }
}

export const test = base.extend<Fixtures>({
  // Page object fixtures
  loginPage: async ({ page }, use) => {
    await use(new LoginPage(page))
  },

  dashboardPage: async ({ page }, use) => {
    await use(new DashboardPage(page))
  },

  // Test data fixture
  testUser: async ({}, use) => {
    await use({
      email: 'test@example.com',
      password: 'password123'
    })
  },

  // Setup fixture that logs in
  authenticatedPage: async ({ page, testUser }, use) => {
    await page.goto('/login')
    await page.fill('[name="email"]', testUser.email)
    await page.fill('[name="password"]', testUser.password)
    await page.click('button[type="submit"]')
    await page.waitForURL('/dashboard')
    await use()
  }
})

export { expect }

// Usage
test('authenticated user can access settings', async ({
  authenticatedPage,
  page
}) => {
  await page.goto('/settings')
  await expect(page).toHaveURL('/settings')
})

test('user can login', async ({ loginPage, testUser, page }) => {
  await loginPage.goto()
  await loginPage.login(testUser.email, testUser.password)
  await expect(page).toHaveURL('/dashboard')
})

Fixture Composition#

// tests/fixtures/compose.ts
import { createUser } from '../factories/user'
import { createPost } from '../factories/post'
import { createComment } from '../factories/comment'

// Compose fixtures for complex scenarios
export function createBlogPost() {
  const author = createUser()
  const post = createPost({ authorId: author.id, published: true })

  const commenters = [createUser(), createUser()]
  const comments = commenters.map(user =>
    createComment({ postId: post.id, userId: user.id })
  )

  return {
    author,
    post,
    comments,
    commenters
  }
}

export function createActiveDiscussion() {
  const participants = Array.from({ length: 5 }, createUser)
  const author = participants[0]
  const post = createPost({ authorId: author.id, published: true })

  const comments = participants.slice(1).flatMap(user => [
    createComment({ postId: post.id, userId: user.id }),
    createComment({ postId: post.id, userId: user.id })
  ])

  return {
    author,
    post,
    comments,
    participants
  }
}

// Usage
it('displays comment count', () => {
  const { post, comments } = createBlogPost()

  render(<PostCard post={{ ...post, _count: { comments: comments.length } }} />)

  expect(screen.getByText('2 comments')).toBeInTheDocument()
})

Usage Instructions#

Create factory functions: Define functions that generate test objects
Use builder pattern: For complex objects with many configurations
Set up database fixtures: Create helpers for seeding test data
Define scenario fixtures: Combine multiple fixtures for common scenarios
Clean up between tests: Reset state in beforeEach hooks

Best Practices#

Use realistic data - Use faker for realistic test data
Allow overrides - Accept partial objects to customize fixtures
Keep fixtures focused - Each fixture should have a clear purpose
Clean between tests - Prevent test pollution
Compose fixtures - Build complex scenarios from simple fixtures
Document scenarios - Name fixtures clearly to describe their purpose
Avoid over-sharing - Don't make fixtures too generic

Vitest - Test runner setup
Integration Testing - Database testing
E2E Testing - Playwright fixtures
Mocking - Mocking dependencies