Deterministic Test Harness
Control clocks, randomness, providers, storage, and concurrency for repeatable tests; inject deterministic dependencies at the boundary.
Sources of Nondeterminism
- Time, time zones, calendars, date cutoffs, settlement windows
- Random ids, UUIDs, references, sampling, shuffling
- External providers: payments, market data, bank files, email, SMS, KYC
- Background jobs, queues, scheduled tasks, retries, polling
- Database ordering without explicit
ORDER BY
- Parallel writes, locks, optimistic concurrency, race-prone state
Test Controls
Prefer existing patterns, else smallest boundary: frozen-time clock, deterministic id factory, provider fake (success/decline/timeout/duplicate), in-memory queue/sync runner, fixture reset, stable sort. Freeze time, seed ids, drive providers from fakes, assert observable behavior.
Prove Stability
Run repeatedly with the repo's runner:
npm test -- <target>
pytest <target> -q
go test ./... -count=20
Guardrails
- Do not add sleeps to fix timing, or hit real payment/market-data providers from tests.
- Do not assert on unordered collections without sorting, use wall-clock dates in expected values, or over-mock internal collaborators.
1---2name: deterministic-test-harness3description: Builds deterministic tests for time, randomness, concurrency, external APIs, queues, databases, or eventual consistency. Use when tests are flaky, financial calcs depend on dates/clocks, or workflows need fake, repeatable test behavior.4---56# Deterministic Test Harness78Control clocks, randomness, providers, storage, and concurrency for repeatable tests; inject deterministic dependencies at the boundary.910## Sources of Nondeterminism1112- Time, time zones, calendars, date cutoffs, settlement windows13- Random ids, UUIDs, references, sampling, shuffling14- External providers: payments, market data, bank files, email, SMS, KYC15- Background jobs, queues, scheduled tasks, retries, polling16- Database ordering without explicit `ORDER BY`17- Parallel writes, locks, optimistic concurrency, race-prone state1819## Test Controls2021Prefer existing patterns, else smallest boundary: frozen-time clock, deterministic id factory, provider fake (success/decline/timeout/duplicate), in-memory queue/sync runner, fixture reset, stable sort. Freeze time, seed ids, drive providers from fakes, assert observable behavior.2223## Prove Stability2425Run repeatedly with the repo's runner:2627```bash28npm test -- <target>29pytest <target> -q30go test ./... -count=2031```3233## Guardrails3435- Do not add sleeps to fix timing, or hit real payment/market-data providers from tests.36- Do not assert on unordered collections without sorting, use wall-clock dates in expected values, or over-mock internal collaborators.
rockclaver