How to Use This Site

No fluff. Just a practical guide to diagnosing bad tests and fixing them fast.

The Problem This Site Solves

You know tests are important. But not all tests are good.

Many tests slow you down:

Flaky tests train you to ignore failures
Cryptic tests waste hours debugging
Brittle tests make you fear refactoring
Useless tests are just maintenance burden

What We Help With

This site helps you identify high-value tests vs low-value tests. Tests are approximations of user experience. Good approximations increase velocity. Bad ones kill it.

The 9 Laws (Organized by Priority)

Tier 1: Can You Trust It? (Fix First)

1. Isolation - Tests are hermits
2. Speed - A slow test is already dead
3. Determinism - Flaky tests are worse than no tests

If Tier 1 fails, the test is worthless. Fix or delete immediately.

Tier 2: Can You Understand It? (Fix Second)

4. Signal Clarity - Fail loudly, fail obviously
5. Focus - One failure reason per test

If Tier 2 fails, debugging takes 10x longer.

Tier 3: Will It Age Well? (Fix Third)

6. Stability - Tests should survive refactoring
7. Setup Honesty - Every line of setup is a smell
8. Boundaries - Test your code, fake the world
9. Maintenance - Delete tests that don't pull their weight

If Tier 3 fails, tests rot over time. Only matters if test is worth keeping.

Using the Examples

1. Find Your Problem

Have a symptom? Quick lookup:

"Test fails randomly" → Law #3 (Determinism)
"Can't understand failure" → Law #4 (Signal Clarity)
"Refactor broke 40 tests" → Law #6 (Stability)
"Test has 50 lines of setup" → Law #7 (Setup Honesty)

2. Filter Examples by Law

Visit Examples and click the law filter. Each example is tagged with violated laws.

3. See Concrete Fixes

Each example shows bad code, good code, and why the fix works.

During Code Review

Quick Review Checklist

Block merge if:

Test uses sleep() or has race conditions
Test shares state or depends on order
Test takes >10 seconds

Request changes if:

Error message is generic ("expected true, got false")
One test checks 8 unrelated things

Suggest improvement if:

Test would break on refactor (mocking internals)
Setup is bloated or mysterious

Pro tip: Link to specific law pages in your review comments. "This violates Law #3: Determinism" is more helpful than "this is flaky."

When Fixing Tests

Priority Order

Fix Tier 1 or delete - Flaky/slow tests hurt everyone
Fix Tier 2 when it fails - Add better assertions when debugging
Fix Tier 3 during refactors - Opportunistic improvement

Don't over-invest. Bad tests are worse than no tests.

If a test never fails, tests trivial logic, or is too expensive to fix: delete it (Law #9: Maintenance).

What This Site Is NOT

Not a testing 101: Assumes you know how to write tests
Not comprehensive: Focused on high-value vs low-value tests
Not dogmatic: Sometimes you need to break the laws (but know why)

Quick Start

1. Diagnose your test problem (flaky? cryptic? brittle?)

2. Identify which law it violates (use the symptom table)

3. Filter examples by that law

4. See concrete bad/good code

5. Apply the pattern to your codebase

Goal: Identify and fix (or delete) low-value tests in <60 seconds.