claude-mpm 4.20.3__py3-none-any.whl → 4.25.10__py3-none-any.whl

claude_mpm/skills/bundled/testing/testing-anti-patterns/SKILL.md

@@ -2,7 +2,17 @@
 name: Testing Anti-Patterns
 description: Never test mock behavior. Never add test-only methods to production classes. Understand dependencies before mocking.
 when_to_use: when writing or changing tests, adding mocks, or tempted to add test-only methods to production code
-version: 1.1.0
+version: 2.0.0
+progressive_disclosure:
+  entry_point:
+    summary: "Avoid testing mocks, test-only production methods, and incomplete mocking. Test real behavior, not mock behavior."
+    when_to_use: "When writing tests, adding mocks, reviewing test failures, or tempted to add test-only methods to production code."
+    quick_start: "1. Ask: 'Am I testing real behavior?' 2. Check: 'Is this method only for tests?' 3. Verify: 'Do I understand what I'm mocking?' 4. Confirm: 'Is my mock complete?' 5. Apply: TDD prevents these patterns"
+  references:
+    - core-anti-patterns.md
+    - completeness-anti-patterns.md
+    - detection-guide.md
+    - tdd-connection.md
 ---
 
 # Testing Anti-Patterns
@@ -13,7 +23,16 @@ Tests must verify real behavior, not mock behavior. Mocks are a means to isolate
 
 **Core principle:** Test what the code does, not what the mocks do.
 
-**Following strict TDD prevents these anti-patterns.**
+**Following strict TDD prevents these anti-patterns.** See [test-driven-development skill](../test-driven-development/) for the complete TDD workflow.
+
+## When to Use This Skill
+
+Activate this skill when you're:
+- **Writing or changing tests** - Verify you're testing real behavior
+- **Adding mocks** - Ensure mocking is necessary and correct
+- **Reviewing test failures** - Check if mock behavior is the issue
+- **Tempted to add test-only methods** - STOP and reconsider
+- **Tests feel overly complex** - Sign of over-mocking
 
 ## The Iron Laws
 
@@ -21,284 +40,101 @@ Tests must verify real behavior, not mock behavior. Mocks are a means to isolate
 1. NEVER test mock behavior
 2. NEVER add test-only methods to production classes
 3. NEVER mock without understanding dependencies
+4. NEVER create incomplete mocks
+5. NEVER treat tests as afterthought
 ```
 
-## Anti-Pattern 1: Testing Mock Behavior
-
-**The violation:**
-```typescript
-// ❌ BAD: Testing that the mock exists
-test('renders sidebar', () => {
-  render(<Page />);
-  expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument();
-});
-```
-
-**Why this is wrong:**
-- You're verifying the mock works, not that the component works
-- Test passes when mock is present, fails when it's not
-- Tells you nothing about real behavior
-
-**your human partner's correction:** "Are we testing the behavior of a mock?"
-
-**The fix:**
-```typescript
-// ✅ GOOD: Test real component or don't mock it
-test('renders sidebar', () => {
-  render(<Page />);  // Don't mock sidebar
-  expect(screen.getByRole('navigation')).toBeInTheDocument();
-});
-
-// OR if sidebar must be mocked for isolation:
-// Don't assert on the mock - test Page's behavior with sidebar present
-```
-
-### Gate Function
-
-```
-BEFORE asserting on any mock element:
-  Ask: "Am I testing real component behavior or just mock existence?"
-
-  IF testing mock existence:
-    STOP - Delete the assertion or unmock the component
-
-  Test real behavior instead
-```
-
-## Anti-Pattern 2: Test-Only Methods in Production
+## Core Anti-Pattern Categories
 
-**The violation:**
-```typescript
-// ❌ BAD: destroy() only used in tests
-class Session {
-  async destroy() {  // Looks like production API!
-    await this._workspaceManager?.destroyWorkspace(this.id);
-    // ... cleanup
-  }
-}
+### 1. Testing Mock Behavior
+Asserting on mock elements instead of real behavior. **Fix:** Test real component or don't mock it.
+**→** [core-anti-patterns.md](references/core-anti-patterns.md#anti-pattern-1-testing-mock-behavior)
 
-// In tests
-afterEach(() => session.destroy());
-```
+### 2. Test-Only Methods in Production
+Methods in production classes only used by tests. **Fix:** Move to test utilities.
+**→** [core-anti-patterns.md](references/core-anti-patterns.md#anti-pattern-2-test-only-methods-in-production)
 
-**Why this is wrong:**
-- Production class polluted with test-only code
-- Dangerous if accidentally called in production
-- Violates YAGNI and separation of concerns
-- Confuses object lifecycle with entity lifecycle
-
-**The fix:**
-```typescript
-// ✅ GOOD: Test utilities handle test cleanup
-// Session has no destroy() - it's stateless in production
-
-// In test-utils/
-export async function cleanupSession(session: Session) {
-  const workspace = session.getWorkspaceInfo();
-  if (workspace) {
-    await workspaceManager.destroyWorkspace(workspace.id);
-  }
-}
-
-// In tests
-afterEach(() => cleanupSession(session));
-```
+### 3. Mocking Without Understanding
+Mocking without understanding dependencies/side effects. **Fix:** Understand first, mock minimally.
+**→** [core-anti-patterns.md](references/core-anti-patterns.md#anti-pattern-3-mocking-without-understanding)
 
-### Gate Function
+### 4. Incomplete Mocks
+Partial mocks missing fields downstream code needs. **Fix:** Mirror complete API structure.
+**→** [completeness-anti-patterns.md](references/completeness-anti-patterns.md#anti-pattern-4-incomplete-mocks)
 
-```
-BEFORE adding any method to production class:
-  Ask: "Is this only used by tests?"
+### 5. Tests as Afterthought
+Implementation "complete" without tests. **Fix:** TDD - write test first.
+**→** [completeness-anti-patterns.md](references/completeness-anti-patterns.md#anti-pattern-5-integration-tests-as-afterthought)
 
-  IF yes:
-    STOP - Don't add it
-    Put it in test utilities instead
+## Quick Detection Checklist
 
-  Ask: "Does this class own this resource's lifecycle?"
+Run this checklist before committing any test:
 
-  IF no:
-    STOP - Wrong class for this method
 ```
+□ Am I asserting on mock elements? (testId='*-mock')
+  → If yes: STOP - Test real component or unmock
 
-## Anti-Pattern 3: Mocking Without Understanding
-
-**The violation:**
-```typescript
-// ❌ BAD: Mock breaks test logic
-test('detects duplicate server', () => {
-  // Mock prevents config write that test depends on!
-  vi.mock('ToolCatalog', () => ({
-    discoverAndCacheTools: vi.fn().mockResolvedValue(undefined)
-  }));
+□ Does this method only exist for tests?
+  → If yes: STOP - Move to test utilities
 
-  await addServer(config);
-  await addServer(config);  // Should throw - but won't!
-});
-```
+□ Do I fully understand what I'm mocking?
+  → If no: STOP - Run with real impl first, then mock minimally
 
-**Why this is wrong:**
-- Mocked method had side effect test depended on (writing config)
-- Over-mocking to "be safe" breaks actual behavior
-- Test passes for wrong reason or fails mysteriously
-
-**The fix:**
-```typescript
-// ✅ GOOD: Mock at correct level
-test('detects duplicate server', () => {
-  // Mock the slow part, preserve behavior test needs
-  vi.mock('MCPServerManager'); // Just mock slow server startup
-
-  await addServer(config);  // Config written
-  await addServer(config);  // Duplicate detected ✓
-});
-```
+□ Is my mock missing fields the real API has?
+  → If yes: STOP - Mirror complete API structure
 
-### Gate Function
+□ Did I write implementation before test?
+  → If yes: STOP - Delete impl, write test first (TDD)
 
+□ Is mock setup >50% of test code?
+  → If yes: Consider integration test with real components
 ```
-BEFORE mocking any method:
-  STOP - Don't mock yet
-
-  1. Ask: "What side effects does the real method have?"
-  2. Ask: "Does this test depend on any of those side effects?"
-  3. Ask: "Do I fully understand what this test needs?"
-
-  IF depends on side effects:
-    Mock at lower level (the actual slow/external operation)
-    OR use test doubles that preserve necessary behavior
-    NOT the high-level method the test depends on
-
-  IF unsure what test depends on:
-    Run test with real implementation FIRST
-    Observe what actually needs to happen
-    THEN add minimal mocking at the right level
-
-  Red flags:
-    - "I'll mock this to be safe"
-    - "This might be slow, better mock it"
-    - Mocking without understanding the dependency chain
-```
-
-## Anti-Pattern 4: Incomplete Mocks
 
-**The violation:**
-```typescript
-// ❌ BAD: Partial mock - only fields you think you need
-const mockResponse = {
-  status: 'success',
-  data: { userId: '123', name: 'Alice' }
-  // Missing: metadata that downstream code uses
-};
+**See:** [detection-guide.md](references/detection-guide.md) for comprehensive red flags and warning signs.
 
-// Later: breaks when code accesses response.metadata.requestId
-```
-
-**Why this is wrong:**
-- **Partial mocks hide structural assumptions** - You only mocked fields you know about
-- **Downstream code may depend on fields you didn't include** - Silent failures
-- **Tests pass but integration fails** - Mock incomplete, real API complete
-- **False confidence** - Test proves nothing about real behavior
-
-**The Iron Rule:** Mock the COMPLETE data structure as it exists in reality, not just fields your immediate test uses.
-
-**The fix:**
-```typescript
-// ✅ GOOD: Mirror real API completeness
-const mockResponse = {
-  status: 'success',
-  data: { userId: '123', name: 'Alice' },
-  metadata: { requestId: 'req-789', timestamp: 1234567890 }
-  // All fields real API returns
-};
-```
-
-### Gate Function
-
-```
-BEFORE creating mock responses:
-  Check: "What fields does the real API response contain?"
-
-  Actions:
-    1. Examine actual API response from docs/examples
-    2. Include ALL fields system might consume downstream
-    3. Verify mock matches real response schema completely
-
-  Critical:
-    If you're creating a mock, you must understand the ENTIRE structure
-    Partial mocks fail silently when code depends on omitted fields
-
-  If uncertain: Include all documented fields
-```
-
-## Anti-Pattern 5: Integration Tests as Afterthought
-
-**The violation:**
-```
-✅ Implementation complete
-❌ No tests written
-"Ready for testing"
-```
-
-**Why this is wrong:**
-- Testing is part of implementation, not optional follow-up
-- TDD would have caught this
-- Can't claim complete without tests
-
-**The fix:**
-```
-TDD cycle:
-1. Write failing test
-2. Implement to pass
-3. Refactor
-4. THEN claim complete
-```
+## The Bottom Line
 
-## When Mocks Become Too Complex
+**Mocks are tools to isolate, not things to test.**
 
-**Warning signs:**
-- Mock setup longer than test logic
-- Mocking everything to make test pass
-- Mocks missing methods real components have
-- Test breaks when mock changes
+If you're testing mock behavior, you've gone wrong. Fix: Test real behavior or question why you're mocking at all.
 
-**your human partner's question:** "Do we need to be using a mock here?"
+**TDD prevents these patterns.** Write test first → Watch fail → Minimal implementation → Pass → Refactor.
 
-**Consider:** Integration tests with real components often simpler than complex mocks
+## Navigation
 
-## TDD Prevents These Anti-Patterns
+### Detailed Anti-Pattern Analysis
+- **[Core Anti-Patterns](references/core-anti-patterns.md)** - Patterns 1-3: Mock behavior, test-only methods, uninformed mocking
+- **[Completeness Anti-Patterns](references/completeness-anti-patterns.md)** - Patterns 4-5: Incomplete mocks, tests as afterthought
 
-**Why TDD helps:**
-1. **Write test first** → Forces you to think about what you're actually testing
-2. **Watch it fail** → Confirms test tests real behavior, not mocks
-3. **Minimal implementation** → No test-only methods creep in
-4. **Real dependencies** → You see what the test actually needs before mocking
+### Detection & Prevention
+- **[Detection Guide](references/detection-guide.md)** - Red flags, warning signs, gate functions
+- **[TDD Connection](references/tdd-connection.md)** - How test-driven development prevents these patterns
 
-**If you're testing mock behavior, you violated TDD** - you added mocks without watching test fail against real code first.
+### Related Skills
+- **[test-driven-development](../test-driven-development/)** - Complete TDD workflow (prevents these patterns)
+- **[verification-before-completion](../../../productivity/verification-before-completion/)** - Testing is part of "done"
 
-## Quick Reference
+## Key Reminders
 
-| Anti-Pattern | Fix |
-|--------------|-----|
-| Assert on mock elements | Test real component or unmock it |
-| Test-only methods in production | Move to test utilities |
-| Mock without understanding | Understand dependencies first, mock minimally |
-| Incomplete mocks | Mirror real API completely |
-| Tests as afterthought | TDD - tests first |
-| Over-complex mocks | Consider integration tests |
+1. **Mocks isolate, don't prove** - Test real code, not mocks
+2. **Production ignores tests** - No test-only methods
+3. **Understand before mocking** - Know dependencies and side effects
+4. **Complete mocks only** - Mirror full API structure
+5. **Tests ARE implementation** - Not optional afterthought
 
-## Red Flags
+## Red Flags - STOP
 
-- Assertion checks for `*-mock` test IDs
-- Methods only called in test files
-- Mock setup is >50% of test
-- Test fails when you remove mock
-- Can't explain why mock is needed
-- Mocking "just to be safe"
+**STOP immediately if you find yourself:**
+- Asserting on `*-mock` test IDs
+- Adding methods only called in test files
+- Mocking "just to be safe" without understanding
+- Creating mocks from memory instead of API docs
+- Saying "tests can wait" or "ready for testing"
 
-## The Bottom Line
-
-**Mocks are tools to isolate, not things to test.**
+**When mocks become too complex:** Consider integration tests with real components. Often simpler and more valuable.
 
-If TDD reveals you're testing mock behavior, you've gone wrong.
+## Integration with Other Skills
 
-Fix: Test real behavior or question why you're mocking at all.
+**Prerequisite:** [test-driven-development](../test-driven-development/) - TDD prevents anti-patterns
+**Complementary:** [verification-before-completion](../../../productivity/verification-before-completion/) - Tests = done
+**Domain-specific:** webapp-testing, backend-testing for framework patterns