Comprehensive guide for testing standards, patterns, and best practices in the Lilith platform.
Table of Contents#
- Overview
- Testing Strategy
- Test Types
- Test Structure
- Coverage Requirements
- Mocking Guidelines
- Test Data Management
- Performance Testing
- CI/CD 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#
text
┌─────────┐
│ 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#
text
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 - Build and deployment
- Development Workflow - Development process
- API Testing - API test patterns