Claude-Code-Workflow/.claude/commands/workflow/tools/test-context-gather.md

---
name: test-context-gather
description: Collect test coverage context and identify files requiring test generation
argument-hint: "--session WFS-test-session-id"
examples:
  - /workflow:tools:test-context-gather --session WFS-test-auth
  - /workflow:tools:test-context-gather --session WFS-test-payment
---

# Test Context Gather Command

## Overview
Specialized context collector for test generation workflows that analyzes test coverage, identifies missing tests, and packages implementation context from source sessions.

## Core Philosophy
- **Coverage-First**: Analyze existing test coverage before planning
- **Gap Identification**: Locate implementation files without corresponding tests
- **Source Context Loading**: Import implementation summaries from source session
- **Framework Detection**: Auto-detect test framework and patterns
- **Ripgrep-Powered**: Leverage ripgrep and native tools for precise analysis

## Core Responsibilities
- Load source session implementation context
- Analyze current test coverage using ripgrep
- Identify files requiring test generation
- Detect test framework and conventions
- Package test context for analysis phase

## Execution Lifecycle

### Phase 1: Session Validation & Source Loading

1. **Test Session Validation**
   - Load `.workflow/{test_session_id}/workflow-session.json`
   - Extract `meta.source_session` reference
   - Validate test session type is "test-gen"

2. **Source Session Context Loading**
   - Read `.workflow/{source_session_id}/workflow-session.json`
   - Load implementation summaries from `.workflow/{source_session_id}/.summaries/`
   - Extract changed files and implementation scope
   - Identify implementation patterns and tech stack

### Phase 2: Test Coverage Analysis (Ripgrep)

1. **Existing Test Discovery**
   ```bash
   # Find all test files
   find . -name "*.test.*" -type f
   find . -name "*.spec.*" -type f
   find . -name "*test_*.py" -type f

   # Search for test patterns
   rg "describe|it|test|@Test" -g "*.test.*"
   ```

2. **Coverage Gap Analysis**
   ```bash
   # For each implementation file from source session
   # Check if corresponding test file exists

   # Example: src/auth/AuthService.ts -> tests/auth/AuthService.test.ts
   #          src/utils/validator.py -> tests/test_validator.py

   # Output: List of files without tests
   ```

3. **Test Statistics**
   - Count total test files
   - Count implementation files from source session
   - Calculate coverage percentage
   - Identify coverage gaps by module

### Phase 3: Test Framework Detection

1. **Framework Identification**
   ```bash
   # Check package.json or requirements.txt
   rg "jest|mocha|jasmine|pytest|unittest|rspec" -g "package.json" -g "requirements.txt" -g "Gemfile" -C 2

   # Analyze existing test patterns
   rg "describe\(|it\(|test\(|def test_" -g "*.test.*" -C 3
   ```

2. **Convention Analysis**
   - Test file naming patterns (*.test.ts vs *.spec.ts)
   - Test directory structure (tests/ vs __tests__ vs src/**/*.test.*)
   - Assertion library (expect, assert, should)
   - Mocking framework (jest.fn, sinon, unittest.mock)

### Phase 4: Context Packaging

Generate `test-context-package.json`:

```json
{
  "metadata": {
    "test_session_id": "WFS-test-auth",
    "source_session_id": "WFS-auth",
    "timestamp": "2025-10-04T10:30:00Z",
    "task_type": "test-generation",
    "complexity": "medium"
  },
  "source_context": {
    "implementation_summaries": [
      {
        "task_id": "IMPL-001",
        "summary_path": ".workflow/WFS-auth/.summaries/IMPL-001-summary.md",
        "changed_files": [
          "src/auth/AuthService.ts",
          "src/auth/TokenValidator.ts",
          "src/middleware/auth.ts"
        ],
        "implementation_type": "feature"
      }
    ],
    "tech_stack": ["typescript", "express", "jsonwebtoken"],
    "project_patterns": {
      "architecture": "layered",
      "error_handling": "try-catch with custom errors",
      "async_pattern": "async/await"
    }
  },
  "test_coverage": {
    "existing_tests": [
      "tests/auth/AuthService.test.ts",
      "tests/middleware/auth.test.ts"
    ],
    "missing_tests": [
      {
        "implementation_file": "src/auth/TokenValidator.ts",
        "suggested_test_file": "tests/auth/TokenValidator.test.ts",
        "priority": "high",
        "reason": "New implementation without tests"
      }
    ],
    "coverage_stats": {
      "total_implementation_files": 3,
      "files_with_tests": 2,
      "files_without_tests": 1,
      "coverage_percentage": 66.7
    }
  },
  "test_framework": {
    "framework": "jest",
    "version": "^29.0.0",
    "test_pattern": "**/*.test.ts",
    "test_directory": "tests/",
    "assertion_library": "expect",
    "mocking_framework": "jest",
    "conventions": {
      "file_naming": "*.test.ts",
      "test_structure": "describe/it blocks",
      "setup_teardown": "beforeEach/afterEach"
    }
  },
  "assets": [
    {
      "type": "implementation_summary",
      "path": ".workflow/WFS-auth/.summaries/IMPL-001-summary.md",
      "relevance": "Source implementation context",
      "priority": "highest"
    },
    {
      "type": "existing_test",
      "path": "tests/auth/AuthService.test.ts",
      "relevance": "Test pattern reference",
      "priority": "high"
    },
    {
      "type": "source_code",
      "path": "src/auth/TokenValidator.ts",
      "relevance": "Implementation requiring tests",
      "priority": "high"
    },
    {
      "type": "documentation",
      "path": "CLAUDE.md",
      "relevance": "Project conventions",
      "priority": "medium"
    }
  ],
  "focus_areas": [
    "Generate comprehensive tests for TokenValidator",
    "Follow existing Jest patterns from AuthService tests",
    "Cover happy path, error cases, and edge cases",
    "Include integration tests for middleware"
  ]
}
```

## Output Location

```
.workflow/{test_session_id}/.process/test-context-package.json
```

## Native Tools Usage

### File Discovery
```bash
# Test files
find . -name "*.test.*" -type f
find . -name "*.spec.*" -type f

# Implementation files
find . -name "*.ts" -type f
find . -name "*.js" -type f
```

### Content Search
```bash
# Test framework detection
rg "jest|mocha|pytest" -g "package.json" -g "requirements.txt"

# Test pattern analysis
rg "describe|it|test" -g "*.test.*" -C 2
```

### Coverage Analysis
```bash
# For each implementation file
# Check if test exists
implementation_file="src/auth/AuthService.ts"
test_file_patterns=(
  "tests/auth/AuthService.test.ts"
  "src/auth/AuthService.test.ts"
  "src/auth/__tests__/AuthService.test.ts"
)

# Search for test file
for pattern in "${test_file_patterns[@]}"; do
  if [ -f "$pattern" ]; then
    echo "✅ Test exists: $pattern"
    break
  fi
done
```

## Error Handling

| Error | Cause | Resolution |
|-------|-------|------------|
| Source session not found | Invalid source_session reference | Verify test session metadata |
| No implementation summaries | Source session incomplete | Complete source session first |
| No test framework detected | Missing test dependencies | Request user to specify framework |

## Native Tools Implementation

```bash
# File discovery
find . -name "*.test.*" -o -name "*.spec.*" | grep -v node_modules

# Framework detection
grep -r "jest\|mocha\|pytest" package.json requirements.txt 2>/dev/null

# Coverage analysis
for impl_file in $(cat changed_files.txt); do
  test_file=$(echo $impl_file | sed 's/src/tests/' | sed 's/\(.*\)\.\(ts\|js\|py\)$/\1.test.\2/')
  [ ! -f "$test_file" ] && echo "$impl_file → MISSING TEST"
done
```

## Integration

### Called By
- `/workflow:test-gen` (Phase 3: Context Gathering)

### Calls
- Ripgrep and find for file analysis
- Bash file operations for coverage analysis

### Followed By
- `/workflow:tools:test-concept-enhanced` - Analyzes context and plans test generation

## Success Criteria

- ✅ Source session context loaded successfully
- ✅ Test coverage gaps identified with ripgrep
- ✅ Test framework detected and documented
- ✅ Valid test-context-package.json generated
- ✅ All missing tests catalogued with priority
- ✅ Execution time < 20 seconds

## Related Commands

- `/workflow:test-gen` - Main test generation workflow
- `/workflow:tools:test-concept-enhanced` - Test generation analysis
- `/workflow:tools:test-task-generate` - Test task JSON generation