TestHarness + PluginTestHarness
约 886 字大约 3 分钟
2026-03-19
测试编排器完整 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() 执行以下步骤:
- 启动核心基础设施(adapter / API / dispatcher / services)
- 配置 PluginLoader 依赖注入
- 如果
skip_builtin=False,加载内置插件 - 通过
loader.load_selected()加载指定插件及其传递依赖 - 启动后台监听任务
使用示例
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
