测试编排器完整 API 参考

---

TestHarness

from ncatbot.testing import TestHarness

多平台测试编排器，在后台启动 BotClient（使用多个 MockAdapter），提供事件注入和 fluent 断言 API。

构造

TestHarness(platforms: Sequence[str] = ("qq",)) -> TestHarness

参数	类型	默认值	说明
platforms	Sequence[str]	("qq",)	要模拟的平台列表，每个平台创建独立的 MockAdapter

Properties

属性	类型	说明
bot	BotClient	Bot 客户端实例
mock_api	MockAPIBase	第一个平台的 Mock API（单平台快捷访问）
dispatcher	AsyncEventDispatcher	事件分发器

平台访问方法

方法	签名	说明
mock_api_for	mock_api_for(platform: str) -> MockAPIBase	获取指定平台的 Mock API
adapter_for	adapter_for(platform: str) -> MockAdapter	获取指定平台的 MockAdapter

生命周期方法

方法	签名	说明
start	async start() -> None	启动 BotClient（非阻塞）
stop	async stop() -> None	停止 BotClient
__aenter__	async __aenter__() -> TestHarness	async with 入口
__aexit__	async __aexit__(...) -> None	async with 出口

事件注入方法

方法	签名	说明
inject	async inject(event_data: BaseEventData) -> None	注入事件（按 event_data.platform 自动路由）
inject_many	async inject_many(events: List[BaseEventData]) -> None	依次注入多个事件
settle	async settle(delay: float = 0.05) -> None	等待 handler 执行
wait_event	async wait_event(predicate=None, timeout=2.0) -> Event	等待特定事件

Fluent 断言方法

方法	签名	说明
assert_api	assert_api(action: str) -> APICallAssertion	全平台范围 fluent 断言
on	on(platform: str) -> PlatformScope	限定平台后再断言
reset_api	reset_api(platform: str = None) -> None	清空调用记录（指定平台或全部）

使用示例

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

async with TestHarness() as h:
    await h.inject(group_message("hello"))
    await h.settle()

    # fluent 断言
    h.assert_api("send_group_msg").called().with_text("hello")

    # 参数匹配
    h.assert_api("send_group_msg").with_params(group_id="100200")

    # 取值
    call = h.assert_api("send_group_msg").last
    print(call.action, call.params)

多平台示例

from ncatbot.testing import TestHarness
from ncatbot.testing.factories import qq, github

async with TestHarness(platforms=["qq", "github"]) as h:
    await h.inject(github.issue_opened("Bug report", repo="owner/repo"))
    await h.settle()

    # 平台作用域断言
    h.on("qq").assert_api("send_group_msg").called()
    h.on("github").assert_api("create_issue_comment").not_called()

---

PluginTestHarness

from ncatbot.testing import PluginTestHarness

继承 TestHarness，增加插件选择性加载和查询能力。

构造

PluginTestHarness(
    plugin_names: List[str],       # 要加载的插件名列表
    plugins_dir: Path,              # 插件根目录
    *,
    platforms: Sequence[str] = ("qq",),  # 平台列表
    skip_builtin: bool = True,     # 是否跳过内置插件
    skip_pip: bool = True,         # 是否跳过 pip 依赖安装
) -> PluginTestHarness

参数	类型	默认值	说明
plugin_names	List[str]	必填	要加载的插件名（manifest.toml 中的 name）
plugins_dir	Path	必填	包含插件文件夹的父目录
platforms	Sequence[str]	("qq",)	平台列表
skip_builtin	bool	True	跳过内置插件加载
skip_pip	bool	True	跳过 pip 依赖安装

额外 Properties

属性	类型	说明
loaded_plugins	List[str]	已加载的插件名列表

继承自 TestHarness 的所有 properties 和方法同样可用。

插件操作方法

方法	签名	说明
get_plugin	get_plugin(name: str) -> Optional[BasePlugin]	获取插件实例
plugin_config	plugin_config(name: str) -> dict	获取插件配置
plugin_data	plugin_data(name: str) -> dict	获取插件数据
reload_plugin	async reload_plugin(name: str) -> bool	热重载插件

plugin_config 和 plugin_data 在插件未加载时抛出 KeyError。

start 流程

PluginTestHarness.start() 执行以下步骤：

1. 启动核心基础设施（adapter / API / dispatcher / services）
2. 配置 PluginLoader 依赖注入
3. 如果 skip_builtin=False，加载内置插件
4. 通过 loader.load_selected() 加载指定插件及其传递依赖
5. 启动后台监听任务

使用示例

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

async with PluginTestHarness(
    plugin_names=["hello_world"],
    plugins_dir=Path("examples/common/01_hello_world"),
) as h:
    assert "hello_world" in h.loaded_plugins

    await h.inject(group_message("hello", group_id="100", user_id="99"))
    await h.settle()

    h.assert_api("send_group_msg").called()
    h.assert_api("send_group_msg").with_params(group_id="100")

    plugin = h.get_plugin("hello_world")
    config = h.plugin_config("hello_world")

---

相关文档

文档	说明
Factory + Scenario + Mock	事件工厂、场景构建器、Mock API、Fluent 断言
测试指南	教程风格入门
Harness 使用详解	实践指南

版权所有

版权归属：MI

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