Danijel Martinek
89d47cce5c
The docs/superpowers/{specs,plans}/ directory was archived to .archive/
in an earlier session (and .archive/ is gitignored). Every md link
into that path is now a broken reference for anyone consuming the
template fresh.
Stripped:
- ADR-011: **Spec:** header line
- ADR-015: **Spec:** + **Plan:** header lines
- ADR-016: **Spec:** + **Plan:** header lines + footer "Spec —"
bullet (the design rationale is captured in the ADR body itself)
- ADR-017: **Spec:** + **Plan:** header lines
- ADR-018: **Spec:** + **Plan:** header lines
- guides/realtime.md: inline "the full spec" link + footer
[Spec] entry (folded its description into the ADR-016 entry)
- guides/events-and-jobs.md: inline "the full spec" link
- architecture/vertical-feature-spec.md: stale "Deleted" subsection
referencing docs/superpowers/plans/*
Updated:
- glossary.md "PRD" entry: clarified status flow now matches the
shipped pnpm work prd-ship lifecycle (draft -> in-review ->
approved -> shipped); removed the parenthetical pointing at
docs/superpowers/specs/ as a definition of "spec"
- glossary.md "spec" flagged-ambiguity: rewritten to reflect that
durable design lives in ADRs (docs/decisions/adr-NNN-*.md) and
implementation seeds live in PRDs (docs/work/prds/*.prd.md) —
"spec" should be avoided in this template
Preserved (legitimate refs to the SuperPowers plugin, not the dir):
- agent-first-workflow-and-conformance.md mentions of
`superpowers:brainstorming` — these reference the external
plugin skill, not a file in the repo
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
70 lines
2.7 KiB
Markdown
70 lines
2.7 KiB
Markdown
# ADR-011: TDD Foundation
|
|
|
|
**Status:** Accepted
|
|
**Date:** 2026-05-05
|
|
**Supersedes:** none
|
|
|
|
## Context
|
|
|
|
The vertical-feature monorepo refactor (ADRs 001-010) established
|
|
clean architecture with per-feature DI containers but did not enforce
|
|
TDD as the path of least resistance. Agentic workers were producing
|
|
code-first commits with tests added later, leading to test theatre and
|
|
mock/real drift.
|
|
|
|
## Decision
|
|
|
|
1. **New package `@repo/core-testing` (tag: tooling)** — shared test
|
|
utilities: defineFactory, defineContractSuite, renderWithProviders,
|
|
mock-payload helpers, jsdom setup file. Tagged `tooling` so any
|
|
package may depend on it as devDependency without boundary violation.
|
|
|
|
2. **Vitest base configs split into node + jsdom** with safety defaults
|
|
(clearMocks, restoreMocks, mockReset, unstubGlobals, sequence.shuffle)
|
|
and coverage thresholds (80/75/80/80 baseline; 100% in entities +
|
|
use-cases + controllers).
|
|
|
|
3. **Factories per feature** in `src/__factories__/` replace inline
|
|
fixtures. Stable date defaults (2026-01-01) so snapshot diffs reflect
|
|
SUT behavior only.
|
|
|
|
4. **Contract suites per repository interface** in `src/__contracts__/`
|
|
run against every implementation (Mock + Payload). Eliminates the
|
|
class of bug where the mock and the real impl drift apart.
|
|
|
|
5. **Tests in core-\* packages and apps** — composition smoke tests
|
|
(appRouter, payloadConfig, bind-production, providers).
|
|
|
|
6. **Storybook test-runner** — every story executed as a smoke test.
|
|
|
|
7. **CI workflow** — typecheck + lint + boundaries + test + build +
|
|
e2e + storybook on every PR. Coverage uploaded as artifact.
|
|
|
|
8. **Two new docs** — tdd-workflow.md (process) + restructured
|
|
adding-a-feature.md (interleaves tests with impl).
|
|
|
|
## Alternatives considered
|
|
|
|
- **Fixture files instead of factories** — rejected. Fixtures rot with
|
|
schema changes and require manual updates per test.
|
|
- **One shared test file per impl** — rejected. Contract suites give
|
|
the same coverage in fewer LOC and prevent drift.
|
|
- **Real Postgres in tests via testcontainers** — rejected for unit
|
|
tests (slow, complex). Repository contract suites + vi.mock('payload')
|
|
give equivalent confidence in milliseconds.
|
|
- **Stryker mutation testing** — deferred. Coverage thresholds + contract
|
|
suites get us most of the way; mutation testing is incremental.
|
|
|
|
## Consequences
|
|
|
|
- New package to maintain (small, mostly stable surface).
|
|
- Coverage thresholds may fail builds initially; we add tests to cross
|
|
threshold as features land.
|
|
- Sequence shuffle may surface latent flakes; we fix as found.
|
|
- Templates for new features now require writing tests first; this is
|
|
by design.
|
|
|
|
## Refines
|
|
|
|
- ADR-006 (boundary tags) — adds @repo/core-testing as a tooling package.
|