Run Tests Watcher

Automatically runs quick tests after code modifications to catch breaking changes immediately during development sessions.

When to Use This Hook

Attach this hook when you need to:

• Get instant feedback on whether code changes break existing tests
• Enforce a continuous testing discipline during Claude Code editing sessions
• Catch regressions within seconds of making changes rather than at commit time

Consider alternatives when:

• Your test suite takes more than 10 seconds to run and would slow down the editing flow
• You prefer to run tests manually after completing a logical set of changes

Quick Start

Configuration

Copy
name: run-tests-watcher
type: hook
trigger: PostToolUse
category: post-tool

Example Trigger

Copy
# Hook triggers after Claude edits a source file
claude> Edit src/utils/calculateTotal.ts
# Quick tests run automatically after the edit

Example Output

Running quick tests...
  PASS src/__tests__/calculateTotal.test.ts (0.8s)
  Tests: 4 passed, 4 total
  Time:  1.2s
Tests passed

Core Concepts

Test Watch Overview

Aspect	Details
Trigger	Runs after every Edit tool operation
Test Command	npm run test:quick (configurable)
Prerequisite	Checks for package.json before running
Feedback	Emits pass/fail status message
Failure Mode	Non-blocking warning on test failure

Test Watch Workflow

Edit Completes
      |
  package.json exists?
   /           \
  No           Yes
  |             |
 Skip      Run test:quick
              |
         ┌────┴────┐
         |         |
       Pass      Fail
         |         |
     "Tests     "Tests may
     passed"    need attention"

Configuration

Parameter	Type	Default	Description
test_command	string	"npm run test:quick"	Command to execute for quick tests
timeout_sec	number	30	Maximum time to wait for test completion
silent_pass	boolean	false	Suppress output on successful test runs
block_on_fail	boolean	false	Prevent further edits when tests fail
related_only	boolean	false	Run only tests related to the changed file

Best Practices

1. Create a Dedicated test:quick Script - Define a test:quick npm script that runs a fast subset of your test suite (unit tests only, no integration). Keep execution under 5 seconds for a responsive editing experience.

2. Use Related Test Detection - Configure Jest's --findRelatedTests or a similar feature to run only tests that import the modified file. This keeps feedback fast even in large codebases.

3. Set Appropriate Timeouts - A 30-second default timeout prevents runaway test processes from blocking your session. Adjust this based on your test suite's characteristics.

4. Non-Blocking by Default - Keep block_on_fail disabled so test failures inform you without preventing further edits. Some changes intentionally break tests temporarily during multi-file refactors.

5. Pair with Coverage Hooks - Combine the test watcher with a coverage threshold hook to ensure that new code includes tests. The watcher confirms existing tests pass; coverage hooks confirm new code is tested.

Common Issues

1. test:quick Script Missing - If package.json does not define a test:quick script, the hook fails silently. Add a test:quick script or update the hook to use your existing test command.

2. Slow Tests Block Editing - If quick tests take too long, they create a bottleneck after every edit. Profile your test suite and move slow tests (API calls, database queries) to a separate suite.

3. False Failures from Shared State - Tests that share global state may fail intermittently after edits. Use --runInBand for deterministic execution or ensure proper test isolation with setup/teardown.