# Deterministic Test Harness

> 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.

- Skill: `rockclaver/deterministic-test-harness` (Agent Skill)
- Install (CLI): `npx skillmds@latest add rockclaver/deterministic-test-harness`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rockclaver/deterministic-test-harness/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: rockclaver (https://skillmd.com/u/rockclaver)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/rockclaver/deterministic-test-harness

---


# 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:

```bash
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.