70 lines
2.9 KiB
Markdown
70 lines
2.9 KiB
Markdown
|
# 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.
|
||
|
|
|
||
|
|
---
|