Testing Utilities

Utilities for testing hook handlers.

MockEvent

Factory for creating test events.

MockEvent

Factory for creating test events.

Example

event = MockEvent.bash(command="ls -la") result = my_handler(event) assert result.decision != "deny"

bash staticmethod

bash(
    command: str,
    *,
    description: str | None = None,
    timeout: int | None = None,
    session_id: str = "test-session",
    cwd: str = "/workspace",
) -> Bash

Create a Bash PreToolUse event.

write staticmethod

write(
    file_path: str,
    content: str = "",
    *,
    session_id: str = "test-session",
    cwd: str = "/workspace",
) -> Write

Create a Write PreToolUse event.

edit staticmethod

edit(
    file_path: str,
    old_string: str,
    new_string: str,
    *,
    session_id: str = "test-session",
    cwd: str = "/workspace",
) -> Edit

Create an Edit PreToolUse event.

read staticmethod

read(
    file_path: str,
    *,
    session_id: str = "test-session",
    cwd: str = "/workspace",
) -> Read

Create a Read PreToolUse event.

grep staticmethod

grep(
    pattern: str,
    *,
    path: str | None = None,
    glob: str | None = None,
    output_mode: str | None = None,
    session_id: str = "test-session",
    cwd: str = "/workspace",
) -> Grep

Create a Grep PreToolUse event.

glob staticmethod

glob(
    pattern: str,
    *,
    path: str | None = None,
    session_id: str = "test-session",
    cwd: str = "/workspace",
) -> Glob

Create a Glob PreToolUse event.

task staticmethod

task(
    prompt: str,
    *,
    description: str = "Test task",
    subagent_type: str | None = None,
    model: str | None = None,
    session_id: str = "test-session",
    cwd: str = "/workspace",
) -> Task

Create a Task PreToolUse event.

web_search staticmethod

web_search(
    query: str,
    *,
    session_id: str = "test-session",
    cwd: str = "/workspace",
) -> WebSearch

Create a WebSearch PreToolUse event.

web_fetch staticmethod

web_fetch(
    url: str,
    prompt: str = "",
    *,
    session_id: str = "test-session",
    cwd: str = "/workspace",
) -> WebFetch

Create a WebFetch PreToolUse event.

stop staticmethod

stop(
    *,
    stop_hook_active: bool = False,
    session_id: str = "test-session",
    cwd: str = "/workspace",
) -> Stop

Create a Stop event.

subagent_stop staticmethod

subagent_stop(
    *,
    stop_hook_active: bool = False,
    session_id: str = "test-session",
    cwd: str = "/workspace",
) -> SubagentStop

Create a SubagentStop event.

session_start staticmethod

session_start(
    source: str = "startup",
    *,
    session_id: str = "test-session",
    cwd: str = "/workspace",
) -> SessionStart

Create a SessionStart event.

session_end staticmethod

session_end(
    reason: str = "user_exit",
    *,
    session_id: str = "test-session",
    cwd: str = "/workspace",
) -> SessionEnd

Create a SessionEnd event.

pre_compact staticmethod

pre_compact(
    trigger: str = "manual",
    *,
    session_id: str = "test-session",
    cwd: str = "/workspace",
) -> PreCompact

Create a PreCompact event.

user_prompt staticmethod

user_prompt(
    prompt: str,
    *,
    session_id: str = "test-session",
    cwd: str = "/workspace",
) -> UserPromptSubmit

Create a UserPromptSubmit event.

notification staticmethod

notification(
    message: str,
    notification_type: str = "info",
    *,
    session_id: str = "test-session",
    cwd: str = "/workspace",
) -> Notification

Create a Notification event.

permission_bash staticmethod

permission_bash(
    command: str,
    *,
    description: str | None = None,
    session_id: str = "test-session",
    cwd: str = "/workspace",
) -> Bash

Create a Bash PermissionRequest event.

permission_write staticmethod

permission_write(
    file_path: str,
    content: str = "",
    *,
    session_id: str = "test-session",
    cwd: str = "/workspace",
) -> Write

Create a Write PermissionRequest event.

permission_edit staticmethod

permission_edit(
    file_path: str,
    old_string: str,
    new_string: str,
    *,
    session_id: str = "test-session",
    cwd: str = "/workspace",
) -> Edit

Create an Edit PermissionRequest event.

TestClient

Client for testing hook applications.

TestClient

Test client for invoking hook handlers.

Allows testing hooks without stdin/stdout plumbing.

Example

app = HookApp()

@app.pre_tool("Bash") def handler(event): return allow()

client = TestClient(app) response = client.send(MockEvent.bash(command="ls")) assert response is None # allowed

__init__

__init__(app: HookApp)

Initialize TestClient.

Parameters:

Name	Type	Description	Default
app	HookApp	HookApp to test	required

send

send(event: BaseEvent) -> BaseHookResponse | None

Send an event to the app and return the response.

Parameters:

Name	Type	Description	Default
event	BaseEvent	Typed event (from MockEvent or manual)	required

Returns:

Type	Description
BaseHookResponse | None	BaseHookResponse if actionable, None if pass-through