Ultimate Pre-push Test Runner Inspector

Runs comprehensive test suites and generates detailed inspection reports before code is pushed to remote, blocking pushes that fail testing criteria.

When to Use This Hook

Attach this hook when you need to:

• Execute full test suites (unit, integration, e2e) before any push to remote repositories
• Generate test coverage reports and enforce minimum coverage thresholds per push
• Prevent pushing code that breaks tests, reducing CI failures and protecting shared branches

Consider alternatives when:

• Your CI/CD pipeline already runs comprehensive tests and you trust branch protection rules
• Push-time testing is too slow for your workflow and you prefer async CI validation

Quick Start

Configuration

Copy
name: ultimate-pre-push-test-runner-inspector
type: hook
trigger: PreToolUse
category: testing

Example Trigger

Copy
# Hook triggers before a git push command
git push origin feature/user-auth
# Inspector runs the full test suite before allowing push

Example Output

Pre-push Test Runner Inspector
  Branch: feature/user-auth → origin/feature/user-auth
  Running test suites...
  Unit tests:     247 pass, 0 fail (4.2s)
  Integration:     38 pass, 0 fail (12.1s)
  Coverage:       87.3% (threshold: 80%)
  Lint check:     0 errors, 2 warnings
Summary: ALL CHECKS PASSED
Push permitted to origin/feature/user-auth

Core Concepts

Inspection Layers Overview

Aspect	Details
Unit Tests	Fast, isolated tests run first for quick feedback
Integration Tests	API and database interaction tests
Coverage Analysis	Line and branch coverage against thresholds
Lint Check	Static analysis for code quality issues
Type Check	TypeScript/Flow type validation (if applicable)

Inspection Workflow

Push Initiated
      |
  Detect Target Branch
      |
  Run Test Suites (ordered)
      |
  Unit ──→ Integration ──→ Coverage
                              |
                         Meets Threshold?
                          /          \
                        Yes           No
                         |             |
                    Lint Check      BLOCK
                         |        + Report
                    ┌────┴────┐
                    |         |
                  Pass      Warn
                    |         |
                  PUSH     PUSH +
                           Advisory

Configuration

Parameter	Type	Default	Description
test_command	string	"npm test"	Command to run the test suite
coverage_threshold	number	80	Minimum coverage percentage required
run_lint	boolean	true	Run linter as part of pre-push inspection
timeout_sec	number	300	Maximum time for all tests to complete
skip_on_wip	boolean	true	Skip tests for branches prefixed with wip/

Best Practices

1. Order Tests by Speed - Run unit tests first, then integration, then e2e. If unit tests fail, skip slower suites to give fast feedback. Developers should not wait 5 minutes to learn about a typo.

2. Set Realistic Coverage Thresholds - Start with 60-70% coverage and increase gradually. An 80% threshold is a good target for mature projects. Unrealistic thresholds lead to low-value tests written just to hit numbers.

3. Allow WIP Branch Exceptions - Branches prefixed with wip/ or draft/ should skip the test runner. Work-in-progress code is pushed for backup or review, not for merge readiness.

4. Cache Test Results - If no source files changed since the last successful test run, skip re-running. Use file hashes to detect changes and avoid unnecessary test execution.

5. Provide Branch-Specific Rules - Pushes to main or release/* branches should have stricter thresholds than feature branches. Configure per-branch rules for appropriate rigor levels.

Common Issues

1. Slow Test Suites Block Development - If the full suite takes over 5 minutes, developers will bypass the hook. Optimize test speed or run only tests related to changed files.

2. Flaky Tests Cause False Blocks - Intermittent test failures block valid pushes. Track and quarantine flaky tests so they do not block the push workflow.

3. Coverage Drop from Deleted Code - Removing well-tested code can drop coverage below the threshold even when new code is fully tested. Use delta coverage (coverage of new lines only) as a complementary metric.