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
24.0 KB
Raw Blame
# Copyright (c) Huawei Technologies Co., Ltd. 2025. All rights reserved.

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

from __future__ import annotations

import asyncio
import json
from unittest.mock import AsyncMock, MagicMock, patch

import pytest

from jiuwenswarm.server.hooks.executor import HookExecutor, HookResult, HookOutcome


def _fake_proc(*, returncode: int = 0, stdout: bytes = b"", stderr: bytes = b""):
    """Build a fake asyncio subprocess for HookExecutor unit tests."""
    proc = MagicMock()
    proc.returncode = returncode
    proc.communicate = AsyncMock(return_value=(stdout, stderr))
    proc.kill = MagicMock()
    proc.wait = AsyncMock(return_value=None)
    return proc


def _close_awaitable(awaitable) -> None:
    """Avoid 'coroutine was never awaited' when timeout mocks skip awaiting."""
    close = getattr(awaitable, "close", None)
    if callable(close):
        close()


async def _raise_timeout(awaitable, timeout=None):
    _close_awaitable(awaitable)
    raise asyncio.TimeoutError


# ============================================================
# HookResult
# ============================================================

class TestHookResult:
    @staticmethod
    def test_defaults():
        r = HookResult()
        assert r.outcome == HookOutcome.SUCCESS
        assert r.error == ""
        assert r.show_to_model is False
        assert r.modified_input is None
        assert r.additional_context == ""

    @staticmethod
    def test_blocking():
        r = HookResult(outcome=HookOutcome.BLOCKING, error="blocked", show_to_model=True)
        assert r.outcome == "blocking"
        assert r.error == "blocked"
        assert r.show_to_model is True


# ============================================================
# HookExecutor: run_all dispatch
# ============================================================

class TestRunAll:
    @staticmethod
    @pytest.mark.asyncio
    async def test_empty_configs():
        e = HookExecutor()
        results = await e.run_all([], {})
        assert results == []

    @staticmethod
    @pytest.mark.asyncio
    async def test_dispatches_command_by_default():
        e = HookExecutor()
        with patch(
            "jiuwenswarm.server.hooks.executor.asyncio.create_subprocess_exec",
            new_callable=AsyncMock,
            return_value=_fake_proc(stdout=b"ok\n"),
        ):
            results = await e.run_all(
                [{"command": "echo ok"}],
                {"event": "Test"},
            )
        assert len(results) == 1
        assert results[0].outcome == HookOutcome.SUCCESS

    @staticmethod
    @pytest.mark.asyncio
    async def test_dispatches_prompt_type():
        e = HookExecutor()
        results = await e.run_all(
            [{"type": "prompt", "prompt": "test"}],
            {"event": "Test"},
        )
        assert len(results) == 1
        # prompt hook 尝试调 LLM → 无配置时 non_blocking_error 也算正常
        assert results[0].outcome in (HookOutcome.SUCCESS, HookOutcome.NON_BLOCKING_ERROR)

    @staticmethod
    @pytest.mark.asyncio
    async def test_parallel_execution():
        """多个 hook 应并行调度并各自返回结果."""
        e = HookExecutor()
        create = AsyncMock(side_effect=[
            _fake_proc(stdout=b"a\n"),
            _fake_proc(stdout=b"b\n"),
            _fake_proc(stdout=b"c\n"),
        ])
        with patch(
            "jiuwenswarm.server.hooks.executor.asyncio.create_subprocess_exec",
            new=create,
        ):
            results = await e.run_all(
                [
                    {"command": "echo a"},
                    {"command": "echo b"},
                    {"command": "echo c"},
                ],
                {"event": "Test"},
            )
        assert len(results) == 3
        assert all(r.outcome == HookOutcome.SUCCESS for r in results)
        assert create.await_count == 3

    @staticmethod
    @pytest.mark.asyncio
    async def test_exception_wrapped_as_error():
        """子进程非 0/2 退出应包装为 non_blocking_error."""
        e = HookExecutor()
        with patch(
            "jiuwenswarm.server.hooks.executor.asyncio.create_subprocess_exec",
            new_callable=AsyncMock,
            return_value=_fake_proc(returncode=1, stderr=b"boom"),
        ):
            results = await e.run_all(
                [{"command": "exit 1"}],
                {"event": "Test"},
            )
        assert len(results) == 1
        assert results[0].outcome == HookOutcome.NON_BLOCKING_ERROR


# ============================================================
# Command Hook: Exit Code Semantics
# ============================================================

class TestCommandHookExitCodes:
    @staticmethod
    @pytest.mark.asyncio
    async def test_exit_0_is_success():
        e = HookExecutor()
        with patch(
            "jiuwenswarm.server.hooks.executor.asyncio.create_subprocess_exec",
            new_callable=AsyncMock,
            return_value=_fake_proc(returncode=0),
        ):
            results = await e.run_all(
                [{"command": "exit 0", "timeout": 5}],
                {"event": "PreToolUse", "tool_name": "Bash"},
            )
        assert results[0].outcome == HookOutcome.SUCCESS

    @staticmethod
    @pytest.mark.asyncio
    async def test_exit_2_is_blocking():
        e = HookExecutor()
        with patch(
            "jiuwenswarm.server.hooks.executor.asyncio.create_subprocess_exec",
            new_callable=AsyncMock,
            return_value=_fake_proc(returncode=2, stderr=b"blocked by policy"),
        ):
            results = await e.run_all(
                [{"command": "echo 'blocked by policy' >&2; exit 2", "timeout": 5}],
                {"event": "PreToolUse", "tool_name": "Bash"},
            )
        r = results[0]
        assert r.outcome == HookOutcome.BLOCKING
        assert r.show_to_model is True

    @staticmethod
    @pytest.mark.asyncio
    async def test_exit_1_is_non_blocking_error():
        e = HookExecutor()
        with patch(
            "jiuwenswarm.server.hooks.executor.asyncio.create_subprocess_exec",
            new_callable=AsyncMock,
            return_value=_fake_proc(returncode=1),
        ):
            results = await e.run_all(
                [{"command": "exit 1", "timeout": 5}],
                {"event": "PreToolUse"},
            )
        assert results[0].outcome == HookOutcome.NON_BLOCKING_ERROR

    @staticmethod
    @pytest.mark.asyncio
    async def test_exit_127_is_non_blocking_error():
        e = HookExecutor()
        with patch(
            "jiuwenswarm.server.hooks.executor.asyncio.create_subprocess_exec",
            new_callable=AsyncMock,
            return_value=_fake_proc(returncode=127),
        ):
            results = await e.run_all(
                [{"command": "exit 127", "timeout": 5}],
                {"event": "Test"},
            )
        assert results[0].outcome == HookOutcome.NON_BLOCKING_ERROR


# ============================================================
# Command Hook: Environment Variables
# ============================================================

class TestCommandHookEnvVars:
    @staticmethod
    @pytest.mark.asyncio
    async def test_arguments_env_var_set():
        """ARGUMENTS 环境变量包含 hook input JSON."""
        e = HookExecutor()
        hook_input = {"event": "PreToolUse", "tool_name": "Write", "key": "value123"}
        create = AsyncMock(return_value=_fake_proc(returncode=0, stdout=b"ok\n"))
        with patch(
            "jiuwenswarm.server.hooks.executor.asyncio.create_subprocess_exec",
            new=create,
        ):
            results = await e.run_all(
                [{"command": "echo $ARGUMENTS", "timeout": 5}],
                hook_input,
            )
        assert results[0].outcome == HookOutcome.SUCCESS
        env = create.await_args.kwargs["env"]
        assert "value123" in env["ARGUMENTS"]
        assert json.loads(env["ARGUMENTS"]) == hook_input

    @staticmethod
    @pytest.mark.asyncio
    async def test_tool_name_env_var_set():
        e = HookExecutor()
        create = AsyncMock(return_value=_fake_proc(returncode=0))
        with patch(
            "jiuwenswarm.server.hooks.executor.asyncio.create_subprocess_exec",
            new=create,
        ):
            results = await e.run_all(
                [{"command": 'test "$TOOL_NAME" = "Write"', "timeout": 5}],
                {"event": "PreToolUse", "tool_name": "Write"},
            )
        assert results[0].outcome == HookOutcome.SUCCESS
        assert create.await_args.kwargs["env"]["TOOL_NAME"] == "Write"

    @staticmethod
    @pytest.mark.asyncio
    async def test_tool_name_empty_when_missing():
        e = HookExecutor()
        create = AsyncMock(return_value=_fake_proc(returncode=0))
        with patch(
            "jiuwenswarm.server.hooks.executor.asyncio.create_subprocess_exec",
            new=create,
        ):
            results = await e.run_all(
                [{"command": 'test "$TOOL_NAME" = ""', "timeout": 5}],
                {"event": "Stop"},
            )
        assert results[0].outcome == HookOutcome.SUCCESS
        assert create.await_args.kwargs["env"]["TOOL_NAME"] == ""


# ============================================================
# Command Hook: timeout handling
# ============================================================

class TestCommandHookTimeout:
    @staticmethod
    @pytest.mark.asyncio
    async def test_timeout_returns_non_blocking_error():
        e = HookExecutor()
        proc = _fake_proc()

        with patch(
            "jiuwenswarm.server.hooks.executor.asyncio.create_subprocess_exec",
            new_callable=AsyncMock,
            return_value=proc,
        ), patch(
            "jiuwenswarm.server.hooks.executor.asyncio.wait_for",
            side_effect=_raise_timeout,
        ):
            results = await e.run_all(
                [{"command": "sleep 5", "timeout": 1}],
                {"event": "Test"},
            )
        r = results[0]
        assert r.outcome == HookOutcome.NON_BLOCKING_ERROR
        assert "timeout" in r.error.lower()
        proc.kill.assert_called()

    @staticmethod
    @pytest.mark.asyncio
    async def test_timeout_does_not_block_execution():
        """超时不应阻止后续 hook 或其他工具."""
        e = HookExecutor()
        timed_out = _fake_proc()
        ok_proc = _fake_proc(stdout=b"ok\n")
        create = AsyncMock(side_effect=[timed_out, ok_proc])

        async def _wait_for(awaitable, timeout=None):
            if timeout == 1:
                _close_awaitable(awaitable)
                raise asyncio.TimeoutError
            return await awaitable

        with patch(
            "jiuwenswarm.server.hooks.executor.asyncio.create_subprocess_exec",
            new=create,
        ), patch(
            "jiuwenswarm.server.hooks.executor.asyncio.wait_for",
            side_effect=_wait_for,
        ):
            results = await e.run_all(
                [
                    {"command": "sleep 5", "timeout": 1},
                    {"command": "echo ok", "timeout": 5},
                ],
                {"event": "Test"},
            )
        assert results[0].outcome == HookOutcome.NON_BLOCKING_ERROR
        assert results[1].outcome == HookOutcome.SUCCESS


# ============================================================
# Command Hook: empty command
# ============================================================

class TestCommandHookEmptyCommand:
    @staticmethod
    @pytest.mark.asyncio
    async def test_empty_command_error():
        e = HookExecutor()
        results = await e.run_all(
            [{"command": "", "timeout": 5}],
            {"event": "Test"},
        )
        assert results[0].outcome == HookOutcome.NON_BLOCKING_ERROR
        assert "empty command" in results[0].error.lower()


# ============================================================
# Command Hook: shell selection
# ============================================================

class TestCommandHookShell:
    @staticmethod
    @pytest.mark.asyncio
    async def test_default_shell_bash():
        e = HookExecutor()
        create = AsyncMock(return_value=_fake_proc(stdout=b"/bin/bash\n"))
        with patch(
            "jiuwenswarm.server.hooks.executor.asyncio.create_subprocess_exec",
            new=create,
        ):
            results = await e.run_all(
                [{"command": "echo $SHELL", "timeout": 5}],
                {"event": "Test"},
            )
        assert results[0].outcome == HookOutcome.SUCCESS
        assert create.await_args.args[0] == "bash"

    @staticmethod
    @pytest.mark.asyncio
    async def test_sh_shell():
        e = HookExecutor()
        create = AsyncMock(return_value=_fake_proc(stdout=b"ok\n"))
        with patch(
            "jiuwenswarm.server.hooks.executor.asyncio.create_subprocess_exec",
            new=create,
        ):
            results = await e.run_all(
                [{"command": "echo ok", "shell": "sh", "timeout": 5}],
                {"event": "Test"},
            )
        assert results[0].outcome == HookOutcome.SUCCESS
        assert create.await_args.args[0] == "sh"
        assert create.await_args.args[1:3] == ("-c", "echo ok")

    @staticmethod
    @pytest.mark.asyncio
    async def test_default_timeout_30():
        e = HookExecutor()
        create = AsyncMock(return_value=_fake_proc(stdout=b"ok\n"))
        captured = {}

        async def _wait_for(awaitable, timeout=None):
            captured["timeout"] = timeout
            return await awaitable

        with patch(
            "jiuwenswarm.server.hooks.executor.asyncio.create_subprocess_exec",
            new=create,
        ), patch(
            "jiuwenswarm.server.hooks.executor.asyncio.wait_for",
            side_effect=_wait_for,
        ):
            results = await e.run_all(
                [{"command": "echo ok"}],  # no timeout specified → default 30
                {"event": "Test"},
            )
        assert results[0].outcome == HookOutcome.SUCCESS
        assert captured["timeout"] == 30


# ============================================================
# Command Hook: JSON Output Protocol (parse_command_output)
# ============================================================

class TestParseCommandOutput:
    @staticmethod
    def test_empty_stdout_returns_success():
        r = HookExecutor.parse_command_output("")
        assert r.outcome == HookOutcome.SUCCESS

    @staticmethod
    def test_whitespace_only():
        r = HookExecutor.parse_command_output("   \n  ")
        assert r.outcome == HookOutcome.SUCCESS

    @staticmethod
    def test_non_json_is_success():
        r = HookExecutor.parse_command_output("just some text")
        assert r.outcome == HookOutcome.SUCCESS

    @staticmethod
    def test_non_dict_json_is_success():
        r = HookExecutor.parse_command_output("[1, 2, 3]")
        assert r.outcome == HookOutcome.SUCCESS

    @staticmethod
    def test_empty_json_object():
        r = HookExecutor.parse_command_output("{}")
        assert r.outcome == HookOutcome.SUCCESS

    @staticmethod
    def test_decision_block():
        stdout = json.dumps({"decision": "block", "reason": "dangerous operation"})
        r = HookExecutor.parse_command_output(stdout)
        assert r.outcome == HookOutcome.BLOCKING
        assert r.show_to_model is True
        assert "dangerous operation" in r.error

    @staticmethod
    def test_decision_block_no_reason():
        stdout = json.dumps({"decision": "block"})
        r = HookExecutor.parse_command_output(stdout)
        assert r.outcome == HookOutcome.BLOCKING

    @staticmethod
    def test_modified_input():
        stdout = json.dumps({"modifiedInput": {"file_path": "/safe/path.txt"}})
        r = HookExecutor.parse_command_output(stdout)
        assert r.outcome == HookOutcome.SUCCESS
        assert r.modified_input == {"file_path": "/safe/path.txt"}

    @staticmethod
    def test_additional_context():
        stdout = json.dumps({"additionalContext": "review: looks good"})
        r = HookExecutor.parse_command_output(stdout)
        assert r.outcome == HookOutcome.SUCCESS
        assert r.additional_context == "review: looks good"

    @staticmethod
    def test_reason_without_block_is_context():
        stdout = json.dumps({"reason": "note: file was modified recently"})
        r = HookExecutor.parse_command_output(stdout)
        assert r.outcome == HookOutcome.SUCCESS
        assert r.additional_context == "note: file was modified recently"

    @staticmethod
    def test_combined_modified_and_context():
        stdout = json.dumps({
            "modifiedInput": {"file_path": "/safe/path.txt"},
            "additionalContext": "path was redirected for safety",
        })
        r = HookExecutor.parse_command_output(stdout)
        assert r.outcome == HookOutcome.SUCCESS
        assert r.modified_input is not None
        assert r.additional_context == "path was redirected for safety"

    @staticmethod
    def test_decision_block_takes_precedence():
        """即使有 modifiedInput,decision: block 也优先."""
        stdout = json.dumps({
            "decision": "block",
            "reason": "dangerous",
            "modifiedInput": {"file_path": "/safe/path.txt"},
        })
        r = HookExecutor.parse_command_output(stdout)
        assert r.outcome == HookOutcome.BLOCKING


# ============================================================
# Prompt Hook: placeholder / template substitution
# ============================================================

class TestPromptHook:
    @staticmethod
    @pytest.mark.asyncio
    async def test_placeholder_returns_non_blocking_error_without_llm_config():
        """未配置 LLM 时 prompt hook 返回 non_blocking_error."""
        e = HookExecutor()
        results = await e.run_all(
            [{"type": "prompt", "prompt": "review: $ARGUMENTS"}],
            {"event": "PreToolUse", "tool_name": "Write"},
        )
        assert len(results) == 1
        # 没有 LLM 配置时,调用会失败 → non_blocking_error
        assert results[0].outcome in (HookOutcome.SUCCESS, HookOutcome.NON_BLOCKING_ERROR)

    @staticmethod
    @pytest.mark.asyncio
    async def test_empty_prompt_config():
        e = HookExecutor()
        results = await e.run_all(
            [{"type": "prompt", "prompt": ""}],
            {"event": "Test"},
        )
        assert results[0].outcome == HookOutcome.NON_BLOCKING_ERROR
        assert "empty prompt" in results[0].error.lower()


# ============================================================
# extract_json_from_response
# ============================================================

class TestExtractJsonFromResponse:
    @staticmethod
    def test_direct_json_object():
        text = '{"decision": "allow"}'
        result = HookExecutor.extract_json_from_response(text)
        assert result == {"decision": "allow"}

    @staticmethod
    def test_json_in_markdown_fence():
        text = '```json\n{"decision": "block", "reason": "bad"}\n```'
        result = HookExecutor.extract_json_from_response(text)
        assert result == {"decision": "block", "reason": "bad"}

    @staticmethod
    def test_json_in_plain_fence():
        text = '```\n{"key": "value"}\n```'
        result = HookExecutor.extract_json_from_response(text)
        assert result == {"key": "value"}

    @staticmethod
    def test_json_with_surrounding_text():
        text = 'Here is my review:\n{"decision": "allow"}\nThat is all.'
        result = HookExecutor.extract_json_from_response(text)
        assert result == {"decision": "allow"}

    @staticmethod
    def test_no_json():
        text = "just a plain response"
        result = HookExecutor.extract_json_from_response(text)
        assert result == {}

    @staticmethod
    def test_empty_string():
        result = HookExecutor.extract_json_from_response("")
        assert result == {}

    @staticmethod
    def test_nested_json():
        text = '{"decision": "allow", "details": {"score": 95}}'
        result = HookExecutor.extract_json_from_response(text)
        assert result == {"decision": "allow", "details": {"score": 95}}


# ============================================================
# End-to-end: full command hook flow
# ============================================================

class TestCommandHookE2E:
    """端到端 command hook 流程测试(子进程通过 mock 注入,避免依赖真实 shell)."""

    @staticmethod
    @pytest.mark.asyncio
    async def test_simple_logging_hook():
        """模拟最简单的日志 hook:echo 内容到 stdout."""
        e = HookExecutor()
        with patch(
            "jiuwenswarm.server.hooks.executor.asyncio.create_subprocess_exec",
            new_callable=AsyncMock,
            return_value=_fake_proc(stdout=b"log: tool=Read\n"),
        ):
            results = await e.run_all(
                [{"command": "echo log: tool=$TOOL_NAME", "timeout": 5}],
                {"event": "PreToolUse", "tool_name": "Read"},
            )
        assert results[0].outcome == HookOutcome.SUCCESS

    @staticmethod
    @pytest.mark.asyncio
    async def test_blocking_hook_via_json_stdout():
        """通过 stdout JSON decision: block 阻止执行."""
        e = HookExecutor()
        payload = b'{"decision":"block","reason":"not allowed"}\n'
        with patch(
            "jiuwenswarm.server.hooks.executor.asyncio.create_subprocess_exec",
            new_callable=AsyncMock,
            return_value=_fake_proc(stdout=payload),
        ):
            results = await e.run_all(
                [{
                    "command": 'echo \'{"decision":"block","reason":"not allowed"}\'',
                    "timeout": 5,
                }],
                {"event": "PreToolUse", "tool_name": "Bash"},
            )
        r = results[0]
        assert r.outcome == HookOutcome.BLOCKING
        assert "not allowed" in r.error

    @staticmethod
    @pytest.mark.asyncio
    async def test_blocking_hook_via_exit_2():
        """通过退出码 2 阻止执行(无 JSON stdout)."""
        e = HookExecutor()
        with patch(
            "jiuwenswarm.server.hooks.executor.asyncio.create_subprocess_exec",
            new_callable=AsyncMock,
            return_value=_fake_proc(returncode=2, stderr=b"blocked"),
        ):
            results = await e.run_all(
                [{"command": "echo blocked >&2; exit 2", "timeout": 5}],
                {"event": "PreToolUse", "tool_name": "Bash"},
            )
        r = results[0]
        assert r.outcome == HookOutcome.BLOCKING
        assert r.show_to_model is True

    @staticmethod
    @pytest.mark.asyncio
    async def test_modify_input_hook():
        """通过 stdout JSON modifiedInput 修改工具输入."""
        e = HookExecutor()
        payload = b'{"modifiedInput":{"file_path":"/safe/path.txt"}}\n'
        with patch(
            "jiuwenswarm.server.hooks.executor.asyncio.create_subprocess_exec",
            new_callable=AsyncMock,
            return_value=_fake_proc(stdout=payload),
        ):
            results = await e.run_all(
                [{
                    "command": 'echo \'{"modifiedInput":{"file_path":"/safe/path.txt"}}\'',
                    "timeout": 5,
                }],
                {"event": "PreToolUse", "tool_name": "Write"},
            )
        r = results[0]
        assert r.outcome == HookOutcome.SUCCESS
        assert r.modified_input == {"file_path": "/safe/path.txt"}

    @staticmethod
    @pytest.mark.asyncio
    async def test_additional_context_hook():
        """通过 stdout JSON additionalContext 注入上下文."""
        e = HookExecutor()
        payload = b'{"additionalContext":"file was last modified 2h ago"}\n'
        with patch(
            "jiuwenswarm.server.hooks.executor.asyncio.create_subprocess_exec",
            new_callable=AsyncMock,
            return_value=_fake_proc(stdout=payload),
        ):
            results = await e.run_all(
                [{
                    "command": 'echo \'{"additionalContext":"file was last modified 2h ago"}\'',
                    "timeout": 5,
                }],
                {"event": "PostToolUse", "tool_name": "Read"},
            )
        r = results[0]
        assert r.outcome == HookOutcome.SUCCESS
        assert "2h ago" in r.additional_context