testomatio-mcp

Testomatio MCP

通过 MCP 配置对 Testomat.io 的访问，并运行 QA 分析工作流：运行分析、失败聚类、根因调查、计划分析和缺陷分诊。

适用场景

• 为 AI Agent（Claude、Cursor、OpenCode 等）检测或配置 Testomat.io MCP 服务。
• 分析测试运行：近期结果、成功率和失败趋势。
• 调查失败：将相似失败归组并查找规律。
• 多个测试因相同问题失败时，查明根因。
• 在用户的缺陷跟踪工具（例如 Jira）中，根据失败的测试创建缺陷。

MCP 工具

• 测试：tests_list、tests_get、tests_search
• 测试计划：plans_list、plans_get、plans_search
• 运行：runs_list、runs_get、runs_search
• 测试运行（运行中的结果）：testruns_list、testruns_get
• 测试套件：suites_list、suites_get、suites_search
• 标签：labels_list、labels_get、labels_create、labels_update、labels_delete。标签可以设定范围（key:value）。通过 link 参数将标签附加到实体或替换实体上的标签 — MCP 设置参考。
• 标记：tags_list、tags_get、tags_search

所有实体均提供 CRUD 工具（创建、更新、删除）。仅在明确需要进行有针对性的更新时使用。

规则

• 优先使用本地测试，而非 MCP。 如果仓库中包含 Markdown 测试用例（*.test.md）或自动化测试文件，请从文件系统读取（或通过 sync-test-cases-with-tms 技能加载），而不要使用 MCP 进行完整的测试发现和分析。
• 在以下场景中使用 MCP：
  • 读取和分析运行报告
  • 分析和报告
  • 测试计划管理
  • 仅存在于 Testomat.io 中的测试（没有本地副本），或快速搜索测试用例（tests_list、tests_search）
  • 有针对性地搜索远程测试用例并对其进行单点更新
• 使用 TQL（Testomat.io 查询语言）筛选 runs_list、plans_list、testruns_list。运算符和示例：MCP 设置参考。

设置

第 1 步：检测现有配置

在用户的 AI Agent 配置文件中检查是否存在 testomatio 或 mcp.testomatio 条目：

• opencode.json
• .cursor/mcp.json
• claude_desktop_config.json
• 其他配置文件，具体取决于用户使用的本地 Agent

验证：

• 服务已启用（客户端支持启用/禁用标志时）
• 已提供 TESTOMATIO_PROJECT_TOKEN 和 TESTOMATIO_PROJECT_ID

已配置且已启用 → 转到“工作流”。缺失、不完整或已禁用 → 第 2 步。

第 2 步：配置 MCP

配置前：

• 优先确认项目包含的测试不超过 1000 个。
• 如果无法确定项目规模，请提醒用户，大型项目可能会受到 MCP 性能限制。
• 仅在用户明确要求时执行有针对性或经过筛选的操作。

TESTOMATIO_PROJECT_TOKEN 和 TESTOMATIO_PROJECT_ID 的凭据优先级：

1. 现有环境变量。
2. 现有 MCP 配置。
3. 用户提供的值。

各 Agent 的配置格式（OpenCode、Cursor、Claude Desktop）以及获取凭据的方法：MCP 设置参考。

规则：

• 不要覆盖无关的 MCP 服务配置。 请谨慎合并更改，并保留现有配置内容。
• 不要在聊天回复中泄露项目令牌、密钥或凭据。

配置成功后，请提供摘要确认：

Testomat.io MCP configuration completed successfully.

AI Agent: Cursor
Config Updated: `.cursor/mcp.json`
MCP Server: Enabled
Authentication: Verified

Available workflows:
- Test run analysis
- Failure clustering
- Root-cause investigation
- Plan analysis & defect triage

工作流

以下是常见模式，并非完整列表 — 请根据用户需求调整并扩展。所有模式均假定 MCP 服务已启用。

工作流 1：分析测试运行

目标：了解近期测试执行的健康状况。

1. 调用 runs_list 并使用 tql 筛选条件（例如 finished、failed、with_defect）；按状态、环境或计划缩小范围。
2. 选择感兴趣的运行，然后调用 runs_get 获取详细元数据。
3. 调用 testruns_list，并传入 run_id 和 filter_status: failed，提取失败结果。
4. 汇总：测试总数、通过数、失败数、跳过数和涉及的环境。
   • 比较不同运行的成功率和失败率，以发现回归。

工作流 2：失败调查与错误聚类

目标：确定发生了什么问题，以及受影响的范围。

1. 调用 testruns_list（filter_status: failed、run_id）获取失败结果。
2. 对于每个失败的测试运行，调用 tests_get，将其对应到所属测试套件、优先级、标签和关联的问题。
3. 对失败进行聚类：
   • 按 suite_id → 找出失败数最多的测试套件
   • 按 message 子字符串 → 找出因相同异常或断言而失败的测试
4. 按数量降序展示各个聚类，并列出测试套件和消息明细，以及受影响的测试标题。

工作流 3：计划分析与根因检测

目标：当许多测试因同一问题失败时，说明根本原因。

1. 调用 plans_get（如果运行关联了计划），了解预期范围；检查失败是否与特定计划部分相关。
2. 调用 runs_list，使用 tql 定位到相同计划或环境，获取历史运行。
3. 比较不同运行中的失败情况：
   • 失败数增加 → 出现新的回归
   • 多次运行中出现相同失败 → 稳定存在的 bug 或不稳定的基础设施
   • 单个测试套件或标签中的失败激增 → 局部代码变更、功能回归
   • 分散在互不相关的测试套件中 → 系统性问题（基础设施、配置、依赖项）
4. 对受影响的测试调用 tests_get，检查 code、state 和关联的问题。
5. 提出根因假设。

示例——用户询问：“检查最近一次运行中有 20 个测试失败的原因——是某个测试套件的问题，还是系统性问题？”

1. Detecting existing Testomat.io MCP configuration:
   - Found `.cursor/mcp.json`
   - Found `testomatio` MCP server entry
   - MCP server status: enabled

2. Verifying MCP availability...
   - Authentication successful
   - Testomat.io tools available

3. Analyzing latest test run...
   - Retrieved last completed run
   - Total failed tests: 20

4. Failure clustering summary:
   - 16/20 failures belong to suite: "Checkout / Payments"
   - 14 failures share the same error: "Timeout waiting for payment confirmation"
   - First failure timestamp indicates failures started simultaneously

5. Probable root cause:
   - The failures appear systemic rather than test-specific.
   - Most failures point to instability or outage in the payment gateway service used during checkout flows.

工作流 4：根据失败测试创建缺陷

目标：将反复出现的失败转化为可跟踪的缺陷。

1. 运行工作流 2，按消息对失败进行聚类。
2. 如果某个聚类中有 5 个或更多测试出现相同失败：
   • 向用户提议创建缺陷（例如 Jira 问题）
   • 起草缺陷摘要：标题、描述、受影响的测试标题、失败消息、运行链接、环境
   • 如果有可用的 Jira MCP，则提议通过 Jira 技能创建工单
3. 创建缺陷后，对每个受影响的测试调用 tests_issues_link，将其关联到该缺陷。

工作流 5：更新测试的标签和标记

目标：设置、更改或移除测试的标签和标记，例如更新用于驱动仪表盘图表的状态标签。

1. 调用 labels_list（或 project_info），读取项目中现有的确切标签值，包括范围标签的完整 key:value 格式。不要猜测标签字符串。
2. 可选：使用 tests_list + TQL 查找要更新的测试：label == 'regression:yes'。
3. 使用 link 数组调用 tests_update（或 tests_create）进行更新——每项更改对应一个 { action, type, value } 条目。要更改值（例如从 regression:no 改为 regression:yes），请在同一次调用中同时发送 remove 和 add。同样的结构也适用于 tag、custom_field、milestone、issue 和 jira。

链接格式和完整替换示例：MCP 设置参考。

快捷命令

操作	MCP 工具	关键参数
列出失败的结果	testruns_list	run_id、filter_status: failed
列出运行记录	runs_list	tql、page、per_page
获取运行详情	runs_get	run_id
获取测试详情	tests_get	test_id
获取计划详情	plans_get	plan_id
将问题关联到测试	tests_issues_link	test_id、url 或 jira_id
列出标签	labels_list	page、per_page
设置 / 替换测试上的标签	tests_update	test_id、link
按标签查找测试	tests_list	tql: label == '...'
检查服务状态	system_ping	无