NcatBot 文档

外观

事件工厂与场景构建器

约 1203 字大约 4 分钟

2026-03-19

构造测试事件和声明式场景测试

目录

  1. 事件工厂
  2. Scenario 构建器
  3. 组合场景示例
  4. 自动冒烟测试
  5. NapCat E2E 简介

1. 事件工厂

ncatbot.testing.factories 按平台组织工厂函数，覆盖消息、请求、通知等各类事件。

QQ 事件工厂

from ncatbot.testing.factories.qq import group_message, private_message
from ncatbot.testing.factories.qq import friend_request, group_request
from ncatbot.testing.factories.qq import group_increase, group_decrease, group_ban, poke

消息事件

# 群消息
event = group_message("hello")
event = group_message("hello", group_id="888", user_id="777", nickname="小明")

# 私聊消息
event = private_message("hi")
event = private_message("hi", user_id="777")

请求事件

# 好友请求
event = friend_request(user_id="777", comment="我是小明")

# 加群请求
event = group_request(user_id="777", group_id="888", sub_type="add")

通知事件

# 群成员增加
event = group_increase(user_id="777", group_id="888")

# 群成员减少（被踢）
event = group_decrease(user_id="777", group_id="888", sub_type="kick")

# 群禁言（10 分钟）
event = group_ban(user_id="777", group_id="888", duration=600)

# 戳一戳
event = poke(user_id="777", target_id="10001", group_id="888")

Bilibili 事件工厂

from ncatbot.testing.factories.bilibili import danmu, super_chat, gift
from ncatbot.testing.factories.bilibili import private_message, comment, dynamic
event = danmu("弹幕内容", room_id="12345")
event = super_chat("SC 内容", price=50, room_id="12345")
event = gift("辣条", num=10, room_id="12345")

GitHub 事件工厂

from ncatbot.testing.factories.github import issue_opened, pr_opened, push
from ncatbot.testing.factories.github import issue_closed, issue_comment, star, release_published
event = issue_opened("Bug report", repo="owner/repo", issue_number=42)
event = pr_opened("Fix bug", repo="owner/repo", pr_number=1)
event = push(ref="refs/heads/main", repo="owner/repo")

默认值一览

平台参数默认值
QQgroup_id"100200"
QQuser_id"99999"
QQself_id"10001"
Bilibiliroom_id"12345"
Bilibiliuser_id"88888"
GitHubrepo"owner/repo"
GitHublogin"test-user"

自定义消息结构

默认情况下，group_message("hello") 会生成纯文本消息段。如果需要自定义消息结构：

# 自定义 message 段（at + 文本）
event = group_message(
    "hello",
    message=[
        {"type": "at", "data": {"qq": "10001"}},
        {"type": "text", "data": {"text": " hello"}},
    ],
    raw_message="[CQ:at,qq=10001] hello",
)

**extra 扩展

所有工厂函数支持 **extra 传入额外字段：

event = group_message("hello", custom_field="value")

2. Scenario 构建器

Scenario 提供声明式链式 API，将「注入 → 等待 → 断言」流程写为可读的测试场景。

基础用法

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

await (
    Scenario("群消息回复")
    .inject(group_message("hello"))
    .settle()
    .assert_api_called("send_group_msg")
    .run(harness)
)

方法链一览

方法说明
.on(platform)切换后续断言的平台作用域
.inject(event)注入一个事件
.inject_many(events)注入多个事件
.settle(delay=0.05)等待 handler 处理
.assert_api_called(action, **match)断言 API 被调用，可选 params 匹配
.assert_api_not_called(action)断言 API 未被调用
.assert_api_count(action, count)断言调用次数
.assert_api_params(action, **params)断言 params 子集匹配
.assert_api_text(action, *fragments)断言文本内容（跨平台感知）
.assert_api_where(action, predicate, desc)自定义条件断言
.assert_that(predicate, desc)自定义断言（接收 harness）
.reset_api()清空调用记录
.run(harness)执行场景（async）

参数与文本断言

# 参数匹配
.assert_api_params("send_group_msg", group_id="888")

# 文本匹配
.assert_api_text("send_group_msg", "hello", "world")

# 自定义条件
.assert_api_where("send_group_msg", lambda call: call.params["group_id"] == "888")

平台作用域

await (
    Scenario("跨平台")
    .inject(github.issue_opened("Bug"))
    .settle()
    .on("qq").assert_api_called("send_group_msg")
    .on("github").assert_api_not_called("create_issue_comment")
    .run(harness)
)

自定义断言

from ncatbot.testing import extract_text

def check_message_content(h):
    call = h.assert_api("send_group_msg").last
    text = extract_text(call)
    assert "hello" in text

await (
    Scenario("检查消息内容")
    .inject(group_message("hello"))
    .settle()
    .assert_that(check_message_content, "回复中包含 hello")
    .run(harness)
)

3. 组合场景示例

多步对话

from ncatbot.testing.factories.qq import group_message

await (
    Scenario("注册流程")
    .inject(group_message("注册", group_id="100", user_id="99"))
    .settle(0.1)
    .assert_api_called("send_group_msg")
    .assert_api_text("send_group_msg", "请输入")
    .reset_api()
    .inject(group_message("张三", group_id="100", user_id="99"))
    .settle(0.1)
    .assert_api_called("send_group_msg")
    .assert_api_params("send_group_msg", group_id="100")
    .run(harness)
)

权限拦截

await (
    Scenario("非管理员被拦截")
    .inject(group_message("/ban 777", group_id="100", user_id="99"))
    .settle()
    .assert_api_not_called("set_group_ban")
    .run(harness)
)

批量事件

from ncatbot.testing.factories.qq import group_message, private_message

await (
    Scenario("多类型事件")
    .inject_many([
        group_message("a"),
        private_message("b"),
        group_message("c"),
    ])
    .settle(0.1)
    .assert_api_count("send_group_msg", 2)
    .assert_api_count("send_private_msg", 1)
    .run(harness)
)

4. 自动冒烟测试

ncatbot.testing 提供插件自动发现和冒烟测试代码生成。

discover_testable_plugins

from ncatbot.testing import discover_testable_plugins

manifests = discover_testable_plugins(Path("examples/"))
for m in manifests:
    print(m.name, m.version)

扫描目录下所有包含 manifest.toml 的子文件夹，返回 PluginManifest 列表。

generate_smoke_tests

from ncatbot.testing import generate_smoke_tests

code = generate_smoke_tests(manifests)
Path("tests/test_smoke.py").write_text(code)

生成的冒烟测试为每个插件验证：

  • 加载成功
  • 卸载成功
  • 收到基础群消息不崩溃

pytest 插件集成

在 conftest.py 中注册 pytest 插件，可使用 --plugin-dir 和 @pytest.mark.plugin：

# conftest.py
from ncatbot.testing import *  # noqa
python -m pytest --plugin-dir=examples/ -v

5. NapCat E2E 简介

除了 Mock 环境下的离线测试，NcatBot 还支持连接真实 NapCat 的端到端测试。

E2E 测试位于 tests/e2e/napcat/run.py，需要：

  • 运行中的 NapCat 实例
  • 配置环境变量：NAPCAT_TEST_GROUP、NAPCAT_TEST_USER
$env:NAPCAT_TEST_GROUP="123456"
$env:NAPCAT_TEST_USER="654321"
python tests/e2e/napcat/run.py

NapCat E2E 测试主要用于框架开发者验证真实协议兼容性，插件开发者通常使用 Mock 测试即可。

相关资源

资源链接
Harness 详解2. 测试工具
测试 API 参考reference/9. 测试框架/
Factory + Mock 完整签名reference/9. 测试框架/2. 工厂场景与 Mock

版权归属：MI

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

© 2025-2026 NcatBot