Content
# Mini-test MCP
This is a MCP (Model Context Protocol) project for calling WeChat Mini Program automation testing framework.
## 🚀 Main Features
### Core Functions
- **Intelligent Connection Management**: Automatic test connection, automatic launch of developer tools on failure
- **Mini Program Automation**: Page navigation, element operation, data management
- **Developer Tool Integration**: Automatic launch/close of WeChat developer tools
- **Configuration Management**: Support for command-line parameter configuration of project path and tool path
### Automation Features
- **Connection Probe Mechanism**: Test WebSocket endpoint availability before connection
- **Automatic Recovery**: Automatic launch of required services on connection failure
- **Custom Port Number**: Support for custom WebSocket port number
- **Real-time Logs**: Capture developer tool and console output
### New Features
- **Command-line Parameter Support**: Configure paths through `-p/--project` and `-d/--devtool` parameters
- **Automated Connection Process**: Automatic use of `cli.bat` to launch developer tools on connection failure
- **Custom Port Number**: Support for specifying port number through `-P/--port` parameter
- **Developer Tool Management**: Added developer tool launch, stop, and status query tools
- **Configuration Verification**: Automatic verification of configuration integrity
## Quick Start
```bash
# Directly launch developer tools
npx mini-test-mcp devtool -p "/path/to/miniprogram" -d "/path/to/WeChat developer tool directory"
# Launch MCP server
npx mini-test-mcp start -p "/path/to/miniprogram" -d "/path/to/WeChat developer tool directory"
```
## Prerequisites
Before using this project, ensure the following software is installed:
1. Node.js (v14 or higher)
2. WeChat developer tools
3. Connected Android/iOS device or simulator
## Installation
### Use npx directly (recommended)
No installation required, use npx directly:
```bash
npx mini-test-mcp start -p "miniprogram project path" -d "WeChat developer tool path"
```
### 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 command-line tool (optional):
```bash
npm link
```
## Usage
### As MCP Server
1. Add this server to Claude Desktop configuration file:
```json
{
"mcpServers": {
"mini-test": {
"command": "npx",
"args": ["mini-test-mcp", "start", "-p", "/path/to/miniprogram", "-d", "/path/to/WeChat developer tool directory"],
"env": {}
}
}
}
```
2. Restart Claude Desktop to use mini program automation related tools
### As Command-line Tool
After installation, use `mini-test-mcp` command to operate mini program automation:
#### Launch MCP Server
```bash
# Launch MCP server and configure project path and developer tool path
mini-test-mcp start -p "/path/to/miniprogram" -d "/path/to/WeChat developer tool directory"
# Or use npx
npx mini-test-mcp start -p "/path/to/miniprogram" -d "/path/to/WeChat developer tool directory"
```
#### Directly Launch WeChat Developer Tools
```bash
# Directly launch WeChat developer tools and open specified project
mini-test-mcp devtool -p "/path/to/miniprogram" -d "/path/to/WeChat developer tool directory"
# Specify port number to launch
mini-test-mcp devtool -p "/path/to/miniprogram" -d "/path/to/WeChat developer tool directory" -P 9430
```
#### View Help
```bash
mini-test-mcp help
# Or use npx
npx mini-test-mcp help
```
## Release
If you are a project maintainer, use the following command to release a new version:
```bash
npm run publish
```
This will check your npm login status and guide you through the release process.
## Contribution
Welcome to submit issues and pull requests to improve this project.
## License
MIT
### Available Tools
#### Connection Management Tools
- `minium_connect`: Connect to mini program automation service
- Parameters: `wsEndpoint` (WebSocket endpoint address)
- `minium_auto_connect`: Automatically connect to mini program automation service
- Parameters: None (use default endpoint, automatically launch developer tools)
- `minium_close`: Close mini program connection
- Parameters: None
- `minium_get_console_logs`: Get console logs
- Parameters: None
#### Navigation Tools
- `minium_navigate_to`: Navigate to specified page
- Parameters: `url` (page path)
- `minium_switch_tab`: Switch to specified tab
- Parameters: `url` (tab path)
#### Element Operation Tools
- `minium_get_element`: Get page element
- Parameters: `selector` (element selector)
- `minium_get_elements`: Get element array
- Parameters: `selector` (element selector)
- `minium_element_tap`: Tap element
- Parameters: `selector` (element selector)
- `minium_element_input`: Input text into element
- Parameters: `selector` (element selector), `value` (text to input)
- `minium_element_text`: Get element text
- Parameters: `selector` (element selector)
- `minium_element_attribute`: Get element attribute
- Parameters: `selector` (element selector), `name` (attribute name)
- `minium_element_property`: Get element property
- Parameters: `selector` (element selector), `name` (property name)
- `minium_element_size`: Get element size
- Parameters: `selector` (element selector)
- `minium_element_offset`: Get element position
- Parameters: `selector` (element selector)
- `minium_wait_for_element`: Wait for element to appear
- Parameters: `selector` (element selector), `timeout` (timeout, optional)
#### Page Operation Tools
- `minium_page_size`: Get page size
- Parameters: None
- `minium_page_data`: Get page data
- Parameters: `path` (data path, optional)
- `minium_page_set_data`: Set page data
- Parameters: `data` (data to set)
- `minium_page_call_method`: Call page method
- Parameters: `method` (method name), `args` (argument array, optional)
#### Developer Tool Management
- `devtool_start`: Launch developer tools
- Parameters: `port` (port number, optional)
- `devtool_stop`: Close developer tools
- Parameters: None
- `devtool_status`: Get developer tool status
- Parameters: None
- `devtool_validate_config`: Verify configuration
- Parameters: None
#### Utility Tools
- `minium_wait`: Wait for specified time
- Parameters: `ms` (milliseconds to wait)
- `minium_screenshot`: Take screenshot
- Parameters: `path` (screenshot save path)
- `config_get`: Get configuration information
- Parameters: None
## Usage Examples
### MCP Server Usage Example
1. Automatically connect to mini program automation service:
```
Use minium_auto_connect tool
```
- This tool will automatically test connection, and if connection fails, it will automatically launch developer tools and retry connection
2. Navigate to specified page:
```
Use minium_navigate_to tool, provide page path
```
3. Get page element:
```
Use minium_get_element tool, provide element selector
```
4. Tap element:
```
Use minium_element_tap tool, provide element selector
```
5. Input text:
```
Use minium_element_input tool, provide input box selector and text content
```
6. Take screenshot:
```
Use minium_screenshot tool, provide screenshot save path
```
7. Close mini program:
```
Use minium_close tool
```
### Automation Connection Process
The project implements a complete automation connection process:
1. **Connection Probe**: Test WebSocket endpoint (`ws://127.0.0.1:9420`) availability
2. **Automatic Launch**: If connection fails, automatically launch WeChat developer tools
3. **Retry Connection**: Wait for developer tools to launch and then retry connection
4. **Error Handling**: If automatic launch fails, provide detailed error information
### Command-line Tool Usage Example
#### Launch MCP Server
```bash
# Launch MCP server and configure project path and developer tool path
npx mini-test-mcp start -p "D:\project\ruijiao\test_mini" -d "D:\tool\WeChat web developer tool"
```
#### Directly Launch Developer Tools
```bash
# Directly launch WeChat developer tools and open specified project
npx mini-test-mcp devtool -p "D:\project\ruijiao\test_mini" -d "D:\tool\WeChat web developer tool"
# Specify port number to launch
npx mini-test-mcp devtool -p "D:\project\ruijiao\test_mini" -d "D:\tool\WeChat web developer tool" -P 9430
```
#### Automation Test Process
```bash
# 1. Launch MCP server
npx mini-test-mcp start -p "/path/to/miniprogram" -d "/path/to/WeChat developer tool directory"
# 2. Use automation tools in Claude Desktop for testing
# - Use minium_auto_connect to automatically connect
# - Use minium_navigate_to to navigate to page
# - Use minium_element_tap to tap element
# - Use minium_element_input to input text
# - Use minium_screenshot to take screenshot
# - Use minium_close to close connection
```
## Migration Notes
This project has been migrated from Minium framework to miniprogram-automator framework. Main changes:
1. Replaced dependencies: from minium to miniprogram-automator
2. Updated API calls: use miniprogram-automator API instead of Minium command-line calls
3. Optimized code structure: simplified command-line tool implementation, directly use JavaScript API
4. Improved error handling: use try-catch and Promise to handle asynchronous operations
5. Added features:
- Command-line parameter support for project path and developer tool path
- Automation connection process (connection probe → automatic launch → retry connection)
- Developer tool management tools
- Custom port number support
- Configuration management function
## Notes
- Ensure WeChat developer tools are correctly installed and automation port is enabled before use
- Ensure WeChat developer tools are correctly configured
- Ensure device is connected and debug mode is enabled
- Command-line tool will create `mini-config.json` file in current directory to save configuration
- Developer tools launch requires use of `cli.bat` command-line tool
- MCP server needs to be used with client (e.g. Claude Desktop), and will exit if run alone
### WeChat Developer Tool Launch Behavior Description
When using `mini-test-mcp devtool` command to launch WeChat developer tools:
1. **CLI Process Behavior Normal**: `cli.bat` process launches and exits immediately (exit code 0), this is normal behavior
2. **Developer Tool GUI Continues Running**: Actual WeChat developer tool GUI window remains open
3. **Status Management**: System correctly marks developer tools as running, even if CLI process has exited
4. **Automation Connection**: Automation connection function works normally, can connect to WebSocket endpoint for testing
This design is because `cli.bat` is just a launcher, it is responsible for opening developer tool GUI, then exits itself. Developer tool GUI runs as an independent process.
## Troubleshooting
### Connection Issues
- **Problem**: Unable to connect to mini program automation service
- **Solution**: Use `minium_auto_connect` tool, it will automatically test connection and launch developer tools on failure
### Developer Tool Launch Issues
- **Problem**: Developer tools cannot be launched
- **Solution**: Ensure use of `cli.bat` command-line tool, check path configuration is correct
### Port Number Conflict
- **Problem**: Port number is occupied
- **Solution**: Use `-P` parameter to specify different port number, e.g. `-P 9430`
### Permission Issues
- **Problem**: Node.js permission is insufficient
- **Solution**: Ensure Node.js has sufficient permissions to execute related operations
### Configuration Issues
- **Problem**: Configuration is incomplete or incorrect
- **Solution**: Use `devtool_validate_config` tool to verify configuration, use `config_get` tool to view current configuration
### CLI Command Issues
- **Problem**: `mini-test-mcp` command is unavailable
- **Solution**: If using `npm link` and still unable to use command, try directly using `node cli.js` to run command
## References
- [WeChat Mini Program Automation Test Official Documentation](https://developers.weixin.qq.com/miniprogram/dev/devtools/auto/quick-start.html)
## License
MIT
