# Asco Test Doc > 为 ASCO 模块编写单元测试与中文文档。用于新增模块、补齐测试覆盖、补写 API/模块说明、整理行为语义说明。重点产出 tests 下的用例与 docs/zh-cn/src 下的专业文档，文档只描述语义、约束和可观察行为，不描述实现细节。 Use when this capability is needed. - Skill: `tomevault-io/asco-test-doc` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/asco-test-doc` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/asco-test-doc/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/asco-test-doc --- # 为模块编写测试和文档 ## 何时使用 - 为新模块或新接口补充单元测试。 - 为已有模块补齐中文文档。 - 重构或扩展行为后，需要同步更新测试与文档。 - 需要把“语义与行为”整理成专业、简洁的 API 说明，而不是实现解读。 ## 目标产出 - 至少一个针对目标模块的测试源文件，或对现有测试文件的增量补充。 - 如有新增测试文件，更新 `tests/CMakeLists.txt` 以纳入统一 `tests` 目标。 - 一份或多份中文文档页面，放在 `docs/zh-cn/src/` 下的合适位置；默认不产出英文文档。 - 如有新增页面，更新 `docs/zh-cn/src/SUMMARY.md` 与对应章节 `README.md` 的导航入口。 ## 输入信息 开始前先确认这些信息；若缺失，先向用户追问： - 目标模块或头文件路径。 - 需要覆盖的公开类型、函数、错误条件或并发语义。 - 这次是“新增测试和文档”，还是“只补测试”或“只补文档”。 - 文档是新增页面还是修改现有页面。 ## 工作流程 ### 1. 建立语义边界 先阅读目标模块及其相邻测试、文档，整理以下内容： - 模块暴露了哪些公开接口。 - 每个接口的成功路径、失败路径和边界条件。 - 是否存在异步、取消、阻塞、并发访问、panic 或 guard 生命周期等特殊语义。 - 哪些行为对调用方可观察，哪些只是内部实现细节。 如果无法只凭现有代码判断公开语义，暂停并向用户确认，不要擅自把内部实现推断写进文档。 ### 2. 设计测试矩阵 围绕“可观察行为”列出测试点，优先覆盖： - 基本成功路径。 - 边界输入与空值路径。 - 失败返回、异常或 panic 路径。 - 状态转换与资源释放。 - 并发或异步模块的时序约束、取消、互斥和唤醒行为。 测试命名应直接对应行为，不要用含糊名称。 ### 3. 实现或补充测试 遵循当前仓库的测试习惯： - 使用 `ASCO_TEST(...)` 定义用例。 - 使用 `ASCO_CHECK(...)` 断言，并让错误信息直接说明预期与实际。 - 异步条件优先使用有界等待或 `yield` 轮询，不依赖无边界阻塞。 - 后台任务、定时器或可取消任务在失败路径需要清理。 - 不共享未同步的全局可变状态。 决策规则： - 如果目标行为已有对应测试文件，优先在原文件中补充，保持主题集中。 - 如果目标模块尚无合适测试文件，创建新的测试源文件，并同步更新 `tests/CMakeLists.txt`。 - 如果行为依赖 runtime、时间或调度，测试应显式约束等待边界，避免挂死。 ### 4. 编写或更新文档 文档只描述语义、约束和行为，不描述实现过程、内部数据结构或优化策略。 写作要求： - 语言专业、简洁、直接。 - 先给出模块职责，再按接口或能力分节。 - 对每个接口说明调用条件、返回语义、失败语义和重要约束。 - 示例代码默认可选；只有在接口用法不直观、容易误用或缺少示例会明显影响理解时才补充最小示例。 - 若存在易误用点，写“语义约束”或“使用建议”，不要写成实现备注。 避免写入以下内容： - 内部锁策略、具体调度算法、容器布局等实现细节。 - “源码中如何做到”的过程性解释。 - 没有稳定语义承诺的推测性描述。 ### 5. 维护文档导航 新增文档页面时检查： - `docs/zh-cn/src/SUMMARY.md` 是否已加入入口。 - 所属章节的 `README.md` 是否需要补充链接。 若本次只更新已有页面，不要无意义调整其他导航结构。 ### 6. 结束前自检 提交前逐项检查： - 测试是否覆盖了主要成功路径、失败路径和边界条件。 - 文档是否只描述语义与行为，没有落入实现细节。 - 新增测试文件是否已加入 `tests/CMakeLists.txt`。 - 新增文档页面是否已加入中文文档导航。 - 名称、术语和返回语义是否与现有代码一致。 ## 完成标准 满足以下条件才算完成： - 测试与文档都与目标模块的公开行为一致。 - 测试失败信息可直接定位行为不符点。 - 文档读者无需阅读实现即可理解如何使用该模块，以及会观察到什么行为。 - 文档没有把内部实现细节误写成 API 语义。 如果用户没有说明，不应将以下内容作为完成标准： - 格式化代码。 - 运行测试。 ## 常见分支 ### 只有接口声明，没有稳定实现 - 可以先写文档骨架和行为预期。 - 测试仅写已经确定的公开契约；未定部分先向用户确认。 ### 只有实现，没有测试和文档 - 先从公开入口逆推出可观察行为。 - 先补测试，再整理文档，避免文档描述与实际行为脱节。 ### 行为涉及并发与取消 - 优先验证最终可观察结果与边界时序。 - 谨慎处理跨挂起点对象生命周期，不要把引用参数直接带入协程边界行为说明。 ## 推荐提示词 - 为 `asco/sync/mutex.h` 补齐测试和中文文档，只描述语义和行为，不解释实现。 - 为某个新同步原语新增测试文件和文档页面，并更新当前仓库需要的导航与构建入口。 - 审查一个模块现有测试和文档，指出缺失的行为覆盖与文档语义漏洞。 --- > Source: [pointertobios/asco](https://github.com/pointertobios/asco) — distributed by [TomeVault](https://tomevault.io).