Content
# Mini-test MCP
This is an MCP (Model Context Protocol) project for calling the WeChat Mini Program automated testing framework.
## 🚀 Main Features
### Core Features
- **Intelligent Connection Management**: Automatically tests the connection and automatically starts the developer tool when it fails
- **Mini Program Automation**: Page navigation, element manipulation, data management
- **Developer Tool Integration**: Automatically starts/closes the WeChat developer tool
- **Configuration Management**: Supports command-line parameters to configure project and tool paths
### Automation Features
- **Connection Probing Mechanism**: Tests WebSocket endpoint availability before connecting
- **Automatic Recovery**: Automatically starts required services when the connection fails
- **Customizable Port Number**: Supports customizing the WebSocket port number
- **Real-time Logging**: Captures developer tool and console output
### New Features
- **Command-Line Parameter Support**: Configure paths via `-p/--project` and `-d/--devtool` parameters
- **Automated Connection Process**: Automatically uses `cli.bat` to start the developer tool when the connection fails
- **Customizable Port Number**: Supports specifying the port number via the `-P/--port` parameter
- **Developer Tool Management**: Added developer tool start, stop, and status query tools
- **Configuration Validation**: Automatically validates configuration integrity
## Quick Start
```bash
# Directly start the developer tool
npx mini-test-mcp devtool -p "/path/to/miniprogram" -d "/path/to/微信开发者工具目录"
# Start the MCP Server
npx mini-test-mcp start -p "/path/to/miniprogram" -d "/path/to/微信开发者工具目录"
```
## Prerequisites
Before using this project, make sure you have the following software installed:
1. Node.js (v14 or higher)
2. WeChat Developer Tool
3. Connected Android/iOS device or simulator
## Installation
### Run Directly with npx (Recommended)
No installation required, run directly with npx:
```bash
npx mini-test-mcp start -p "小程序项目路径" -d "微信开发者工具路径"
```
### Global Installation
```bash
npm install -g mini-test-mcp
```
### Local Installation
1. Clone or download this project
2. Install dependencies:
```bash
npm install
```
3. Install the command-line tool (optional):
```bash
npm link
```
## Usage
### Using as an MCP Server
1. Add this server to the Claude Desktop configuration file:
```json
{
"mcpServers": {
"mini-test": {
"command": "npx",
"args": ["mini-test-mcp", "start", "-p", "/path/to/miniprogram", "-d", "/path/to/微信开发者工具目录"],
"env": {}
}
}
}
```
2. Restart Claude Desktop to use the Mini Program automation tools
### Using as a Command-Line Tool
After installation, you can use the `mini-test-mcp` command to operate Mini Program automation:
#### Start the MCP Server
```bash
# Start the MCP server and configure the project path and developer tool path
mini-test-mcp start -p "/path/to/miniprogram" -d "/path/to/微信开发者工具目录"
# Or use npx
npx mini-test-mcp start -p "/path/to/miniprogram" -d "/path/to/微信开发者工具目录"
```
#### Directly Start the WeChat Developer Tool
```bash
# Directly start the WeChat developer tool and open the specified project
mini-test-mcp devtool -p "/path/to/miniprogram" -d "/path/to/微信开发者工具目录"
# Start with a specified port number
mini-test-mcp devtool -p "/path/to/miniprogram" -d "/path/to/微信开发者工具目录" -P 9430
```
#### View Help
```bash
mini-test-mcp help
# Or use npx
npx mini-test-mcp help
```
## Publish
If you are a project maintainer, you can use the following command to publish a new version:
```bash
npm run publish
```
This will check your npm login status and guide you through the publishing process.
## Contribution
Welcome to submit Issues and Pull Requests to improve this project.
## License
MIT
### Available Tools
#### Connection Management Tools
- `minium_connect`: Connect to the Mini Program automation service
- Parameters: `wsEndpoint` (WebSocket endpoint address)
- `minium_auto_connect`: Automatically connect to the Mini Program automation service
- Parameters: None (uses the default endpoint, automatically starts the developer tool)
- `minium_close`: Close the Mini Program connection
- Parameters: None
- `minium_get_console_logs`: Get console logs
- Parameters: None
#### Navigation Tools
- `minium_navigate_to`: Navigate to the specified page
- Parameters: `url` (page path)
- `minium_switch_tab`: Switch to the specified tab
- Parameters: `url` (tab path)
#### Element Manipulation Tools
- `minium_get_element`: Get the page element
- Parameters: `selector` (element selector)
- `minium_get_elements`: Get an array of elements
- Parameters: `selector` (element selector)
- `minium_element_tap`: Tap the element
- Parameters: `selector` (element selector)
- `minium_element_input`: Enter text in the element
- Parameters: `selector` (element selector), `value` (text to enter)
- `minium_element_text`: Get the element text
- Parameters: `selector` (element selector)
- `minium_element_attribute`: Get the element attribute
- Parameters: `selector` (element selector), `name` (attribute name)
- `minium_element_property`: Get the element property
- Parameters: `selector` (element selector), `name` (property name)
- `minium_element_size`: Get the element size
- Parameters: `selector` (element selector)
- `minium_element_offset`: Get the element position
- Parameters: `selector` (element selector)
- `minium_wait_for_element`: Wait for the element to appear
- Parameters: `selector` (element selector), `timeout` (timeout time, optional)
#### Page Manipulation Tools
- `minium_page_size`: Get the page size
- Parameters: None
- `minium_page_data`: Get the page data
- Parameters: `path` (data path, optional)
- `minium_page_set_data`: Set the page data
- Parameters: `data` (data to set)
- `minium_page_call_method`: Call the page method
- Parameters: `method` (method name), `args` (array of arguments, optional)
#### Developer Tool Management
- `devtool_start`: Start the developer tool
- Parameters: `port` (port number, optional)
- `devtool_stop`: Close the developer tool
- Parameters: None
- `devtool_status`: Get the developer tool status
- Parameters: None
- `devtool_validate_config`: Validate the configuration
- Parameters: None
#### Utility Tools
- `minium_wait`: Wait for the specified time
- Parameters: `ms` (milliseconds to wait)
- `minium_screenshot`: Take a screenshot
- Parameters: `path` (screenshot save path)
- `config_get`: Get configuration information
- Parameters: None
## Usage Examples
### MCP Server Usage Example
1. Automatically connect to the Mini Program automation service:
```
Use the minium_auto_connect tool
```
- This tool automatically tests the connection and automatically starts the developer tool and retries the connection if the connection fails
2. Navigate to the specified page:
```
Use the minium_navigate_to tool, providing the page path
```
3. Get the page element:
```
Use the minium_get_element tool, providing the element selector
```
4. Tap the element:
```
Use the minium_element_tap tool, providing the element selector
```
5. Enter text:
```
Use the minium_element_input tool, providing the input box selector and text content
```
6. Take a screenshot:
```
Use the minium_screenshot tool, providing the screenshot save path
```
7. Close the Mini Program:
```
Use the minium_close tool
```
### Automated Connection Process
The project implements a complete automated connection process:
1. **Connection Probing**: First, test whether the WebSocket endpoint (`ws://127.0.0.1:9420`) is available
2. **Automatic Startup**: If the connection fails, automatically start the WeChat developer tool
3. **Retry Connection**: Re-attempt the connection after waiting for the developer tool to start
4. **Error Handling**: Provides detailed error information if automatic startup fails
### Command-Line Tool Usage Examples
#### Start the MCP Server
```bash
# Start the MCP server and configure the project path and developer tool path
npx mini-test-mcp start -p "D:\project\ruijiao\test_mini" -d "D:\tool\微信web开发者工具"
```
#### Directly Start the Developer Tool
```bash
# Directly start the WeChat developer tool and open the specified project
npx mini-test-mcp devtool -p "D:\project\ruijiao\test_mini" -d "D:\tool\微信web开发者工具"
# Start with a specified port number
npx mini-test-mcp devtool -p "D:\project\ruijiao\test_mini" -d "D:\tool\微信web开发者工具" -P 9430
```
#### Automated Testing Process
```bash
# 1. Start the MCP Server
npx mini-test-mcp start -p "/path/to/miniprogram" -d "/path/to/微信开发者工具目录"
# 2. Use the automation tools in Claude Desktop for testing
# - Use minium_auto_connect to automatically connect
# - Use minium_navigate_to to navigate to the page
# - Use minium_element_tap to tap the element
# - Use minium_element_input to enter text
# - Use minium_screenshot to take a screenshot
# - Use minium_close to close the connection
```
## Migration Instructions
This project has been migrated from the Minium framework to the miniprogram-automator framework. Main changes:
1. Replaced dependencies: from minium to miniprogram-automator
2. Updated API calling method: Use miniprogram-automator's API to replace Minium's command-line calls
3. Optimized code structure: Simplified the implementation of the command-line tool, directly using the JavaScript API
4. Improved error handling: Use try-catch and Promise to handle asynchronous operations
5. New features:
- Command-line parameters support project path and developer tool path
- Automated connection process (connection probing → automatic startup → retry connection)
- Developer tool management tools
- Customizable port number support
- Configuration management features
## Precautions
- Make sure you have correctly installed the WeChat developer tool and enabled the automation port before use
- Make sure the WeChat developer tool is configured correctly
- Make sure the device is connected and debugging mode is enabled
- The command-line tool will create a `mini-config.json` file in the current directory to save the configuration
- Developer tool startup requires the use of the `cli.bat` command-line tool
- The MCP server needs to be used in conjunction with a client (such as Claude Desktop), and will exit if run alone
### WeChat Developer Tool Startup Behavior Description
When using the `mini-test-mcp devtool` command to start the WeChat developer tool:
1. **CLI Process Behavior is Normal**: The `cli.bat` process will exit immediately after starting (exit code 0), which is normal behavior
2. **Developer Tool GUI Continues to Run**: The actual WeChat developer tool GUI window will remain open
3. **Status Management**: The system will correctly mark the developer tool as running, even if the CLI process has exited
4. **Automated Connection**: The automated connection function will work normally and can connect to the WebSocket endpoint for testing
This design is because `cli.bat` is just a launcher, it is responsible for opening the developer tool GUI and then exiting itself. The developer tool GUI will continue to run as an independent process.
## Troubleshooting
### Connection Issues
- **Problem**: Unable to connect to the Mini Program automation service
- **Solution**: Use the `minium_auto_connect` tool, which will automatically test the connection and start the developer tool if it fails
### Developer Tool Startup Issues
- **Problem**: The developer tool cannot be started
- **Solution**: Make sure to use the `cli.bat` command-line tool, check whether the path configuration is correct
### Port Number Conflicts
- **Problem**: The port number is occupied
- **Solution**: Use the `-P` parameter to specify a different port number, such as `-P 9430`
### Permission Issues
- **Problem**: Insufficient Node.js permissions
- **Solution**: Make sure Node.js has sufficient permissions to perform related operations
### Configuration Issues
- **Problem**: Incomplete or incorrect configuration
- **Solution**: Use the `devtool_validate_config` tool to validate the configuration, use the `config_get` tool to view the current configuration
### CLI Command Issues
- **Problem**: The `mini-test-mcp` command is not available
- **Solution**: If the command is still not available after using `npm link`, you can try running the command directly using `node cli.js`
## References
- [WeChat Mini Program Automated Testing Official Documentation](https://developers.weixin.qq.com/miniprogram/dev/devtools/auto/quick-start.html)
## License
MIT
