1# Testing Anti-Patterns
2 
3**Load this reference when:** writing or changing tests, adding mocks, or tempted to add test-only methods to production code.
4 
5## Overview
6 
7Tests must verify real behavior, not mock behavior. Mocks are a means to isolate, not the thing being tested.
8 
9**Core principle:** Test what the code does, not what the mocks do.
10 
11**Following strict TDD prevents these anti-patterns.**
12 
13## The Iron Laws
14 
15```
161. NEVER test mock behavior
172. NEVER add test-only methods to production classes
183. NEVER mock without understanding dependencies
19```
20 
21## Anti-Pattern 1: Testing Mock Behavior
22 
23**The violation:**
24```typescript
25// ❌ BAD: Testing that the mock exists
26test('renders sidebar', () => {
27  render(<Page />);
28  expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument();
29});
30```
31 
32**Why this is wrong:**
33- You're verifying the mock works, not that the component works
34- Test passes when mock is present, fails when it's not
35- Tells you nothing about real behavior
36 
37**your human partner's correction:** "Are we testing the behavior of a mock?"
38 
39**The fix:**
40```typescript
41// ✅ GOOD: Test real component or don't mock it
42test('renders sidebar', () => {
43  render(<Page />);  // Don't mock sidebar
44  expect(screen.getByRole('navigation')).toBeInTheDocument();
45});
46 
47// OR if sidebar must be mocked for isolation:
48// Don't assert on the mock - test Page's behavior with sidebar present
49```
50 
51### Gate Function
52 
53```
54BEFORE asserting on any mock element:
55  Ask: "Am I testing real component behavior or just mock existence?"
56 
57  IF testing mock existence:
58    STOP - Delete the assertion or unmock the component
59 
60  Test real behavior instead
61```
62 
63## Anti-Pattern 2: Test-Only Methods in Production
64 
65**The violation:**
66```typescript
67// ❌ BAD: destroy() only used in tests
68class Session {
69  async destroy() {  // Looks like production API!
70    await this._workspaceManager?.destroyWorkspace(this.id);
71    // ... cleanup
72  }
73}
74 
75// In tests
76afterEach(() => session.destroy());
77```
78 
79**Why this is wrong:**
80- Production class polluted with test-only code
81- Dangerous if accidentally called in production
82- Violates YAGNI and separation of concerns
83- Confuses object lifecycle with entity lifecycle
84 
85**The fix:**
86```typescript
87// ✅ GOOD: Test utilities handle test cleanup
88// Session has no destroy() - it's stateless in production
89 
90// In test-utils/
91export async function cleanupSession(session: Session) {
92  const workspace = session.getWorkspaceInfo();
93  if (workspace) {
94    await workspaceManager.destroyWorkspace(workspace.id);
95  }
96}
97 
98// In tests
99afterEach(() => cleanupSession(session));
100```
101 
102### Gate Function
103 
104```
105BEFORE adding any method to production class:
106  Ask: "Is this only used by tests?"
107 
108  IF yes:
109    STOP - Don't add it
110    Put it in test utilities instead
111 
112  Ask: "Does this class own this resource's lifecycle?"
113 
114  IF no:
115    STOP - Wrong class for this method
116```
117 
118## Anti-Pattern 3: Mocking Without Understanding
119 
120**The violation:**
121```typescript
122// ❌ BAD: Mock breaks test logic
123test('detects duplicate server', () => {
124  // Mock prevents config write that test depends on!
125  vi.mock('ToolCatalog', () => ({
126    discoverAndCacheTools: vi.fn().mockResolvedValue(undefined)
127  }));
128 
129  await addServer(config);
130  await addServer(config);  // Should throw - but won't!
131});
132```
133 
134**Why this is wrong:**
135- Mocked method had side effect test depended on (writing config)
136- Over-mocking to "be safe" breaks actual behavior
137- Test passes for wrong reason or fails mysteriously
138 
139**The fix:**
140```typescript
141// ✅ GOOD: Mock at correct level
142test('detects duplicate server', () => {
143  // Mock the slow part, preserve behavior test needs
144  vi.mock('MCPServerManager'); // Just mock slow server startup
145 
146  await addServer(config);  // Config written
147  await addServer(config);  // Duplicate detected ✓
148});
149```
150 
151### Gate Function
152 
153```
154BEFORE mocking any method:
155  STOP - Don't mock yet
156 
157  1. Ask: "What side effects does the real method have?"
158  2. Ask: "Does this test depend on any of those side effects?"
159  3. Ask: "Do I fully understand what this test needs?"
160 
161  IF depends on side effects:
162    Mock at lower level (the actual slow/external operation)
163    OR use test doubles that preserve necessary behavior
164    NOT the high-level method the test depends on
165 
166  IF unsure what test depends on:
167    Run test with real implementation FIRST
168    Observe what actually needs to happen
169    THEN add minimal mocking at the right level
170 
171  Red flags:
172    - "I'll mock this to be safe"
173    - "This might be slow, better mock it"
174    - Mocking without understanding the dependency chain
175```
176 
177## Anti-Pattern 4: Incomplete Mocks
178 
179**The violation:**
180```typescript
181// ❌ BAD: Partial mock - only fields you think you need
182const mockResponse = {
183  status: 'success',
184  data: { userId: '123', name: 'Alice' }
185  // Missing: metadata that downstream code uses
186};
187 
188// Later: breaks when code accesses response.metadata.requestId
189```
190 
191**Why this is wrong:**
192- **Partial mocks hide structural assumptions** - You only mocked fields you know about
193- **Downstream code may depend on fields you didn't include** - Silent failures
194- **Tests pass but integration fails** - Mock incomplete, real API complete
195- **False confidence** - Test proves nothing about real behavior
196 
197**The Iron Rule:** Mock the COMPLETE data structure as it exists in reality, not just fields your immediate test uses.
198 
199**The fix:**
200```typescript
201// ✅ GOOD: Mirror real API completeness
202const mockResponse = {
203  status: 'success',
204  data: { userId: '123', name: 'Alice' },
205  metadata: { requestId: 'req-789', timestamp: 1234567890 }
206  // All fields real API returns
207};
208```
209 
210### Gate Function
211 
212```
213BEFORE creating mock responses:
214  Check: "What fields does the real API response contain?"
215 
216  Actions:
217    1. Examine actual API response from docs/examples
218    2. Include ALL fields system might consume downstream
219    3. Verify mock matches real response schema completely
220 
221  Critical:
222    If you're creating a mock, you must understand the ENTIRE structure
223    Partial mocks fail silently when code depends on omitted fields
224 
225  If uncertain: Include all documented fields
226```
227 
228## Anti-Pattern 5: Integration Tests as Afterthought
229 
230**The violation:**
231```
232✅ Implementation complete
233❌ No tests written
234"Ready for testing"
235```
236 
237**Why this is wrong:**
238- Testing is part of implementation, not optional follow-up
239- TDD would have caught this
240- Can't claim complete without tests
241 
242**The fix:**
243```
244TDD cycle:
2451. Write failing test
2462. Implement to pass
2473. Refactor
2484. THEN claim complete
249```
250 
251## When Mocks Become Too Complex
252 
253**Warning signs:**
254- Mock setup longer than test logic
255- Mocking everything to make test pass
256- Mocks missing methods real components have
257- Test breaks when mock changes
258 
259**your human partner's question:** "Do we need to be using a mock here?"
260 
261**Consider:** Integration tests with real components often simpler than complex mocks
262 
263## TDD Prevents These Anti-Patterns
264 
265**Why TDD helps:**
2661. **Write test first** → Forces you to think about what you're actually testing
2672. **Watch it fail** → Confirms test tests real behavior, not mocks
2683. **Minimal implementation** → No test-only methods creep in
2694. **Real dependencies** → You see what the test actually needs before mocking
270 
271**If you're testing mock behavior, you violated TDD** - you added mocks without watching test fail against real code first.
272 
273## Quick Reference
274 
275| Anti-Pattern | Fix |
276|--------------|-----|
277| Assert on mock elements | Test real component or unmock it |
278| Test-only methods in production | Move to test utilities |
279| Mock without understanding | Understand dependencies first, mock minimally |
280| Incomplete mocks | Mirror real API completely |
281| Tests as afterthought | TDD - tests first |
282| Over-complex mocks | Consider integration tests |
283 
284## Red Flags
285 
286- Assertion checks for `*-mock` test IDs
287- Methods only called in test files
288- Mock setup is >50% of test
289- Test fails when you remove mock
290- Can't explain why mock is needed
291- Mocking "just to be safe"
292 
293## The Bottom Line
294 
295**Mocks are tools to isolate, not things to test.**
296 
297If TDD reveals you're testing mock behavior, you've gone wrong.
298 
299Fix: Test real behavior or question why you're mocking at all.
300