Instruction file imported from michaelbarone/cc3 (.cursor/rules/054-test-data-management.mdc). Copyright stays with the author.

description: Define standards for managing test data and fixtures across different test types globs: {e2e,test}/**/*.{ts,tsx} alwaysApply: true

Test Data Management Standards

Context

• Applies to all test data and fixtures
• Supports both E2E and unit tests
• Works with 053-playwright-e2e-standards.mdc
• Integrates with 051-vitest-react-testing-lib-testing-standards.mdc

Critical Rules

• ALWAYS use fixtures for API layer tests
• ONLY use Prisma mocks for service layer tests
• Keep data transformations in fixtures
• Follow proper directory structure
• Use factory functions for test data
• Clean up test data after use
• Document data dependencies
• Maintain type safety

Test Data Organization

1. Directory Structure

test/
├── fixtures/           # API layer test fixtures
│   ├── factories.ts   # Factory functions with API transformations
│   ├── data/         # Static test data
│   └── responses/    # Expected API responses
├── mocks/             # Service layer mocks
│   ├── prisma.ts     # Prisma client mock
│   └── services/     # Service-specific mocks
└── helpers/           # Test utilities
    ├── setup.ts
    └── cleanup.ts

2. Layer-Specific Data Management

API Layer

// GOOD: Factory function with API transformations
export function createMockUser(overrides?: Partial<User>): User {
  const now = new Date();
  return {
    id: `user-${Math.random().toString(36).slice(2, 9)}`,
    createdAt: now.toISOString(), // API format
    updatedAt: now.toISOString(), // API format
    ...overrides
  };
}

// Usage in API test
test("GET /api/users/:id", async () => {
  const mockUser = createMockUser();
  prismaMock.user.findUnique.mockResolvedValue(mockUser);

  const response = await GET(`/api/users/${mockUser.id}`);
  const data = await response.json();

  expect(data).toEqual(mockUser); // Dates match API format
});

Service Layer

// GOOD: Raw data for service tests
const rawUserData = {
  id: "1",
  createdAt: new Date(), // Native Date object
  updatedAt: new Date()
};

// Usage in service test
test("createUser service", async () => {
  prismaMock.user.create.mockResolvedValue(rawUserData);
  const result = await userService.createUser(rawUserData);
  expect(result.createdAt).toBeInstanceOf(Date);
});

Factory Functions

1. API Fixtures

// Factory with API transformations
export function createMockPost(
  author: User,
  overrides?: Partial<Post>
): Post {
  const now = new Date();
  return {
    id: `post-${Date.now()}`,
    title: "Test Post",
    content: "Test content",
    authorId: author.id,
    createdAt: now.toISOString(), // API format
    updatedAt: now.toISOString(), // API format
    ...overrides
  };
}

2. Service Layer Data

// Raw data factory for services
export function createRawPost(
  author: User,
  overrides?: Partial<Post>
): Post {
  const now = new Date();
  return {
    id: `post-${Date.now()}`,
    title: "Test Post",
    content: "Test content",
    authorId: author.id,
    createdAt: now, // Date object
    updatedAt: now, // Date object
    ...overrides
  };
}

Best Practices

1. Data Transformations:

   • Keep transformations in fixtures
   • Document transformation logic
   • Maintain consistency across fixtures
   • Test transformation edge cases

2. Type Safety:

   • Use TypeScript interfaces
   • Validate fixture data
   • Test type compatibility
   • Document type requirements

3. Data Cleanup:

   • Clean up after each test
   • Use transaction boundaries
   • Handle cleanup failures
   • Document cleanup requirements

Dependencies

• 053-playwright-e2e-standards.mdc
• 051-vitest-react-testing-lib-testing-standards.mdc
• 056-test-prisma-standards.mdc

metadata: priority: high version: 1.2.0 tags: - testing - data - fixtures - mocking