MaaEnd节点测试教程：如何用测试用例验证识别稳定命中
【免费下载链接】MaaEndMaaEnd 终末地小助手：基于视觉 AI 的「明日方舟：终末地」自动化工具项目地址: https://gitcode.com/gh_mirrors/maa/MaaEnd
MaaEnd 是基于视觉 AI 的《明日方舟：终末地》自动化工具。本文讲解 MaaEnd 的节点测试玩法：用一张张静态截图 + 一份 JSON 测试用例，快速验证识别节点"该命中的命中、不该命中的不命中"，把靠感觉能跑的流程变成可回归、可维护的稳定识别。
一、节点测试是什么？什么时候用
MaaEnd 的自动化流程由一个个识别节点串成。某个按钮模板改动了、某个 ROI 调过了、某个新场景上线了，都会影响识别稳定性。节点测试就是给这些节点做"体检"：
- ✅ 适合验证：识别节点、通用节点、场景判断节点是否稳定命中
- ✅ 适合补回归：改完模板 / ROI / 阈值后，确认没有误伤旧场景
- ❌ 不适合：验证完整流程时序（流程正确性要结合开发工具和实机调试）
官方开发手册详见 node-testing.md，这是编写测试用例前最值得先读的一份资料。
二、3 分钟看懂目录结构
测试用例和截图都放在tests/下，约定如下：
| 内容 | 位置 |
|---|---|
| 测试用例（JSON） | tests/下任意子目录，文件名必须匹配test_*.json |
| 测试截图 | tests/MaaEndTestset/<控制器>/<资源服>/下 |
几个关键约定：
image字段要写完整截图文件名，并显式包含扩展名，例如帝江号_大世界.png；- 截图分辨率统一 1280×720，模板和坐标都以 720p 为基准，运行时自动缩放；
- 用 VS Code 的 Maa Pipeline Support 插件（
Ctrl+Shift+P→Maa: Screenshot）截图，放到对应目录即可。
以现有用例 test_region.json 为例，它针对"地区识别"准备了一组正例：大世界主页应命中InWorld，四号谷地地区建设应命中InRegionalDevelopmentValleyIV，武陵则命中InRegionalDevelopmentWuling。一个测试文件只测一类能力，失败时也好定位原因。
三、测试用例怎么写：hits 是灵魂
每个用例文件都受 test.schema.json 约束，顶层只有两个部分：
configs：这组测试跑在哪个控制器（Win32/ADB）和哪个资源服（官服）上；cases：一张截图对应一个用例，每个用例必须有image和hits。
hits表示这张图"期望命中的节点列表"，支持三种写法：
- 只写节点名——只关心有没有命中，最常用；
- 节点名 + box——同时校验识别框位置，格式为
[x, y, 宽, 高]，适合全屏搜索、同屏多个相似目标的节点； - box 写成矩阵——不同控制器坐标有差异时，可以为
Win32和ADB各写一份坐标，还能用default做兜底。
另外别忘了负例：hits写成空数组[]，就表示这张图上不该命中任何节点。负例是拦住误识别的关键，尤其适合那些容易串台、容易和相邻按钮混淆的节点。
四、控制器矩阵：一份用例跑两个平台
configs.controller写成数组时，同一个测试文件会在Win32和ADB两个截图目录里各执行一轮，坐标差异用 box 矩阵解决即可，不必维护两份重复文件。展开逻辑实现见 loader.mts。
如果差异只体现在坐标上，保留一个文件 + 矩阵 box；如果截图和命中节点本身都不一样，再拆成独立文件。
五、一键运行：pnpm test
安装依赖后，在项目根目录执行：
pnpm test这条命令由 package.json 中的test脚本映射到maa-tools test，CI 跑的也是同一条命令。测试日志默认输出到：
tests/maatools/跑失败了怎么排查？先看终端输出定位失败的用例，再打开tests/maatools/error_details.json查看具体原因（节点没命中、box 不匹配等）。如果只是想先检查配置和资源是否符合约定，可以执行pnpm check。
六、提交前自查清单
- 文件名符合
test_*.json； configs.resource/configs.controller在 maatools.config.mts 中有映射；image写全了扩展名，且对应目录里真的存在这张截图；- 正例、负例都覆盖了真实易错场景（Hover 态、弹窗、相邻地区 UI 等）；
- 位置敏感的节点补了
box断言； - 改完模板、ROI、阈值后重跑过一遍
pnpm test。
写在最后
节点测试的价值，是在后续重构、调阈值、换模板时帮你兜底。用例写得越完善，识别就越"稳"——这正是 MaaEnd 这类视觉 AI 自动化工具长期可用、可持续维护的底气所在。动手写第一份用例吧，从你最近改过的那个按钮节点开始 🚀
【免费下载链接】MaaEndMaaEnd 终末地小助手：基于视觉 AI 的「明日方舟：终末地」自动化工具项目地址: https://gitcode.com/gh_mirrors/maa/MaaEnd
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
