weixin-devtools-mcp 0.0.1 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Wooter Shen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,18 +2,19 @@
 
 > 强大的微信小程序自动化测试解决方案，基于 Model Context Protocol 实现
 
-[![Version](https://img.shields.io/badge/version-0.3.3-blue.svg)](https://github.com/yourusername/weixin-devtools-mcp)
+[![Version](https://img.shields.io/badge/version-0.3.3-blue.svg)](https://github.com/wooter-s/weixin-devtools-mcp)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
 
 ## ✨ 核心特性
 
-- 🚀 **31个专业工具** - 覆盖连接、查询、交互、断言、导航、调试等完整测试场景
+- 🚀 **31个专业工具（full profile）** - 覆盖连接、查询、交互、断言、导航、调试等完整测试场景
 - 🤖 **智能连接** - 支持 auto/launch/connect 三种模式，自动端口检测，无需手动配置
 - 🔍 **自动网络监控** - 连接时自动启动，实时拦截 wx.request/uploadFile/downloadFile
-- ✅ **完整断言体系** - 5类断言工具，验证元素存在、可见性、文本、属性、状态
+- ✅ **完整断言体系** - 3类断言工具（`assert_text`/`assert_attribute`/`assert_state`），覆盖文本、属性与状态校验
 - 📸 **丰富调试能力** - 支持页面截图、Console 监听、网络请求追踪、诊断工具
 - 🏗️ **模块化架构** - 基于 chrome-devtools-mcp 架构模式，易于扩展和维护
+- 🧩 **可配置工具暴露** - 默认 core profile（20个工具），支持按类别开启 Console/Network/Debug
 - 🧪 **全面测试覆盖** - 单元测试 + 集成测试，测试覆盖率 >80%
 
 ## 📦 安装
@@ -41,7 +42,7 @@ npm install -g weixin-devtools-mcp
 
 ```bash
 # 克隆项目
-git clone https://github.com/yourusername/weixin-devtools-mcp.git
+git clone https://github.com/wooter-s/weixin-devtools-mcp.git
 cd weixin-devtools-mcp
 
 # 安装依赖
@@ -89,13 +90,56 @@ npm run build
 
 ### 配置方式三：开发者本地路径
 
-如果从源码安装，使用绝对路径：
+如果从源码安装，推荐通过 Node.js 启动构建产物（跨平台）：
 
 ```json
 {
   "mcpServers": {
     "weixin-devtools-mcp": {
-      "command": "/path/to/weixin-devtools-mcp/build/server.js"
+      "command": "node",
+      "args": ["/path/to/weixin-devtools-mcp/build/server.js"]
+    }
+  }
+}
+```
+
+### 工具 Profile 配置（v0.4+）
+
+服务器支持按 profile 控制暴露工具，降低默认工具数量：
+
+- `core`（默认）：20 个核心自动化工具
+- `full`：31 个完整工具
+- `minimal`：10 个最小工具
+
+也支持按类别增减：
+
+- `--enable-categories=console,network,debug`
+- `--disable-categories=console,network,debug,core`
+
+`npx` 配置示例（启用 full）：
+
+```json
+{
+  "mcpServers": {
+    "weixin-devtools-mcp": {
+      "command": "npx",
+      "args": ["-y", "weixin-devtools-mcp", "--tools-profile=full"]
+    }
+  }
+}
+```
+
+本地构建产物示例（在 core 基础上启用 network + debug）：
+
+```json
+{
+  "mcpServers": {
+    "weixin-devtools-mcp": {
+      "command": "node",
+      "args": [
+        "/path/to/weixin-devtools-mcp/build/server.js",
+        "--enable-categories=network,debug"
+      ]
     }
   }
 }
@@ -106,130 +150,44 @@ npm run build
 ### 第一个自动化测试
 
 ```typescript
-// 1. 智能连接到微信开发者工具（自动检测端口）
-connect_devtools_enhanced({
+// 1. 连接微信开发者工具（auto 策略）
+connect_devtools({
   projectPath: "/path/to/your/miniprogram",
-  mode: "auto",
+  strategy: "auto",
   verbose: true
 })
 
 // 2. 查找登录按钮
-$({ selector: "button.login-btn" })
+query_selector({ selector: "button.login-btn" })
 
 // 3. 点击登录按钮
 click({ uid: "button.login-btn" })
 
 // 4. 等待登录成功
-waitFor({ selector: ".welcome-message", timeout: 5000 })
+wait_for({ selector: ".welcome-message", timeout: 5000 })
 
 // 5. 验证登录成功
 assert_text({ uid: ".welcome-message", text: "欢迎回来" })
 
-// 6. 获取页面截图
+// 6. 获取页面截图（需在服务启动参数中启用 --enable-categories=debug）
 screenshot({ path: "/tmp/login-success.png" })
 ```
 
 ## 🛠️ 功能概览
 
-项目提供 **31个工具**，分为 8 大类别：
-
-| 类别 | 工具数 | 主要功能 |
-|------|--------|----------|
-| **连接管理** | 3个 | 智能连接、传统连接、获取当前页面 |
-| **页面查询** | 3个 | CSS选择器查找、条件等待、页面快照 |
-| **交互操作** | 7个 | 点击、输入、获取值、表单控件、选择器、开关、滑块 |
-| **断言验证** | 5个 | 存在性、可见性、文本、属性、状态断言 |
-| **页面导航** | 6个 | 跳转、返回、Tab切换、重启、重定向、页面信息 |
-| **调试工具** | 5个 | 截图、Console监听、日志获取、日志清空 |
-| **网络监控** | 5个 | 请求拦截、监听控制、请求获取、清空记录、拦截器诊断 |
-| **诊断工具** | 3个 | 连接诊断、环境检查、元素调试 |
-
-### 工具详细列表
-
-<details>
-<summary><b>连接管理（3个工具）</b></summary>
-
-- `connect_devtools` - 传统连接方式（兼容性）
-- `connect_devtools_enhanced` - 智能连接，支持三种模式，自动端口检测（推荐）
-- `get_current_page` - 获取当前活动页面信息
-
-</details>
-
-<details>
-<summary><b>页面查询和快照（3个工具）</b></summary>
+当前工具暴露采用 profile 机制：
 
-- `$` - 通过CSS选择器查找元素，返回详细信息
-- `waitFor` - 等待条件满足（时间/元素出现/消失/文本匹配）
-- `get_page_snapshot` - 获取完整页面快照和所有元素UID
-
-</details>
-
-<details>
-<summary><b>交互操作（7个工具）</b></summary>
-
-- `click` - 点击元素（支持单击/双击）
-- `input_text` - 向input/textarea输入文本
-- `get_value` - 获取元素的值或文本内容
-- `set_form_control` - 设置表单控件的值
-- `select_picker` - 选择picker控件选项
-- `toggle_switch` - 切换switch开关状态
-- `set_slider` - 设置slider滑块值
-
-</details>
-
-<details>
-<summary><b>断言验证（5个工具）</b></summary>
-
-- `assert_exists` - 断言元素存在或不存在
-- `assert_visible` - 断言元素可见或不可见
-- `assert_text` - 断言元素文本内容（精确/包含/正则）
-- `assert_attribute` - 断言元素属性值
-- `assert_state` - 断言元素状态（选中/启用/聚焦/可见）
-
-</details>
-
-<details>
-<summary><b>页面导航（6个工具）</b></summary>
-
-- `navigate_to` - 跳转到指定页面
-- `navigate_back` - 返回上一页
-- `switch_tab` - 切换到指定Tab页
-- `relaunch` - 重启小程序并跳转到指定页面
-- `redirect_to` - 关闭当前页并跳转
-- `get_page_info` - 获取当前页面详细信息
-
-</details>
-
-<details>
-<summary><b>调试工具（5个工具）</b></summary>
-
-- `screenshot` - 页面截图（返回base64或保存文件）
-- `start_console_monitoring` - 开始监听console和exception
-- `stop_console_monitoring` - 停止console监听
-- `get_console` - 获取收集的console消息
-- `clear_console` - 清空console缓存
-
-</details>
-
-<details>
-<summary><b>网络监控（5个工具）</b></summary>
-
-- `start_network_monitoring` - 开始监听网络请求
-- `stop_network_monitoring` - 停止网络监听
-- `get_network_requests` - 获取拦截的网络请求（支持过滤）
-- `clear_network_requests` - 清空网络请求记录
-- `diagnose_interceptor` - 诊断网络拦截器状态
-
-</details>
-
-<details>
-<summary><b>诊断工具（3个工具）</b></summary>
-
-- `diagnose_connection` - 诊断连接问题，检查配置和环境
-- `check_environment` - 检查自动化环境配置
-- `debug_page_elements` - 调试页面元素获取问题
-
-</details>
+- `core`（默认，20个）：
+  - 连接/页面：`connect_devtools`、`reconnect_devtools`、`disconnect_devtools`、`get_connection_status`、`get_current_page`、`get_page_snapshot`、`query_selector`、`wait_for`
+  - 交互：`click`、`input_text`、`get_value`、`set_form_control`
+  - 断言：`assert_text`、`assert_attribute`、`assert_state`
+  - 导航：`navigate_to`、`navigate_back`、`switch_tab`、`relaunch`
+  - 脚本：`evaluate_script`
+- 可选类别（默认关闭）：
+  - `console`：`list_console_messages`、`get_console_message`
+  - `network`：`list_network_requests`、`get_network_request`、`stop_network_monitoring`、`clear_network_requests`
+  - `debug`：`screenshot`、`diagnose_connection`、`check_environment`、`debug_page_elements`、`debug_connection_flow`
+- `full` profile：暴露全部 31 个工具。
 
 ## 💡 使用示例
 
@@ -237,31 +195,32 @@ screenshot({ path: "/tmp/login-success.png" })
 
 ```typescript
 // 连接到开发者工具
-connect_devtools_enhanced({
+connect_devtools({
   projectPath: "/path/to/miniprogram",
-  mode: "auto"
+  strategy: "auto"
 })
 
 // 输入用户名
-$({ selector: "input#username" })
+query_selector({ selector: "input#username" })
 input_text({ uid: "input#username", text: "testuser" })
 
 // 输入密码
-$({ selector: "input#password" })
+query_selector({ selector: "input#password" })
 input_text({ uid: "input#password", text: "password123" })
 
 // 点击登录按钮
-$({ selector: "button.login" })
+query_selector({ selector: "button.login" })
 click({ uid: "button.login" })
 
 // 等待登录成功
-waitFor({ selector: ".welcome", timeout: 5000 })
+wait_for({ selector: ".welcome", timeout: 5000 })
 
 // 验证欢迎消息
 assert_text({ uid: ".welcome", textContains: "欢迎" })
 
-// 检查网络请求
-get_network_requests({ urlPattern: "/api/login", successOnly: true })
+// 检查网络请求（两阶段查询，需在服务启动参数中启用 --enable-categories=network）
+const requests = list_network_requests({ urlPattern: "/api/login", successOnly: true })
+get_network_request({ reqid: requests[0].reqid })
 ```
 
 ### 示例 2：表单填写和提交
@@ -272,22 +231,22 @@ input_text({ uid: "input#name", text: "张三" })
 input_text({ uid: "input#email", text: "zhangsan@example.com" })
 
 // 选择下拉框
-select_picker({ uid: "picker#city", value: "北京" })
+set_form_control({ uid: "picker#city", value: "北京" })
 
 // 切换开关
-toggle_switch({ uid: "switch#agree", checked: true })
+set_form_control({ uid: "switch#agree", value: true })
 
 // 设置滑块
-set_slider({ uid: "slider#age", value: 25 })
+set_form_control({ uid: "slider#age", value: 25 })
 
 // 提交表单
 click({ uid: "button.submit" })
 
 // 等待提交成功
-waitFor({ selector: ".success-toast", timeout: 3000 })
+wait_for({ selector: ".success-toast", timeout: 3000 })
 
 // 验证提交结果
-assert_visible({ uid: ".success-toast", visible: true })
+assert_state({ uid: ".success-toast", visible: true })
 assert_text({ uid: ".success-toast", text: "提交成功" })
 
 // 截图保存结果
@@ -307,17 +266,35 @@ screenshot({ path: "/tmp/form-submit-success.png" })
 
 ### 构建和测试
 
+项目采用分层测试架构，分为协议测试、工具测试和集成测试：
+
 ```bash
 # 开发模式（监听文件变化）
 npm run watch
 
-# 运行单元测试
+# 运行单元测试（协议 + 工具 + 工具类）
 npm test
 
+# 分类运行单元测试
+npm run test:protocol      # 协议层测试
+npm run test:tools         # 工具逻辑测试
+
 # 运行集成测试（需要微信开发者工具）
 npm run test:integration
 
-# 运行所有测试
+# 推荐：复用现有 DevTools 会话，避免反复重启项目（默认）
+INTEGRATION_CLEANUP_MODE=reuse npm run test:integration
+
+# 如需强制隔离环境（CI 或排查端口脏状态）
+INTEGRATION_CLEANUP_MODE=force npm run test:integration
+
+# 禁用跨 suite 会话复用（仅调试时建议）
+INTEGRATION_REUSE_SESSION=false npm run test:integration
+
+# 如需每个 suite 结束后强制断开（默认不强制）
+INTEGRATION_FORCE_DISCONNECT_AFTER_EACH_SUITE=true npm run test:integration
+
+# 运行所有测试（单元 + 集成）
 npm run test:all
 
 # 生成测试覆盖率报告
@@ -327,17 +304,39 @@ npm run test:coverage
 npm run inspector
 ```
 
+### 手工验证与诊断
+
+- 连接诊断能力通过 MCP 工具提供：启用 `debug` 类别后调用 `diagnose_connection`、`check_environment`、`debug_connection_flow`
+- 截图调试通过 MCP 工具提供：启用 `debug` 类别后调用 `screenshot`
+- 集成测试夹具项目固定为 `playground/wx/`，请勿移动或删除目录
+- 夹具关键文件白名单：`playground/wx/app.json`、`playground/wx/project.config.json`
+
 ### 添加新工具
 
 1. 在 `src/tools/` 下创建或修改工具模块
 2. 使用 `ToolDefinition` 框架定义工具
 3. 在 `src/tools/index.ts` 中导出工具
-4. 编写单元测试（`tests/*.test.ts`）
-5. 编写集成测试（`tests/*.integration.test.ts`）
+4. 编写单元测试（`tests/tools/*.test.ts` 或 `tests/protocol/*.test.ts`）
+5. 编写集成测试（`tests/integration/*.integration.test.ts`）
 6. 更新文档
 
 详细开发指南请参考 [CLAUDE.md](CLAUDE.md)
 
+### 测试架构
+
+项目采用三层测试架构（参考 chrome-devtools-mcp）：
+
+- **协议层测试** (`tests/protocol/`) - 测试 MCP 服务器协议实现
+- **工具逻辑测试** (`tests/tools/`) - 直接测试工具 handler，无需服务器
+- **集成测试** (`tests/integration/`) - 端到端测试，需要真实环境
+
+集成测试支持以下运行模式：
+- `INTEGRATION_CLEANUP_MODE=reuse`：复用已有 DevTools 实例（默认）
+- `INTEGRATION_CLEANUP_MODE=smart`：优雅关闭后重连
+- `INTEGRATION_CLEANUP_MODE=force`：强制清理全部实例
+- `INTEGRATION_REUSE_SESSION=true/false`：控制跨 suite 连接复用
+- `INTEGRATION_FORCE_DISCONNECT_AFTER_EACH_SUITE=true/false`：控制每个 suite 结束后是否强制断连（默认 `false`）
+
 ## 📋 系统要求
 
 - **Node.js** >= 16.0.0
@@ -367,7 +366,7 @@ npm run inspector
 
 ## 📞 联系方式
 
-- 问题反馈：[GitHub Issues](https://github.com/yourusername/weixin-devtools-mcp/issues)
+- 问题反馈：[GitHub Issues](https://github.com/wooter-s/weixin-devtools-mcp/issues)
 - 文档网站：[项目文档](docs/)
 
 ---