test-architecture

Test Architecture

Well-structured tests are maintainable, fast, and reliable. This skill covers how to organize test files, create reusable fixtures and factories, ensure test isolation, and configure test environments.

When to Use

• User is setting up a new test suite or framework
• User asks about test file organization or naming
• User needs test fixtures, factories, or seed data
• Tests are flaky due to shared state or ordering issues
• User asks about database cleanup between tests
• User needs test configuration (vitest.config, jest.config, conftest.py)

Core Patterns

Test File Organization

Co-locate tests with source files for discoverability:

src/
  services/
    auth.ts
    auth.test.ts          # Unit tests next to source
    billing.ts
    billing.test.ts
  routes/
    users.ts
    users.test.ts
test/
  integration/
    api.test.ts           # Integration tests in separate dir
  e2e/
    login.spec.ts         # E2E tests in dedicated dir
  fixtures/
    users.json            # Shared test data
  factories/
    user.factory.ts       # Data factories
  helpers/
    setup.ts              # Test setup utilities
    db.ts                 # Database helpers

Fixtures: Static Test Data

Fixtures are pre-defined data objects for predictable testing:

// test/fixtures/users.ts
export const validUser = {
  email: '[email protected]',
  name: 'Test User',
  role: 'member',
} as const

export const adminUser = {
  email: '[email protected]',
  name: 'Admin User',
  role: 'admin',
} as const

export const invalidUser = {
  email: 'not-an-email',
  name: '',
  role: 'unknown',
} as const

Usage in tests:

import { validUser, adminUser } from '../fixtures/users'

it('creates a user', async () => {
  const result = await createUser(validUser)
  expect(result.email).toBe(validUser.email)
})

Factories: Dynamic Test Data

Factories generate unique test data with sensible defaults. Override only what matters for each test: