测试矩阵设计实战：claude-plugins-community 中 run_report

测试矩阵设计实战：claude-plugins-community 中 run_report_matrix.py 完整指南

【免费下载链接】claude-plugins-communityCommunity plugin marketplace for Claude Cowork and Claude Code. Read-only mirror — submit plugins at clau.de/plugin-directory-submission.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-plugins-community

在开源社区插件市场claude-plugins-community中，run_report_matrix.py是一个设计精巧的端到端测试矩阵脚本：它连接 TRES Finance MCP 服务器，自动发现所有报表类型，逐个触发导出并轮询直到完成，最终打印一份 pass/fail 结果矩阵。本文将带你快速看懂它的测试矩阵设计思路——无需深厚背景，几分钟即可掌握这种"批量验证 + 失败归类"的测试范式。

测试矩阵是什么？为什么需要它 🧪

tres-report-create这个技能教会 AI"如何生成任意一份 TRES 报表"。但技能的"配方"真的对每一种报表都有效吗？

run_report_matrix.py给出的答案是：全量验证。它不做抽查，而是：

发现服务器上暴露的每一种报表类型
对每种报表逐个触发导出
轮询直到每种报表完成、报错或超时
输出一张一目了然的结果矩阵

这种"矩阵式设计"的核心价值在于：让失败可见、可归类、可追踪，而不是淹没在一堆日志里。

📍 核心文件位置：

测试脚本：run_report_matrix.py
被测技能定义：SKILL.md
插件总览：tres-finance-plugin/README.md

测试矩阵的 4 阶段设计 🎯

阶段 1：连接 MCP 并发现工具

脚本内置了一个仅用 Python 标准库实现的 MCP 客户端 McpClient，完成三件事：

发送initialize握手，拿到服务器版本信息
调用tools/list列出服务器暴露的全部工具
自动识别"执行查询"的那个工具（容忍execute/execute_query等命名差异）

💡设计亮点：不硬编码工具名，而是从候选列表中探测。服务器端改名时，测试依然能跑。

阶段 2：发现全部报表类型

通过一条 GraphQL 查询availableReportTypes拉取组织支持的所有报表，每条包含name（报表名）、exportType（导出格式）、entitiesType（实体类型）。

紧接着脚本用一张映射表把实体类型翻译成应调用的查询：

entitiesType	触发的查询
LEDGER	`transaction`
ASSETS / BALANCE / HISTORICAL_BALANCE	`organizationBalance`
ACCOUNTS / GENERAL	`internalAccount`
STAKING_DATA	`stakingYieldRecord`
AUDIT_LOG	`auditLog`
LOGIN_HISTORY	`loginHistoryExport`

这张表定义在 ENTITIES_TO_QUERY。任何无法映射的报表类型会被标记为SKIPPED而不是让脚本崩溃——单个异常不应中断整个矩阵。

阶段 3：批量触发导出（Phase 1）

触发逻辑封装在 build_trigger 函数中，体现了测试矩阵的**"特例处理"**思想：

普通报表：统一携带exportFormat、exportName、currency、outputFormat四个参数
日期范围类报表（transaction、auditLog）：额外附加timestamp_Gte/timestamp_Lte
登录历史：参数结构完全不同，单独构造查询
成本基础清单：必须恰好传入一个资产类别 ID，脚本会先查询assetClass取一个真实 ID 备用

每个触发结果被记录为矩阵中的一行，失败原因分门别类：

标记	含义
`OK`	触发成功，进入轮询
`TRIGGER_FAILED`	GraphQL 报错或抛异常
`SKIPPED`	无法映射 / 缺少导出类型

阶段 4：轮询直到收敛（Phase 2）

导出是异步的——触发成功 ≠ 报表就绪。脚本使用 POLL_QUERY 按精确名称查询每份报表的状态，轮询逻辑位于 Phase 2 代码段：

DONE→ 记录文件大小与下载链接是否存在 ✅
ERROR→ 生成器拒绝了输入，记为失败
其他状态 → 继续等待，默认 12 轮 × 每轮 20 秒（均可通过参数调整）
轮完仍未收敛 → 标记为TIMEOUT

轮询期间还会实时打印进度：round 1: done=3 error=0 open=8，让等待过程透明可控。

结果矩阵：一眼看懂全局 📊

最终输出长这样（结构见 RESULT MATRIX 代码段）：

=== RESULT MATRIX === REPORT ENTITIES TRIGGER FINAL SIZE/NOTE Transaction Ledger LEDGER OK DONE size=... link=yes Cost Basis Inventory BALANCE FAIL ERROR GQL_ERROR: ... Login History LOGIN_HISTORY OK TIMEOUT Totals: DONE=28, ERROR=1, TIMEOUT=1

三个设计细节值得学习：

每行状态自解释：FINAL列只有 5 种取值（DONE/ERROR/TIMEOUT/TRIGGER_FAILED/SKIPPED），失败原因列自动补上细节
完整结果落盘：全部行数据写入matrix_<时间戳>.json，方便事后比对两次运行
有意义的退出码：只有当所有非跳过项都DONE时返回 0，否则返回 1——可以直接接入 CI 流水线

常用命令行参数速查 ⚙️

脚本支持 4 个参数（定义见 main 函数）：

参数	作用	典型场景
`--dry-run`	只连接 + 列出报表，不触发导出	先探明环境，零副作用
`--only`	按 entitiesType 过滤，如`--only LEDGER ASSETS`	回归测试某类报表
`--poll-rounds`	最大轮询轮数（默认 12）	大数据量表调整等待预算
`--poll-interval`	每轮间隔秒数（默认 20）	报表生成慢时放宽节奏

典型使用流程：

export TRES_BEARER_TOKEN="<你的令牌>" python run_report_matrix.py --dry-run # 第 1 步：确认连接与报表清单 python run_report_matrix.py # 第 2 步：跑完整矩阵

值得借鉴的安全与工程细节 🔒

令牌只读环境变量：从TRES_BEARER_TOKEN读取，全程不打印
预签名链接不落盘：报表下载链接只判断"存在与否"，绝不写入 JSON 或终端
零第三方依赖：仅用urllib、json、argparse等标准库，克隆下来即可运行
失败即记录而非中断：任何单点异常都被捕获并写入矩阵行，保证矩阵完整性

总结

run_report_matrix.py是"测试矩阵设计"的一个优秀样本：发现 → 触发 → 轮询 → 归类四段式流程，配合唯一命名、失败分类、JSON 落盘和 CI 友好退出码，把"技能配方是否真的对全部报表有效"这个模糊问题，变成了一张可以逐行核对的表。

📚 延伸阅读：

技能完整工作流（含防静默失败校验）：SKILL.md
报表推荐技能：tres-report-advisor
报表分析技能：tres-report-analyzer

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

测试矩阵设计实战：claude-plugins-community 中 run_report_matrix.py 完整指南