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:**
```typescript
// 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:**
```typescript
// 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

```bash
# 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

```typescript
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

```typescript
// 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

```typescript
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

```bash
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:**
```typescript
it('should call getUserById', () => {
  service.login(email, password);
  expect(mockService.getUserById).toHaveBeenCalled();
});
```

**✅ Good:**
```typescript
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:**
```typescript
it('works', () => { ... });
it('test 1', () => { ... });
```

**✅ Good:**
```typescript
it('should return 401 for invalid credentials', () => { ... });
it('should create session with 24h expiration', () => { ... });
```

### 3. Arrange-Act-Assert Pattern

```typescript
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

```typescript
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

```typescript
// ❌ 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

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

### Skip Test

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

### Verbose Output

```bash
pnpm test --reporter=verbose
```

### Debug in VS Code

Add to `.vscode/launch.json`:
```json
{
  "type": "node",
  "request": "launch",
  "name": "Vitest",
  "runtimeExecutable": "pnpm",
  "runtimeArgs": ["test", "--no-coverage"],
  "console": "integratedTerminal"
}
```

## Test Database

Use separate test database:

```bash
# .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](3-committing.md)
- **Learn Database Testing** — [Database](../2-database/3-prisma.md)
- **Check Code Style** — [Google TypeScript Style Guide](https://google.github.io/styleguide/tsguide.html)