stack/docs/2-development/1-workflow/2-testing.md

Testing Requirements

Test-driven development standards and practices for Mosaic Stack.

Testing Philosophy

• Test-Driven Development (TDD) — Write tests before implementation
• Minimum 85% coverage for all new code
• All tests must pass before PR approval
• No untested code in production

Test Types

Unit Tests

Test individual functions and methods in isolation.

Location: *.spec.ts next to source file

Example:

// apps/api/src/auth/auth.service.spec.ts
describe('AuthService', () => {
  it('should create a session for valid user', async () => {
    const result = await authService.createSession(mockUser);
    expect(result.session.token).toBeDefined();
  });
});

Integration Tests

Test interactions between components.

Location: *.integration.spec.ts in module directory

Example:

// apps/api/src/auth/auth.integration.spec.ts
describe('Auth Integration', () => {
  it('should complete full login flow', async () => {
    const login = await request(app.getHttpServer())
      .post('/auth/sign-in')
      .send({ email, password });
    expect(login.status).toBe(200);
  });
});

E2E Tests

Test complete user flows across the entire stack.

Location: apps/web/tests/e2e/ (when implemented)

Framework: Playwright

Running Tests

# All tests
pnpm test

# Watch mode (re-run on changes)
pnpm test:watch

# Coverage report
pnpm test:coverage

# Specific file
pnpm test apps/api/src/auth/auth.service.spec.ts

# API tests only
pnpm test:api

# E2E tests (when implemented)
pnpm test:e2e

Writing Tests

Structure

import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';

describe('ComponentName', () => {
  beforeEach(() => {
    // Setup
  });

  afterEach(() => {
    // Cleanup
  });

  describe('methodName', () => {
    it('should handle normal case', () => {
      // Arrange
      const input = 'test';

      // Act
      const result = component.method(input);

      // Assert
      expect(result).toBe('expected');
    });

    it('should handle error case', () => {
      expect(() => component.method(null)).toThrow();
    });
  });
});

Mocking

// Mock service dependency
const mockPrismaService = {
  user: {
    findUnique: vi.fn(),
    create: vi.fn(),
  },
};

// Mock module
vi.mock('./some-module', () => ({
  someFunction: vi.fn(() => 'mocked'),
}));

Testing Async Code

it('should complete async operation', async () => {
  const result = await asyncFunction();
  expect(result).toBeDefined();
});

// Or with resolves/rejects
it('should resolve with data', async () => {
  await expect(asyncFunction()).resolves.toBe('data');
});

it('should reject with error', async () => {
  await expect(failingFunction()).rejects.toThrow('Error');
});

Coverage Requirements

Minimum Coverage

• Statements: 85%
• Branches: 80%
• Functions: 85%
• Lines: 85%

View Coverage Report

pnpm test:coverage

# Opens HTML report
open coverage/index.html

Exemptions

Some code types may have lower coverage requirements:

• DTOs/Interfaces: No coverage required (type checking sufficient)
• Constants: No coverage required
• Database migrations: Manual verification acceptable

Always document exemptions in PR description.

Best Practices

1. Test Behavior, Not Implementation

❌ Bad:

it('should call getUserById', () => {
  service.login(email, password);
  expect(mockService.getUserById).toHaveBeenCalled();
});

✅ Good:

it('should return session for valid credentials', async () => {
  const result = await service.login(email, password);
  expect(result.session.token).toBeDefined();
  expect(result.user.email).toBe(email);
});

2. Use Descriptive Test Names

❌ Bad:

it('works', () => { ... });
it('test 1', () => { ... });

✅ Good:

it('should return 401 for invalid credentials', () => { ... });
it('should create session with 24h expiration', () => { ... });

3. Arrange-Act-Assert Pattern

it('should calculate total correctly', () => {
  // Arrange - Set up test data
  const items = [{ price: 10 }, { price: 20 }];

  // Act - Execute the code being tested
  const total = calculateTotal(items);

  // Assert - Verify the result
  expect(total).toBe(30);
});

4. Test Edge Cases

describe('validateEmail', () => {
  it('should accept valid email', () => {
    expect(validateEmail('user@example.com')).toBe(true);
  });

  it('should reject empty string', () => {
    expect(validateEmail('')).toBe(false);
  });

  it('should reject null', () => {
    expect(validateEmail(null)).toBe(false);
  });

  it('should reject invalid format', () => {
    expect(validateEmail('notanemail')).toBe(false);
  });
});

5. Keep Tests Independent

// ❌ Bad - Tests depend on order
let userId;
it('should create user', () => {
  userId = createUser();
});
it('should get user', () => {
  getUser(userId); // Fails if previous test fails
});

// ✅ Good - Each test is independent
it('should create user', () => {
  const userId = createUser();
  expect(userId).toBeDefined();
});
it('should get user', () => {
  const userId = createUser(); // Create fresh data
  const user = getUser(userId);
  expect(user).toBeDefined();
});

CI/CD Integration

Tests run automatically on:

• Every push to feature branch
• Every pull request
• Before merge to develop

Pipeline must pass before merging.

Debugging Tests

Run Single Test

it.only('should test specific case', () => {
  // Only this test runs
});

Skip Test

it.skip('should test something', () => {
  // This test is skipped
});

Verbose Output

pnpm test --reporter=verbose

Debug in VS Code

Add to .vscode/launch.json:

{
  "type": "node",
  "request": "launch",
  "name": "Vitest",
  "runtimeExecutable": "pnpm",
  "runtimeArgs": ["test", "--no-coverage"],
  "console": "integratedTerminal"
}

Test Database

Use separate test database:

# .env.test
TEST_DATABASE_URL=postgresql://mosaic:mosaic@localhost:5432/mosaic_test

# Reset test DB before each run
pnpm test:db:reset

Next Steps

• Review Commit Guidelines — Committing
• Learn Database Testing — Database
• Check Code Style — Google TypeScript Style Guide