# dd0c/alert — Test Architecture & TDD Strategy
**Product:** dd0c/alert (Alert Intelligence Platform)
**Version:** 2.0 | **Date:** 2026-02-28 | **Phase:** 7 — Test Architecture
**Stack:** TypeScript / Node.js 20 | Vitest | Testcontainers | LocalStack

---

## 1. Testing Philosophy & TDD Workflow

### 1.1 Core Principle

dd0c/alert is an intelligence platform — it makes decisions about what engineers see during incidents. A wrong suppression decision can hide a P1. A wrong correlation can create noise. **Tests are not optional; they are the specification.**

Every behavioral rule in the Correlation Engine, Noise Scorer, and Notification Router must be expressed as a failing test before a single line of implementation is written.

### 1.2 Red-Green-Refactor Cycle

```
RED    → Write a failing test that describes the desired behavior.
         The test must fail for the right reason (not a compile error).

GREEN  → Write the minimum code to make the test pass.
         No gold-plating. No "while I'm here" changes.

REFACTOR → Clean up the implementation without breaking tests.
           Extract functions, rename for clarity, remove duplication.
           Tests stay green throughout.
```

**Strict rule:** No implementation code is written without a failing test first. PRs that add implementation without a corresponding test are blocked by CI.

### 1.3 Test Naming Convention

Tests follow the `given_when_then` pattern using Vitest's `describe`/`it` structure:

```typescript
describe('NoiseScorer', () => {
  describe('given a deploy-correlated alert window', () => {
    it('should boost noise score by 25 points when deploy is attached', () => { ... });
    it('should add 5 additional points when PR title contains "feature-flag"', () => { ... });
    it('should not boost score above 50 when service matches never-suppress safelist', () => { ... });
  });
});
```

Test file naming: `{module}.test.ts` for unit tests, `{module}.integration.test.ts` for integration tests, `{journey}.e2e.test.ts` for E2E.

### 1.4 When Tests Lead (TDD Mandatory)

TDD is **mandatory** for:
- All noise scoring logic (`src/scoring/`)
- All correlation rules (`src/correlation/`)
- All suppression decisions (`src/suppression/`)
- HMAC validation per provider
- Canonical schema mapping (every provider parser)
- Feature flag circuit breaker logic
- Governance policy enforcement (`policy.json` evaluation)
- Any function with cyclomatic complexity > 3

TDD is **recommended but not enforced** for:
- Infrastructure glue code (SQS consumers, DynamoDB adapters)
- Slack Block Kit message formatting
- Dashboard API route handlers (covered by integration tests)

### 1.5 Test Ownership

Each epic owns its tests. The Correlation Engine team owns `src/correlation/**/*.test.ts`. No cross-team test ownership. If a test breaks due to a dependency change, the team that changed the dependency fixes the test.

---