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:

Check package.json:
- Review existing test scripts
- Detect test runner from dependencies (jest, vitest, mocha)
- Check for existing Husky installation
- Review existing coverage configuration
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)
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
Verify Existing Husky Setup:
- Check if
```
.husky/
```
  directory exists
- Review existing pre-commit hook
- Check if Husky is in package.json dependencies
Detect Test Files:
- Scan for
```
*.test.*
```
  or
```
*.spec.*
```
  files
- Verify tests exist before enforcing coverage

Quick Start

bash

# 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:

json

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

Package.json Configuration

Alternatively, add to

package.json

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:

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:

typescript

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:

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:

Discover Project Context:
- Scan package.json for test runner and dependencies
- Check existing Husky configuration
- Review existing coverage config files
- Verify test files exist
Detect Test Runner:
- Identify Jest, Vitest, or Mocha
- Detect coverage tool (built-in or nyc/c8)
- Determine package manager
Setup or Verify Husky:
- Install Husky if missing
- Initialize Husky hooks
- Add prepare script if needed
Configure Coverage:
- Create or update coverage configuration
- Set coverage thresholds (default 80%)
- Configure appropriate reporters
Create Pre-commit Hook:
- Generate hook script with test command
- Configure to run tests with coverage
- Set enforcement behavior (block or warn)
Verify Setup:
- Review generated configuration
- Test hook with a commit
- Adjust thresholds if needed

Integration with Other Skills

This skill works alongside:

Skill	How It Works Together
fullstack-workspace-init	Automatically invoked after scaffolding to set up 80% coverage threshold
linter-formatter-init	Both configure Husky; this skill focuses on test coverage, linter-formatter-init focuses on linting/formatting
testing-expert	Uses testing patterns and coverage targets from testing-expert skill

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:

bash

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

Troubleshooting

Pre-commit hook not running

bash

# 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

Start with reasonable thresholds: Begin with 80% and adjust based on project needs
Monitor coverage trends: Use coverage reports to identify gaps
Incremental improvement: Gradually increase thresholds as coverage improves
Consider context: Some files (utilities, configs) may not need high coverage
Use with CI/CD: Pre-commit hooks catch issues early, but CI/CD provides final gate
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:

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

husky-test-coverage

NPX Install

Tags

SKILL.md Content

Husky Test Coverage

Purpose

When to Use

Project Context Discovery

Quick Start

What Gets Configured

Husky Setup

Test Runner Detection

Coverage Configuration

Pre-commit Hook

Configuration Options

Command Line Arguments

Configuration File

Package.json Configuration

Tech Stack Adaptation

Jest Projects

Vitest Projects

Mocha Projects

Package Manager Support

Workflow

Integration with Other Skills

Automatic Setup with fullstack-workspace-init

Manual Integration

Troubleshooting

Pre-commit hook not running

Coverage not being checked

Hook fails even when tests pass

Tests run but coverage not enforced

Multiple test runners detected

Best Practices

Resources