When to invoke (auto-trigger)

Invoke automatically whenever:

• Source files under src/ have been edited and a commit is about to happen
• The user asks to verify, check, or run tests without specifying which suite
• Tests are mentioned as a blocker ("make sure tests pass before merging")

Do NOT invoke for: documentation-only edits, config-only changes, or when the user explicitly says to skip tests.

Intelligent Test Workflow Coordinator

When to Use This Skill

Use this skill when:

• You've made code changes and need to run tests
• Unsure which test suite is appropriate (unit, E2E, visual, all?)
• Want smart test selection based on changed files
• Need coordinated test execution with dev server awareness

What This Skill Does

Analyzes your changes and intelligently runs the appropriate test suite(s):

• Unit tests for logic, utilities, hooks
• E2E tests for user flows and integration
• Visual regression for UI component changes
• CSS lint for style changes
• Full suite for widespread changes

Usage Flow

Phase 0: Read the project's scripts

Before running anything, list the scripts the project defines (scripts in package.json, or the repo's equivalent such as a Makefile or pyproject.toml). Map each phase below (type check, CSS lint, unit, E2E, visual) to the script that does that job. Script names differ between projects, so every command in this skill is an example. If a phase has no matching script, skip it and say so in the report. Never run a script name you haven't confirmed exists.

Phase 1: Analyze Changes

Detect what changed:

# Get changed files (staged or unstaged)
git diff --name-only HEAD
git diff --cached --name-only

# Or compare against the base branch (develop if it exists, else main)
base=$(git rev-parse --verify -q origin/develop || echo origin/main)
git diff "$base"...HEAD --name-only

Categorize changes:

📝 **Changed Files Analysis**

Component files: 3
- src/components/UserProfile.tsx
- src/components/Dashboard.tsx
- src/components/common/Button.tsx

Test files: 2
- src/components/UserProfile.test.ts
- src/components/Dashboard.test.ts

Style files: 1
- src/styles/dashboard.css

Utility files: 0

E2E test files: 0

Phase 2: Recommend Test Strategy

Based on changes:

## Recommended Test Strategy

### Why This Strategy

You've changed:
- 3 component files → Need unit tests + E2E tests
- 1 CSS file → Need CSS lint + visual regression
- Modified existing tests → They'll run automatically

### Recommended Test Suite

**Primary (Must Pass):**
1. Unit tests for changed components
2. CSS lint validation
3. TypeScript type check

**Secondary (Highly Recommended):**
4. E2E tests that use these components
5. Visual regression for Button component

**Optional (If Time Permits):**
6. Full test suite (confidence check)

### Execution Plan

Script names below are examples. Substitute the project's own from Phase 0.

```bash
# Phase 1: Quick validation (< 1 minute)
npm run type-check
npm run lint:css

# Phase 2: Unit tests (1-2 minutes)
npm test -- UserProfile Dashboard Button

# Phase 3: E2E tests (2-3 minutes)
npm run test:e2e:critical

# Phase 4: Visual regression (3-5 minutes)
npm run test:visual -- Button

# Total estimated time: 7-11 minutes

Proceed with: (a) Recommended strategy (all phases) (b) Quick validation only (phase 1) (c) Skip E2E/visual (phases 1-2 only) (d) Full test suite (everything) (e) Custom (I'll ask which tests)

### Phase 3: Dev Server Coordination

**Critical check before running tests:**

Find this checkout's dev-server port first: the dev server's entry in `.claude/launch.json`, the port in its dev script, or a `PORT` in its env. Don't assume 3000; in a worktree or another app, 3000 is usually someone else's server.

```bash
# PORT comes from the project (see above). No fallback: a guess checks the wrong server.
DEV_SERVER_PID=$([ -n "$PORT" ] && lsof -ti:"$PORT")

if [ -z "$PORT" ]; then
  echo "No dev-server port found for this checkout"
  NEED_SERVER=true
elif [ -n "$DEV_SERVER_PID" ]; then
  echo "✅ Dev server running on port $PORT (PID: $DEV_SERVER_PID)"
  echo "Tests will use existing server"
  NEED_SERVER=false
else
  echo "❌ No dev server found"
  echo "E2E and visual tests require dev server"
  NEED_SERVER=true
fi

If dev server needed:

⚠️ Dev server required for E2E/visual tests

Options:
(a) Start dev server now (I'll wait for it)
(b) Skip E2E/visual tests for now
(c) You start the server, then I'll continue

Which option?

Never:

• Kill existing dev server
• Start multiple dev servers
• Proceed with E2E/visual tests without dev server

Phase 4: Execute Tests

Run tests in phases, reporting after each:

Phase 1: Quick Validation

echo "Phase 1: Quick Validation"
echo "========================="

# Type check
npm run type-check
TYPE_CHECK_STATUS=$?

# CSS lint
npm run lint:css
CSS_LINT_STATUS=$?

# ESLint
npm run lint
LINT_STATUS=$?

Report:

## Phase 1 Results: Quick Validation

✅ Type Check: PASS
✅ CSS Lint: PASS
✅ ESLint: PASS

Time: 32 seconds

Phase 2: Unit Tests

echo "Phase 2: Unit Tests"
echo "==================="

# Run specific test files
npm test -- UserProfile Dashboard Button --coverage
UNIT_TEST_STATUS=$?

Report:

## Phase 2 Results: Unit Tests

✅ UserProfile.test.ts: 12/12 passed
✅ Dashboard.test.ts: 8/8 passed
✅ Button.test.ts: 15/15 passed

Coverage:
- Statements: 87% (target: 80%)
- Branches: 76% (target: 75%)
- Functions: 92% (target: 85%)

Time: 1m 23s

Phase 3: E2E Tests

echo "Phase 3: E2E Tests"
echo "=================="

# Verify dev server still running
if ! lsof -ti:"$PORT" > /dev/null; then
  echo "❌ Dev server not running! Cannot proceed."
  exit 1
fi

# Run E2E tests
npm run test:e2e:critical
E2E_STATUS=$?

If E2E test fails: Apply the test-fix skill (3-attempt limit)

Report:

## Phase 3 Results: E2E Tests

✅ Login flow: PASS
✅ Dashboard navigation: PASS
⚠️  User profile edit: FAIL (1 test)

Failed Test: user-profile-edit.spec.ts
Error: Timeout waiting for save button

Applied test-fix skill (attempt 1/3)...
Fixed: Added explicit wait for API response
Re-run: ✅ PASS

Time: 2m 45s

Phase 4: Visual Regression

echo "Phase 4: Visual Regression"
echo "=========================="

# Run visual tests for changed components
npm run test:visual -- Button
VISUAL_STATUS=$?

Report:

## Phase 4 Results: Visual Regression

✅ Button component: All snapshots match

Snapshots tested: 8
- Default state
- Hover state
- Disabled state
- Loading state
- Primary variant
- Secondary variant
- Small size
- Large size

Time: 4m 12s

Phase 5: Final Report

## Test Workflow Complete

### ✅ All Tests Passed

**Phase 1:** Quick Validation ✅ (32s)
**Phase 2:** Unit Tests ✅ (1m 23s)
**Phase 3:** E2E Tests ✅ (2m 45s)*
**Phase 4:** Visual Regression ✅ (4m 12s)

*1 test fixed using test-fix skill

### 📊 Summary

- **Total time:** 8m 52s
- **Tests run:** 43 tests
- **Tests passed:** 43/43 (100%)
- **Coverage:** 87% statements, 76% branches
- **Visual snapshots:** 8/8 matched

### 🎯 Next Steps

All tests passing! Ready to:
- Commit changes: `git add . && git commit`
- Create PR: `pr-review-fix-pipeline`
- Push: `git push`

### 💡 Insights

Based on this run:
- Unit tests are fast and thorough
- One E2E test needed fixing (race condition with API)
- Visual regression caught no UI breaks ✅
- Consider adding E2E test for error states (gap in coverage)

Test Suite Reference

Example script names. Replace them with the ones Phase 0 found in your project; skip any suite the project doesn't have:

Unit Tests

npm test                           # All unit tests
npm test -- [FILE]                 # Specific file
npm run test:coverage              # With coverage
npm run test:prompt-templates      # Specific suite

E2E Tests

npm run test:e2e:critical          # Critical path only
npm run test:visual                # Visual regression
npm run test:visual:headed         # With browser visible
npm run test:visual:debug          # Debug mode

Linting

npm run lint                       # ESLint
npm run lint:css                   # Stylelint
npm run type-check                 # TypeScript

Smart Test Selection Rules

When to Run Unit Tests

• Changed any .ts, .tsx, .js, .jsx files
• Modified utilities, hooks, components
• Always run (fast, thorough)

When to Run E2E Tests

• Changed user-facing components
• Modified routes or navigation
• Updated API integration
• Changed authentication logic
• Only if dev server is running

When to Run Visual Regression

• Changed component styles
• Modified CSS files
• Updated design tokens
• Changed layout or spacing
• Only if dev server is running

When to Run CSS Lint

• Modified any .css files
• Changed style-related code
• Updated design system

When to Run Full Suite

• Before merging to main/develop
• After major refactoring
• Before releasing
• Periodic confidence check

Integration with Other Skills

With test-fix

When test fails:

1. Apply test-fix skill (3-attempt limit)
2. If fails 3 times, flag for review
3. Continue with other tests
4. Report flagged tests in final summary

With pr-review-fix-pipeline

After tests pass:

1. Tests validated ✅
2. Create/update PR
3. Run pr-review-fix-pipeline
4. Merge when approved

With worktree-enhanced

In worktree context:

1. Verify dev server running
2. Run appropriate test suite
3. Never kill dev server
4. Report results

Error Handling

Dev Server Not Running (E2E/Visual Needed)

❌ Dev server required but not running

Options:
(a) Start dev server now: npm run dev
(b) Skip E2E/visual tests
(c) Exit (you start server first)

Recommendation: (a) - I'll start the server and wait

Test Failure After 3 Attempts

⚠️ Test failed after 3 fix attempts

Test: user-profile-edit.spec.ts
Applied: test-fix skill (3 attempts)

Failed fixes:
1. Added wait for button → still timeout
2. Increased timeout → still failed
3. Changed selector → element not found

Flagging for manual review.

Continue with remaining tests? (y/n)

Multiple Test Failures

Work through them one at a time using the test-fix skill (3-attempt limit each). If 3+ tests each fail after 3 attempts, present a consolidated summary and ask the user how to proceed — skip with TODOs, rewrite the tests, or investigate a shared root cause.

Success Metrics

Track these outcomes:

• Test selection accuracy (were recommended tests sufficient?)
• Time saved by smart selection vs. full suite
• Test fix success rate (% fixed within 3 attempts)
• Dev server coordination (no accidental kills)

Notes

• Intelligent test selection saves significant time — a focused run on changed files beats the full suite for day-to-day work
• Dev server protection prevents a common class of test environment failures
• Integration with the test-fix skill prevents debugging spirals
• macOS tiling window managers: When running headed visual tests (test:visual:headed), tiling window managers (AeroSpace, yabai, Amethyst, etc.) will constrain the browser window's viewport. Float the window after it appears using the WM's float command to prevent viewport-dependent test failures from mismatched breakpoints.