| name | clean-tests |
| description | Audits and refactors existing test files for quality — removes brittle assertions, fixes implementation coupling (mocking internals), improves test names, eliminates duplication, and enforces behavior-over-implementation testing. Does NOT write new tests (use /tdd for that). Use when asked to "clean up the tests", "improve test quality", "fix brittle tests", "refactor the test suite", "tests keep breaking on refactor", "tests are a mess", or "make the tests better". |
clean-tests
Audits and refactors existing tests without removing coverage.
What Gets Fixed
| Issue | Symptom | Fix |
|---|
| Implementation coupling | Mocking internal modules, testing private methods, asserting on internal state | Rewrite to test through public API only |
| Brittle assertions | Exact error message strings, hardcoded IDs, timestamp comparisons | Use flexible matchers, freeze time, assert structure not exact value |
| Poor test names | test_1, test_user, testGetUser | Rewrite as sentences: returns_404_when_user_not_found |
| Multi-assertion tests | One test checks 5 things — failure is ambiguous | Split into focused single-assertion tests |
| Duplicated setup | Same 15-line setup repeated across every test | Extract to fixture/factory/helper |
| False confidence | assert True, assert result is not None, empty tests | Add meaningful behavioral assertions |
| Order dependence | Tests pass together but fail in isolation | Make each test fully self-contained |
| Flaky time/random | datetime.now() or random() in assertions | Freeze time, seed random, or use matchers |
Process
1. Discover test files
find . -type f \( -name "test_*.py" -o -name "*_test.py" -o -name "*.test.ts" -o -name "*.spec.ts" -o -name "*.test.tsx" -o -name "*.spec.tsx" \) \
| grep -v node_modules | grep -v .venv | grep -v dist | sort
2. Analyze → Prioritize → Fix → Run tests after each file
Fix order: implementation coupling → poor naming → brittle assertions → duplication → false confidence.
Run tests after every file:
pytest <file> -x -q 2>&1 | tail -8
npx vitest run <file> 2>&1 | tail -8
3. Rules
- Never delete a test — only improve it
- Never change WHAT a test asserts about behavior, only HOW
- If a fix is uncertain, leave
# TODO clean-tests: <reason> rather than breaking coverage
- Run tests after every file before moving to the next
4. Report findings at the end with counts per category
