🚀 Testomat.io MCP Server
Testomat.io MCP Server 是一个用于将 Testomat.io API 与 Cursor 等 AI 助手集成的模型上下文协议(MCP)服务器,为开发者提供便捷的测试管理和查询功能。
🚀 快速开始
本服务器为 Testomat.io API 与 AI 助手(如 Cursor)的集成提供了支持。你可以按照以下步骤安装并使用它。
📦 安装指南
前提条件
- Node.js 18 或更高版本(需支持内置的 fetch 功能)
- npm 或 yarn 包管理器
- 拥有具备 API 访问权限的 Testomat.io 账户
通过 npm 安装
npm install -g @testomatio/mcp
或者使用 npx 直接运行
npx @testomatio/mcp --token <your-token> --project <project-id>
💻 使用示例
命令行选项
MCP 服务器可以通过命令行参数或环境变量启动:
使用命令行参数
npx @testomatio/mcp -t testomat_YOUR_TOKEN_HERE -p your-project-id
npx @testomatio/mcp --token testomat_YOUR_TOKEN_HERE --project your-project-id
testomatio-mcp --token testomat_YOUR_TOKEN_HERE --project your-project-id
npx @testomatio/mcp --token testomat_YOUR_TOKEN_HERE --project your-project-id --base-url https://your-instance.testomat.io
使用环境变量
export TESTOMATIO_API_TOKEN=testomat_YOUR_TOKEN_HERE
export TESTOMATIO_BASE_URL=https://app.testomat.io
npx @testomatio/mcp --project your-project-id
TESTOMATIO_API_TOKEN=testomat_YOUR_TOKEN_HERE npx @testomatio/mcp --project your-project-id
获取 API 令牌
- 访问 Testomat.io
- 导航至用户令牌页面 https://app.testomat.io/account/access_tokens
- 创建并复制 通用 API 令牌(以
testomat_
开头)
获取项目 ID
在查看项目时,项目 ID 可以在 URL 中找到:
https://app.testomat.io/projects/YOUR_PROJECT_ID
与 Cursor 集成
要在 Cursor 中使用此 MCP 服务器,请将以下配置添加到 Cursor 设置中:
选项 1:使用 npx(推荐)
将以下内容添加到你的 Cursor MCP 设置(cursor-settings.json
或通过 Cursor 设置界面):
{
"mcpServers": {
"testomatio": {
"command": "npx",
"args": ["@testomatio/mcp", "--token", "testomat_YOUR_TOKEN_HERE", "--project", "YOUR_PROJECT_ID"]
}
}
}
选项 2:使用环境变量
首先,在你的 shell 配置文件(如 .bashrc
, .zshrc
等)中设置环境变量:
export TESTOMATIO_API_TOKEN=testomat_YOUR_TOKEN_HERE
然后将以下内容添加到你的 Cursor MCP 设置中:
{
"mcpServers": {
"testomatio": {
"command": "npx",
"args": ["@testomatio/mcp", "--project", "YOUR_PROJECT_ID"],
"env": {
"TESTOMATIO_API_TOKEN": "testomat_YOUR_TOKEN_HERE"
}
}
}
}
选项 3:全局安装
如果你已经全局安装了该包:
{
"mcpServers": {
"testomatio": {
"command": "testomatio-mcp",
"args": ["--token", "testomat_YOUR_TOKEN_HERE", "--project", "YOUR_PROJECT_ID"]
}
}
}
✨ 主要特性
工具
测试
get_tests
– 获取所有测试(参数:plan
, query
, state
, suite_id
, tag
, labels
) — API:GET /tests
search_tests
– 搜索测试(参数:query
, tql
, labels
, state
, priority
, filter
, page
) — API:GET /tests
测试套件
search_suites
– 搜索套件(参数:query
, labels
, state
, priority
, page
) — API:GET /suites
get_root_suites
– 列出根级套件(无参数) — API:GET /suites
get_suite
– 获取一个套件(参数:suite_id
) — API:GET /suites/{suite_id}
测试运行
get_runs
– 列出所有运行(无参数) — API:GET /runs
get_run
– 获取一次运行(参数:run_id
, tree
) — API:GET /runs/{run_id}
get_testruns
– 某个测试的运行记录(参数:test_id
, finished_at_date_range
) — API:GET /testruns
测试计划
get_plans
– 列出所有计划(参数:detail
, labels
, page
) — API:GET /plans
get_plan
– 获取一个计划(参数:plan_id
) — API:GET /plans/{plan_id}
💻 使用示例
基础用法
配置完成后,你可以向 AI 助手提出以下问题:
- "Show me all the tests in the project"(显示项目中的所有测试)
- "Get the test runs for test ID abc123"(获取测试 ID 为 abc123 的测试运行记录)
- "What are the root suites in this project?"(该项目中的根套件有哪些?)
- "Show me details for test run xyz789"(显示测试运行 xyz789 的详细信息)
- "List all automated tests with the @smoke tag"(列出所有带有 @smoke 标签的自动化测试)
- "Get all test plans for this project"(获取该项目的所有测试计划)
🔍 查询模式
基本信息查询
这些查询用于检索通用信息,无需特定过滤:
- "Show me all the tests in the project" →
get_tests
工具
- "What are the root suites in this project?" →
get_root_suites
工具
- "Get all test runs" →
get_runs
工具
- "Get all test plans for this project" →
get_plans
工具
特定项目查询
这些查询通过 ID 定位特定实体:
- "Get test runs for test ID abc123" →
get_testruns
工具,test_id: "abc123"
- "Show me details for test run xyz789" →
get_run
工具,run_id: "xyz789"
- "Get suite details for suite-456" →
get_suite
工具,suite_id: "suite-456"
搜索和过滤查询
这些查询使用高级过滤功能:
- "List all automated tests with the @smoke tag" →
search_tests
工具,query: "@smoke"
,state: "automated"
- "Find tests with priority high" →
search_tests
工具,priority: "high"
- "Search for tests containing 'login'" →
search_tests
工具,query: "login"
- "List tests tagged @critical or labelled 'ux' with high priority" →
search_tests
工具,tql: "tag == 'critical' or label == 'ux' and priority == 'high'"
- "Find tests linked to JIRA-123" →
search_tests
工具,tql: jira == 'BDCP-2'
高级查询语法
测试查询语言(TQL)
search_tests
工具支持使用 TQL 进行复杂过滤:
"tag == 'smoke' and state == 'manual'"
"priority == 'high' or label == 'ux'"
基于标签的搜索
可以使用 @
前缀搜索标签:
@smoke # 带有 'smoke' 标签的测试
@regression # 带有 'regression' 标签的测试
@critical # 带有 'critical' 标签的测试
Jira 集成
可以使用问题键查找与 Jira 问题关联的测试:
JIRA-123 # 与 JIRA-123 关联的测试
PROJ-456 # 与 PROJ-456 关联的测试
🛠️ 故障排除
常见问题
-
"API token is required" 错误
- 确保你的令牌以
testomat_
开头
- 验证令牌在你的 Testomat.io 项目设置中是否正确
-
"Project ID is required" 错误
- 检查你传递的项目 ID 是否正确
- 验证项目 ID 是否存在,并且你有权限访问
-
连接错误
- 确保你有互联网连接
- 检查防火墙是否允许连接到
app.testomat.io
- 验证你的 API 令牌是否具有必要的权限
-
MCP 服务器在 Cursor 中无法启动
- 检查 Cursor 的 MCP 日志以获取错误信息
- 确保已安装并可访问 Node.js 18+
- 尝试先手动运行命令进行测试
调试模式
运行服务器时查看详细日志:
DEBUG=* npx @testomatio/mcp --token <token> --project <project-id>
📚 详细文档
有关底层 Testomat.io API 的详细信息,请参考 Testomat.io API 文档。
🤝 贡献
欢迎贡献代码!请随时提交拉取请求。
📄 许可证
本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。
🎈 支持
如需支持,请:
- 查看 Testomat.io 文档
- 在 GitHub 上提交问题
- 联系 Testomat.io 支持团队
📝 变更日志
v1.0.0
- 初始版本发布
- 支持所有主要的 Testomat.io API 端点
- 兼容 MCP 的工具接口
- 为大语言模型(LLM)处理提供语义 XML 格式化