[misc] Add unit test admission criteria to agent rules (#30608)

2026-07-08 23:41:48 -07:00
parent fdf6c70e3a
commit 9e4483d725
1 changed files with 43 additions and 0 deletions
@@ -0,0 +1,43 @@
+---
+paths:
+  - "test/**/*.py"
+---
+
+# Unit Test Admission Criteria
+
+Every test case must have a concrete answer to: "what future diff would turn
+this case red?" If the only answer is "editing the test itself", delete it.
+
+A new unit test case must fall into one of these categories:
+
+1. **Bug regression.** Guards a bug that actually happened (CI failure, issue,
+   incident). Before committing, verify the case fails on the pre-fix code and
+   passes on the fix. Describe the bug mechanism in the docstring in black-box
+   terms. For concurrency bugs, reproduce the exact interleaving
+   deterministically (`create_task` + `sleep(0)` scheduling); do not rely on
+   probabilistic stress -- a stress loop that cannot hit the bug even on the
+   buggy code has zero guard value.
+
+2. **Derived property.** Pins down a conclusion that required reasoning to
+   establish -- boundary/alignment math, invariants, protocol semantics (FIFO
+   fairness, idempotency, round-trip). Protects against "looks equivalent"
+   rewrites that silently break the derivation.
+
+3. **Critical-path bookkeeping.** Defends conventions that are easy to break by
+   forgetting to sync -- registry completeness, field lifecycle, serialization
+   compatibility. Enumerating assertions are fine here; the guarded failure
+   mode is "someone extended X without updating Y". Example: the ratchet tests
+   (`test/registered/unit/test_module_state_ratchet.py`).
+
+Not admissible:
+
+- Happy-path tautologies that re-assert what the implementation trivially does.
+- Mirror tests that restate the implementation logic as assertions.
+- Probabilistic stress that cannot reproduce the failure it claims to guard.
+
+One strong case beats several weak ones: each additional case must guard a
+distinct failure mode. Ask "which bug escapes if I delete this case?" -- no
+answer means delete it.
+
+Test mechanics (placement, CI registration, fixtures) live in
+[`write-sglang-test`](../skills/write-sglang-test/SKILL.md).