Run Tests Skill

⚠️ MANDATORY SKILL – AUTO-INVOKED BY SAFE-COMMIT

Purpose

Execute comprehensive testing to ensure code correctness, prevent regressions, and maintain quality standards before committing.

CRITICAL: This skill is automatically invoked by safe-commit. NEVER run tests manually before commit.

Testing Requirements

Coverage Thresholds

• Unit Tests: Minimum 90% code coverage
• Integration Tests: All integration points tested
• End-to-End Tests: 100% pass rate (no mocks)

Philosophy

• Tests are NOT optional
• Failing tests = failing build
• Coverage below thresholds = failure
• E2E tests use real dependencies, never mocks

🚫 NEVER DO THIS

• ❌ Running npm test or jest manually before commit
• ❌ Running go test ./... manually before commit
• ❌ Running pytest manually before commit
• ❌ Running tests outside of this skill during commit workflow

Let safe-commit invoke this skill automatically. Manual testing before commit is REDUNDANT and FORBIDDEN.

⚠️ SKILL GUARD – READ BEFORE RUNNING TESTS MANUALLY

Before using Bash tool to run tests, answer these questions:

❓ Are you about to run npm test, npm run test, or jest?

→ STOP. Are you doing this before commit? If YES, use safe-commit instead (it invokes this skill).

❓ Are you about to run go test ./... or go test -v?

→ STOP. Are you doing this before commit? If YES, use safe-commit instead (it invokes this skill).

❓ Are you about to run pytest, python -m pytest, or py.test?

→ STOP. Are you doing this before commit? If YES, use safe-commit instead (it invokes this skill).

❓ Are you about to run cargo test or yarn test?

→ STOP. Are you doing this before commit? If YES, use safe-commit instead (it invokes this skill).

❓ Are you checking test coverage before committing?

→ STOP. Invoke safe-commit skill (it will invoke this skill automatically).

IF YOU RUN TESTS MANUALLY BEFORE COMMIT, YOU ARE CREATING REDUNDANCY AND WASTING TIME.

When to run tests manually:

• ✅ During development/debugging (TDD workflow)
• ✅ After implementing features (to verify locally)
• ✅ When user explicitly requests “run tests”

When NOT to run tests manually:

• ❌ Before commit (use safe-commit instead)
• ❌ As part of commit workflow (use safe-commit instead)

Safe-commit invokes this skill automatically with full coverage reporting. Don’t duplicate the work.

Workflow

Step 1: Detect Project Type and Test Framework

Check for test indicators:

# Check for test framework markers in parallel
ls package.json go.mod requirements.txt Cargo.toml pytest.ini jest.config.js 2>/dev/null

Test Framework Detection:

• package.json + jest.config.js or "jest" in package.json → Jest
• package.json + vitest.config → Vitest
• go.mod + *_test.go files → Go testing
• requirements.txt + pytest.ini or pyproject.toml → pytest
• Cargo.toml → cargo test
• pom.xml → JUnit/Maven
• Makefile with test target → make test

Step 2: Run Unit Tests (Language-Specific)

Node.js / TypeScript (Jest)

npm test -- --coverage
# OR
npx jest --coverage --verbose

Parse output for:

• Test pass/fail counts
• Coverage percentages (Statements, Branches, Functions, Lines)
• Specific test failures with file/line numbers

Success criteria:

• All tests pass
• Coverage ≥ 90% for all metrics

Node.js / TypeScript (Vitest)

npx vitest run --coverage

Go

go test ./... -v -cover -coverprofile=coverage.out

Parse coverage:

go tool cover -func=coverage.out | tail -1

Success criteria:

• All tests pass (PASS in output)
• Total coverage ≥ 90%

For detailed HTML report:

go tool cover -html=coverage.out -o coverage.html

Python (pytest)

pytest --cov=. --cov-report=term-missing --cov-report=html --verbose

Success criteria:

• All tests pass
• Coverage ≥ 90%

Rust (cargo)

cargo test --verbose

For coverage (requires tarpaulin):

cargo tarpaulin --out Html --output-dir coverage

Success criteria:

• All tests pass
• Coverage ≥ 90% (if coverage tool available)

Java (Maven)

mvn test -Pcoverage

Success criteria:

• BUILD SUCCESS
• Coverage ≥ 90% (check target/site/jacoco/index.html)

Step 3: Run Integration Tests (If Applicable)

Integration tests verify service-to-service communication, database interactions, and API contracts.

Detection

Look for:

• *_integration_test.go
• tests/integration/ directory
• test_integration_*.py
• *.integration.test.ts

Execution

Go:

go test ./... -tags=integration -v

Python:

pytest tests/integration/ -v

Node.js:

npm test -- --testPathPattern=integration

Success criteria:

• All integration tests pass
• Real dependencies used (database, external services)
• Proper setup/teardown of test data

Step 4: Run End-to-End Tests (If Applicable)

E2E tests verify complete user workflows against production-like environment.

Detection

Look for:

• tests/e2e/ directory
• e2e/ directory
• *.e2e.test.ts
• Playwright, Cypress, or Selenium configs

Execution

Playwright:

npx playwright test

Cypress:

npx cypress run

Go (if using testcontainers):

go test ./e2e/... -v

Success criteria:

• 100% pass rate (MANDATORY – no failures allowed)
• Tests use real browser/application
• Tests verify actual user experience
• No mocks – real dependencies only

Step 5: Parse and Report Results

Success Report Format

✅ ALL TESTS PASSED

Unit Tests:
- Go: 156 passed, 0 failed
- Coverage: 94.5% (exceeds 90% threshold)

Integration Tests:
- Database: 12 passed
- API: 8 passed
- gRPC: 5 passed

E2E Tests:
- User flows: 15 passed (100%)

Total: 196/196 tests passed
Coverage: 94.5% ✓

Safe to proceed with commit.

Failure Report Format

❌ TESTS FAILED

Unit Tests:
✗ pkg/parser/parser_test.go:45: TestParseInvalidInput FAILED
  Expected: error
  Got: nil

✗ src/api/handlers.test.ts:128: should handle 404 errors FAILED
  Expected status: 404
  Received status: 500

Coverage: 87.3% ✗ (below 90% threshold)
  Missing coverage:
  - pkg/auth/validator.go: 78.5%
  - src/utils/helpers.ts: 82.1%

Integration Tests:
✓ 12/12 passed

E2E Tests:
✗ 14/15 passed (93.3%)
✗ e2e/checkout.spec.ts: Payment processing timeout

CANNOT COMMIT - Must fix failing tests and improve coverage.

Next Steps:
1. Fix failing unit tests in parser_test.go and handlers.test.ts
2. Add tests to increase coverage in validator.go and helpers.ts
3. Investigate E2E payment processing timeout
4. Re-run tests after fixes

Step 6: Generate Coverage Report (Optional)

If user wants detailed coverage report:

Go:

go tool cover -html=coverage.out -o coverage.html
echo "Coverage report: coverage.html"

Python:

echo "Coverage report: htmlcov/index.html"

Node.js:

echo "Coverage report: coverage/lcov-report/index.html"

Handling Test Failures

Step-by-Step Remediation:

1. Identify Root Cause

   • Parse error messages
   • Identify failing test files
   • Note expected vs actual behavior

2. Categorize Failures

   • Legitimate bugs (code is wrong)
   • Broken tests (test is wrong)
   • Environment issues (setup problem)
   • Flaky tests (timing/concurrency)

3. Report to User

   Test Failure Analysis:
   
   1. parser_test.go:45 - Legitimate bug
      Issue: ParseInvalidInput returns nil instead of error
      Fix needed: Add error handling in parser.go:128
   
   2. handlers.test.ts:128 - Test expectation issue
      Issue: API changed from 404 to 500 for this case
      Fix needed: Update test expectation or API behavior
   
   3. checkout.spec.ts - Environment issue
      Issue: Payment service timeout (external dependency)
      Fix needed: Verify payment service is running, increase timeout, or check network
   

4. Suggest Fixes

   • Provide code snippets for fixes
   • Link to relevant files/lines
   • Suggest test additions for coverage gaps

Handling Low Coverage

If coverage < 90%:

1. Identify Uncovered Code

   go tool cover -func=coverage.out | grep -E "[0-9]+\.[0-9]+%" | awk '$3 < 90'
   

2. Report Specific Gaps

   Coverage Gaps:
   
   - pkg/auth/validator.go: 78.5%
     Missing: Lines 45-62 (error handling)
     Missing: Lines 89-95 (edge case validation)
   
   - src/utils/helpers.ts: 82.1%
     Missing: Lines 34-41 (error path)
     Missing: Function 'formatDate' (no tests)
   

3. Suggest Test Additions

   • Identify untested functions
   • Note missing error path tests
   • Highlight edge cases not covered

Integration with Other Skills

This skill is invoked by:

• safe-commit – Before committing changes
• create-pr – Before creating pull requests

Best Practices

1. Run all test types – Unit, integration, E2E in sequence
2. Report comprehensively – Show pass/fail, coverage, and specific errors
3. No partial success – All thresholds must be met
4. Suggest fixes – Don’t just report failures, help resolve them
5. Verify environment – Check test dependencies are available
6. Time awareness – Warn if tests take > 5 minutes

Common Issues

Issue: Tests not found

Solution:

• Verify test files exist
• Check test file naming conventions
• Ensure test framework installed

Issue: Database connection failed

Solution:

• Check database is running
• Verify connection string
• Ensure test database exists
• Check migrations are applied

Issue: E2E tests timing out

Solution:

• Increase timeout values
• Check application is running
• Verify network connectivity
• Check browser/driver versions

Issue: Flaky tests

Solution:

• Identify intermittent failures
• Check for timing issues
• Review async/await usage
• Consider retry logic for external services

Emergency Override

If user explicitly states “skip tests” or “tests are broken but commit anyway”:

YOU MUST:

1. Warn about the risk
2. Document which tests were skipped
3. Get explicit confirmation
4. Suggest creating immediate follow-up ticket
5. Note in commit message: “Tests skipped – see #TICKET”

This should be EXTREMELY RARE and only with explicit approval.

Related Commands

• /coverage-trend – Track coverage changes across commits to catch regressions
• /test-coverage – Detailed coverage analysis and reporting