test-suite

What this skill does

# Test Suite Generator

Generate comprehensive test suites with coverage gap analysis and parallel test writing, following testing best practices across any project type and framework.

## Target

$ARGUMENTS

## Anti-Hallucination Guidelines

**CRITICAL**: Test generation must be based on ACTUAL code and VERIFIED project patterns:
1. **Read source code first** - Never write tests for code that has not been read and understood
2. **Discover test framework** - Do NOT assume pytest, vitest, jest, or any specific framework
3. **Follow existing patterns** - Match the project's existing test style, fixtures, and conventions exactly
4. **Verify tests run** - All generated tests must actually pass when executed
5. **No invented APIs** - Only test methods, functions, and interfaces that actually exist in the code
6. **Real assertions** - Every test must have meaningful assertions, not just "does not throw"
7. **Coverage-driven** - Focus on untested code paths, not duplicating existing coverage

## Quality Gates

This skill includes automatic verification before completion:

### Test Verification (Stop Hook)

When attempting to stop working, an automated verification agent runs to ensure quality:

**Verification Steps:**
1. **Test Execution**: Runs discovered test command. All tests (new and existing) must pass.
2. **Coverage Check**: If coverage tooling exists, verifies improvement over baseline.
3. **Lint Check**: Ensures test files pass linting rules.

**Behavior:**
- All checks pass: Test generation marked complete
- Any check fails: Completion blocked, error details provided, Claude continues fixing
- Commands not found: Hook discovers them from CLAUDE.md or project files

**Example blocked completion:**
```
Test verification failed:

Tests: FAILED (2 new tests failing)
  - test_user_service_create: AttributeError: 'UserService' has no method 'create_user'
  - test_parse_config_empty: Expected ValueError, got None

Coverage: IMPROVED (72% → 78%)
Lint: PASSED

Cannot complete until all tests pass. Fix the failing tests.
```

## Task Management

This skill uses Claude Code's Task Management System to track test generation progress with dependency-aware task tracking.

**When to Use Tasks:**
- Generating tests for multiple files or modules
- Coverage improvement across a codebase
- Complex test generation requiring parallel subagents

**When to Skip Tasks:**
- Adding 1-2 tests to a single file
- Simple unit test additions
- Quick test fixes

## Implementation Workflow

### Phase 0: Project Discovery (REQUIRED)

**Step 0.1: Create Task Structure**

Before generating tests, create the dependency-aware task structure:

```
TaskCreate:
  subject: "Phase 0: Discover project test workflow"
  description: "Identify test framework, coverage tools, and conventions"
  activeForm: "Discovering test workflow"

TaskCreate:
  subject: "Phase 1: Analyze coverage gaps"
  description: "Run coverage, identify untested code, prioritize targets"
  activeForm: "Analyzing coverage gaps"

TaskCreate:
  subject: "Phase 2: Create test plan"
  description: "Present test plan to user for approval"
  activeForm: "Creating test plan"

TaskCreate:
  subject: "Phase 3: Generate tests in parallel"
  description: "Spawn subagents to write tests for each module group"
  activeForm: "Generating tests"

TaskCreate:
  subject: "Phase 4: Quality verification"
  description: "Run all tests, check coverage improvement, lint"
  activeForm: "Verifying test quality"

TaskCreate:
  subject: "Phase 5: Final commit"
  description: "Commit tests with coverage summary"
  activeForm: "Committing tests"

# Set up strict sequential chain
TaskUpdate: { taskId: "2", addBlockedBy: ["1"] }
TaskUpdate: { taskId: "3", addBlockedBy: ["2"] }
TaskUpdate: { taskId: "4", addBlockedBy: ["3"] }
TaskUpdate: { taskId: "5", addBlockedBy: ["4"] }
TaskUpdate: { taskId: "6", addBlockedBy: ["5"] }

# Start first task
TaskUpdate: { taskId: "1", status: "in_progress" }
```

**Step 0.2: Discover Test Workflow**

Use Haiku-powered Explore agent for token-efficient discovery:

```
Use Task tool with Explore agent:
- prompt: "Discover the testing workflow for this project:
    1. Read CLAUDE.md if it exists - extract testing conventions and commands
    2. Check for task runners: Makefile, justfile, package.json scripts, pyproject.toml scripts
    3. Identify the test framework:
       - Python: pytest, unittest, nose2
       - JavaScript/TypeScript: vitest, jest, mocha, playwright, cypress
       - Other: go test, cargo test, etc.
    4. Identify the test command (e.g., make test, npm test, pytest, bun test)
    5. Identify the coverage command (e.g., pytest --cov, vitest --coverage, jest --coverage, make coverage)
    6. Identify the lint command
    7. Find existing test directory structure and naming conventions
    8. Look at 2-3 existing test files to understand:
       - Import patterns and test utilities
       - Fixture/mock patterns used
       - Assertion style (assert, expect, etc.)
       - Test organization (describe/it vs test functions)
       - Setup/teardown patterns
       - Factory or fixture patterns
    9. Check for test configuration files:
       - pytest.ini, conftest.py, setup.cfg [tool.pytest]
       - vitest.config.ts, jest.config.js
       - .nycrc, c8 config, istanbul config
    10. Note any test-related CI/CD configuration
    Return a structured summary of all testing infrastructure."
- subagent_type: "Explore"
- model: "haiku"
```

Store discovered commands and patterns for use in later phases.

**Step 0.3: Complete Phase 0**

```
TaskUpdate: { taskId: "1", status: "completed" }
TaskList  # Check that Task 2 is now unblocked
```

### Phase 1: Coverage Gap Analysis

**Goal**: Identify what code lacks test coverage and prioritize test generation targets.

**Step 1.1: Start Phase 1**

```
TaskUpdate: { taskId: "2", status: "in_progress" }
```

**Step 1.2: Establish Coverage Baseline**

Run the discovered coverage command to get the current state:

```bash
# Examples (use the ACTUAL discovered command):
pytest --cov --cov-report=term-missing
vitest --coverage
jest --coverage
make coverage
```

Capture the output. If no coverage tooling exists, use an Explore agent to manually identify untested code:

```
Use Task tool with Explore agent:
- prompt: "Analyze test coverage gaps for this project:
    1. List all source files/modules in the project (exclude test files, configs, migrations)
    2. List all test files
    3. For each source file, check if a corresponding test file exists
    4. For files with tests, skim the test file to estimate which functions/methods are tested
    5. Identify files with no tests at all
    6. Identify complex files (many functions, classes, branching logic) that likely need more tests
    Return a structured report:
    - Files with NO test coverage (highest priority)
    - Files with PARTIAL coverage (functions/methods missing tests)
    - Files with GOOD coverage (low priority)
    - Overall estimated coverage percentage"
- subagent_type: "Explore"
- model: "haiku"
```

**Step 1.3: Prioritize Test Targets**

Rank files/modules for test generation by:
1. **Critical business logic** - Authentication, payments, data processing
2. **Untested code** - Files with zero test coverage
3. **Complex code** - High cyclomatic complexity, many branches
4. **Recently changed** - Code modified in recent commits (use `git log --oneline -20 --name-only`)
5. **Error-prone areas** - Code with known bugs or frequent changes

If the user specified target files/modules, prioritize those. Otherwise, use the ranking above.

**Step 1.4: Complete Phase 1**

```
TaskUpdate: { taskId: "2", status: "completed" }
TaskList  # Check that Task 3 is now unblocked
```

### Phase 2: Test Plan (User Approval)

**Goal**: Present a test plan for user review before generating tests.

**Step 2.1: Start Phase 2**

```
TaskUpdate: { taskId: "3", status: "in_progress" }
```

**Step 2.2: Present Test Plan**

Use `A