test-debugging

Test Debugging & Maintenance Workflow

When asked to debug tests or improve test coverage, follow this workflow to identify problems, determine root causes, and apply appropriate fixes.

Contents

• How to use this skill
• Related skills
• Step 1: Run and Observe the Test
• Step 2: Investigate Root Cause
• Step 3: Report Findings
• Step 4: Determine Fix Strategy
• Step 5: Verify Test Fix
• Project-Specific Considerations

How to use this skill

Attach this file to your Copilot Chat context, then invoke it with the failing test file, test name, or flakiness symptom. Stop at Step 3 for diagnosis-only requests unless the user asks for implementation.

Related skills

• RSpec Unit Testing Standards — rules governing test isolation, determinism, and order independence (Rules 25–28); consult when flakiness is caused by a test design violation rather than a production bug
• Development Workflow — required TDD process when fixes involve production code
• CI/CD Troubleshooting — investigate failures that appear only in CI

Step 1: Run and Observe the Test

1. Run the failing test:

   # RSpec unit test
   bundle exec rspec spec/unit/git/commands/<command>_spec.rb
   
   # RSpec integration test
   bundle exec rspec spec/integration/git/commands/<command>_spec.rb
   
   # Specific example, by line number
   bundle exec rspec spec/unit/git/commands/<command>_spec.rb:42
   

2. For suspected flaky tests, run multiple times:

   for i in {1..20}; do
     echo "Run $i"
     bundle exec rspec <spec_file> || break
   done
   

3. Check test isolation — run the test alone vs. within the full suite:

   bundle exec rspec <spec_file>   # alone
   bundle exec rake default        # full suite
   

Step 2: Investigate Root Cause

1. Read the full error including stack trace. Identify exact failing line and expected vs. actual values.

2. Check recent changes with git log and git blame on the test file and related production code.

3. For flaky tests, look for:

   • Shared state between tests (global/class variables, shared filesystem resources)
   • Timing dependencies or race conditions
   • Non-deterministic behavior (time-dependent logic, unordered iteration)
   • Test execution order dependencies

4. For environment issues, check:

   • Platform differences (paths, line endings, permissions)
   • Git version differences (use git --version)
   • Ruby version differences

Step 3: Report Findings

Present diagnostic findings to the user:

# Test Failure Diagnosis: <test_name>

**Failure Type:** [Consistent / Flaky / Coverage Gap]
**Test File:** <path/to/test_file.rb>

## Error
<error message and relevant stack trace>

## Root Cause
<Explanation of why the test is failing>

## Recommended Fix
<Specific recommendation>

**Would you like me to implement this fix?**

STOP here unless the user asks you to proceed with the fix.

Step 4: Determine Fix Strategy

CRITICAL: Get user confirmation before modifying existing tests.

Step 5: Verify Test Fix

# Run the specific test
bundle exec rspec <spec_file>

# For flaky test fixes, run many times
for i in {1..50}; do
  echo "Run $i"
  bundle exec rspec <spec_file> || break
done

# Run full suite
bundle exec rake default

Project-Specific Considerations

Test framework: This project uses RSpec exclusively (spec/unit/ and spec/integration/).

Test helpers: Use the 'in an empty repository' shared context (and other spec/support/contexts/ shared contexts) plus Git::IntegrationTestHelpers methods (e.g. write_file) for integration specs. Use let/let! and verifying doubles for unit specs — see RSpec Unit Testing Standards.

Mocking: The project uses RSpec doubles (instance_double, class_double) for unit specs. Be careful with stubs — they can mask real issues.

Test data: Integration specs create temporary repos on the fly (e.g. via Dir.mktmpdir and the shared contexts above). Static fixture files in spec/support/fixtures/ exist for a small number of specs that need pre-built content (e.g. spec/integration/git/command_line_spec.rb); prefer dynamic helpers for new specs. Clean up any state created outside those helpers.

CI vs. local differences: If tests pass locally but fail in CI, use the ci-cd-troubleshooting skill.