Skip to content

JiuwenSwarm is an intelligent AI Agent built on openJiuwen. It extends the powerful capabilities of large language models directly to your fingertips through various communication apps you use daily.

Python
17.0 KB
Raw Blame
# Copyright (c) Huawei Technologies Co., Ltd. 2025. All rights reserved.

"""Unit tests for jiuwenswarm.server.hooks.user_hook_rail."""

from __future__ import annotations

from dataclasses import dataclass, field
from typing import Any
from unittest.mock import AsyncMock, patch

import pytest

from jiuwenswarm.common.hooks_config import HooksConfig, HookMatcher
from jiuwenswarm.server.hooks.executor import HookOutcome, HookResult
from jiuwenswarm.server.hooks.user_hook_rail import UserHookRail


# ============================================================
# Mock helpers: 模拟 openjiuwen 的 AgentCallbackContext
# ============================================================

@dataclass
class MockToolInputs:
    tool_name: str = ""
    tool_args: Any = None
    tool_result: Any = None
    tool_msg: Any = None


@dataclass
class MockCallbackContext:
    inputs: MockToolInputs = field(default_factory=MockToolInputs)
    extra: dict = field(default_factory=dict)
    session: Any = None


def _rail_with_mocked_executor(config, results):
    """构造 UserHookRail,其 executor.run_all 被 mock 为返回 results。

    CI(Linux/Py3.11) 下 asyncio.create_subprocess_exec 不稳定,异常被
    executor 吞为 NON_BLOCKING_ERROR,断言 hook 输出的用例会失败。这些是
    rail 逻辑单测,HookResult 由 mock 直接提供,不依赖真实 bash 子进程。
    """
    rail = UserHookRail(config)
    rail._executor.run_all = AsyncMock(return_value=results)
    return rail


# ============================================================
# UserHookRail: before_tool_call (PreToolUse)
# ============================================================

class TestBeforeToolCall:
    @staticmethod
    def _make_config(**events):
        matchers = {}
        for event_name, matcher_list in events.items():
            matchers[event_name] = [
                HookMatcher(matcher=m[0], hooks=m[1]) for m in matcher_list
            ]
        return HooksConfig(events=matchers)

    @pytest.mark.asyncio
    async def test_no_matching_hooks_does_nothing(self):
        config = self._make_config()
        rail = UserHookRail(config)
        ctx = MockCallbackContext(inputs=MockToolInputs(tool_name="Write"))
        await rail.before_tool_call(ctx)
        # ctx 不应被修改
        assert "_skip_tool" not in ctx.extra

    @pytest.mark.asyncio
    async def test_passes_session_id_from_context_session_to_tool_and_stop_hooks(self):
        config = self._make_config(
            PreToolUse=[("*", [{"command": "echo ok", "timeout": 5}])],
            Stop=[("*", [{"command": "echo ok", "timeout": 5}])],
        )
        rail = _rail_with_mocked_executor(config, [])
        ctx = MockCallbackContext(
            inputs=MockToolInputs(tool_name="Bash"),
            session=type(
                "Session",
                (),
                {"get_session_id": lambda self: "session-5081"},
            )(),
        )

        await rail.before_tool_call(ctx)

        hook_input = rail._executor.run_all.await_args.kwargs["hook_input"]
        assert hook_input["session_id"] == "session-5081"

        rail._executor.run_all.reset_mock()
        await rail.after_invoke(ctx)

        hook_input = rail._executor.run_all.await_args.kwargs["hook_input"]
        assert hook_input["session_id"] == "session-5081"

    @pytest.mark.asyncio
    async def test_blocking_hook_sets_skip_tool(self):
        config = self._make_config(
            PreToolUse=[("*", [{"command": "echo block >&2; exit 2", "timeout": 5}])]
        )
        rail = _rail_with_mocked_executor(config, [
            HookResult(outcome=HookOutcome.BLOCKING, error="block", show_to_model=True),
        ])
        ctx = MockCallbackContext(inputs=MockToolInputs(tool_name="Bash"))
        await rail.before_tool_call(ctx)
        assert ctx.extra["_skip_tool"] is True
        assert "_hook_feedback" in ctx.extra

    @pytest.mark.asyncio
    async def test_modifying_hook_updates_tool_args(self):
        config = self._make_config(
            PreToolUse=[(
                "Write",
                [{
                    "command": 'echo \'{"modifiedInput":{"file_path":"/safe/path.txt"}}\'',
                    "timeout": 5,
                }]
            )]
        )
        rail = _rail_with_mocked_executor(config, [
            HookResult(
                outcome=HookOutcome.SUCCESS,
                modified_input={"file_path": "/safe/path.txt"},
            ),
        ])
        ctx = MockCallbackContext(
            inputs=MockToolInputs(
                tool_name="Write",
                tool_args={"file_path": "/dangerous/path.txt"},
            )
        )
        await rail.before_tool_call(ctx)
        assert ctx.inputs.tool_args == {"file_path": "/safe/path.txt"}

    @pytest.mark.asyncio
    async def test_modifying_hook_updates_tool_name(self):
        """modifiedInput 中的 _tool_name 可改变工具名."""
        config = self._make_config(
            PreToolUse=[(
                "*",
                [{
                    "command": 'echo \'{"modifiedInput":{"_tool_name":"Read","file_path":"/tmp/x.txt"}}\'',
                    "timeout": 5,
                }]
            )]
        )
        rail = _rail_with_mocked_executor(config, [
            HookResult(
                outcome=HookOutcome.SUCCESS,
                modified_input={"_tool_name": "Read", "file_path": "/tmp/x.txt"},
            ),
        ])
        ctx = MockCallbackContext(inputs=MockToolInputs(tool_name="Write"))
        await rail.before_tool_call(ctx)
        assert ctx.inputs.tool_name == "Read"

    @pytest.mark.asyncio
    async def test_matcher_filters_by_tool_name(self):
        """只有匹配的工具名才会触发 hook."""
        config = self._make_config(
            PreToolUse=[("Write", [{"command": "exit 2", "timeout": 5}])]
        )
        rail = UserHookRail(config)
        # Bash 不匹配 Write → 不会被阻止
        ctx = MockCallbackContext(inputs=MockToolInputs(tool_name="Bash"))
        await rail.before_tool_call(ctx)
        assert "_skip_tool" not in ctx.extra

    @pytest.mark.asyncio
    async def test_additional_context_appended(self):
        config = self._make_config(
            PreToolUse=[(
                "*",
                [{"command": 'echo \'{"additionalContext":"pre-write check passed"}\'', "timeout": 5}]
            )]
        )
        rail = _rail_with_mocked_executor(config, [
            HookResult(
                outcome=HookOutcome.SUCCESS,
                additional_context="pre-write check passed",
            ),
        ])
        ctx = MockCallbackContext(inputs=MockToolInputs(tool_name="Write"))
        await rail.before_tool_call(ctx)
        assert "pre-write check passed" in ctx.extra.get("_hook_additional_context", "")

    @pytest.mark.asyncio
    async def test_blocking_takes_priority_over_modify(self):
        """第一个 blocking hook 应阻止,后续结果不再处理."""
        config = self._make_config(
            PreToolUse=[(
                "Bash",
                [
                    {"command": "echo block >&2; exit 2", "timeout": 5},
                    {
                        "command": 'echo \'{"modifiedInput":{"safe":"yes"}}\'',
                        "timeout": 5,
                    },
                ]
            )]
        )
        rail = UserHookRail(config)
        ctx = MockCallbackContext(inputs=MockToolInputs(tool_name="Bash"))
        with patch.object(
            rail._executor,
            "run_all",
            new=AsyncMock(
                return_value=[
                    HookResult(
                        outcome=HookOutcome.BLOCKING,
                        error="blocked",
                        show_to_model=True,
                    ),
                    HookResult(
                        outcome=HookOutcome.SUCCESS,
                        modified_input={"safe": "yes"},
                    ),
                ]
            ),
        ):
            await rail.before_tool_call(ctx)
        assert ctx.extra["_skip_tool"] is True
        # modifiedInput 不应该被应用(因为早已 return)
        assert "safe" not in str(ctx.inputs.tool_args)

    @pytest.mark.asyncio
    async def test_empty_tool_name_handled(self):
        """空工具名不应崩溃."""
        config = self._make_config(
            PreToolUse=[("*", [{"command": "echo ok", "timeout": 5}])]
        )
        rail = UserHookRail(config)
        ctx = MockCallbackContext(inputs=MockToolInputs(tool_name=""))
        await rail.before_tool_call(ctx)
        # 不应抛出异常

    @pytest.mark.asyncio
    async def test_no_matching_matchers_skip_execution(self):
        """没有匹配的 matcher 时,不应执行任何 hook."""
        config = self._make_config(
            PreToolUse=[("Write", [{"command": "echo ok", "timeout": 5}])]
        )
        rail = UserHookRail(config)
        ctx = MockCallbackContext(inputs=MockToolInputs(tool_name="Bash"))
        await rail.before_tool_call(ctx)
        assert "_skip_tool" not in ctx.extra


# ============================================================
# UserHookRail: after_tool_call (PostToolUse)
# ============================================================

class TestAfterToolCall:
    @staticmethod
    def _make_config(**events):
        matchers = {}
        for event_name, matcher_list in events.items():
            matchers[event_name] = [
                HookMatcher(matcher=m[0], hooks=m[1]) for m in matcher_list
            ]
        return HooksConfig(events=matchers)

    @pytest.mark.asyncio
    async def test_no_matching_hooks_does_nothing(self):
        config = self._make_config()
        rail = UserHookRail(config)
        ctx = MockCallbackContext(inputs=MockToolInputs(tool_name="Write"))
        await rail.after_tool_call(ctx)
        assert "_post_tool_hook_feedback" not in ctx.extra

    @pytest.mark.asyncio
    async def test_appends_additional_context_to_result(self):
        config = self._make_config(
            PostToolUse=[(
                "*",
                [{"command": 'echo \'{"additionalContext":"review note"}\'', "timeout": 5}]
            )]
        )
        rail = _rail_with_mocked_executor(config, [
            HookResult(outcome=HookOutcome.SUCCESS, additional_context="review note"),
        ])
        ctx = MockCallbackContext(
            inputs=MockToolInputs(tool_name="Bash", tool_result="command output")
        )
        await rail.after_tool_call(ctx)
        assert "review note" in ctx.inputs.tool_result
        assert "command output" in ctx.inputs.tool_result  # 原内容保留

    @pytest.mark.asyncio
    async def test_additional_context_appended_to_none_result(self):
        """即使 tool_result 为 None,也能正常工作."""
        config = self._make_config(
            PostToolUse=[(
                "*",
                [{"command": 'echo \'{"additionalContext":"note"}\'', "timeout": 5}]
            )]
        )
        rail = _rail_with_mocked_executor(config, [
            HookResult(outcome=HookOutcome.SUCCESS, additional_context="note"),
        ])
        ctx = MockCallbackContext(inputs=MockToolInputs(tool_name="Read", tool_result=None))
        await rail.after_tool_call(ctx)
        assert "note" in (ctx.inputs.tool_result or "")

    @pytest.mark.asyncio
    async def test_blocking_post_tool_triggers_feedback(self):
        config = self._make_config(
            PostToolUse=[(
                "Bash",
                [{"command": "echo 'blocked after review' >&2; exit 2", "timeout": 5}]
            )]
        )
        rail = _rail_with_mocked_executor(config, [
            HookResult(
                outcome=HookOutcome.BLOCKING,
                error="blocked after review",
                show_to_model=True,
            ),
        ])
        ctx = MockCallbackContext(inputs=MockToolInputs(tool_name="Bash"))
        await rail.after_tool_call(ctx)
        assert "_post_tool_hook_feedback" in ctx.extra


# ============================================================
# UserHookRail: on_tool_exception (PostToolUseFailure)
# ============================================================

class TestOnToolException:
    @staticmethod
    def _make_config(**events):
        matchers = {}
        for event_name, matcher_list in events.items():
            matchers[event_name] = [
                HookMatcher(matcher=m[0], hooks=m[1]) for m in matcher_list
            ]
        return HooksConfig(events=matchers)

    @pytest.mark.asyncio
    async def test_no_matching_hooks_does_nothing(self):
        config = self._make_config()
        rail = UserHookRail(config)
        ctx = MockCallbackContext(inputs=MockToolInputs(tool_name="Write"))
        await rail.on_tool_exception(ctx)
        # 不应崩溃

    @pytest.mark.asyncio
    async def test_hook_runs_but_does_not_block(self):
        """PostToolUseFailure 只收集信息,不改变异常处理流程."""
        config = self._make_config(
            PostToolUseFailure=[(
                "*",
                [{"command": "echo 'error logged'", "timeout": 5}]
            )]
        )
        rail = UserHookRail(config)
        ctx = MockCallbackContext(inputs=MockToolInputs(tool_name="Bash"))
        await rail.on_tool_exception(ctx)
        # 不应修改 ctx.extra(结果被丢弃)


# ============================================================
# UserHookRail: after_invoke (Stop)
# ============================================================

class TestAfterInvoke:
    @staticmethod
    def _make_config(**events):
        matchers = {}
        for event_name, matcher_list in events.items():
            matchers[event_name] = [
                HookMatcher(matcher=m[0], hooks=m[1]) for m in matcher_list
            ]
        return HooksConfig(events=matchers)

    @pytest.mark.asyncio
    async def test_no_matching_hooks_does_nothing(self):
        config = self._make_config()
        rail = UserHookRail(config)
        ctx = MockCallbackContext()
        await rail.after_invoke(ctx)
        assert "_stop_hook_feedback" not in ctx.extra

    @pytest.mark.asyncio
    async def test_blocking_stop_hook_sets_feedback(self):
        config = self._make_config(
            Stop=[("*", [{"command": "echo 'final check failed' >&2; exit 2", "timeout": 5}])]
        )
        rail = UserHookRail(config)
        ctx = MockCallbackContext()
        with patch.object(
            rail._executor,
            "run_all",
            new=AsyncMock(return_value=[
                HookResult(
                    outcome=HookOutcome.BLOCKING,
                    error="final check failed",
                    show_to_model=True,
                ),
            ]),
        ):
            await rail.after_invoke(ctx)
        assert "_stop_hook_feedback" in ctx.extra

    @pytest.mark.asyncio
    async def test_stop_matches_without_tool_name(self):
        """Stop 事件不按 tool_name 过滤,match 时 query 为空."""
        config = self._make_config(
            Stop=[("*", [{"command": "echo stop", "timeout": 5}])]
        )
        rail = UserHookRail(config)
        ctx = MockCallbackContext()
        await rail.after_invoke(ctx)
        # 不应崩溃

    @pytest.mark.asyncio
    async def test_multiple_stop_hooks_both_run(self):
        config = self._make_config(
            Stop=[(
                "*",
                [
                    {"command": "echo first", "timeout": 5},
                    {"command": "echo second; exit 2", "timeout": 5},
                ]
            )]
        )
        rail = UserHookRail(config)
        ctx = MockCallbackContext()

        with patch.object(
            rail._executor,
            "run_all",
            new=AsyncMock(return_value=[
                HookResult(outcome=HookOutcome.SUCCESS),
                HookResult(
                    outcome=HookOutcome.BLOCKING,
                    error="hook blocked execution",
                    show_to_model=True,
                ),
            ]),
        ):
            await rail.after_invoke(ctx)
        # 即使第二个 hook 是 blocking,也应记录 feedback
        assert "_stop_hook_feedback" in ctx.extra


# ============================================================
# UserHookRail: priority
# ============================================================

class TestPriority:
    @staticmethod
    def test_priority_is_60():
        config = HooksConfig()
        rail = UserHookRail(config)
        assert rail.priority == 60


# ============================================================
# UserHookRail: disable_all_hooks
# ============================================================

class TestDisableAllHooks:
    @pytest.mark.asyncio
    async def test_disabled_hooks_skip_all(self):
        config = HooksConfig(
            events={
                "PreToolUse": [HookMatcher(matcher="*", hooks=[{"command": "exit 2", "timeout": 5}])],
                "Stop": [HookMatcher(matcher="*", hooks=[{"command": "exit 2", "timeout": 5}])],
            },
            disable_all_hooks=True,
        )
        rail = UserHookRail(config)
        ctx = MockCallbackContext(inputs=MockToolInputs(tool_name="Bash"))
        await rail.before_tool_call(ctx)
        assert "_skip_tool" not in ctx.extra