🧪 Testing Guide
This guide details how to test a Pithos utility: when to use each level, available tools, commands, and coverage goals.
To understand the multi-layered testing strategy and why it exists, see the Testing Strategy page.
When to Use Each Level
| Situation | Recommended Approach |
|---|---|
| New function | Start with standard tests, add property-based for invariants |
| Union types in API | Add `[🎯]` tests for each branch |
| Mutation score < 100% | Add targeted `[👾]` tests for surviving mutants |
| Complex input domain | Add `[🎲]` tests with appropriate arbitraries |
| Bug report | Write a failing test first, then fix |
Tools
Running Tests
Pithos provides several test commands depending on what you want to verify, from a quick full run to targeted mutation testing on a single file:
# Run all tests
pnpm test
# Run tests with coverage report
pnpm coverage
# Run mutation tests (entire project)
pnpm test:mutation
# Run mutation tests on a specific file
pnpm stryker run --mutate 'packages/pithos/src/arkhe/object/evolve.ts'
Coverage Goals
| Metric | Target | Why |
|---|---|---|
| Code coverage | 100% | Baseline: ensures all code executes |
| Mutation score | 100% | Ensures tests actually verify behavior |
| Property-based tests | 1-5 per function | Explores edge cases automatically |
| Edge case coverage | All union types + `@note` | Ensures API contracts are tested |
The Philosophy
"A test that passes when the code is wrong is worse than no test at all: it gives false confidence."
Each prefix tells a story:
- No prefix: "This is expected behavior"
[🎯]: "This covers a specific API branch"[👾]: "This kills a specific mutant"[🎲]: "This verifies an invariant holds for any input"
When you see a failing test, the prefix immediately tells you why that test exists and what kind of bug you're dealing with.