tdd

name

tdd

description

Test-first loop for NEW Coremetry backend work — write the failing table-driven test against a pure seam (SQL builder, decision function, key/format helper) BEFORE the implementation, iterate to green, then ship via /release. Use when building a new backend feature, endpoint or pure helper, or when the operator says "tdd ile" / "test-first"; it extends the bug-fix regression-test gate (v0.5.447) to features. Prefer this repo's stdlib table-driven style over any external testing skill — no testify, goleak or testcontainers. Do NOT use for frontend work (vitest rules live in /frontend-conventions), for a production bug (use /bugfix), or when the change is pure I/O wiring with no testable seam.

/tdd — test-first feature loop

The bug-fix flow already enforces "every fix ships with the test that would catch the regression" (v0.5.447). This skill runs the same discipline FORWARD: for a new feature, the test exists and FAILS before the implementation does. Horizon seed #3 (2026-05-28); drafted v0.8.277.

When to use

• New backend endpoint, chstore method, evaluator rule, or any pure helper (SQL builders, formatters, URL codecs, filters).
• Frontend pure logic (lib/*.ts — compilers, codecs, segmenters).
• NOT for: UI layout/JSX work (no meaningful unit seam — gates are tsc + lint + manual check), one-line config changes, docs.

The loop

1. Extract the seam FIRST

Before writing anything, name the pure function the feature pivots on. If the design doesn't have one, reshape it until it does — this is the same move the bug-fix flow uses ("if the fix lives behind ClickHouse / network I/O, extract the pure SQL-building helper"). The seam is what makes the test cheap and the feature reviewable.

Coremetry seam examples: snapshotLogsJSON (share capture), buildFieldStatsBody (ES cost guards), compileSearch / extractHighlightTerms (log filters), snapAnomalyWindow (key cardinality), filterHiddenTopologyEdges, serviceGraphToMap, withProblemParam.

2. Write the failing test

• Go: table-driven, <package>/<feature>_test.go, comment header cites the upcoming vX.Y.Z + WHAT CONTRACT the feature promises.
• TS: vitest file next to the module (lib/foo.test.ts).
• Include the hostile cases up front: empty input, unit variants (the v0.6.36 lesson — exercise EVERY unit a template accepts), boundary/overflow, garbage tolerance for parsers.
• RUN IT. It must FAIL (compile error counts). A test that passes before the implementation exists is testing nothing — fix the test, not your morale.

3. Implement to green — smallest honest step

Write the implementation the test demands, no more. Re-run: go test ./internal/<pkg>/ -run <TestName> or npm run test -- --run <file>. Iterate until green. Don't touch the test to make it pass unless the CONTRACT was wrong — and say so out loud when that happens.

4. Wire + full gates

Only after green: wire the seam into the handler/page (route registration in api.go per the backend rules, serveCached + hash-all-inputs key, auth/audit if it writes). Then the standard release gates: npx tsc --noEmit / go build ./... / go test ./... / make audit.

5. Release

Normal /release flow — one logical unit per vX.Y.Z. The commit body names the seam + its test file, same as bug-fix commits do.

Anti-patterns

• Test-after theatre. Writing the impl, then a test that mirrors it line-for-line. The test must encode the CONTRACT (inputs → promised outputs), not the implementation's shape.
• Skipping the red run. If you never saw it fail, you don't know it can.
• Mock forests. If the test needs three mocks, the seam is in the wrong place — extract a purer function instead.
• UI TDD. Don't force this loop onto JSX; the operator's manual check + tsc is the honest gate there.