Menu
设计 NcatBot 测试策略：测试分层决策、规范驱动原则、不测什么、分配规范编号、维护测试索引。Use when: 写什么测试、要不要测、测试设计、测试分层、规范编号、spec-id、测试索引、测试策略、应该加什么测试、不测什么、什么值得测。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
定位 NcatBot 代码实现：锁定模块目录、找到关键类/函数、追踪调用链。当文档不够时才读代码，用搜索而非遍历。Use when: 找代码实现、哪个文件、哪个类、追踪调用链、定位 bug 行号、代码在哪、模块目录、源码定位。
通过文档理解 NcatBot 项目：查阅功能说明、API 签名、架构设计、预期行为。文档优先，按优先级分层查阅。Use when: 理解功能、查 API、架构理解、预期行为、怎么用、设计决策、模块职责、文档在哪。
维护 NcatBot 项目文档、示例、Skills 知识资产。编写/编辑文档、修复文档问题、文档结构规范审查。Use when: 写文档、改文档、新增文档、修复断链、修复索引、修复代码块标注、文档规范、文档模板、文档结构设计、docs maintenance。
整体/局部防腐检查：Docs 内部链接断裂、README 索引不同步、guide↔reference 内容不一致、examples 导入过时、Code↔Docs API 对齐。逐文件检查，最大化并发 subagent。Use when: docs 防腐、docs 链接、docs 断链、断链检查、docs 审计、docs audit、code docs 对齐、reference 过时、guide reference 不同步、examples 检查、定期检查。
开发与维护 NcatBot 框架本体。调试 bug、开发新功能、维护 Skill、代码审查、重构。Use when: 框架调试、debug、fix bug、feat、新功能、Skill 维护、代码贡献、模块修改、代码审查、重构。
使用 NcatBot 框架开发 QQ 机器人或跨平台 Bot。当用户需要快速体验、创建插件、注册事件处理、发送消息、调用 Bot API、使用 Mixin/Hook、使用 CLI 工具、编写插件测试、或调试运行问题时触发此技能。Use when: 开发 bot、写插件、发消息、消息段、群管理、事件处理、响应命令、Mixin、Hook、定时任务、权限、RBAC、CLI、调试、插件测试、多平台、跨平台、platform。
| name | testing-design |
| description | 设计 NcatBot 测试策略：测试分层决策、规范驱动原则、不测什么、分配规范编号、维护测试索引。Use when: 写什么测试、要不要测、测试设计、测试分层、规范编号、spec-id、测试索引、测试策略、应该加什么测试、不测什么、什么值得测。 |
决定写什么测试、测试层级选择，以及如何维护规范编号和测试索引。
工具使用（TestHarness / PluginTestHarness / Scenario / 运行命令）→ testing-framework 技能
框架行为优先通过以下方式验证：
tests/integration/）：多模块协作链路tests/e2e/）：基于 TestHarness / PluginTestHarness 的完整生命周期单元测试仅在有明确隔离价值时使用：
| ✅ 值得写单元测试 | ❌ 应用集成/E2E 测试替代 |
|---|---|
| 纯解析算法（段解析、CQ 码、配置迁移） | 事件处理全链路 |
| 无副作用的数据模型转换 | handler 注册与触发 |
| 独立工具函数边界值 | 插件加载与生命周期 |
| 错误层级/异常分类 | 多模块状态交互 |
每个测试用例必须对应一条规范条目，并在 docstring 第一行写明规范编号：
async def test_registrar_on_collects_handler(fresh_registrar):
"""R-10: Registrar.on() 将 handler 收集到全局 _pending_handlers"""
...
测试是规范的可执行版本，不是代码的镜像。规范不存在的行为不要写测试。
以下场景不需要测试：
| 反模式 | 原因 |
|---|---|
assert obj is not None（仅验证加载成功） | 无行为验证，意义不大 |
assert hasattr(module, "Symbol") | 导入检查不是行为测试 |
obj.field = x; assert obj.field == x | 平凡 setter，不验证副作用 |
| 重测框架/库已保证的行为（如 pydantic 字段验证） | 外部依赖不需重测 |
例外：若"加载成功"本身是规范的一部分（如 PL-01 插件加载），相关断言是有意义的。
新增测试时，三处必须同时更新：
R-10）tests/README.md 中对应前缀的范围（R-01 ~ R-09 → R-01 ~ R-10）tests/unit/<module>/README.md 或 tests/integration/README.md 等）规范编号权威来源：
tests/README.md
# ✅ 异步 fixture 要 yield + teardown
@pytest_asyncio.fixture
async def event_dispatcher():
d = AsyncEventDispatcher()
yield d
await d.close() # 必须清理
# ✅ 全局状态在每次测试前/后清理
@pytest.fixture(autouse=True)
def clean_pending():
_pending_handlers.clear()
yield
_pending_handlers.clear()
所有含异步测试的文件顶部声明：
pytestmark = pytest.mark.asyncio(mode="strict")
目标是什么？
├─ 纯算法/解析器/数据模型 ──────────────────→ 单元测试 tests/unit/<module>/
├─ 多模块协作链路（dispatcher → handler）──→ 集成测试 tests/integration/
├─ BotClient 完整生命周期 ───────────────────→ E2E tests/e2e/test_bot_client.py
├─ 插件加载/命令/生命周期 ───────────────────→ 插件 E2E tests/e2e/plugin/
└─ 真实 WebSocket 连接（QQ 在线）────────────→ NapCat E2E tests/e2e/napcat/（非 pytest）
打开 tests/README.md，找到对应模块的前缀及当前最大序号。
若对应模块没有前缀，选一个不冲突的 2~3 字母缩写，补入 tests/README.md 的编号表。
在该前缀最大序号上 +1。例如已有 D-01 ~ D-09，新增用 D-10。
docstring 第一行必须包含规范编号：
async def test_dispatcher_routes_group_message(event_dispatcher):
"""D-10: AsyncEventDispatcher 正确路由群消息到 message.group 订阅者"""
...
更新对应行的范围，例如：
-| D | AsyncEventDispatcher | D-01 ~ D-09 |
+| D | AsyncEventDispatcher | D-01 ~ D-10 |
在对应测试目录的 README.md 中补充测试条目，格式参照现有条目。
完整前缀列表及已分配序号见：tests/README.md
tests/README.md 包含所有已注册前缀（T / S / CQ / D / H / K / R / I / B / PL / SC / PR / TS / LD 等 30+ 个）及当前最大序号，是分配新编号的唯一权威来源，不在 Skill 文件中单独维护副本。