miniprogram-automator

让 AI 成为你小程序测试的最佳拍档——自动化控制 WeChat DevTools，一句话完成页面巡检、元素操作、数据验证和用例执行。

🎯 这是什么

miniprogram-automator 是一个基于 Model Context Protocol (MCP) 的智能小程序测试服务器。它将微信官方 miniprogram-automator SDK 封装为一组结构化工具，无缝接入 OpenCode，让 AI Agent 能够直接操控 WeChat DevTools 完成端到端测试——无需手动点击，真正的 AI 驱动测试工作流。

一句话：把你平时用鼠标做的事情，交给 AI。

✨ 核心能力

🤖 AI 原生集成

接入 OpenCode 后，通过自然语言描述即可驱动小程序。AI 能自主观察页面状态、执行操作、验证数据，形成"观察 → 决策 → 执行 → 验证"的闭环。

🔧 全链路工具覆盖

维度	能做什么
连接管理	一键启动或连接 WeChat DevTools，支持自动化参数自定义
页面导航	任意页面切换（navigateTo / redirectTo / reLaunch / switchTab / navigateBack），获取完整页面栈
元素交互	CSS 选择器精确定位，tap / input / longpress / waitFor 等操作全覆盖
数据注入	直接读写小程序 data，调用 wx.* 接口，在小程序上下文执行任意 JS
视觉验证	页面截图（base64 直出），WXML 结构快照（截取前 10000 字符）
自动化测试	对 UniApp 项目执行完整的 Jest + @dcloudio/uni-automator e2e 测试套件

⚡ 开箱即用

一条命令完成安装与启动，npx 零配置运行。OpenCode 用户只需在配置文件中加一行，即可在 AI 对话中直接调用全部工具。

🚀 快速上手

安装

# 全局安装
npm install -g miniprogram-automator

# 或直接运行（无需安装）
npx miniprogram-automator

OpenCode 集成

在项目根目录 opencode.json 中添加：

{
  "mcp": {
    "miniprogram-automator": {
      "type": "local",
      "command": ["npx", "-y", "miniprogram-automator"],
      "enabled": true
    }
  }
}

连接小程序

方式一：AI 自动启动（推荐）

在 OpenCode 中直接告诉 AI：

帮我连接到 /path/to/your/miniprogram-project

AI 会调用 mp_launch，自动启动 WeChat DevTools 并建立连接。

方式二：连接已有实例

1. 打开 WeChat DevTools → 设置 → 安全设置 → 勾选"启用 CLI/HTTP 调用"
2. 通过命令行启动 DevTools：

   cli --auto /path/to/project --auto-port 9420

3. 在 OpenCode 中使用 mp_connect，AI 即能控制已运行的实例

典型 AI 对话示例

用户：截图看看当前页面
AI：  [调用 mp_screenshot]

用户：点一下登录按钮，然后检查是否跳转到了首页
AI：  [调用 mp_tap] → [调用 mp_currentPage 验证路径]

用户：在输入框里填写手机号 13800138000，然后提交
AI：  [调用 mp_input] → [调用 mp_tap 触发提交按钮]

用户：运行一下项目的 e2e 测试
AI：  [调用 mp_runTests，传入 projectPath]

📋 全部工具一览

连接管理

工具	说明
mp_launch	启动 WeChat DevTools 并连接项目
mp_connect	连接已运行的 DevTools 实例（WebSocket）
mp_close	关闭当前会话
mp_status	查看连接状态

页面导航

工具	说明
mp_navigate	页面导航（支持 5 种模式）
mp_currentPage	获取当前页面信息（路径、参数、尺寸、滚动位置）
mp_getPageStack	获取完整页面栈

元素交互

工具	说明
mp_snapshot	获取页面 WXML 快照（结构化元素树）
mp_query	CSS 选择器查询元素属性（tagName / text / value / size / offset）
mp_tap	点击元素
mp_input	向输入框填入文本
mp_longpress	长按元素
mp_waitFor	等待元素出现或等待指定时间

数据与接口

工具	说明
mp_getData	读取页面 data（支持深层 keyPath）
mp_setData	修改页面 data
mp_evaluate	在小程序 AppService 上下文执行任意 JS
mp_callWx	调用微信小程序 API（wx.showToast / wx.getSystemInfo 等）
mp_screenshot	页面截图（base64 编码返回）

测试执行

工具	说明
mp_runTests	对 UniApp 项目执行 Jest e2e 测试套件
mp_testConfig	输出完整的 UniApp e2e Jest 配置模板

🧪 UniApp E2E 测试

对于使用 UniApp 开发的跨平台小程序，本工具支持直接运行 UniApp 官方 e2e 测试框架：

# 确保目标项目已安装依赖
npm install --save-dev jest @dcloudio/uni-automator

# 通过 AI 执行测试（自动传入 UNI_PLATFORM）
mp_runTests({ projectPath: "/path/to/uniapp/project" })

测试结果（通过/失败状态、输出摘要）直接返回到 AI 对话中，无需切换窗口查看。

获取配置示例：

mp_testConfig({ projectPath: "/path/to/project" })

📌 环境要求

要求	说明
Node.js	>= 18
WeChat DevTools	最新版，CLI/HTTP 已启用（安全设置中开启）
UniApp e2e	UniApp 项目已配置 Jest + @dcloudio/uni-automator

🏗️ 技术架构

src/
├── index.ts              # MCP Server 入口（StdioServerTransport）
├── session.ts            # Session 状态机（launch / connect / close）
├── types.ts              # TypeScript 类型定义
└── tools/
    ├── connection.ts     # 连接管理工具
    ├── navigation.ts     # 页面导航工具
    ├── element.ts        # 元素交互工具
    ├── data.ts           # 数据与接口工具
    └── testing.ts        # UniApp e2e 测试工具

技术栈： TypeScript（strict 模式）+ @modelcontextprotocol/sdk + miniprogram-automator + zod v4

🤝 贡献

欢迎提交 Issue 和 Pull Request！如果你发现了一个 bug或有新功能建议，请先搜索是否已有相关讨论。

📄 License

MIT