test-failure-investigator

name	test-failure-investigator
description	Use when a test is failing and you need to determine root cause: is it flaky, an environment issue, or a real regression? Traces failure from symptom to fix.
user-invocable	true

Test Failure Investigator

Runbook-style skill for systematic test failure investigation. Given a failing test, determines root cause and recommends action.

Activation

/test-failure-investigator [test-name-or-file]

Investigation Flow

Step 1: Classify the Failure

Run the test 3 times and classify:

Result Pattern	Classification	Action
Fails consistently	Regression or Environment	Continue to Step 2
Fails intermittently	Flaky	Skip to Step 4
Passes now	Transient	Check CI logs, environment diff

# Run test 3 times
for i in 1 2 3; do npx jest {{test_file}} 2>&1 | tail -5; echo "--- Run $i ---"; done

Step 2: Narrow the Scope

# When did it start failing?
git log --oneline -20 -- {{related_source_files}}

# What changed recently?
git diff HEAD~5 -- {{related_source_files}}

# Does it fail in isolation?
npx jest {{test_file}} --testNamePattern="{{test_name}}"

# Does it fail with other tests?
npx jest --runInBand  # sequential execution

Step 3: Root Cause Analysis

Symptom	Likely Cause	Investigation
Timeout	Network/DB dependency	Check external service availability
Assertion mismatch	Logic change	Compare expected vs actual, check git blame
Import error	Dependency change	Check package.json changes, run npm ci
Permission denied	Environment	Check file permissions, Docker volumes
Out of memory	Resource leak	Profile with --detectOpenHandles

Step 4: Flaky Test Investigation

# Run 10 times to confirm flakiness
for i in $(seq 1 10); do npx jest {{test_file}} --forceExit 2>&1 | grep -E 'PASS|FAIL'; done

# Common flaky causes:
# - Shared state between tests (missing cleanup)
# - Time-dependent assertions (use fake timers)
# - Race conditions (missing await)
# - Port conflicts (use random ports)
# - Order dependency (run with --randomize)

Step 5: Report

## Test Failure Report
- **Test**: {{test_name}}
- **File**: {{test_file}}
- **Classification**: Regression / Flaky / Environment / Transient
- **Root Cause**: {{description}}
- **First Failed**: {{commit_hash}} ({{date}})
- **Fix**: {{recommended_action}}
- **Verified**: [ ] Fix applied and test passes 3x consecutively

Composition

After investigation, compose with:

• /bug-reporting-excellence — if regression found, file a bug report
• /regression-testing — if regression, add to regression suite
• /qe-test-execution — for re-running tests after fix

Gotchas

• Agent may guess at root cause without running the test — always reproduce first
• "Works on my machine" is not a diagnosis — compare environments (node version, OS, deps)
• Flaky tests that pass 9/10 times will still be reported as "passing" by CI — run 10+ times
• Test isolation failures are the #1 cause of flaky tests — check for shared state in beforeAll/afterAll