name: husky-test-coverage
description: Set up or verify Husky git hooks to ensure all tests run and coverage stays above 80% (configurable) for Node.js/TypeScript projects. This skill should be used when users want to enforce test coverage through pre-commit hooks, verify existing Husky/test setup, or configure coverage thresholds for Jest, Vitest, or Mocha test runners.

Husky Test Coverage

Set up or verify Husky git hooks to ensure tests run and coverage thresholds are enforced on every commit.

Purpose

This skill automates the setup of:

• Husky git hooks for pre-commit testing
• Test runner detection (Jest, Vitest, Mocha)
• Coverage configuration with thresholds (default: 80%)
• Pre-commit hook that runs tests with coverage
• Configurable coverage enforcement (block or warn)

When to Use

This skill should be used when:

• Setting up test coverage enforcement for the first time
• Verifying existing Husky/test setup is correctly configured
• Ensuring coverage thresholds are met before commits
• Configuring pre-commit hooks for test coverage
• Adapting coverage setup to different test runners

Project Context Discovery

Before setting up test coverage, discover the project's context:

1. Check package.json:
2. Review existing test scripts
3. Detect test runner from dependencies (jest, vitest, mocha)
4. Check for existing Husky installation

5. Review existing coverage configuration

6. Identify Test Runner:

7. Jest: Check for jest in dependencies, look for jest.config.js or jest.config.json
8. Vitest: Check for vitest in dependencies, look for vitest.config.ts or vitest.config.js

9. Mocha: Check for mocha in dependencies, check for coverage tool (nyc, c8)

10. Check Coverage Configuration:

11. Jest: Look for coverageThreshold in jest.config.*
12. Vitest: Look for coverage.thresholds in vitest.config.*

13. Mocha: Look for .nycrc.json or coverage config in package.json

14. Verify Existing Husky Setup:

15. Check if .husky/ directory exists
16. Review existing pre-commit hook

17. Check if Husky is in package.json dependencies

18. Detect Test Files:

19. Scan for *.test.* or *.spec.* files
20. Verify tests exist before enforcing coverage

Quick Start

# Basic setup (80% coverage threshold, blocks commits below threshold)
python3 ~/.claude/skills/husky-test-coverage/scripts/setup-husky-coverage.py \
  --root /path/to/project

# Custom threshold (85%)
python3 ~/.claude/skills/husky-test-coverage/scripts/setup-husky-coverage.py \
  --root /path/to/project \
  --threshold 85

# Warn only (don't block commits)
python3 ~/.claude/skills/husky-test-coverage/scripts/setup-husky-coverage.py \
  --root /path/to/project \
  --no-fail-on-below

# Skip if no tests found
python3 ~/.claude/skills/husky-test-coverage/scripts/setup-husky-coverage.py \
  --root /path/to/project \
  --skip-if-no-tests

# Dry run to preview changes
python3 ~/.claude/skills/husky-test-coverage/scripts/setup-husky-coverage.py \
  --root /path/to/project \
  --dry-run

What Gets Configured

Husky Setup

• Installs Husky if not already present
• Initializes Husky (npx husky install)
• Creates .husky/pre-commit hook that runs tests with coverage
• Adds prepare script to package.json (if missing)

Test Runner Detection

The skill automatically detects:

• Jest: Uses jest --coverage --watchAll=false in pre-commit hook
• Vitest: Uses vitest --coverage --run in pre-commit hook
• Mocha: Uses nyc or c8 with mocha test command

Coverage Configuration

Jest:

• Creates or updates jest.config.json with coverageThreshold
• Default thresholds: 80% lines, 75% branches, 80% functions, 80% statements

Vitest:

• Creates or updates vitest.config.ts/js with coverage thresholds
• Configures v8 coverage provider
• Sets same default thresholds as Jest

Mocha + nyc:

• Creates or updates .nycrc.json with coverage thresholds
• Configures text, html, and lcov reporters

Pre-commit Hook

The created hook:

• Runs tests with coverage before every commit
• Fails the commit if coverage is below threshold (configurable)
• Can skip if no test files are found (optional)

Configuration Options

Command Line Arguments

• --root <path>: Project root directory (required)
• --threshold <number>: Coverage threshold percentage (default: 80)
• --fail-on-below: Fail commit if coverage below threshold (default: true)
• --no-fail-on-below: Allow commit even if coverage below threshold
• --skip-if-no-tests: Skip hook if no test files found
• --dry-run: Show what would be done without making changes

Configuration File

Create .husky-test-coverage.json in project root:

{
  "coverageThreshold": {
    "lines": 80,
    "branches": 75,
    "functions": 80,
    "statements": 80
  },
  "failOnCoverageBelowThreshold": true,
  "skipIfNoTests": false
}

Package.json Configuration

Alternatively, add to package.json:

{
  "huskyTestCoverage": {
    "threshold": 80,
    "failOnBelow": true
  }
}

Tech Stack Adaptation

Jest Projects

Detection:

• Checks for jest in dependencies
• Looks for jest.config.js or jest.config.json

Configuration:

• Updates or creates jest.config.json with coverage thresholds
• Pre-commit hook: npm test -- --coverage --watchAll=false

Example jest.config.json:

{
  "coverageThreshold": {
    "global": {
      "lines": 80,
      "branches": 75,
      "functions": 80,
      "statements": 80
    }
  }
}

Vitest Projects

Detection:

• Checks for vitest in dependencies
• Looks for vitest.config.ts or vitest.config.js

Configuration:

• Updates or creates Vitest config with coverage thresholds
• Pre-commit hook: npm test -- --coverage --run

Example vitest.config.ts:

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json', 'html'],
      thresholds: {
        lines: 80,
        branches: 75,
        functions: 80,
        statements: 80
      }
    }
  }
})

Mocha Projects

Detection:

• Checks for mocha in dependencies
• Checks for coverage tool (nyc or c8)

Configuration:

• Creates or updates .nycrc.json for nyc
• Pre-commit hook: nyc --reporter=text --reporter=html npm test

Example .nycrc.json:

{
  "check-coverage": true,
  "lines": 80,
  "branches": 75,
  "functions": 80,
  "statements": 80,
  "reporter": ["text", "text-summary", "html", "lcov"]
}

Package Manager Support

The skill automatically detects and uses:

• npm: npm run test
• yarn: yarn test
• pnpm: pnpm run test
• bun: bun run test

Workflow

When using this skill:

1. Discover Project Context:
2. Scan package.json for test runner and dependencies
3. Check existing Husky configuration
4. Review existing coverage config files

5. Verify test files exist

6. Detect Test Runner:

7. Identify Jest, Vitest, or Mocha
8. Detect coverage tool (built-in or nyc/c8)

9. Determine package manager

10. Setup or Verify Husky:

11. Install Husky if missing
12. Initialize Husky hooks

13. Add prepare script if needed

14. Configure Coverage:

15. Create or update coverage configuration
16. Set coverage thresholds (default 80%)

17. Configure appropriate reporters

18. Create Pre-commit Hook:

19. Generate hook script with test command
20. Configure to run tests with coverage

21. Set enforcement behavior (block or warn)

22. Verify Setup:

23. Review generated configuration
24. Test hook with a commit
25. Adjust thresholds if needed

Integration with Other Skills

This skill works alongside:

Automatic Setup with fullstack-workspace-init

When using fullstack-workspace-init to scaffold a new project, this skill is automatically applied with:

• Vitest as the test runner
• 80% coverage threshold
• Pre-commit hooks enabled
• GitHub Actions CI/CD integration

You don't need to run this skill separately if you used fullstack-workspace-init.

Manual Integration

If adding to an existing project:

python3 ~/.claude/skills/husky-test-coverage/scripts/setup-husky-coverage.py \
  --root /path/to/project \
  --threshold 80

Troubleshooting

Pre-commit hook not running

# Reinstall Husky
npx husky install
chmod +x .husky/pre-commit

Coverage not being checked

• Verify test command includes coverage flag
• Check coverage configuration file exists and is correct
• Ensure coverage tool is installed (nyc/c8 for Mocha)

Hook fails even when tests pass

• Check coverage thresholds are achievable
• Review coverage report to see what's below threshold
• Consider adjusting thresholds or improving test coverage

Tests run but coverage not enforced

• Verify coverage configuration file has correct thresholds
• Check test runner supports coverage (Jest/Vitest have built-in, Mocha needs nyc/c8)
• Review pre-commit hook script for correct command

Multiple test runners detected

The skill uses the first detected runner in priority order: Vitest > Jest > Mocha

Best Practices

1. Start with reasonable thresholds: Begin with 80% and adjust based on project needs
2. Monitor coverage trends: Use coverage reports to identify gaps
3. Incremental improvement: Gradually increase thresholds as coverage improves
4. Consider context: Some files (utilities, configs) may not need high coverage
5. Use with CI/CD: Pre-commit hooks catch issues early, but CI/CD provides final gate
6. Team alignment: Ensure team understands coverage requirements and goals

Resources

• Husky Documentation: https://typicode.github.io/husky/
• Jest Coverage: https://jestjs.io/docs/configuration#coveragethreshold-object
• Vitest Coverage: https://vitest.dev/config/#coverage
• nyc (Istanbul): https://github.com/istanbuljs/nyc

When this skill is active, Claude will:

1. Discover project test setup and configuration
2. Detect test runner and coverage tool
3. Set up or verify Husky installation
4. Configure coverage thresholds appropriately
5. Create pre-commit hook that enforces coverage
6. Provide troubleshooting guidance when needed