npm package: @iflow-mcp/mingzhanliao-mini-test-mcp
Description: MCP项目，用于调用微信小程序自动化测试框架
Latest version: 1.0.9

# Mini-test MCP

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

## 🚀 主要特性

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

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

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

## 快速开始

```bash
# 直接启动开发者工具
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运行：

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

### 全局安装

```bash
npm install -g mini-test-mcp
```

### 本地安装

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

```bash
npm install
```

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

```bash
npm link
```

## 使用方法

### 作为MCP服务器使用

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

```json
{
  "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服务器

```bash
# 启动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/微信开发者工具目录"
```

#### 直接启动微信开发者工具

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

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

#### 查看帮助

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

## 发布

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

```bash
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服务器

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

#### 直接启动开发者工具

```bash
# 直接启动微信开发者工具并打开指定项目
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
```

#### 自动化测试流程

```bash
# 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`来运行命令

## 参考资料

- [微信小程序自动化测试官方文档](https://developers.weixin.qq.com/miniprogram/dev/devtools/auto/quick-start.html)

## 许可证

MIT