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:

   • Review existing test scripts
   • Detect test runner from dependencies (jest, vitest, mocha)
   • Check for existing Husky installation
   • Review existing coverage configuration

2. Identify Test Runner:

   • Jest: Check for jest in dependencies, look for jest.config.js or jest.config.json
   • Vitest: Check for vitest in dependencies, look for vitest.config.ts or vitest.config.js
   • Mocha: Check for mocha in dependencies, check for coverage tool (nyc, c8)

3. Check Coverage Configuration:

   • Jest: Look for coverageThreshold in jest.config.*
   • Vitest: Look for coverage.thresholds in vitest.config.*
   • Mocha: Look for .nycrc.json or coverage config in package.json

4. Verify Existing Husky Setup:

   • Check if .husky/ directory exists
   • Review existing pre-commit hook
   • Check if Husky is in package.json dependencies

5. Detect Test Files:

   • Scan for *.test.* or *.spec.* files
   • 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 --

...