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

name, description, argument-hint, examples

name	description	argument-hint	examples
test-context-gather	Collect test coverage context and identify files requiring test generation	--session WFS-test-session-id	/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

   # 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

   # 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

   # 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:

{
  "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

# 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

# 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

# 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

# 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