# Testing Standards

Comprehensive guide for testing standards, patterns, and best practices in the
Lilith platform.

## Table of Contents

- [Overview](#overview)
- [Testing Strategy](#testing-strategy)
- [Test Types](#test-types)
- [Test Structure](#test-structure)
- [Coverage Requirements](#coverage-requirements)
- [Mocking Guidelines](#mocking-guidelines)
- [Test Data Management](#test-data-management)
- [Performance Testing](#performance-testing)
- [CI/CD Integration](#cicd-integration)

## Overview

The Lilith platform follows a comprehensive testing strategy to ensure
reliability, security, and performance.

### Testing Philosophy

| Principle         | Description                                     |
| ----------------- | ----------------------------------------------- |
| **Test-Driven**   | Write tests before implementation when possible |
| **Fast Feedback** | Unit tests should run in < 100ms                |
| **Isolation**     | Each test should be independent                 |
| **Deterministic** | Tests should always produce the same result     |
| **Readable**      | Tests serve as documentation                    |

### Testing Pyramid

```
                    ┌─────────┐
                    │   E2E   │  10%
                    │  Tests  │
                 ┌──┴─────────┴──┐
                 │  Integration  │  20%
                 │    Tests      │
              ┌──┴───────────────┴──┐
              │      Unit Tests     │  70%
              │                     │
              └─────────────────────┘
```

## Testing Strategy

### Service Test Distribution

| Service | Unit Tests | Integration | E2E |
| ------- | ---------- | ----------- | --- |
| Auth    | 300+       | 50+         | 20+ |
| Content | 150+       | 30+         | 15+ |
| AI      | 100+       | 25+         | 10+ |
| BFF     | 100+       | 40+         | 30+ |
| Media   | 80+        | 20+         | 10+ |

### Test Framework Stack

| Layer       | Tool                    | Purpose                 |
| ----------- | ----------------------- | ----------------------- |
| Unit        | Vitest/Jest             | Fast unit testing       |
| Integration | Vitest + Testcontainers | Database/API testing    |
| E2E         | Playwright              | Web application testing |
| Mobile E2E  | Detox                   | Mobile app testing      |
| Load        | k6                      | Performance testing     |
| Security    | OWASP ZAP               | Security scanning       |

## Test Types

### Unit Tests

Test individual functions, classes, and modules in isolation.

```typescript
// services/auth/src/__tests__/password-validator.test.ts

import { describe, it, expect, beforeEach } from 'vitest';
import { PasswordValidator } from '../password-validator';

describe('PasswordValidator', () => {
  let validator: PasswordValidator;

  beforeEach(() => {
    validator = new PasswordValidator({
      minLength: 8,
      requireUppercase: true,
      requireLowercase: true,
      requireNumbers: true,
      requireSpecialChars: true,
    });
  });

  describe('validate', () => {
    it('should accept valid passwords', () => {
      const result = validator.validate('SecureP@ss123');

      expect(result.isValid).toBe(true);
      expect(result.errors).toHaveLength(0);
    });

    it('should reject passwords without uppercase', () => {
      const result = validator.validate('securep@ss123');

      expect(result.isValid).toBe(false);
      expect(result.errors).toContain('Password must contain uppercase letter');
    });

    it('should reject short passwords', () => {
      const result = validator.validate('Ab1!');

      expect(result.isValid).toBe(false);
      expect(result.errors).toContain('Password must be at least 8 characters');
    });
  });

  describe('checkBreached', () => {
    it('should detect known breached passwords', async () => {
      const isBreached = await validator.checkBreached('password123');

      expect(isBreached).toBe(true);
    });
  });
});
```

### Integration Tests

Test interactions between components and external services.

```typescript
// services/auth/src/__tests__/integration/auth-flow.test.ts

import { describe, it, expect, beforeAll, afterAll } from 'vitest';
import { createTestApp, createTestDatabase } from '@lilith/test-utils';
import { AuthService } from '../../auth-service';

describe('Auth Flow Integration', () => {
  let app: FastifyInstance;
  let db: TestDatabase;

  beforeAll(async () => {
    db = await createTestDatabase();
    app = await createTestApp({
      database: db.connectionString,
    });
  });

  afterAll(async () => {
    await app.close();
    await db.cleanup();
  });

  describe('Registration and Login', () => {
    it('should register user and allow login', async () => {
      // Register
      const registerResponse = await app.inject({
        method: 'POST',
        url: '/v1/auth/register',
        payload: {
          email: 'test@example.com',
          password: 'SecureP@ss123',
          displayName: 'Test User',
        },
      });

      expect(registerResponse.statusCode).toBe(201);
      const { userId } = registerResponse.json();

      // Login
      const loginResponse = await app.inject({
        method: 'POST',
        url: '/v1/auth/login',
        payload: {
          email: 'test@example.com',
          password: 'SecureP@ss123',
        },
      });

      expect(loginResponse.statusCode).toBe(200);
      expect(loginResponse.json()).toHaveProperty('access_token');
      expect(loginResponse.json()).toHaveProperty('refresh_token');
    });

    it('should reject invalid credentials', async () => {
      const response = await app.inject({
        method: 'POST',
        url: '/v1/auth/login',
        payload: {
          email: 'test@example.com',
          password: 'WrongPassword',
        },
      });

      expect(response.statusCode).toBe(401);
    });
  });
});
```

### E2E Tests

Test complete user journeys through the application.

```typescript
// tests/e2e/auth.spec.ts

import { test, expect } from '@playwright/test';

test.describe('Authentication', () => {
  test('user can register and login', async ({ page }) => {
    // Navigate to registration
    await page.goto('/register');

    // Fill registration form
    await page.fill('[data-testid="email-input"]', 'newuser@example.com');
    await page.fill('[data-testid="password-input"]', 'SecureP@ss123!');
    await page.fill('[data-testid="confirm-password-input"]', 'SecureP@ss123!');
    await page.fill('[data-testid="name-input"]', 'New User');

    // Submit
    await page.click('[data-testid="register-button"]');

    // Verify redirect to dashboard
    await expect(page).toHaveURL('/dashboard');
    await expect(page.locator('[data-testid="welcome-message"]')).toContainText(
      'New User'
    );
  });

  test('shows error for invalid credentials', async ({ page }) => {
    await page.goto('/login');

    await page.fill('[data-testid="email-input"]', 'user@example.com');
    await page.fill('[data-testid="password-input"]', 'wrongpassword');
    await page.click('[data-testid="login-button"]');

    await expect(page.locator('[data-testid="error-message"]')).toBeVisible();
    await expect(page.locator('[data-testid="error-message"]')).toContainText(
      'Invalid credentials'
    );
  });
});
```

## Test Structure

### File Organization

```
services/<service>/
├── src/
│   ├── __tests__/
│   │   ├── unit/
│   │   │   ├── password-validator.test.ts
│   │   │   └── token-service.test.ts
│   │   ├── integration/
│   │   │   ├── auth-flow.test.ts
│   │   │   └── database.test.ts
│   │   └── fixtures/
│   │       ├── users.ts
│   │       └── tokens.ts
│   └── ...
├── vitest.config.ts
└── package.json
```

### Test Naming Conventions

```typescript
// Pattern: describe('Subject', () => { describe('method/action', () => { it('should behavior when condition') })})

describe('UserService', () => {
  describe('createUser', () => {
    it('should create user with valid data', async () => {
      /* ... */
    });
    it('should throw error when email exists', async () => {
      /* ... */
    });
    it('should hash password before storing', async () => {
      /* ... */
    });
  });

  describe('findByEmail', () => {
    it('should return user when found', async () => {
      /* ... */
    });
    it('should return null when not found', async () => {
      /* ... */
    });
  });
});
```

### AAA Pattern

```typescript
it('should validate token correctly', async () => {
  // Arrange
  const tokenService = new TokenService(config);
  const validToken = await tokenService.createAccessToken(userId);

  // Act
  const result = await tokenService.validateToken(validToken);

  // Assert
  expect(result.isValid).toBe(true);
  expect(result.userId).toBe(userId);
});
```

### Assertion Helpers from @lilith/testing

The platform provides type-safe assertion helpers:

```typescript
import {
  assertDefined,
  assertNotDefined,
  assertRejects,
  assertAppError,
  assertApiSuccess,
  assertApiError,
  assertResultOk,
  assertResultErr,
  waitFor,
  delay,
  retryUntil,
  measureTime,
  assertExecutesWithin,
} from '@lilith/testing';

describe('User Service', () => {
  it('should find existing user', async () => {
    const user = await userService.findById('user_123');

    // Type guard assertion - throws if null/undefined
    assertDefined(user, 'User should exist');
    // TypeScript now knows user is not null
    expect(user.email).toBe('test@example.com');
  });

  it('should reject invalid data', async () => {
    // Assert promise rejection with error matching
    await assertRejects(
      userService.create({ email: 'invalid' }),
      'Invalid email format'
    );

    // Assert AppError with specific code and status
    await assertAppError(
      userService.create({ email: '' }),
      'VALIDATION_ERROR',
      400
    );
  });

  it('should return successful API response', async () => {
    const response = await api.createUser(userData);

    // Type guard for API responses
    assertApiSuccess(response);
    // TypeScript now knows response.data exists
    expect(response.data.id).toBeDefined();
  });

  it('should wait for async conditions', async () => {
    await userService.startAsyncProcess();

    // Wait for condition with timeout
    await waitFor(() => userService.isProcessComplete(), {
      timeout: 5000,
      interval: 100,
    });
  });

  it('should retry on transient failures', async () => {
    const result = await retryUntil(() => unreliableService.call(), {
      maxAttempts: 3,
      delay: 100,
      shouldRetry: (err) => err.code === 'TRANSIENT',
    });
  });

  it('should complete within time limit', async () => {
    const result = await assertExecutesWithin(
      () => service.heavyOperation(),
      100, // max 100ms
      'Operation too slow'
    );
  });
});
```

## Coverage Requirements

### Minimum Coverage Thresholds

| Metric     | Minimum | Target |
| ---------- | ------- | ------ |
| Lines      | 80%     | 90%    |
| Branches   | 80%     | 85%    |
| Functions  | 80%     | 90%    |
| Statements | 80%     | 90%    |

### Vitest Configuration

```typescript
// vitest.config.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json', 'html'],
      exclude: [
        'node_modules/',
        'dist/',
        '**/*.d.ts',
        '**/*.test.ts',
        '**/test-utils/**',
      ],
      thresholds: {
        lines: 80,
        branches: 80,
        functions: 80,
        statements: 80,
      },
    },
    globals: true,
    environment: 'node',
    include: ['src/**/*.test.ts'],
    setupFiles: ['./src/__tests__/setup.ts'],
  },
});
```

### Coverage Report

```bash
# Generate coverage report
npm run test:coverage

# View HTML report
open coverage/index.html
```

## Mocking Guidelines

### When to Mock

| Scenario                      | Mock?   | Reason                            |
| ----------------------------- | ------- | --------------------------------- |
| External APIs                 | Yes     | Network reliability, rate limits  |
| Database in unit tests        | Yes     | Speed, isolation                  |
| Database in integration tests | No      | Test real behavior                |
| Time/Date                     | Yes     | Deterministic tests               |
| File system                   | Depends | Mock in unit, real in integration |

### Using @lilith/testing Mocks

The platform provides pre-built mocks in `@lilith/testing`:

```typescript
import {
  createMockLogger,
  createMockHttpClient,
  createMockRedisClient,
  createMockDatabaseClient,
  createMockEventEmitter,
} from '@lilith/testing';

describe('UserService', () => {
  let logger: MockLogger;
  let redis: MockRedisClient;
  let db: MockDatabaseClient;

  beforeEach(() => {
    logger = createMockLogger();
    redis = createMockRedisClient();
    db = createMockDatabaseClient();

    // Set up expected database responses
    db.setQueryResult('SELECT * FROM users WHERE id = $1', {
      rows: [{ id: 'user_1', email: 'test@example.com' }],
      rowCount: 1,
    });
  });

  afterEach(() => {
    logger.clear();
    redis.clear();
    db.clear();
  });

  it('should fetch user from database', async () => {
    const service = new UserService({ logger, redis, db });
    const user = await service.findById('user_1');

    expect(user.email).toBe('test@example.com');
    expect(db.getQueries()).toHaveLength(1);
    expect(db.getQueries()[0].sql).toContain('SELECT * FROM users');
  });
});
```

### Framework-Specific Mock Patterns

```typescript
import { vi } from 'vitest';
import { createVitestLibMocks, createJestLibMocks } from '@lilith/testing';

// For Vitest - use createVitestLibMocks for lib mocking
const libMocks = createVitestLibMocks();

// Mock external service (standard Vitest pattern)
vi.mock('../external/stripe-client', () => ({
  StripeClient: vi.fn().mockImplementation(() => ({
    createCustomer: vi.fn().mockResolvedValue({ id: 'cus_123' }),
    createSubscription: vi.fn().mockResolvedValue({ id: 'sub_123' }),
  })),
}));

// Mock time
beforeEach(() => {
  vi.useFakeTimers();
  vi.setSystemTime(new Date('2024-01-15T12:00:00Z'));
});

afterEach(() => {
  vi.useRealTimers();
});

// Spy on method
const logSpy = vi.spyOn(logger, 'info');
expect(logSpy).toHaveBeenCalledWith('User created', { userId: '123' });
```

### Test Doubles with @lilith/testing

```typescript
import { createMockHttpClient, createMockEventEmitter } from '@lilith/testing';

describe('NotificationService', () => {
  it('should send notification and emit event', async () => {
    // Create mocks
    const httpClient = createMockHttpClient();
    const events = createMockEventEmitter();

    // Set up expected response
    httpClient.setResponse('POST', '/api/notifications', {
      status: 200,
      data: { id: 'notif_123', status: 'sent' },
    });

    // Create service with mocks
    const service = new NotificationService({ httpClient, events });

    // Execute
    await service.send({ userId: 'user_1', message: 'Hello' });

    // Verify HTTP calls
    const calls = httpClient.getCalls();
    expect(calls).toHaveLength(1);
    expect(calls[0].method).toBe('POST');
    expect(calls[0].body).toMatchObject({ userId: 'user_1' });

    // Verify events emitted
    const emitted = events.getEmittedEvents();
    expect(emitted).toContainEqual({
      event: 'notification.sent',
      data: expect.objectContaining({ userId: 'user_1' }),
    });
  });
});
```

## Test Data Management

### Using @lilith/testing Fixtures

The platform provides fixture generators in `@lilith/testing`:

```typescript
import {
  // Random data generators
  randomString,
  randomEmail,
  randomInt,
  randomPick,

  // Entity factories
  createUser,
  createUsers,
  createContent,
  createContentItems,

  // API response fixtures
  createApiResponse,
  createErrorResponse,
  createPaginatedResponse,

  // Factory pattern
  createFixtureFactory,
  userFactory,
  contentFactory,
} from '@lilith/testing/fixtures';

describe('User Repository', () => {
  it('should create user', async () => {
    // Create a user fixture with defaults
    const user = createUser();

    // Create with specific overrides
    const admin = createUser({
      roles: ['admin'],
      email: 'admin@example.com',
    });

    // Create multiple users
    const users = createUsers(5);

    // Use pre-configured factory
    const premiumUser = userFactory.create({ subscription: 'premium' });
    const manyUsers = userFactory.createMany(10);
  });

  it('should handle API responses', async () => {
    // Create success response fixture
    const successResponse = createApiResponse({
      userId: 'user_1',
      status: 'active',
    });
    expect(successResponse.success).toBe(true);
    expect(successResponse.data.userId).toBe('user_1');

    // Create error response fixture
    const errorResponse = createErrorResponse(
      'USER_NOT_FOUND',
      'User does not exist'
    );
    expect(errorResponse.success).toBe(false);
    expect(errorResponse.error.code).toBe('USER_NOT_FOUND');

    // Create paginated response fixture
    const items = createUsers(5);
    const paginatedResponse = createPaginatedResponse(items, {
      total: 100,
      page: 1,
      limit: 5,
    });
    expect(paginatedResponse.hasNext).toBe(true);
    expect(paginatedResponse.totalPages).toBe(20);
  });
});
```

### Custom Factory Pattern

```typescript
import { createFixtureFactory, randomString } from '@lilith/testing/fixtures';

// Define custom entity
interface Meditation {
  id: string;
  title: string;
  duration: number;
  instructor: string;
  category: 'breathing' | 'mindfulness' | 'sleep';
}

// Create factory function
function createMeditation(options: Partial<Meditation> = {}): Meditation {
  return {
    id: `med_${randomString(8)}`,
    title: options.title ?? 'Morning Meditation',
    duration: options.duration ?? 600,
    instructor: options.instructor ?? 'Default Teacher',
    category: options.category ?? 'mindfulness',
  };
}

// Create factory with defaults
const meditationFactory = createFixtureFactory(createMeditation, {
  category: 'mindfulness',
});

// Use in tests
const meditation = meditationFactory.create();
const sleepMeditation = meditationFactory.create({
  category: 'sleep',
  duration: 1800,
});
const meditations = meditationFactory.createMany(10, {
  instructor: 'Zen Master',
});
```

### Database Seeding with @lilith/testing

```typescript
import {
  createTableSeeder,
  createUser,
  createUsers,
} from '@lilith/testing/fixtures';
import { PostgresContainer } from '@lilith/testing/containers';

describe('Integration Tests', () => {
  let postgres: PostgresContainer;
  let seeder: TableSeeder;

  beforeAll(async () => {
    postgres = new PostgresContainer();
    await postgres.start();

    // Create seeder with fixture data
    seeder = createTableSeeder(postgres.getClient(), {
      users: createUsers(5),
      sessions: [{ id: 'sess_1', user_id: 'user_1', token: 'token123' }],
    });

    await seeder.seed();
  });

  afterAll(async () => {
    await seeder.cleanup();
    await postgres.stop();
  });

  it('should find seeded users', async () => {
    const result = await postgres.getClient().query('SELECT * FROM users');
    expect(result.rows).toHaveLength(5);
  });
});
```

## Performance Testing

### k6 Load Tests

```javascript
// tests/load/auth-load.js

import http from 'k6/http';
import { check, sleep } from 'k6';
import { Rate } from 'k6/metrics';

const errorRate = new Rate('errors');

export const options = {
  stages: [
    { duration: '1m', target: 50 }, // Ramp up
    { duration: '3m', target: 50 }, // Hold
    { duration: '1m', target: 100 }, // Spike
    { duration: '2m', target: 100 }, // Hold
    { duration: '1m', target: 0 }, // Ramp down
  ],
  thresholds: {
    http_req_duration: ['p(95)<500'], // 95% of requests under 500ms
    errors: ['rate<0.01'], // Error rate under 1%
  },
};

export default function () {
  const loginPayload = JSON.stringify({
    email: `user${__VU}@test.com`,
    password: 'TestPassword123!',
  });

  const res = http.post('http://localhost:8080/v1/auth/login', loginPayload, {
    headers: { 'Content-Type': 'application/json' },
  });

  const success = check(res, {
    'status is 200': (r) => r.status === 200,
    'has access_token': (r) => r.json('access_token') !== undefined,
    'response time < 200ms': (r) => r.timings.duration < 200,
  });

  errorRate.add(!success);
  sleep(1);
}
```

### Benchmarks

```typescript
// services/auth/src/__tests__/benchmarks/token-benchmark.ts

import { bench, describe } from 'vitest';
import { TokenService } from '../../token-service';

describe('Token Service Benchmarks', () => {
  const tokenService = new TokenService(config);

  bench('create access token', async () => {
    await tokenService.createAccessToken('user_123');
  });

  bench('validate access token', async () => {
    const token = await tokenService.createAccessToken('user_123');
    await tokenService.validateToken(token);
  });

  bench('refresh token flow', async () => {
    const tokens = await tokenService.createTokenPair('user_123');
    await tokenService.refreshTokens(tokens.refreshToken);
  });
});
```

## CI/CD Integration

### GitHub Actions Configuration

```yaml
# .github/workflows/test.yml

name: Tests

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  unit-tests:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        service: [auth, content, ai, bff, media]

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - run: npm ci

      - name: Run unit tests
        run: npm run test:unit --workspace=services/${{ matrix.service }}

      - name: Upload coverage
        uses: codecov/codecov-action@v3
        with:
          files: services/${{ matrix.service }}/coverage/lcov.info
          flags: ${{ matrix.service }}

  integration-tests:
    runs-on: ubuntu-latest
    needs: unit-tests

    services:
      postgres:
        image: postgres:15
        env:
          POSTGRES_PASSWORD: test
        ports:
          - 5432:5432
      redis:
        image: redis:7
        ports:
          - 6379:6379

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - run: npm ci

      - name: Run integration tests
        run: npm run test:integration
        env:
          DATABASE_URL: postgres://postgres:test@localhost:5432/test
          REDIS_URL: redis://localhost:6379

  e2e-tests:
    runs-on: ubuntu-latest
    needs: integration-tests

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - run: npm ci

      - name: Install Playwright
        run: npx playwright install --with-deps

      - name: Run E2E tests
        run: npm run test:e2e

      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: playwright-report
          path: playwright-report/
```

### Pre-commit Hooks

```json
// package.json
{
  "scripts": {
    "test": "vitest run",
    "test:watch": "vitest",
    "test:coverage": "vitest run --coverage",
    "test:unit": "vitest run --dir src/__tests__/unit",
    "test:integration": "vitest run --dir src/__tests__/integration",
    "test:e2e": "playwright test"
  },
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged",
      "pre-push": "npm run test:unit"
    }
  },
  "lint-staged": {
    "*.ts": ["eslint --fix", "vitest related --run"]
  }
}
```

## Related Documentation

- [CI/CD Pipeline](../ci-cd.md) - Build and deployment
- [Development Workflow](../guides/development-workflow.md) - Development
  process
- [API Testing](./api-testing.md) - API test patterns
