Mock 适配器使用指南 — 用于插件集成测试的内存适配器，无需网络连接。

---

Quick Reference

属性	值
适配器名称	mock
平台标识	mock（可自定义）
协议	内存模拟
类	MockAdapter
导入	from ncatbot.adapter import MockAdapter

---

概述

Mock 适配器不连接任何外部服务，完全在内存中运行。它的主要用途是：

• 插件集成测试：注入模拟事件，验证插件行为
• API 调用验证：记录所有 API 调用，断言调用参数和次数
• 无网络开发：不需要运行 NapCat 或其他外部服务

---

基本用法

from ncatbot.app import BotClient
from ncatbot.adapter import MockAdapter

adapter = MockAdapter(platform="qq")
bot = BotClient(adapters=[adapter])

# 启动后注入事件
await adapter.inject_event(some_event_data)

# 检查 API 调用
assert adapter.mock_api.called("send_group_msg")

# 停止
adapter.stop()

自定义平台标识

Mock 适配器的 platform 可以自定义，模拟不同平台的事件。MockAdapter 会根据平台自动选择对应的 Mock API 实现：

adapter = MockAdapter(platform="qq")        # → MockBotAPI (IQQAPIClient)
adapter = MockAdapter(platform="bilibili")  # → MockBiliAPI (IBiliAPIClient)
adapter = MockAdapter(platform="github")    # → MockGitHubAPI (IGitHubAPIClient)

---

MockAPIBase 继承体系

所有 Mock API 共享基类 MockAPIBase，提供统一的调用录制和查询基础设施：

MockAPIBase (IAPIClient)
├── MockBotAPI    (IQQAPIClient)     — QQ 平台
├── MockBiliAPI   (IBiliAPIClient)   — Bilibili 平台
└── MockGitHubAPI (IGitHubAPIClient) — GitHub 平台

每个子类的 API 方法以 self._record("action", key=val, ...) 形式录制调用，所有参数以关键字形式存储到 APICall.params: Dict[str, Any]。

调用记录方法（MockAPIBase 提供）

方法	签名	说明
called	(action) → bool	检查 action 是否被调用过
call_count	(action) → int	获取调用次数
get_calls	(action) → List[APICall]	获取指定 action 的所有调用记录
last_call	(action=None) → Optional[APICall]	获取最后一次调用
calls	@property → List[APICall]	所有调用记录
set_response	(action, response) → None	为指定 action 预设返回值
reset	() → None	清除所有记录和预设

APICall 数据类

from ncatbot.adapter.mock.api_base import APICall

@dataclass
class APICall:
    action: str                # API 方法名
    params: Dict[str, Any]     # 所有参数按名存储

示例

# 预设 API 返回值
adapter.mock_api.set_response("send_group_msg", {"message_id": 12345})

# 触发插件逻辑（注入事件）
await adapter.inject_event(event_data)

# 验证 API 被调用
assert adapter.mock_api.called("send_group_msg")
assert adapter.mock_api.call_count("send_group_msg") == 1

# 检查调用参数
call = adapter.mock_api.last_call("send_group_msg")
assert call.params["group_id"] == "123456"

---

与 TestHarness 的关系

TestHarness 和 PluginTestHarness 内部使用 MockAdapter。如果你使用测试框架，通常不需要直接操作 MockAdapter：

from ncatbot.testing import PluginTestHarness
from ncatbot.testing.factories.qq import group_message

async with PluginTestHarness(
    plugin_names=["hello_world"],
    plugins_dir=Path("plugins/"),
) as h:
    await h.inject(group_message("hello"))
    await h.settle()
    h.assert_api("send_group_msg").called()

直接使用 MockAdapter 适合需要更底层控制的测试场景。

---

延伸阅读

• 插件测试指南 → 测试指南
• 适配器接口参考（含 MockAdapter API）→ 适配器参考
• TestHarness 详解 → 测试工具

版权所有

版权归属：MI

许可证：署名 4.0 国际 (CC-BY-4.0)