Stop Running Your Entire Test Suite on Every Commit 🚫🧪

We've all been there. You make a small fix in one file, commit your changes, and watch as your entire test suite runs for the next 5 minutes. Sound familiar?

What if I told you there's a way to run only the tests that are actually related to your changes? Enter test-staged.

The Problem

Running your complete test suite before every commit is:

• ⏰ Slow - Wasting precious development time


• 😤 Frustrating - Breaking your flow state


• 🔄 Redundant - Testing code you didn't even touch

Most developers either:

1. Skip tests entirely (dangerous!)


2. Wait through long test runs (frustrating!)


3. Push and pray the CI catches issues (risky!)

There has to be a better way.

The Solution: test-staged

test-staged is like lint-staged, but for tests. It intelligently identifies which tests are related to your staged changes and runs only those.

How Smart Is It?

test-staged uses different strategies depending on your test runner:

• 
  Jest/Vitest: Uses native dependency graph analysis (--findRelatedTests / vitest related)


• 
  Mocha/Ava: Intelligently maps source files to test files (e.g., user.ts → user.test.ts, src/api/users.ts → src/api/__tests__/users.test.ts)

Getting Started in 30 Seconds

Installation is a breeze:

npm install -D test-staged

# or

pnpm add -D test-staged

# or

yarn add -D test-staged

# or

bun add -D test-staged

And that's it. Seriously. It's zero-config by default.

Set Up as a Pre-Commit Hook

The magic happens when you combine it with Husky:

# Install husky

npm install -D husky

npx husky init



# Add test-staged to pre-commit

echo "npx test-staged" > .husky/pre-commit

Now every commit will:

1. ✅ Only run tests related to your changes


2. ⚡ Complete in seconds instead of minutes


3. 🛡️ Block commits if tests fail

Real-World Examples

Example 1: Single File Change

You're working on a user authentication feature:

# You modified:

git add src/auth/login.ts



# test-staged runs ONLY:

src/auth/__tests__/login.test.ts

src/integration/__tests__/auth-flow.test.ts  # (because it imports login.ts)



# NOT running:

src/payments/__tests__/*.test.ts  ❌

src/dashboard/__tests__/*.test.ts  ❌

(and 200+ other unrelated tests)  ❌

Result: Tests complete in 3 seconds instead of 2 minutes.

Example 2: Refactoring Utilities

You refactored a utility function:

# You modified:

git add src/utils/formatDate.ts



# test-staged automatically finds ALL tests that depend on it:

src/utils/__tests__/formatDate.test.ts

src/components/__tests__/DatePicker.test.ts

src/pages/__tests__/Dashboard.test.ts

Smart enough to catch indirect dependencies, fast enough to keep you productive.

Example 3: Monorepo Support

Working in a monorepo? test-staged has you covered:

# You're in packages/ui

git add Button.tsx



# Only runs:

packages/ui/__tests__/Button.test.tsx



# Doesn't run tests from:

packages/api/  ❌

packages/cli/  ❌

Why You'll Love It

🎯 Zero Configuration

It automatically detects:

• Your package manager (npm, pnpm, yarn, bun)


• Your test runner (Jest, Vitest, Mocha, Ava)


• Your project structure (monorepo or single package)

⚡ Lightning Fast

On a typical project with 500+ tests:

• 
  Before: 2-3 minutes per commit


• 
  After: 2-5 seconds per commit

That's a 36x speed improvement in real-world usage.

🧠 Actually Intelligent

For Jest and Vitest, it uses the native dependency graph:

// If you change userService.ts

// it finds tests that import it:

import { createUser } from './userService'

import { validateUser } from './userService'

For Mocha and Ava, it uses pattern matching:

src/models/user.ts → src/models/user.test.ts

src/api/users.ts   → src/api/__tests__/users.test.ts

lib/parser.ts      → lib/parser.spec.ts

🛠️ Customizable When Needed

While it works out-of-the-box, you can customize it:

// package.json

{

  "test-staged": {

    "runner": "jest",

    "mode": "related",

    "testExtensions": [".test", ".spec", ".e2e"]

  }

}

Or create a .test-stagedrc.json:

{

  "runner": "vitest",

  "testExtensions": [".test", ".spec", "Test", "E2E"]

}

Supported Test Runners

More runners coming soon!

The Developer Experience

Here's what your workflow looks like:

# Make your changes

vim src/components/Button.tsx



# Stage them

git add src/components/Button.tsx



# Commit (test-staged runs automatically via pre-commit hook)

git commit -m "fix: button hover state"



# Output:

Running tests for staged files...

✓ src/components/__tests__/Button.test.tsx (2 tests) 0.8s



Tests passed! ✨

[main abc1234] fix: button hover state

No manual test commands. No waiting. No broken commits.

Common Questions

Q: What if I want to run all tests?


A: Just bypass the hook: git commit --no-verify or run your test suite manually.

Q: Does it work with CI?


A: Yes! Your CI should still run the full test suite. test-staged is for local development speed.

Q: What about integration/E2E tests?


A: test-staged will find them if they import your changed files. You can also customize which tests run.

Q: Can I use it without Git hooks?


A: Absolutely! Just run npx test-staged manually whenever you want.

Try It Today

Get started in less than a minute:

npm install -D test-staged husky

npx husky init

echo "npx test-staged" > .husky/pre-commit

Then make a commit and watch the magic happen. ✨

Links

• 📦 NPM Package
  


• 📖 Documentation
  


• 🐙 GitHub Repository
  


• 🐛 Report Issues
  

The Bottom Line

If you're still running your entire test suite on every commit, you're wasting time. test-staged gives you:

• ⚡ Faster commits (seconds instead of minutes)


• 🎯 Better focus (test only what changed)


• 🛡️ Safer code (tests actually run instead of being skipped)


• 🚀 Better DX (zero config, just works)

Give it a try and let me know what you think! Your future self will thank you. 🙌

Have you tried test-staged? What's your current pre-commit testing strategy? Share in the comments below! 👇