测试运行程序MCP服务器

🤖 将AI助手连接到您的测试基础设施

一个模型上下文协议（MCP）服务器，支持AI助手，如 克劳德桌面版 和 谷歌双子座 通过自然语言与您的网络和移动测试基础设施进行交互。

由...驱动: @应用程序/测试运行器 ()-企业级浏览器和移动自动化引擎\ MCP版本：1.0+兼容\ 支持的客户：Claude Desktop 0.7+，Gemini CLI，自定义MCP客户端

🎯 这能带来什么

改变您与测试自动化的交互方式：

“打开浏览器会话https://example.com然后单击登录按钮“
“测试结账流程并验证总数是否正确”
“获取可访问性树并检查ARIA违规情况”
“在iOS模拟器上运行移动测试”
“为此工作流生成测试运行器JSON，这样我就可以在没有人工智能的情况下回放它” 💡

🚀 主要特点

核心技术

🎯 由Applitest测试运行器提供支持 -用途 @应用程序/测试运行器 ()作为所有浏览器和移动交互的自动化引擎
🔄 AI生成→ 独立测试 -生成可以在没有MCP或AI的情况下重放的测试运行器JSON格式
📝 出口和再利用 -将AI对话转换为可重用的测试自动化脚本

能力

🗣️ 自然语言测试 -通过对话控制测试自动化
🌐 多浏览器支持 -Chrome、Firefox、Edge通过测试运行器实现自动化
📱 移动测试 -通过测试运行器集成Appium，实现iOS和Android\*
🔍 可及性分析 -内置可达性树检查
🤝 多客户端支持 -适用于Claude Desktop、Gemini等
🛠️ 开发者工具 -使用MCP Inspector进行全面调试

⚠️ 移动测试注意事项：虽然 @应用程序/测试运行器 MCP服务器完全支持iOS和Android的原生移动应用测试，但尚未为原生移动应用生成完全验证的测试运行器JSON。完全支持Web和移动Web测试。通过MCP支持本地移动应用程序即将推出。

💰 经济高效的测试策略

经济优势：

使用AI进行设计：让Claude/Gemini帮助您创建和完善测试场景
生成JSON格式：从AI对话中获取测试运行器JSON输出
无AI回放：仅使用测试运行器重复执行相同的测试（无人工智能成本！）
需要时迭代：仅在需要修改或创建新测试时才返回AI

工作流程示例：

1. AI Conversation → Design test flow with Claude
2. Generate → Export as test-runner JSON
3. Save → Store JSON in your test repository
4. Execute → Run unlimited times via test-runner CLI (free!)
5. CI/CD → Integrate in your pipeline without MCP overhead

📋 先决条件

Node.js 20+（建议24+）
npm 或纱线
@应用程序/测试运行器 （作为依赖项自动安装）
用于网络测试：Chrome、Firefox或Edge浏览器
用于移动测试：Appium服务器和模拟器/仿真器

⚡ 快速开始

# Clone and install
git clone https://github.com/Applitest-co-il/test-runner-mcp.git
cd test-runner-mcp
npm install
npm run build

# The test-runner dependency is included automatically
# No separate installation of @applitest/test-runner needed!

🚀 安装和设置

步骤1：安装依赖项

cd test-runner-mcp
npm install
npm run build

💡 备注：The @应用程序/测试运行器 ()包作为核心依赖项自动安装

第二步：选择你的AI助手

🎭 部署选项

选项1:克劳德桌面（推荐）

需求：克劳德桌面0.7.0或更高版本

1.查找配置文件

视窗: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2.添加MCP服务器配置

{
  "mcpServers": {
    "test-runner": {
      "command": "node",
      "args": ["/absolute/path/to/test-runner-mcp/dist/cli.js"]
    }
  }
}

示例（Windows）:

{
  "mcpServers": {
    "test-runner": {
      "command": "node",
      "args": ["C:\\Users\\YourName\\Projects\\test-runner-mcp\\dist\\cli.js"]
    }
  }
}

示例（macOS/Linux）:

{
  "mcpServers": {
    "test-runner": {
      "command": "node",
      "args": ["/Users/yourname/projects/test-runner-mcp/dist/cli.js"]
    }
  }
}

3.重新启动克劳德桌面

完全退出并重新启动Claude Desktop（而不仅仅是关闭窗口）。

4.验证安装

在克劳德，寻找🔌 图标或类型：

_“列出可用的MCP工具”_
_“你们有什么测试运行工具？”_

你应该看到这样的工具 open-session, close-session, do-step，以及 get-accessibility-tree.

______________________________________________________________________

选项2:Google Gemini CLI

需求：支持MCP的Gemini CLI

📚 文档：参见 Gemini CLI MCP服务器指南

1.安装Gemini CLI

npm install -g @google/genai-cli

2.配置MCP服务器

选项A：工作区配置（推荐）

创建 /.gemini/settings.json 在您的工作空间中：

{
  "mcpServers": {
    "test-runner": {
      "command": "node",
      "args": ["./dist/cli.js"]
    }
  }
}

然后从您的工作区目录启动Gemini：

cd /path/to/test-runner-mcp
gemini

选项B：全系统配置

为系统上的所有用户全局配置MCP服务器：

Linux: /etc/gemini-cli/settings.json
视窗: C:\ProgramData\gemini-cli\settings.json
macOS: /Library/Application Support/GeminiCli/settings.json

{
  "mcpServers": {
    "test-runner": {
      "command": "node",
      "args": ["/absolute/path/to/test-runner-mcp/dist/cli.js"]
    }
  }
}

💡 备注：使用绝对路径。在Windows上，避开反斜杠(C:\\path\\to\\file)或使用正斜杠(C:/path/to/file)

正常启动Gemini：

gemini  # Automatically loads system settings

📌 小贴士：使用覆盖系统设置路径 GEMINI_CLI_SYSTEM_SETTINGS_PATH 环境变量（如果需要）

3.测试连接

在Gemini CLI中：

> use mcp test-runner
> call tool open-session with {"type": "web", "url": "https://example.com", "browser": "chrome"}

______________________________________________________________________

选项3:HTTP服务器模式

对于自定义集成或web应用程序：

1.启动HTTP服务器

npm run http
# Server starts on http://localhost:3000

2.配置自定义端口（可选）

创建 .env 文件：

MCP_SERVER_PORT=3000

3.发送MCP请求

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

______________________________________________________________________

选项4：直接CLI使用

对于脚本编写或测试：

# Standard mode
npm run cli

# Debug mode
npm run cli:debug

🔧 可用工具

一旦连接到AI助手，这些工具就可以使用：

`open-session`

使用打开测试自动化会话 Applitest测试运行器

Parameters:
- type: 'web' | 'mobile' | 'api'
- url: Target URL (for web sessions)
- browser: 'chrome' | 'firefox' | 'edge'

Returns: sessionId, sessionType

Note: Currently optimized for web and mobile web sessions.
Native mobile app testing is supported by test-runner but
not yet fully integrated in MCP JSON generation.

`close-session`

关闭当前测试运行程序会话

Parameters:
- sessionId: ID of session to close

`get-accessibility-tree`

通过以下方式检索页面可访问性信息 测试工具相关

Parameters:
- sessionId: Active session ID
- selector: Optional CSS selector to focus on

Returns: Accessibility tree structure

`do-step`

通过以下方式执行测试自动化操作 试车跑道发动机

Parameters:
- sessionId: Active session ID
- command: Action to perform (click, input-text, etc.)
- selector: Target element selector
- value: Input value (for text input)
- position: Element index (if multiple matches)
- operator: Optional operator for assertions

Note: All commands use test-runner's automation engine
Full command list: https://github.com/Applitest-co-il/test-runner/blob/main/docs/step-commands.md

📋 可用提示

`generate-test-json`

从您的AI对话中生成测试运行器JSON格式

Use this prompt to:
1. Convert AI-guided test flows into test-runner JSON
2. Save the JSON for unlimited replay without AI costs
3. Share tests with your team
4. Integrate into CI/CD pipelines

Example usage in Claude:
"Use the generate-test-json prompt to create a reusable test
 for the login flow we just executed"

优点：

✅ 设计测试的一次性人工智能成本
✅ 后续执行的零成本
✅ 生产中无MCP开销
✅ 标准测试运行程序JSON格式
✅ 版本控制友好
✅ 团队协作就绪

Parameters:
- sessionId: Active session ID
- command: Action to perform (click, input-text, etc.)
- selector: Target element selector
- value: Input value (for text input)
- position: Element index (if multiple matches)

🤖 对话示例

使用Claude Desktop-交互式测试

你：“打开一个网络会话https://example.com在Chrome中”

克劳德: ✅ _用途 open-session 工具（由测试运行器提供动力）_\ “我在以下位置打开了Chrome浏览器会话https://example.com.会话ID:abc123“

______________________________________________________________________

你：“点击登录按钮”

克劳德: ✅ _用途 do-step 工具（通过测试运行器执行）_\ “我成功单击了登录按钮。”

______________________________________________________________________

你：“类型”admin@test.com'在电子邮件字段中“

克劳德: ✅ _用途 do-step 命令=“输入文本”_\ “我已经输入了电子邮件地址。”

______________________________________________________________________

你：“登录表单的可访问性树是什么？”

克劳德: ✅ _用途 get-accessibility-tree （测试运行器的内置功能）_\ “这是登录表单的可访问性结构：\[树数据\]”

______________________________________________________________________

💰 高效的工作流程-生成可重用的测试

你：“现在使用generate-test json提示符从我们刚才做的创建一个可重用的测试”

克劳德: ✅ _用途 generate-test-json 提示_\ “以下是登录流的测试运行器JSON格式：

{
  "suites": [
    {
      "name": "Login Flow Test",
      "tests": [
        {
          "name": "Complete Login",
          "type": "web",
          "steps": [
            {
              "command": "navigate",
              "value": "https://example.com"
            },
            {
              "command": "click",
              "selectors": ["button=Login"]
            },
            {
              "command": "input-text",
              "selectors": ["input[type='email']"],
              "value": "admin@test.com"
            }
          ]
        }
      ]
    }
  ]
}

保存此JSON并随时使用测试运行器CLI运行它-不需要AI！

# Run unlimited times without MCP/AI costs
npx @applitest/test-runner --config login-test.json

Key Benefit: You just paid for AI once to design the test. Now you can run it thousands of times in CI/CD with zero AI costs! 🎉

With Gemini CLI

gemini> use mcp test-runner

# Open session via test-runner
gemini> call tool open-session with {
  "type": "web",
  "url": "https://google.com",
  "browser": "chrome"
}
# Returns: { sessionId: "xyz789", sessionType: "web" }

gemini> call tool do-step with {
  "sessionId": "xyz789",
  "command": "click",
  "selector": "button[name='btnK']"
}
# Returns: { result: true }

# Generate reusable test-runner JSON
gemini> call prompt generate-test-json with { "sessionId": "xyz789" }
# Returns test-runner JSON format you can save and replay

🏗️ 建筑及其工作原理

测试跑者核心

此MCP服务器是 薄包装纸 大约 @应用程序/测试运行器 ()，它可以处理所有重物：

┌─────────────────┐
│  Claude/Gemini  │  ← Natural language input
└────────┬────────┘
         │ MCP Protocol
┌────────▼─────────┐
│   MCP Server     │  ← This project (translation layer)
└────────┬─────────┘
         │ Direct API calls
┌────────▼──────────┐
│ Test Runner Core │  ← @applitest/test-runner
│  - WebDriver      │     (does all the work)
│  - Appium         │
│  - Browser Control│
└───────────────────┘

MCP服务器的功能：

翻译自然语言→ test-runner API调用
管理会话状态
为JSON生成提供提示模板
处理MCP协议通信

测试运行者做什么：

所有浏览器自动化（Chrome、Firefox、Edge）
所有移动自动化（iOS、安卓通过Appium）
元素选择和交互
无障碍树检查
屏幕截图
测试执行和验证

为什么这种架构是经济的

AI设计测试 → MCP转换为测试运行器命令
Prompt生成JSON → 纯测试运行器格式（无MCP依赖性）
JSON独立执行 → 测试运行器CLI运行它（不需要AI/MCP！）
结果：一次性支付人工智能设计费用，永远免费运行

🛠️ 开发与测试

MCP检查员（建议用于开发）

在连接到Claude之前，以交互方式测试您的服务器：

# Start the MCP inspector
npm run inspector:cli

# Or test HTTP mode
npm run inspector:http

打开一个web界面，您可以在其中手动测试所有工具。

直接测试

# Run the CLI version
npm run cli

# Run with debugging
npm run cli:debug

# Run HTTP server
npm run http

# HTTP with debugging
npm run http:debug

向MCP服务器发送请求
实时查看响应
测试不同的MCP操作
调试通信问题

自动化测试

该框架包括MCP服务器功能的自动化测试。用以下方式运行它们：

npm test -- --grep "MCP"

🏗️ 架构概述

MCP服务器是用TypeScript实现的，由几个关键组件组成：

核心文件

src/mcpserver/cli.ts -命令行界面和入口点
src/mcpserver/mcp-service.ts -主MCP服务器实现
src/mcpserver/http.ts -HTTP传输层（如果需要）

传输层

MCP服务器使用 stdio传输 用于与Claude Desktop通信，后者提供：

可靠的双向通信
JSON-RPC消息协议
错误处理和恢复
流程生命周期管理

可用工具和资源

MCP服务器公开了AI助手可以使用的各种工具和资源：

测试执行 -运行单独的测试或测试套件
配置管理 -读取和修改测试配置
结果分析 -访问测试结果并生成报告
环境管理 -控制测试环境和设置

🐛 故障排除

Claude桌面问题

服务器未出现

检查配置文件位置

- Windows：按 Win+R，类型 %APPDATA%\Claude 并验证 claude_desktop_config.json 存在 - Mac：检查 ~/Library/Application Support/Claude/ - 验证JSON语法是否有效（使用JSON验证器）

验证路径是否为绝对路径

   // ❌ Wrong (relative path)
   "args": ["./dist/cli.js"]

   // ✅ Correct (absolute path)
   "args": ["C:\\Users\\YourName\\Projects\\test-runner-mcp\\dist\\cli.js"]

检查克劳德桌面版本

- 转到帮助→ 关于克劳德桌面 - 确保版本为0.7.0或更高版本 - 必要时进行更新

查看日志

- 窗户： %APPDATA%\Claude\logs - 雨衣： ~/Library/Logs/Claude - 查找与MCP相关的错误

工具不工作

重建服务器

   npm run build

先与检验员一起测试

   npm run inspector:cli

检查相关性

   npm install
   npm list @applitest/test-runner

常见错误

“找不到模块”

# Solution: Ensure all dependencies installed
npm install
npm run build

“足够：没有这样的文件或目录”

// Solution: Use absolute paths and escape backslashes on Windows
"args": ["C:\\Projects\\test-runner-mcp\\dist\\cli.js"]

______________________________________________________________________

Gemini CLI问题

MCP配置未加载

验证配置文件位置

   cat ~/.config/gemini/mcp_config.json

检查JSON语法

   # Validate JSON
   cat ~/.config/gemini/mcp_config.json | python -m json.tool

明确指定配置

   gemini --mcp-config /full/path/to/mcp_config.json

工具不可用

列出可用服务器

   gemini> list mcp servers

连接到特定服务器

   gemini> use mcp test-runner

检查Gemini CLI版本

   gemini --version
   # Ensure MCP support is available

______________________________________________________________________

一般连接问题

端口冲突（HTTP模式）

# Check if port 3000 is in use
netstat -an | grep 3000  # Mac/Linux
netstat -an | findstr 3000  # Windows

# Use different port
# Edit .env file:
MCP_SERVER_PORT=3001

Node.js版本问题

# Check version
node --version

# Should be 18.x or 20.x
# Update if needed

权限错误

# On Mac/Linux, may need to make CLI executable
chmod +x dist/cli.js

🔗 高级配置

多环境设置（克劳德桌面）

为开发、暂存和生产运行不同的实例：

{
  "mcpServers": {
    "test-runner-dev": {
      "command": "node",
      "args": ["C:\\dev\\test-runner-mcp\\dist\\cli.js"],
      "env": {
        "NODE_ENV": "development",
        "TEST_BASE_URL": "http://localhost:3000"
      }
    },
    "test-runner-staging": {
      "command": "node",
      "args": ["C:\\staging\\test-runner-mcp\\dist\\cli.js"],
      "env": {
        "NODE_ENV": "staging",
        "TEST_BASE_URL": "https://staging.example.com"
      }
    },
    "test-runner-prod": {
      "command": "node",
      "args": ["C:\\prod\\test-runner-mcp\\dist\\cli.js"],
      "env": {
        "NODE_ENV": "production",
        "TEST_BASE_URL": "https://example.com"
      }
    }
  }
}

自定义环境变量

{
  "mcpServers": {
    "test-runner": {
      "command": "node",
      "args": ["/path/to/dist/cli.js"],
      "env": {
        "APPIUM_HOST": "localhost",
        "APPIUM_PORT": "4723",
        "HEADLESS": "true",
        "SCREENSHOT_PATH": "/tmp/screenshots"
      }
    }
  }
}

Gemini CLI高级用法

📚 参考: Gemini CLI MCP服务器文档

工作区特定配置

对于特定于项目的MCP服务器，创建 .gemini/settings.json 在项目根目录中：

{
  "mcpServers": {
    "test-runner": {
      "command": "node",
      "args": ["./dist/cli.js"],
      "env": {
        "NODE_ENV": "development",
        "HEADLESS": "false"
      }
    }
  }
}

从项目根开始Gemini：

cd /path/to/test-runner-mcp
gemini  # Automatically loads .gemini/settings.json

每个会话的自定义配置

# Start with specific config
gemini --mcp-config ~/configs/test-config.json

# Override environment variables
MCP_SERVER_PORT=3001 gemini --mcp-config ~/configs/test-config.json

脚本化测试

创建Gemini脚本文件 test-script.gemini:

use mcp test-runner
call tool open-session with {"type":"web","url":"https://example.com","browser":"chrome"}
call tool do-step with {"sessionId":"[SESSION_ID]","command":"click","selector":"#login"}
call tool close-session with {"sessionId":"[SESSION_ID]"}

运行它：

gemini --script test-script.gemini

HTTP API集成

对于自定义客户端或webhooks：

// POST to http://localhost:3000/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "open-session",
    "arguments": {
      "type": "web",
      "url": "https://example.com",
      "browser": "chrome"
    }
  }
}

🆘 获取帮助

快速诊断

使用MCP检查员进行测试 （最快的调试方式）

   npm run inspector:cli

打开显示的URL以交互方式测试所有工具

检查构建状态

   npm run build
   # Should complete without errors

验证依赖关系

   npm list @applitest/test-runner @modelcontextprotocol/sdk

启用调试日志记录

   # For CLI
   npm run cli:debug

   # For HTTP
   npm run http:debug

平台特定日志

克劳德桌面：

窗户： %APPDATA%\Claude\logs\mcp*.log
雨衣： ~/Library/Logs/Claude/mcp*.log
应用内：帮助→ 查看日志

Gemini CLI：

# Enable verbose logging
gemini --verbose --mcp-config ~/.config/gemini/mcp_config.json

常见解决方案

问题	解决方案
未检测到服务器	检查绝对路径，重新生成 `npm run build`
工具不可用	重新启动Claude/Gemini，检查MCP版本兼容性
模块错误	运行 `npm install`，验证Node.js 18+
端口冲突	更改 `MCP_SERVER_PORT` 在 `.env` 文件
权限被拒绝	`chmod +x dist/cli.js` 在Mac/Linux上

报告问题

如果您遇到问题：

✅ 首先与MCP检查员进行测试
📋 收集相关日志
🐛
📧 包括：

- 平台（Windows/Mac/Linux） - 客户端（Claude Desktop/Gemini CLI） - Node.js版本 - 错误消息 - 配置文件（编辑敏感信息）

🌟 接下来是什么？

扩展您的设置

自定义命令：添加特定于域的测试步骤
CI/CD集成：从您的管道中触发测试
多会话：处理并行浏览器会话
自定义断言：为您的应用程序构建验证规则

资源

Applitest测试运行器

📦 -安装和文档
🔧 -源代码和示例
📚 步骤命令参考 -所有可用的自动化命令

MCP和AI客户端

📖 MCP规范 -最新MCP协议文件
🤖 克劳德桌面版 -下载克劳德桌面
💎 双子座命令行界面 -Gemini命令行文档
🔍 MCP检查员 -调试工具

本项目

🐛 -报告错误
💬 讨论 -提问

版本兼容性

客户端	最低版本	状态
克劳德桌面	0.7.0	✅ 完全支持
Gemini CLI	最新	⚠️ 实验性
自定义客户端	MCP 1.0+	✅ 支持

______________________________________________________________________

Test Runner

快速接入

详细介绍

测试运行程序MCP服务器

🎯 这能带来什么

🚀 主要特点

核心技术

能力

💰 经济高效的测试策略

📋 先决条件

⚡ 快速开始

🚀 安装和设置

步骤1：安装依赖项

第二步：选择你的AI助手

🎭 部署选项

选项1:克劳德桌面（推荐）

1.查找配置文件

2.添加MCP服务器配置

3.重新启动克劳德桌面

4.验证安装

选项2:Google Gemini CLI

1.安装Gemini CLI

2.配置MCP服务器

3.测试连接

选项3:HTTP服务器模式

1.启动HTTP服务器

2.配置自定义端口（可选）

3.发送MCP请求

选项4：直接CLI使用

🔧 可用工具

open-session

close-session

get-accessibility-tree

do-step

📋 可用提示

generate-test-json

🤖 对话示例

使用Claude Desktop-交互式测试

💰 高效的工作流程-生成可重用的测试

With Gemini CLI

🏗️ 建筑及其工作原理

测试跑者核心

为什么这种架构是经济的

🛠️ 开发与测试

MCP检查员（建议用于开发）

直接测试

自动化测试

🏗️ 架构概述

核心文件

传输层

可用工具和资源

🐛 故障排除

Claude桌面问题

服务器未出现

工具不工作

常见错误

Gemini CLI问题

MCP配置未加载

工具不可用

一般连接问题

🔗 高级配置

多环境设置（克劳德桌面）

自定义环境变量

Gemini CLI高级用法

工作区特定配置

每个会话的自定义配置

脚本化测试

HTTP API集成

🆘 获取帮助

快速诊断

平台特定日志

常见解决方案

报告问题

🌟 接下来是什么？

扩展您的设置

资源

Applitest测试运行器

MCP和AI客户端

本项目

版本兼容性

`open-session`

`close-session`

`get-accessibility-tree`

`do-step`

`generate-test-json`