/testing-preferred-patterns

name: testing-preferred-patterns
description: "Identify and fix testing mistakes: flaky, brittle, over-mocked tests."
user-invocable: false
allowed-tools:
  - Read
  - Write
  - Bash
  - Grep
  - Glob
  - Edit
  - Task
routing:
  category: testing
  triggers:
    - flaky test
    - brittle test
    - test smell
    - test quality issue
    - slow tests
    - skipped test
    - test depends on order
    - over-mocking
    - fragile test
    - testing implementation details
  pairs_with:
    - test-driven-development
    - go-patterns
    - vitest-runner
  complementary: test-driven-development

Testing Pattern Quality Skill

Overview

This skill identifies and fixes common testing mistakes across unit, integration, and E2E test suites. Tests should verify behavior, be reliable, run fast, and fail for the right reasons.

**Scope:** This skill focuses on improving test quality and reliability. It complements `test-driven-development` by addressing what goes wrong with tests, complementing how to write them correctly from scratch.

**Out of scope:** Writing new tests from scratch (use `test-driven-development`), fixing fundamental architectural issues (use `systematic-refactoring`), or profiling test performance with external tools.

---

Reference Loading Table

| Signal | Load These Files | Why | |---|---|---| | BAD/GOOD code examples for all 10 testing failure modes | `preferred-pattern-catalog.md` | Loads detailed guidance from `preferred-pattern-catalog.md`. | | auditing coverage gaps: concurrency, boundaries, security, error recovery | `blind-spot-taxonomy.md` | Loads detailed guidance from `blind-spot-taxonomy.md`. | | errors, error handling | `error-handling.md` | Loads detailed guidance from `error-handling.md`. | | fixing review feedback | `fix-strategies.md` | Loads detailed guidance from `fix-strategies.md`. | | tests | `load-test-scenarios.md` | Loads detailed guidance from `load-test-scenarios.md`. | | classifying test-quality failure modes found during SCAN | `quality-catalog.md` | Loads detailed guidance from `quality-catalog.md`. | | fast pattern-symptom-fix lookup | `quick-reference.md` | Loads detailed guidance from `quick-reference.md`. |

Instructions

Phase 1: SCAN

**Goal**: Identify quality issues present in the target test code.

**Step 1: Locate test files**

Use Grep/Glob to find test files in the relevant area. If user pointed to specific files, start there. Common patterns:

• Go: `*_test.go`
• Python: `test_*.py` or `*_test.py`
• JavaScript/TypeScript: `*.test.ts`, `*.spec.ts`, `*.test.js`, `*.spec.js`

**Step 2: Read CLAUDE.md**

Check for project-specific testing conventions before flagging quality issues. Some projects intentionally deviate from general best practices. This prevents false positives based on organizational standards.

**Step 3: Classify quality issues**

For each test file, scan for these 10 categories (detailed examples in `references/preferred-pattern-catalog.md`):

| # | Pattern to Fix | Detection Signal | |---|-------------|-----------------| | 1 | Testing implementation details | Asserts on private fields, internal regex, spy on private methods | | 2 | Over-mocking / brittle selectors | Mock setup > 50% of test code, CSS nth-child selectors | | 3 | Order-dependent tests | Shared mutable state, class-level variables, numbered test names | | 4 | Incomplete assertions | `!= nil`, `> 0`, `toBeTruthy()`, no value checks | | 5 | Over-specification | Exact timestamps, hardcoded IDs, asserting every default field | | 6 | Ignored failures | `@skip`, `.skip`, `xit`, empty catch blocks, `_ = err` | | 7 | Poor naming | `testFunc2`, `test_new`, `it('works')`, `it('handles case')` | | 8 | Missing edge cases | Only happy path, no empty/null/boundary/error tests | | 9 | Slow test suites | Full DB reset per test, no parallelization, no fixture sharing | | 10 | Flaky tests | `sleep()`, `time.Sleep()`, `setTimeout()`, unsynchronized goroutines |

**Step 4: Document findings**

## Pattern Quality Report

### [File:Line] - [Pattern Name]
- **Severity**: HIGH / MEDIUM / LOW
- **Issue**: [What is wrong]
- **Impact**: [Flaky / slow / false-confidence / maintenance burden]

**Gate**: At least one quality issue identified with file:line reference. Proceed only when gate passes.

Phase 2: PRIORITIZE

**Goal**: Rank findings by impact to fix the most damaging patterns first.

**Priority order:** 1. **HIGH** - Flaky tests, order-dependent tests, ignored failures (erode trust in suite) 2. **MEDIUM** - Over-mocking, incomplete assertions, missing edge cases (false confidence) 3. **LOW** - Poor naming, over-specification, slow suites (maintenance burden)

**Constraint: Fix one pattern at a time.** Mechanical bulk fixes (applying the same pattern to 50 tests without running them) miss context-specific nuances and cause regressions. Fix one, verify it works, then move to the next.

**Constraint: Preserve test intent.** When fixing quality issues, maintain what the test was originally trying to verify. Preserve the original test coverage scope.

**Constraint: Prevent over-engineering.** Fix the specific quality issue identified; make targeted fixes to the specific failure mode or delete tests and write new ones from scratch. Institutional knowledge lives in the existing tests.

**Gate**: Findings ranked. User agrees on scope of fixes. Proceed only when gate passes.

Phase 3: FIX

**Goal**: Apply targeted fixes to identified quality issues.

**Step 1: For each quality issue (highest priority first):**

ISSUE: [Name]
Location: [file:line]
Issue: [What is wrong]
Impact: [Flaky/slow/false-confidence/maintenance burden]

Current:
[problematic code snippet]

Fixed:
[improved code snippet]

Priority: [HIGH/MEDIUM/LOW]

**Step 2: Apply fix**

**Constraint: Show real examples.** Point to actual code when identifying quality issues, not abstract descriptions. Check for rationalization — if a test breaks during refactoring