@weapp-vite/miniprogram-automator 1.0.1 → 1.0.2

package/README.md

@@ -1,7 +1,98 @@
 # @weapp-vite/miniprogram-automator
 
-面向 `weapp-vite` 生态的现代化 `miniprogram-automator` 兼容实现。
+## 1. 简介
 
-- 提供纯根入口 named exports
-- 对齐官方 `MiniProgram / Page / Element / Native` 能力模型
-- 支持 DevTools 启动、WebSocket 协议连接与 headless 适配
+`@weapp-vite/miniprogram-automator` 是面向 `weapp-vite` 生态维护的 `miniprogram-automator` 兼容实现，目标是在保留官方心智模型的前提下，提供更现代的 ESM 导出、类型支持与 headless 调试能力。
+
+它同时服务于：
+
+- `weapp-ide-cli` 的自动化能力
+- 仓库内 WeChat DevTools 相关 e2e 测试
+- 需要直接连接微信开发者工具 WebSocket 协议的 Node 工具
+
+## 2. 特性
+
+- 对齐官方常见对象模型：`MiniProgram`、`Page`、`Element`、`Native`
+- 提供 `Launcher` 用于启动、连接和复用 DevTools 会话
+- 支持截图、输入、滚动、点击、页面跳转等自动化操作
+- 默认输出现代 ESM 与完整类型声明
+- 内置二维码打印与解码辅助能力，便于配合登录、连接流程调试
+- 支持 headless 自动化启动入口
+
+## 3. 安装
+
+```bash
+pnpm add -D @weapp-vite/miniprogram-automator
+```
+
+> **注意**：运行前仍需要本机安装微信开发者工具，并开启服务端口。
+
+## 4. 快速开始
+
+### 4.1 连接现有会话
+
+```ts
+import { Launcher } from '@weapp-vite/miniprogram-automator'
+
+const launcher = new Launcher()
+const miniProgram = await launcher.connect({
+  wsEndpoint: 'ws://127.0.0.1:9420',
+})
+
+const page = await miniProgram.currentPage()
+console.log(await page.data())
+```
+
+### 4.2 启动并打开项目
+
+```ts
+import { Launcher } from '@weapp-vite/miniprogram-automator'
+
+const launcher = new Launcher()
+const miniProgram = await launcher.launch({
+  projectPath: './dist/build/mp-weixin',
+})
+
+await miniProgram.reLaunch('/pages/index/index')
+```
+
+### 4.3 使用页面与元素对象
+
+```ts
+import { Launcher } from '@weapp-vite/miniprogram-automator'
+
+const launcher = new Launcher()
+const miniProgram = await launcher.launch({
+  projectPath: './dist/build/mp-weixin',
+})
+
+const page = await miniProgram.currentPage()
+const button = await page.$('.submit')
+
+await button?.tap()
+await page.waitFor(500)
+```
+
+## 5. 主要导出
+
+| 导出                      | 说明                                     |
+| ------------------------- | ---------------------------------------- |
+| `Launcher`                | 启动 DevTools、连接 WebSocket、创建会话  |
+| `MiniProgram`             | 小程序级操作入口，如页面跳转、获取当前页 |
+| `Page`                    | 页面级查询与操作入口                     |
+| `Element`                 | 通用节点对象，支持点击、输入、事件触发   |
+| `Native`                  | 原生能力桥接                             |
+| `launchHeadlessAutomator` | headless 启动辅助函数                    |
+
+## 6. 本地开发
+
+```bash
+pnpm --filter @weapp-vite/miniprogram-automator build
+pnpm --filter @weapp-vite/miniprogram-automator test
+pnpm --filter @weapp-vite/miniprogram-automator typecheck
+```
+
+## 7. 相关链接
+
+- 仓库：https://github.com/weapp-vite/weapp-vite
+- `weapp-ide-cli`：[../weapp-ide-cli/README.md](../weapp-ide-cli/README.md)

package/dist/index.d.mts

@@ -265,6 +265,11 @@ interface ILaunchOptions {
   cwd?: string;
   runtimeProvider?: 'devtools' | 'headless';
 }
+interface ILauncherSessionMetadata {
+  port: number;
+  projectPath: string;
+  wsEndpoint: string;
+}
 /** Launcher 的实现。 */
 declare class Launcher {
   launch(options: ILaunchOptions): Promise<any>;
@@ -301,4 +306,4 @@ declare function isPluginPath(p: string): boolean;
 /** extractPluginId 的方法封装。 */
 declare function extractPluginId(p: string): string;
 //#endregion
-export { Automator, Connection, ContextElement, CustomElement, Element, IConnectOptions, ILaunchOptions, InputElement, Launcher, MiniProgram, MovableViewElement, Native, Page, ScrollViewElement, SliderElement, SwiperElement, SwitchElement, TextareaElement, Transport, decodeQrCode, extractPluginId, isPluginPath, printQrCode };
+export { Automator, Connection, ContextElement, CustomElement, Element, IConnectOptions, ILaunchOptions, ILauncherSessionMetadata, InputElement, Launcher, MiniProgram, MovableViewElement, Native, Page, ScrollViewElement, SliderElement, SwiperElement, SwitchElement, TextareaElement, Transport, decodeQrCode, extractPluginId, isPluginPath, printQrCode };

package/dist/index.mjs

@@ -497,6 +497,7 @@ var Transport = class extends EventEmitter {
 */
 const debugProtocol = debug("automator:protocol");
 const closeErrTip = "Connection closed, check if wechat web devTools is still running";
+const REQUEST_TIMEOUT = 3e4;
 /** Connection 的实现。 */
 var Connection = class Connection extends EventEmitter {
 	callbacks = /* @__PURE__ */ new Map();
@@ -515,13 +516,22 @@ var Connection = class Connection extends EventEmitter {
 		});
 		debugProtocol(`${dateFormat("yyyy-mm-dd HH:MM:ss:l")} SEND ► ${payload}`);
 		return new Promise((resolve, reject) => {
+			const timeout = setTimeout(() => {
+				this.callbacks.delete(id);
+				const error = /* @__PURE__ */ new Error(`DevTools did not respond to protocol method ${method} within ${REQUEST_TIMEOUT}ms`);
+				error.code = "DEVTOOLS_PROTOCOL_TIMEOUT";
+				error.method = method;
+				reject(error);
+			}, REQUEST_TIMEOUT);
 			this.callbacks.set(id, {
 				resolve,
-				reject
+				reject,
+				timeout
 			});
 			try {
 				this.transport.send(payload);
 			} catch {
+				clearTimeout(timeout);
 				this.callbacks.delete(id);
 				reject(new Error(closeErrTip));
 			}
@@ -540,6 +550,7 @@ var Connection = class Connection extends EventEmitter {
 		const callback = this.callbacks.get(id);
 		if (!callback) return;
 		this.callbacks.delete(id);
+		clearTimeout(callback.timeout);
 		if (error) {
 			callback.reject(new Error(error.message || closeErrTip));
 			return;
@@ -547,7 +558,10 @@ var Connection = class Connection extends EventEmitter {
 		callback.resolve(result);
 	};
 	onClose = () => {
-		for (const callback of this.callbacks.values()) callback.reject(new Error(closeErrTip));
+		for (const callback of this.callbacks.values()) {
+			clearTimeout(callback.timeout);
+			callback.reject(new Error(closeErrTip));
+		}
 		this.callbacks.clear();
 	};
 	static create(url) {
@@ -563,11 +577,11 @@ var Connection = class Connection extends EventEmitter {
 //#endregion
 //#region src/headless.ts
 async function launchHeadlessAutomator(options) {
-	return await (await import("./launch-IFPMxQYb.mjs")).launch({ projectPath: options.projectPath });
+	return await (await import("./launch-Bd3TZy1I.mjs")).launch({ projectPath: options.projectPath });
 }
 //#endregion
 //#region package.json
-var version = "1.0.1";
+var version = "1.0.2";
 //#endregion
 //#region src/Native.ts
 /** Native 的实现。 */
@@ -755,9 +769,24 @@ function extractPluginId(p) {
 }
 //#endregion
 //#region src/MiniProgram.ts
+const CLOSE_STEP_TIMEOUT = 2e3;
 function sleep(ms) {
 	return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function withTimeout(task, timeoutMs) {
+	return new Promise((resolve, reject) => {
+		const timeout = setTimeout(() => {
+			reject(/* @__PURE__ */ new Error(`Operation timed out after ${timeoutMs}ms`));
+		}, timeoutMs);
+		task.then((value) => {
+			clearTimeout(timeout);
+			resolve(value);
+		}).catch((error) => {
+			clearTimeout(timeout);
+			reject(error);
+		});
+	});
+}
 function isFnStr(value) {
 	if (!isStr(value)) return false;
 	const trimmed = trim(value);
@@ -878,11 +907,14 @@ var MiniProgram = class extends EventEmitter {
 	}
 	async close() {
 		try {
-			await this.send("App.exit");
+			await withTimeout(this.send("App.exit"), CLOSE_STEP_TIMEOUT);
 		} catch {}
 		await sleep(1e3);
-		await this.send("Tool.close");
-		this.disconnect();
+		try {
+			await withTimeout(this.send("Tool.close"), CLOSE_STEP_TIMEOUT);
+		} catch {} finally {
+			this.disconnect();
+		}
 	}
 	async remote(auto = false) {
 		const { qrCode } = await this.send("Tool.enableRemoteDebug", { auto });
@@ -972,7 +1004,11 @@ const DEFAULT_PORT = 9420;
 const DEFAULT_TIMEOUT = 3e4;
 const DEFAULT_RUNTIME_PROVIDER_ENV = "WEAPP_VITE_AUTOMATOR_RUNTIME_PROVIDER";
 const LEGACY_RUNTIME_PROVIDER_ENV = "WEAPP_VITE_E2E_RUNTIME_PROVIDER";
+const EXTENSION_CONTEXT_INVALIDATED_RE = /Extension context invalidated/i;
 let localhostListenPatched = false;
+function isExtensionContextInvalidatedError(error) {
+	return error instanceof Error && EXTENSION_CONTEXT_INVALIDATED_RE.test(error.message);
+}
 function patchNetListenToLoopback() {
 	if (localhostListenPatched) return;
 	localhostListenPatched = true;
@@ -1039,22 +1075,38 @@ var Launcher = class {
 			processError = error;
 		}
 		let miniProgram = null;
+		let lastConnectError = null;
 		await waitUntil(async () => {
 			try {
 				if (processError || exited) return true;
-				miniProgram = await this.connectTool({ wsEndpoint: `ws://127.0.0.1:${port}` });
+				const candidate = await this.connectTool({ wsEndpoint: `ws://127.0.0.1:${port}` });
+				try {
+					await candidate.checkVersion();
+				} catch (error) {
+					candidate.disconnect();
+					lastConnectError = error;
+					if (isExtensionContextInvalidatedError(error)) return false;
+					throw error;
+				}
+				miniProgram = candidate;
 				return true;
-			} catch {
+			} catch (error) {
+				lastConnectError = error;
 				return false;
 			}
 		}, timeout, 1e3);
 		if (!miniProgram) {
 			if (processError) throw new Error("Failed to launch wechat web devTools, please make sure cliPath is correctly specified");
+			if (lastConnectError) throw lastConnectError;
 			if (exited) throw new Error("Failed to launch wechat web devTools, please make sure http port is open");
 			throw new Error("Failed connecting to devtools websocket endpoint");
 		}
 		const resolvedMiniProgram = miniProgram;
-		await resolvedMiniProgram.checkVersion();
+		Reflect.set(resolvedMiniProgram, "__WEAPP_VITE_SESSION_METADATA", {
+			port,
+			projectPath,
+			wsEndpoint: `ws://127.0.0.1:${port}`
+		});
 		await sleep$1(5e3);
 		return resolvedMiniProgram;
 	}