agent-plugins示例目录教程：valid/invalid测试夹具实战演练
【免费下载链接】agent-plugins项目地址: https://gitcode.com/GitHub_Trending/skills16/agent-plugins
agent-plugins是官方维护的 Flutter/Dart 智能体技能插件集合，其配套的 Skills CLI 工具位于 tool/generator/，用于从文档自动生成SKILL.md。本教程带你走进它的测试目录，实战演练valid/invalid 测试夹具——看看官方如何在测试中构造"合法配置"与"非法配置"两种场景，用测试夹具精准验证技能校验器的每一条规则，是学习 Dart 测试设计模式的绝佳范例。
一、先搞清楚：测试夹具是什么？
🔍 测试夹具（Test Fixture）就是测试用的"样例数据"。写校验类代码时，最稳妥的办法是准备两套数据：
| 夹具类型 | 作用 | 期望结果 |
|---|---|---|
| ✅valid（合法） | 完全符合规则的配置 | 校验通过，不报错 |
| ❌invalid（非法） | 违反某一规则的故意错误配置 | 校验失败，且报出对应错误 |
💡冷知识：打开本项目你会发现，它并没有单独的
fixtures/valid、fixtures/invalid静态目录，而是把夹具直接写在测试代码里、运行到临时目录中。这种方式零文件污染、隔离性更好，非常值得借鉴。
二、认识主角：技能校验命令
被测试的"目标"是validate-skill命令，源码在 validate_skill_command.dart。它会检查 YAML 配置文件是否满足这些规则：
- 根节点必须是 YAML 列表，且列表非空
- 每一项必须是 Map，且包含
name、description、resources三个必填字段 - 技能名必须是 kabob-case（如
abc-def） flutter_skills.yaml中的技能名必须以flutter-开头resources列表不能为空，且 URL 必须使用 HTTPS- 各字段类型必须正确（
name、description必须是字符串）
配套的真实配置文件 resources/flutter_skills.yaml 本身就是一个最大的 valid 夹具——它必须通过全部校验，否则工具链就跑不起来。
三、valid 夹具实战：一条"完美配置"的诞生
打开 validate_skills_input_test.dart，第一个用例就是"合法场景"：
'name': 'flutter-test-skill' // kabob-case ✔ 前缀 ✔ 'description': 'A Flutter test skill' // 非空字符串 ✔ 'resources': ['https://example.com/doc'] // 非空列表、HTTPS ✔测试断言非常"反向思维"：它不检查"输出成功"，而是断言日志中不包含Configuration validation failed.。这正是 valid 夹具的精髓——用"无错误"来证明"全合法"。
对比手法在 validate_skills_test.dart 里更完整：测试先搭好临时目录（tempDir+skills/+validation/），写入一份合法配置和一份SKILL.md，再运行命令，断言日志出现Validating skill: test-skill...。
⚙️关键技巧：MockClient。测试用MockClient替代真实 HTTP 客户端，让https://example.com等假地址可以"有内容返回"，从而完全离线复现网络抓取流程。
四、invalid 夹具实战：八种"故意写错"的配置
validate_skills_input_test.dart 是本次演练的核心，它像清单一样逐条构造非法夹具：
| # | invalid 夹具构造 | 触发的错误信息 |
|---|---|---|
| 1 | 根节点写成 Map 而非列表 | Root must be a YAML list. |
| 2 | 列表为空[] | Configuration list must not be empty. |
| 3 | 列表项是普通字符串 | Item 0 is not a Map. |
| 4 | 缺少description、resources | is missing required field ... |
| 5 | 技能名用下划线（flutter_skill_invalid） | must be kabob-case (e.g. abc-def). |
| 6 | dart-前缀写进flutter_skills.yaml | must start with "flutter-". |
| 7 | resources为空列表 | field "resources" must not be empty. |
| 8 | URL 使用http:// | must use secure HTTPS. |
每个用例都遵循同一个节奏，改一个字段 → 断言一条错误，让"一条规则 = 一个测试"的映射关系一目了然。
再往前看，validate_skill_command.dart 的"配置文件不存在"分支，则由 validate_skills_test.dart 中传一个不存在的NON_EXISTENT.yaml路径来覆盖——invalid 夹具不只有"内容错"，还有"文件缺失"这一类。
五、进阶演练：用 MockClient 制造"运行时异常"夹具
内容合法不代表流程顺利。validate_skills_test.dart 展示了更高级的夹具设计：用 MockClient 抛异常来模拟网络故障。
- 模拟抓取失败：
throw Exception('Network Error')，断言日志出现Error validating ... - 模拟评分接口崩溃：抓取地址正常返回，但 Gemini 接口抛错，断言出现
Failed to generate validation report - 模拟"干跑"模式：
--dry-run时断言不调用Gemini、不写验证报告文件
🧩 这类夹具的通用套路：happy path 用"返回正常数据"的 Mock，异常路径用"抛错"的 Mock。两者合起来，测试才算覆盖了完整的运行时行为。
六、动手跑起来：验证你的理解
在仓库根目录安装依赖后，进入工具目录即可运行全部测试：
cd tool/generator dart test如果你希望亲手加一条 invalid 用例，只需照抄现有模板：在setUp的临时目录里写入新的错误配置，调用runValidation，再用expect(logs, contains('...'))断言目标错误信息即可——这正是"夹具驱动开发"的魅力：规则、数据、断言三位一体。
📌 延伸阅读：
- 校验规则实现：validate_skill_command.dart
- 输入校验测试：validate_skills_input_test.dart
- 端到端验证测试：validate_skills_test.dart
- 真实合法配置夹具：flutter_skills.yaml
- 技能 lint 规则：skills_lint.yaml
七、小结：从 agent-plugins 学到的 3 个夹具设计要点
- valid 夹具断言"无错"：合法场景靠"不包含失败信息"来证明，避免假阳性
- invalid 夹具一错一测：每种违规独立成用例，错误信息与规则一一对应
- Mock 即夹具：
MockClient让网络边界可离线、可异常化，覆盖真实运行时才会暴露的分支
掌握这套 valid/invalid 演练思路后，无论写配置解析器还是 AI 工作流工具，你都能快速搭起高覆盖率的测试骨架。
【免费下载链接】agent-plugins项目地址: https://gitcode.com/GitHub_Trending/skills16/agent-plugins
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
、u(n)与周期判定)
