Hook测试策略：保证Hook质量 - 学习笔记-Hooks案例

核心要点：Hook是Claude Code可扩展性的核心机制，直接影响工具调用的安全性和工作流的可靠性。系统化的测试策略是保证Hook在生产环境中稳定运行的关键。本文从单元测试、集成测试、模拟测试、边界情况测试和CI自动化五个维度，全面阐述如何建立完善的Hook质量保障体系。

一、Hook测试的重要性

Hook是Claude Code的行为扩展点，它们直接嵌入在工具的调用链中，在每次工具调用前（before）或调用后（after）执行自定义逻辑。Hook的质量直接影响Claude Code的稳定性、安全性和用户体验。一个未经充分测试的Hook可能在以下场景中引发严重问题：在生产环境中意外拦截合法命令导致工作流中断、错误地脱敏关键数据导致信息丢失、或者在超时处理不当的情况下阻塞整个工具调用链。

系统化的Hook测试需要覆盖以下关键场景：正常执行路径验证Hook是否按预期工作、异常输入测试Hook的健壮性（如空环境变量、非法JSON格式、超大负载数据）、边界条件测试（超时阈值、权限不足、磁盘空间不足）、以及并发场景测试（多个工具同时触发Hook时的互斥和状态管理）。只有通过全面的测试覆盖，才能确保Hook在各种真实场景下可靠运行。

为什么测试Hook比测试普通脚本更重要？

Hook运行在Claude Code的上下文中，其执行结果会直接影响AI与外部系统的交互。一个Hook的失败可能导致：命令被错误拒绝、数据被错误修改、审计日志缺失、或者整个工具调用链中断。因此，Hook的测试标准应当高于普通脚本的测试标准。

二、Shell脚本测试

Shell Hook是最常见的Hook类型，通常用于执行系统命令、环境检查和简单的数据预处理。BATS（Bash Automated Testing System）是测试Shell脚本的标准工具，它提供了类似单元测试框架的语法，能够对Shell Hook进行结构化测试。

使用BATS测试Shell Hook

BATS测试文件的基本结构包括setup（每个测试前的初始化）、teardown（每个测试后的清理）和独立的测试函数。每个测试函数使用@test注解声明，通过run命令执行目标脚本，然后使用断言函数验证执行结果。以下是一个典型的BATS测试结构：

# file: tests/hook_security_check.bats

setup() {
    # 设置测试环境变量
    export CLAUDE_TOOL_NAME="Bash"
    export CLAUDE_TOOL_INPUT='{"command": "ls -la"}'
    export CLAUDE_HOOK_TIMEOUT=30
}

teardown() {
    # 清理环境变量
    unset CLAUDE_TOOL_NAME
    unset CLAUDE_TOOL_INPUT
    unset CLAUDE_HOOK_TIMEOUT
}

@test "允许安全的Bash命令" {
    run ./hooks/before-bash.sh
    [ "$status" -eq 0 ]
}

@test "拦截危险命令并返回非零退出码" {
    export CLAUDE_TOOL_INPUT='{"command": "rm -rf /"}'
    run ./hooks/before-bash.sh
    [ "$status" -ne 0 ]
}

@test "正确读取CLAUDE_TOOL_INPUT中的JSON字段" {
    run ./hooks/before-bash.sh
    echo "$output" | grep -q "检查命令: ls"
}

@test "处理空命令的情况" {
    export CLAUDE_TOOL_INPUT='{"command": ""}'
    run ./hooks/before-bash.sh
    [ "$status" -eq 0 ]
}

@test "处理超长命令的情况" {
    local long_cmd=$(python3 -c "print('echo ' + 'a'*100000)")
    export CLAUDE_TOOL_INPUT="{\"command\": \"$long_cmd\"}"
    run ./hooks/before-bash.sh
    [ "$status" -eq 0 ]
}

测试退出码是否正确

Hook的退出码是Claude Code判断Hook执行结果的核心依据。退出码0表示允许操作继续，非零退出码表示拒绝或错误。测试退出码的正确性至关重要。需要测试的场景包括：合法命令返回0、危险命令返回非0（典型的拒绝码如1或特定错误码）、环境变量缺失时返回适当的错误码、超时发生时返回特定的超时错误码。

测试环境变量读取和处理

Hook依赖环境变量获取上下文信息（如CLAUDE_TOOL_NAME、CLAUDE_TOOL_INPUT、CLAUDE_HOOK_TIMEOUT等）。测试需要覆盖：环境变量完整时的正常读取、关键环境变量缺失时的降级处理、环境变量包含特殊字符时的转义处理、多个环境变量组合使用时的逻辑正确性。建议在每个测试中显式设置所需环境变量，并在teardown中清理，避免测试间相互污染。

测试条件分支逻辑

Hook通常包含复杂的条件分支逻辑，根据不同的工具名称、命令内容或上下文状态执行不同的操作。条件分支测试需要覆盖：针对不同CLAUDE_TOOL_NAME值走不同分支、命令内容匹配特定模式时的特殊处理逻辑、条件嵌套时所有可能的组合路径、默认分支（else/case *)）的兜底行为。使用BATS的参数化测试或循环测试可以有效减少重复代码，提高测试覆盖率。

最佳实践：在BATS测试中使用bats-assert和bats-support库可以获得更丰富的断言函数（如assert_success、assert_failure、assert_output、assert_line），使测试代码更具可读性，错误信息更清晰。

三、Python Hook测试

Python Hook适用于需要复杂数据处理、网络请求或使用第三方库的场景。pytest是Python生态中最流行的测试框架，配合pytest-mock插件可以高效地测试Python Hook脚本。

使用pytest测试Python Hook脚本

Python Hook通常从环境变量或标准输入读取数据，执行处理后返回结果。测试时需要模拟Claude Code的运行环境，验证Hook的输入解析、逻辑处理和输出格式。以下是一个pytest测试的结构示例：

# file: tests/test_data_sanitize_hook.py

import os
import json
import pytest
from unittest.mock import patch, MagicMock


@pytest.fixture
def setup_env():
    """设置测试环境"""
    env_vars = {
        "CLAUDE_TOOL_NAME": "Bash",
        "CLAUDE_TOOL_INPUT": json.dumps({
            "command": "echo 'user: alice@example.com, key: sk-12345'"
        }),
        "CLAUDE_HOOK_TIMEOUT": "30"
    }
    with patch.dict(os.environ, env_vars, clear=True):
        yield


@pytest.fixture
def hook_script():
    """加载Hook脚本模块"""
    import importlib.util
    spec = importlib.util.spec_from_file_location(
        "sanitize_hook",
        "hooks/after-bash-sanitize.py"
    )
    module = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(module)
    return module


class TestDataSanitizeHook:

    def test_detect_email_in_output(self, setup_env, hook_script):
        """测试检测输出中的电子邮件地址"""
        result = hook_script.sanitize_text(
            "contact: alice@example.com"
        )
        assert "[REDACTED_EMAIL]" in result
        assert "alice@example.com" not in result

    def test_detect_api_key(self, setup_env, hook_script):
        """测试检测和替换API密钥"""
        result = hook_script.sanitize_text(
            "API Key: sk-12345abcdef"
        )
        assert "[REDACTED_API_KEY]" in result

    def test_no_false_positive(self, setup_env, hook_script):
        """测试正常文本不被误脱敏"""
        result = hook_script.sanitize_text(
            "正常运行日志: 处理完成，耗时2.3秒"
        )
        assert result == "正常运行日志: 处理完成，耗时2.3秒"

    def test_empty_input(self, setup_env, hook_script):
        """测试空输入的处理"""
        result = hook_script.sanitize_text("")
        assert result == ""

    def test_malformed_json_env(self):
        """测试CLAUDE_TOOL_INPUT为非法JSON时的处理"""
        with patch.dict(os.environ, {
            "CLAUDE_TOOL_INPUT": "not-json-format"
        }, clear=True):
            with pytest.raises(json.JSONDecodeError):
                from hooks.after_bash_sanitize import parse_input
                parse_input()

    def test_cross_platform_newline(self, setup_env, hook_script):
        """测试跨平台换行符兼容性"""
        result_windows = hook_script.sanitize_text(
            "line1\r\nline2"
        )
        result_unix = hook_script.sanitize_text(
            "line1\nline2"
        )
        assert result_windows == result_unix

Mock环境变量和外部调用

在测试Python Hook时，需要模拟Claude Code设置的环境变量和Hook可能调用的外部服务。使用pytest-mock的mocker fixture或unittest.mock的patch context manager可以临时替换环境变量字典、模拟网络请求避免真实调用外部API、模拟文件系统操作避免读写真实文件、模拟子进程调用避免执行真实系统命令。Mock的关键原则是：只模拟Hook的依赖，不模拟被测试的逻辑本身。

测试错误处理逻辑

Hook的错误处理逻辑是质量保障的关键部分。需要测试的错误场景包括：输入JSON格式错误时的异常捕获和降级处理、环境变量缺失时使用默认值或优雅退出、外部服务不可用时的超时和重试逻辑、权限不足时的错误提示和退出策略、内存不足或文件描述符耗尽时的资源管理。每个错误处理路径都应当有对应的测试用例，确保Hook在非正常情况下不会静默失败或产生不可预期的行为。

测试跨平台兼容性

Claude Code运行在Windows、macOS和Linux三个平台上，Hook需要在这三个平台上都能正常工作。跨平台测试需要覆盖：文件路径分隔符的处理（/ vs \）、换行符的处理（\n vs \r\n）、环境变量大小写敏感性的差异、系统命令和工具的可用性差异、编码问题（UTF-8 BOM、GBK等）。建议在CI中使用矩阵构建同时运行多平台测试。

注意：Windows环境中Python的os.environ默认不区分大小写，而Linux环境区分。如果Hook代码中直接使用大写的环境变量名（如CLAUDE_TOOL_NAME），在Windows下getenv("claude_tool_name")也能获取到值，这可能导致测试结果在不同平台上不一致。建议统一使用大写形式访问环境变量。

四、模拟测试方法

模拟测试（Mock Testing）是Hook测试的核心策略之一。由于Hook运行在Claude Code的上下文中，直接集成测试成本较高，通过精心设计的模拟环境可以高效验证Hook的行为。

设置模拟环境变量模拟不同事件

Hook的行为由环境变量驱动，通过设置不同的环境变量组合可以模拟各种触发事件。关键模拟场景包括：模拟before:Bash事件（设置CLAUDE_TOOL_NAME=Bash和CLAUDE_TOOL_INPUT为命令JSON）、模拟after:Bash事件（额外设置CLAUDE_TOOL_OUTPUT或CLAUDE_TOOL_EXIT_CODE）、模拟before:Read事件（设置CLAUDE_TOOL_NAME=Read和CLAUDE_TOOL_INPUT为文件路径JSON）、模拟user-prompt-submit事件（设置CLAUDE_PROMPT变量）。每次模拟应当只改变一个变量，以便精确定位问题。

# 模拟不同事件的Shell测试辅助函数

simulate_before_bash() {
    export CLAUDE_TOOL_NAME="Bash"
    export CLAUDE_TOOL_INPUT='{"command": "'"$1"'"}'
    export CLAUDE_TOOL_EXECUTION_ID="test-$(date +%s)"
}

simulate_after_bash() {
    simulate_before_bash "$1"
    export CLAUDE_TOOL_OUTPUT="$2"
    export CLAUDE_TOOL_EXIT_CODE="${3:-0}"
}

simulate_user_prompt() {
    unset CLAUDE_TOOL_NAME
    unset CLAUDE_TOOL_INPUT
    export CLAUDE_PROMPT="$1"
    export CLAUDE_PROMPT_FILE="/tmp/test_prompt.md"
    echo "$1" > "$CLAUDE_PROMPT_FILE"
}

# 使用示例
@test "before:Bash 拒绝rm命令" {
    simulate_before_bash "rm -rf /"
    run ./hooks/before-bash.sh
    [ "$status" -ne 0 ]
}

@test "after:Bash 记录失败命令" {
    simulate_after_bash "deploy.sh" "Error: connection refused" 1
    run ./hooks/after-bash-logger.sh
    echo "$output" | grep -q "失败"
}

@test "user-prompt-submit 检测敏感信息" {
    simulate_user_prompt "请帮我连接数据库，密码是 admin123"
    run ./hooks/before-prompt.sh
    [ "$status" -ne 0 ]
}

创建模拟文件测试Hook行为

许多Hook需要读取或写入文件（如日志记录、配置文件管理）。创建模拟文件系统可以测试Hook的文件操作行为。测试方法包括：使用临时目录（mktemp -d）创建隔离的测试文件系统、在临时目录中预置测试文件（如模拟的项目配置文件、Git仓库状态）、验证Hook在模拟目录中的文件创建和修改行为、测试完成后使用teardown清理临时目录。对于更复杂的场景，可以使用tmpfs（Linux）或ramdisk创建内存文件系统，提高测试速度。

模拟错误条件

全面的Hook测试必须覆盖各种错误条件，确保Hook在异常情况下能够优雅处理。需要模拟的错误条件包括：超时场景（设置CLAUDE_HOOK_TIMEOUT为极小值如1，然后让Hook执行耗时操作验证超时处理）、权限不足（使用chmod移除Hook脚本的执行权限验证错误提示）、磁盘空间不足（在测试容器中限制磁盘配额）、内存不足（使用ulimit限制可用内存）、网络不可达（模拟网络请求的超时和连接拒绝）。

模拟Hook链的完整执行流程

实际生产环境中，多个Hook可能串联执行形成Hook链。模拟Hook链的完整执行流程可以验证Hook之间的交互是否正常。测试策略包括：创建测试脚本按顺序调用多个Hook、验证前一个Hook的输出（如设置的环境变量）是否能被后一个Hook正确读取、测试某个Hook失败时后序Hook是否按预期跳过、测试Hook链的总体执行时间是否在合理范围内。建议使用专门的集成测试目录（tests/integration/）来存放Hook链测试用例，与单元测试分开管理。

测试金字塔在Hook测试中的应用：

底层：大量快速的单元测试（BATS/pytest）验证单个Hook函数的逻辑正确性。中层：适量的模拟测试验证Hook在模拟环境中的行为。顶层：少量的端到端集成测试验证Hook与Claude Code的真实交互。遵循这个金字塔结构可以在保证质量的同时控制测试成本和执行时间。

五、CI自动化测试

将Hook测试集成到CI流水线中是保证Hook质量持续稳定的关键。每次修改Hook时自动运行测试可以及时发现回归问题，防止有缺陷的Hook被部署到生产环境。

将Hook测试集成到CI流水线

推荐使用GitHub Actions、GitLab CI或Jenkins等CI工具自动运行Hook测试。CI流水线应当包含以下阶段：lint阶段（使用shellcheck检查Shell脚本、使用flake8/pylint检查Python脚本确保代码风格和基本质量）、unit-test阶段（运行所有BATS和pytest单元测试）、integration-test阶段（运行模拟测试和Hook链测试）、coverage阶段（收集和报告测试覆盖率）。每个阶段都应当在前一阶段成功后执行，确保问题尽早发现。

# .github/workflows/hook-tests.yml

name: Hook Tests

on:
  push:
    paths:
      - 'hooks/**'
      - 'tests/**'
      - '.github/workflows/hook-tests.yml'
  pull_request:
    paths:
      - 'hooks/**'
      - 'tests/**'

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: ShellCheck Shell Hooks
        run: |
          sudo apt-get install -y shellcheck
          shellcheck hooks/*.sh
      - name: Lint Python Hooks
        run: |
          pip install flake8
          flake8 hooks/*.py

  unit-tests:
    needs: lint
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - name: Install BATS
        run: |
          npm install -g bats
          npm install -g bats-assert bats-support
        shell: bash
      - name: Run BATS Tests
        run: bats tests/*.bats
        shell: bash
      - name: Run Python Tests
        run: |
          pip install pytest pytest-mock pytest-cov
          pytest tests/ --cov=hooks/ --cov-report=xml
        shell: bash
      - name: Upload Coverage
        uses: codecov/codecov-action@v4
        with:
          file: ./coverage.xml

  integration-tests:
    needs: unit-tests
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Claude Code (模拟环境)
        run: |
          pip install claude-code-mock
      - name: Run Integration Tests
        run: |
          bats tests/integration/*.bats
          pytest tests/integration/

测试覆盖率报告

测试覆盖率是衡量测试完整性的重要指标。对于Shell Hook，可以使用kcov或bashcov生成覆盖率报告。对于Python Hook，pytest-cov插件可以提供详细的覆盖率数据。建议的目标覆盖率：核心逻辑路径覆盖率不低于90%、错误处理路径覆盖率不低于80%、条件分支覆盖率不低于85%。覆盖率报告应当集成到CI流水线中，并在覆盖率下降时发出告警。但需要注意，高覆盖率不等于高质量测试，每个测试用例的价值比覆盖率数字更重要。

多平台自动化测试

Claude Code支持Windows、macOS和Linux三个平台，Hook必须在这三个平台上都能正常运行。多平台测试的关键关注点包括：使用CI的矩阵构建功能在三个操作系统上并行运行测试、每个平台上验证Shell脚本的解释器兼容性（bash vs sh vs zsh）、验证Python版本兼容性（3.8+）、验证文件系统行为一致性（大小写敏感、路径分隔符、权限模型）、验证系统命令的可用性差异（如Linux的grep vs macOS的ggrep）。建议在CI配置中使用fail-fast: false确保一个平台失败不会取消其他平台的测试，以便全面了解跨平台兼容性问题。

质量门禁（Quality Gate）建议：在CI中设置质量门禁，只有满足以下条件的PR才能合并：所有lint检查通过、所有单元测试通过、所有集成测试通过、测试覆盖率不低于设定阈值、没有引入新的shellcheck或flake8告警。质量门禁可以有效防止低质量的Hook代码进入主分支。

六、最佳实践总结

综合以上五个测试维度，以下是Hook测试的最佳实践总结：

测试先行：在编写Hook代码之前先编写测试用例，以测试驱动开发（TDD）的方式保证每个功能点都有对应的测试覆盖。
隔离测试环境：每个测试用例应当独立运行，不依赖外部状态。使用setup/teardown确保测试环境的一致性。
测试命名规范：测试用例名称应当清晰描述测试场景和预期行为，如"拒绝危险命令_rm_rf"、"空输入返回零退出码"。
边界条件优先：空输入、极限长度、特殊字符、并发访问等边界条件比正常路径更容易暴露问题，应当优先测试。
持续维护测试：Hook代码修改后及时更新对应的测试用例，保持测试与代码的同步。过时的测试比没有测试更危险。
测试文档化：在Hook的README或注释中说明测试的覆盖范围、运行方法和常见问题，降低后续维护者的上手成本。