Consolidate Test Suites
Purpose: place each invariant in one owning test layer only.
Definitions:
- Invariant: the rule that must stay true.
- Owning layer: the lowest layer that truly owns and can prove that rule.
- Canonical suite: the normal existing suite for that owning layer.
- Probe: temporary test code, fixture, script, snapshot, diagnostic, assertion,
instrumentation, or helper created to investigate or reproduce one task.
Default: reuse an existing canonical suite. Do not create a new standalone regression test unless the exception rule below allows it.
Probes are useful working material, not permanent coverage by default. Before
finishing, classify every probe created for the current task as PROMOTE,
MERGE, or DROP.
Hard Rules
- You MUST identify the invariant before adding or moving any test.
- You MUST identify one primary owning layer: unit, integration, or end-to-end.
- You MUST first try to place coverage in an existing canonical suite for that layer.
- You MUST prefer editing an existing test file over creating a new test file.
- You MUST NOT add the same invariant in multiple layers unless each layer covers a different failure mode. If you keep more than one layer, name the distinct failure mode for each.
- You MUST NOT add tests that lock in implementation details unless that implementation unit itself owns the invariant.
- You MUST NOT create a standalone regression test because it is faster or easier.
- If you cannot name the invariant and the owning layer, STOP. Report that placement is not justified.
- You MUST remove current-task probes that are not promoted or merged, including
temporary code inserted into a permanent test or production file.
- You MUST preserve tests and dirty changes that predate the current task. Never
delete or rewrite them merely to reduce test count.
- If the request is review-only, report probe dispositions and cleanup
recommendations without modifying files.
Required Decision Order
Choose the first option that fits:
- Add to an existing test in an existing file in the owning layer.
- Add a new test to an existing canonical file in the owning layer.
- Create a new file inside the existing canonical suite in the owning layer.
- Create a standalone regression-style test only if the Exception Rule passes.
Owning Layer Rules
Choose unit when:
- one module owns the rule, and
- the bug reproduces without I/O, transport, persistence, retries, IPC, orchestration, or lifecycle coupling.
Choose integration when:
- the rule lives at a boundary between components, or
- the bug depends on serialization, persistence, ordering, replay, retries, IPC, process lifecycle, or multi-component coordination.
Choose end-to-end only when:
- the user-visible contract cannot be trusted from lower-layer tests alone.
Tie-breakers:
- If torn between unit and integration, choose integration.
- Never choose end-to-end to compensate for uncertainty.
- Never choose a higher layer just because it is easier to reproduce there.
Exception Rule for Standalone Regression Tests
A standalone regression-style test is allowed only if ALL are true:
- no existing canonical suite can express the case cleanly
- the reproduction is deterministic
- the case has durable incident or contract value
- adding it to the canonical suite would make that suite less clear
If any condition is false, fold the coverage into the canonical suite.
Probe Lifecycle
Use temporary probes when they materially help reproduce, diagnose, or falsify
a suspected bug. Keep their lifecycle lightweight:
- Before editing tests, inspect the existing test-related status and diff so
pre-existing work is distinguishable from task-created probes. Keep this
baseline in the working context; do not create tracking files for it.
- Once the behavior is accepted, compare each task-created probe with the
nearest canonical suite and choose exactly one disposition:
PROMOTE: keep the smallest version because it protects a unique durable
invariant at the stable owning boundary.
MERGE: move only its unique signal into an existing canonical test, then
remove the redundant probe.
DROP: remove it because it is diagnostic-only, redundant, speculative,
implementation-coupled, flaky, slow, or low-value.
- Parameterize or extend an existing behavior test when several examples prove
the same invariant. Test count and coverage percentage are not reasons to
keep another test.
- Remove every unpromoted task-created probe before final verification. If its
ownership is uncertain, preserve it and report the uncertainty instead of
guessing that it is safe to delete.
Promote a probe only when it is deterministic, protects an accepted observable
contract, would catch a meaningful regression, adds signal not already owned
elsewhere, and has maintenance cost proportional to its risk. When cheap and
safe, confirm that the proposed test fails against the faulty behavior and
passes against the fix; do not build extra infrastructure merely to produce
that proof.
Duplicate Cleanup
After placing coverage:
- Search for tests that assert the same invariant.
- Keep the strongest owned location.
- Merge any unique assertions into that location.
- Delete or simplify weaker duplicates.
- Rename tests by behavior and owner, not by ticket number or bug history.
Delete or rewrite pre-existing tests only when the task includes suite
consolidation and duplicate coverage has been demonstrated. Routine bug-fix work
may clean up only the probes it created.
Verification
Before finishing:
- Run the narrowest relevant test target first.
- Run required typecheck, build, or lint steps for touched code.
- Report exactly what was run and whether it passed.
Default Output Format
Use this format by default:
Invariant:
Owning layer: <unit | integration | end-to-end>
Target suite/file:
Action: <reuse existing test | add to existing suite | create file in canonical suite | keep standalone regression>
Why this layer owns it:
Duplicates to merge/delete: <list or "none">
Current-task probes: <PROMOTE / MERGE / DROP for each, or "none">
Probe cleanup completed: <removed paths or inline code, or "none">
Verification run:
Residual risk: <what is still not covered, if anything>
1---
2name: consolidate-test-suites
3description: Decide where durable test coverage belongs and clean up temporary test probes. Use while testing a bug fix or architectural change, or before finishing work that added tests, fixtures, snapshots, diagnostics, or temporary assertions. Select one owning layer, reuse canonical suites, merge unique signal, and remove task-created probe residue without disturbing pre-existing work.
4metadata:
5 source: https://skillmd.com/skills/gabrielmoreira/consolidate-test-suites
6---
7
8# Consolidate Test Suites
9
10Purpose: place each invariant in one owning test layer only.
11
12Definitions:
13- Invariant: the rule that must stay true.
14- Owning layer: the lowest layer that truly owns and can prove that rule.
15- Canonical suite: the normal existing suite for that owning layer.
16- Probe: temporary test code, fixture, script, snapshot, diagnostic, assertion,
17 instrumentation, or helper created to investigate or reproduce one task.
18
19Default: reuse an existing canonical suite. Do not create a new standalone regression test unless the exception rule below allows it.
20
21Probes are useful working material, not permanent coverage by default. Before
22finishing, classify every probe created for the current task as `PROMOTE`,
23`MERGE`, or `DROP`.
24
25## Hard Rules
26
27- You MUST identify the invariant before adding or moving any test.
28- You MUST identify one primary owning layer: unit, integration, or end-to-end.
29- You MUST first try to place coverage in an existing canonical suite for that layer.
30- You MUST prefer editing an existing test file over creating a new test file.
31- You MUST NOT add the same invariant in multiple layers unless each layer covers a different failure mode. If you keep more than one layer, name the distinct failure mode for each.
32- You MUST NOT add tests that lock in implementation details unless that implementation unit itself owns the invariant.
33- You MUST NOT create a standalone regression test because it is faster or easier.
34- If you cannot name the invariant and the owning layer, STOP. Report that placement is not justified.
35- You MUST remove current-task probes that are not promoted or merged, including
36 temporary code inserted into a permanent test or production file.
37- You MUST preserve tests and dirty changes that predate the current task. Never
38 delete or rewrite them merely to reduce test count.
39- If the request is review-only, report probe dispositions and cleanup
40 recommendations without modifying files.
41
42## Required Decision Order
43
44Choose the first option that fits:
45
461. Add to an existing test in an existing file in the owning layer.
472. Add a new test to an existing canonical file in the owning layer.
483. Create a new file inside the existing canonical suite in the owning layer.
494. Create a standalone regression-style test only if the Exception Rule passes.
50
51## Owning Layer Rules
52
53Choose unit when:
54- one module owns the rule, and
55- the bug reproduces without I/O, transport, persistence, retries, IPC, orchestration, or lifecycle coupling.
56
57Choose integration when:
58- the rule lives at a boundary between components, or
59- the bug depends on serialization, persistence, ordering, replay, retries, IPC, process lifecycle, or multi-component coordination.
60
61Choose end-to-end only when:
62- the user-visible contract cannot be trusted from lower-layer tests alone.
63
64Tie-breakers:
65- If torn between unit and integration, choose integration.
66- Never choose end-to-end to compensate for uncertainty.
67- Never choose a higher layer just because it is easier to reproduce there.
68
69## Exception Rule for Standalone Regression Tests
70
71A standalone regression-style test is allowed only if ALL are true:
72
73- no existing canonical suite can express the case cleanly
74- the reproduction is deterministic
75- the case has durable incident or contract value
76- adding it to the canonical suite would make that suite less clear
77
78If any condition is false, fold the coverage into the canonical suite.
79
80## Probe Lifecycle
81
82Use temporary probes when they materially help reproduce, diagnose, or falsify
83a suspected bug. Keep their lifecycle lightweight:
84
851. Before editing tests, inspect the existing test-related status and diff so
86 pre-existing work is distinguishable from task-created probes. Keep this
87 baseline in the working context; do not create tracking files for it.
882. Once the behavior is accepted, compare each task-created probe with the
89 nearest canonical suite and choose exactly one disposition:
90 - `PROMOTE`: keep the smallest version because it protects a unique durable
91 invariant at the stable owning boundary.
92 - `MERGE`: move only its unique signal into an existing canonical test, then
93 remove the redundant probe.
94 - `DROP`: remove it because it is diagnostic-only, redundant, speculative,
95 implementation-coupled, flaky, slow, or low-value.
963. Parameterize or extend an existing behavior test when several examples prove
97 the same invariant. Test count and coverage percentage are not reasons to
98 keep another test.
994. Remove every unpromoted task-created probe before final verification. If its
100 ownership is uncertain, preserve it and report the uncertainty instead of
101 guessing that it is safe to delete.
102
103Promote a probe only when it is deterministic, protects an accepted observable
104contract, would catch a meaningful regression, adds signal not already owned
105elsewhere, and has maintenance cost proportional to its risk. When cheap and
106safe, confirm that the proposed test fails against the faulty behavior and
107passes against the fix; do not build extra infrastructure merely to produce
108that proof.
109
110## Duplicate Cleanup
111
112After placing coverage:
113
1141. Search for tests that assert the same invariant.
1152. Keep the strongest owned location.
1163. Merge any unique assertions into that location.
1174. Delete or simplify weaker duplicates.
1185. Rename tests by behavior and owner, not by ticket number or bug history.
119
120Delete or rewrite pre-existing tests only when the task includes suite
121consolidation and duplicate coverage has been demonstrated. Routine bug-fix work
122may clean up only the probes it created.
123
124## Verification
125
126Before finishing:
127
1281. Run the narrowest relevant test target first.
1292. Run required typecheck, build, or lint steps for touched code.
1303. Report exactly what was run and whether it passed.
131
132## Default Output Format
133
134Use this format by default:
135
136Invariant: <rule that failed>
137
138Owning layer: <unit | integration | end-to-end>
139
140Target suite/file: <path or suite name>
141
142Action: <reuse existing test | add to existing suite | create file in canonical suite | keep standalone regression>
143
144Why this layer owns it: <one short paragraph>
145
146Duplicates to merge/delete: <list or "none">
147
148Current-task probes: <PROMOTE / MERGE / DROP for each, or "none">
149
150Probe cleanup completed: <removed paths or inline code, or "none">
151
152Verification run: <commands and result>
153
154Residual risk: <what is still not covered, if anything>