微信小程序自动化测试工具

Mini-test MCP

这是一个MCP (Model Context Protocol) 项目，用于调用微信小程序自动化测试框架。

🚀 主要特性

核心功能

• 智能连接管理：自动测试连接，失败时自动启动开发者工具
• 小程序自动化：页面导航、元素操作、数据管理
• 开发者工具集成：自动启动/关闭微信开发者工具
• 配置管理：支持命令行参数配置项目路径和工具路径

自动化特性

• 连接试探机制：连接前先测试WebSocket端点可用性
• 自动恢复：连接失败时自动启动所需服务
• 端口号自定义：支持自定义WebSocket端口号
• 实时日志：捕获开发者工具和控制台输出

新增功能

• 命令行参数支持：通过 -p/--project 和 -d/--devtool 参数配置路径
• 自动化连接流程：连接失败时自动使用 cli.bat 启动开发者工具
• 端口号自定义：支持通过 -P/--port 参数指定端口号
• 开发者工具管理：新增开发者工具启动、停止、状态查询工具
• 配置验证：自动验证配置完整性

快速开始

# 直接启动开发者工具
npx mini-test-mcp devtool -p "/path/to/miniprogram" -d "/path/to/微信开发者工具目录"

# 启动MCP服务器
npx mini-test-mcp start -p "/path/to/miniprogram" -d "/path/to/微信开发者工具目录"

前提条件

在使用此项目之前，请确保已安装以下软件：

1. Node.js (v14或更高版本)
2. 微信开发者工具
3. 已连接的Android/iOS设备或模拟器

安装

使用npx直接运行（推荐）

无需安装，直接使用npx运行：

npx mini-test-mcp start -p "小程序项目路径" -d "微信开发者工具路径"

全局安装

npm install -g mini-test-mcp

本地安装

1. 克隆或下载此项目
2. 安装依赖:

npm install

3. 安装命令行工具（可选）:

npm link

使用方法

作为MCP服务器使用

1. 在Claude Desktop的配置文件中添加此服务器:

{
  "mcpServers": {
    "mini-test": {
      "command": "npx",
      "args": ["mini-test-mcp", "start", "-p", "/path/to/miniprogram", "-d", "/path/to/微信开发者工具目录"],
      "env": {}
    }
  }
}

2. 重启Claude Desktop，即可使用小程序自动化相关工具

作为命令行工具使用

安装后，您可以使用mini-test-mcp命令来操作小程序自动化：

启动MCP服务器

# 启动MCP服务器并配置项目路径和开发者工具路径
mini-test-mcp start -p "/path/to/miniprogram" -d "/path/to/微信开发者工具目录"

# 或者使用npx
npx mini-test-mcp start -p "/path/to/miniprogram" -d "/path/to/微信开发者工具目录"

直接启动微信开发者工具

# 直接启动微信开发者工具并打开指定项目
mini-test-mcp devtool -p "/path/to/miniprogram" -d "/path/to/微信开发者工具目录"

# 指定端口号启动
mini-test-mcp devtool -p "/path/to/miniprogram" -d "/path/to/微信开发者工具目录" -P 9430

查看帮助

mini-test-mcp help
# 或者使用npx
npx mini-test-mcp help

发布

如果您是项目维护者，可以使用以下命令发布新版本：

npm run publish

这将检查您的npm登录状态，并引导您完成发布过程。

贡献

欢迎提交Issue和Pull Request来改进这个项目。

许可证

MIT

可用工具

连接管理工具

• minium_connect: 连接到小程序自动化服务

  • 参数: wsEndpoint (WebSocket端点地址)

• minium_auto_connect: 自动连接到小程序自动化服务

  • 参数: 无 (使用默认端点，自动启动开发者工具)

• minium_close: 关闭小程序连接

  • 参数: 无

• minium_get_console_logs: 获取控制台日志

  • 参数: 无

导航工具

• minium_navigate_to: 导航到指定页面

  • 参数: url (页面路径)

• minium_switch_tab: 切换到指定标签页

  • 参数: url (标签页路径)

元素操作工具

• minium_get_element: 获取页面元素

  • 参数: selector (元素选择器)

• minium_get_elements: 获取元素数组

  • 参数: selector (元素选择器)

• minium_element_tap: 点击元素

  • 参数: selector (元素选择器)

• minium_element_input: 在元素中输入文本

  • 参数: selector (元素选择器), value (要输入的文本)

• minium_element_text: 获取元素文本

  • 参数: selector (元素选择器)

• minium_element_attribute: 获取元素特性

  • 参数: selector (元素选择器), name (特性名称)

• minium_element_property: 获取元素属性

  • 参数: selector (元素选择器), name (属性名称)

• minium_element_size: 获取元素大小

  • 参数: selector (元素选择器)

• minium_element_offset: 获取元素位置

  • 参数: selector (元素选择器)

• minium_wait_for_element: 等待元素出现

  • 参数: selector (元素选择器), timeout (超时时间，可选)

页面操作工具

• minium_page_size: 获取页面大小

  • 参数: 无

• minium_page_data: 获取页面数据

  • 参数: path (数据路径，可选)

• minium_page_set_data: 设置页面数据

  • 参数: data (要设置的数据)

• minium_page_call_method: 调用页面方法

  • 参数: method (方法名称), args (参数数组，可选)

开发者工具管理

• devtool_start: 启动开发者工具

  • 参数: port (端口号，可选)

• devtool_stop: 关闭开发者工具

  • 参数: 无

• devtool_status: 获取开发者工具状态

  • 参数: 无

• devtool_validate_config: 验证配置

  • 参数: 无

实用工具

• minium_wait: 等待指定时间

  • 参数: ms (等待毫秒数)

• minium_screenshot: 截图

  • 参数: path (截图保存路径)

• config_get: 获取配置信息

  • 参数: 无

使用示例

MCP服务器使用示例

1. 自动连接小程序自动化服务:

   复制

   使用minium_auto_connect工具
   

   • 该工具会自动测试连接，如果连接失败会自动启动开发者工具并重试连接

2. 导航到指定页面:

   复制

   使用minium_navigate_to工具，提供页面路径
   

3. 获取页面元素:

   复制

   使用minium_get_element工具，提供元素选择器
   

4. 点击元素:

   复制

   使用minium_element_tap工具，提供元素选择器
   

5. 输入文本:

   复制

   使用minium_element_input工具，提供输入框选择器和文本内容
   

6. 截图:

   复制

   使用minium_screenshot工具，提供截图保存路径
   

7. 关闭小程序:

   复制

   使用minium_close工具
   

自动化连接流程

项目实现了完整的自动化连接流程：

1. 连接试探: 首先测试 WebSocket 端点 (ws://127.0.0.1:9420) 是否可用
2. 自动启动: 如果连接失败，自动启动微信开发者工具
3. 重试连接: 等待开发者工具启动完成后重新尝试连接
4. 错误处理: 如果自动启动失败，提供详细的错误信息

命令行工具使用示例

启动MCP服务器

# 启动MCP服务器并配置项目路径和开发者工具路径
npx mini-test-mcp start -p "D:\project\ruijiao\test_mini" -d "D:\tool\微信web开发者工具"

直接启动开发者工具

# 直接启动微信开发者工具并打开指定项目
npx mini-test-mcp devtool -p "D:\project\ruijiao\test_mini" -d "D:\tool\微信web开发者工具"

# 指定端口号启动
npx mini-test-mcp devtool -p "D:\project\ruijiao\test_mini" -d "D:\tool\微信web开发者工具" -P 9430

自动化测试流程

# 1. 启动MCP服务器
npx mini-test-mcp start -p "/path/to/miniprogram" -d "/path/to/微信开发者工具目录"

# 2. 在Claude Desktop中使用自动化工具进行测试
#    - 使用 minium_auto_connect 自动连接
#    - 使用 minium_navigate_to 导航到页面
#    - 使用 minium_element_tap 点击元素
#    - 使用 minium_element_input 输入文本
#    - 使用 minium_screenshot 截图
#    - 使用 minium_close 关闭连接

迁移说明

本项目已从Minium框架迁移到miniprogram-automator框架。主要变更：

1. 替换了依赖：从minium改为miniprogram-automator
2. 更新了API调用方式：使用miniprogram-automator的API替代Minium的命令行调用
3. 优化了代码结构：简化了命令行工具的实现，直接使用JavaScript API
4. 改进了错误处理：使用try-catch和Promise处理异步操作
5. 新增功能：
   • 命令行参数支持项目路径和开发者工具路径
   • 自动化连接流程（连接试探 → 自动启动 → 重试连接）
   • 开发者工具管理工具
   • 端口号自定义支持
   • 配置管理功能

注意事项

• 使用前请确保已正确安装微信开发者工具并启用自动化端口
• 确保微信开发者工具已正确配置
• 确保设备已连接并启用调试模式
• 命令行工具会在当前目录创建mini-config.json文件来保存配置
• 开发者工具启动需要使用cli.bat命令行工具
• MCP服务器需要与客户端（如Claude Desktop）配合使用，单独运行会退出

微信开发者工具启动行为说明

当使用 mini-test-mcp devtool 命令启动微信开发者工具时：

1. CLI进程行为正常：cli.bat 进程启动后会立即退出（退出码 0），这是正常行为
2. 开发者工具GUI继续运行：实际的微信开发者工具GUI窗口会保持打开状态
3. 状态管理：系统会正确标记开发者工具为运行状态，即使CLI进程已退出
4. 自动化连接：自动化连接功能会正常工作，可以连接到 WebSocket 端点进行测试

这种设计是因为 cli.bat 只是一个启动器，它负责打开开发者工具GUI，然后自身退出。开发者工具GUI会作为一个独立的进程继续运行。

故障排除

连接问题

• 问题: 无法连接到小程序自动化服务
• 解决: 使用 minium_auto_connect 工具，它会自动测试连接并在失败时启动开发者工具

开发者工具启动问题

• 问题: 开发者工具无法启动
• 解决: 确保使用 cli.bat 命令行工具，检查路径配置是否正确

端口号冲突

• 问题: 端口号被占用
• 解决: 使用 -P 参数指定不同的端口号，如 -P 9430

权限问题

• 问题: Node.js权限不足
• 解决: 确保Node.js有足够的权限执行相关操作

配置问题

• 问题: 配置不完整或错误
• 解决: 使用 devtool_validate_config 工具验证配置，使用 config_get 工具查看当前配置

CLI命令问题

• 问题: mini-test-mcp 命令不可用
• 解决: 如果使用npm link后仍无法使用命令，可以尝试直接使用node cli.js来运行命令

参考资料

• 微信小程序自动化测试官方文档

许可证

MIT