메뉴
设计 NcatBot 测试策略：测试分层决策、规范驱动原则、不测什么、分配规范编号、维护测试索引。Use when: 写什么测试、要不要测、测试设计、测试分层、规范编号、spec-id、测试索引、测试策略、应该加什么测试、不测什么、什么值得测。
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
定位 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 文件中单独维护副本。