dd0c/products/03-alert-intelligence/test-architecture/test-architecture.md

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:

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.

---