What is the purpose of the Python test harness?

The harness allows you to create mock payloads and use predefined assertions like assert_blocked or assert_allowed to test specific hook logic in isolation from the AI.

How do I signal a blocked action in a Claude hook?

Hooks should exit with code 2 and provide the reason for blocking in the stderr output to notify Claude that the action is prohibited.

What are the three levels of testing supported by this skill?

It supports Level 1 (Python unit tests with pytest), Level 2 (Direct shell invocation via JSON payloads), and Level 3 (End-to-end headless Claude CLI testing).

Can I test hooks without triggering the full Claude UI?

Yes, you can use headless mode with the -p (or --print) and --debug flags to execute Claude and monitor hook behavior via terminal output.

Where should I store local test configurations?

It is recommended to use .claude/settings.local.json for local test hooks to avoid committing experimental configurations to your main repository.

Hooks Test Suite

Name: Hooks Test Suite
Author: srnnkls

bysrnnkls

0•

Security & Testing

Validates and debugs Claude Code hooks through unit testing, direct payload invocation, and headless CLI integration.

The Hooks Test skill provides a comprehensive framework for developing and verifying custom Claude Code hooks. It enables developers to test hook logic in isolation using a Python test harness, simulate real-world execution through shell-based JSON payloads, and perform end-to-end validation using Claude's headless mode. This ensures that hooks for tool blocking, input modification, and context enrichment function reliably before deployment, preventing regressions and simplifying the debugging process for complex AI workflows.

Key Features

010 GitHub stars

02Python test harness with standardized assertions for blocking and allowing

03End-to-end integration testing using Claude CLI headless flags

04Multi-level testing architecture including Unit, Direct, and Headless modes

05Support for all major hook events: PreToolUse, PostToolUse, and UserPromptSubmit

06Comprehensive exit code and payload reference for debugging

Use Cases

01Regression testing hook behavior after modifying system prompts or tools

02Developing and debugging custom security or validation hooks for Claude

03Validating tool-use restrictions in automated CI/CD pipelines

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add srnnkls/tropos hooks-test

For use in Claude.ai and ChatGPT

Download Skill