@weapp-vite/miniprogram-automator 1.0.1 → 1.0.3

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

@@ -247,7 +247,6 @@ declare class MiniProgram extends EventEmitter {
 }
 //#endregion
 //#region src/Launcher.d.ts
-/** IConnectOptions 的类型定义。 */
 interface IConnectOptions {
   wsEndpoint: string;
 }
@@ -265,6 +264,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 +305,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-Didv0lMX.mjs")).launch({ projectPath: options.projectPath });
 }
 //#endregion
 //#region package.json
-var version = "1.0.1";
+var version = "1.0.3";
 //#endregion
 //#region src/Native.ts
 /** Native 的实现。 */
@@ -755,14 +769,34 @@ function extractPluginId(p) {
 }
 //#endregion
 //#region src/MiniProgram.ts
+const CLOSE_STEP_TIMEOUT = 2e3;
+const CURRENT_PAGE_RETRIES = 3;
+const CURRENT_PAGE_RETRY_DELAY = 400;
 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);
 	return startWith(trimmed, "function") || startWith(trimmed, "() =>");
 }
+function isCurrentPageProtocolTimeout(error) {
+	return error instanceof Error && "code" in error && error.code === "DEVTOOLS_PROTOCOL_TIMEOUT" && "method" in error && error.method === "App.getCurrentPage";
+}
 /** MiniProgram 的实现。 */
 var MiniProgram = class extends EventEmitter {
 	appBindings = /* @__PURE__ */ new Map();
@@ -801,12 +835,20 @@ var MiniProgram = class extends EventEmitter {
 		return await this.changeRoute("switchTab", url);
 	}
 	async currentPage() {
-		const { pageId, path, query } = await this.send("App.getCurrentPage");
-		return Page.create(this.connection, {
-			id: pageId,
-			path,
-			query
-		}, this.pageMap);
+		let lastError;
+		for (let attempt = 1; attempt <= CURRENT_PAGE_RETRIES; attempt += 1) try {
+			const { pageId, path, query } = await this.send("App.getCurrentPage");
+			return Page.create(this.connection, {
+				id: pageId,
+				path,
+				query
+			}, this.pageMap);
+		} catch (error) {
+			lastError = error;
+			if (!isCurrentPageProtocolTimeout(error) || attempt >= CURRENT_PAGE_RETRIES) throw error;
+			await sleep(CURRENT_PAGE_RETRY_DELAY);
+		}
+		throw lastError;
 	}
 	async systemInfo() {
 		return await this.callWxMethod("getSystemInfoSync");
@@ -878,11 +920,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 +1017,12 @@ 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;
+const WINDOWS_BATCH_CLI_RE = /\.(?:bat|cmd)$/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;
@@ -990,6 +1040,25 @@ function patchNetListenToLoopback() {
 		return rawListen.apply(this, args);
 	};
 }
+/** IConnectOptions 的类型定义。 */
+function shouldUseWindowsCommandShell(cliPath) {
+	return isWindows && WINDOWS_BATCH_CLI_RE.test(cliPath);
+}
+function escapeWindowsCmdArg(arg) {
+	const escaped = arg.replace(/"/g, "\"\"").replace(/%/g, "%%");
+	return /[\s"&<>^|()]/.test(arg) ? `"${escaped}"` : escaped;
+}
+function resolveWindowsBatchSpawn(cliPath, args) {
+	return {
+		file: process.env.ComSpec || "cmd.exe",
+		args: [
+			"/d",
+			"/s",
+			"/c",
+			`"${[cliPath, ...args].map(escapeWindowsCmdArg).join(" ")}"`
+		]
+	};
+}
 function resolveRuntimeProvider(options) {
 	return options.runtimeProvider || process.env[DEFAULT_RUNTIME_PROVIDER_ENV] || process.env[LEGACY_RUNTIME_PROVIDER_ENV] || "devtools";
 }
@@ -1009,7 +1078,8 @@ var Launcher = class {
 		if (!await import("node:fs/promises").then((fs) => fs.access(projectPath).then(() => true).catch(() => false))) throw new Error(`Project path ${projectPath} doesn't exist`);
 		if (!isEmpty(projectConfig)) await this.extendProjectConfig(projectConfig, projectPath);
 		let processError = null;
-		let exited = false;
+		let processExitCode = null;
+		let processSignal = null;
 		args = [
 			...args,
 			"auto",
@@ -1022,39 +1092,63 @@ var Launcher = class {
 		else if (ticket) args.push("--ticket", ticket);
 		if (trustProject) args.push("--trust-project");
 		try {
-			const child = spawn(cliPath, args, {
+			const spawnTarget = shouldUseWindowsCommandShell(cliPath) ? resolveWindowsBatchSpawn(cliPath, args) : {
+				file: cliPath,
+				args
+			};
+			const child = spawn(spawnTarget.file, spawnTarget.args, {
 				stdio: "ignore",
-				cwd: cwd || void 0
+				cwd: cwd || void 0,
+				...shouldUseWindowsCommandShell(cliPath) ? {
+					windowsHide: true,
+					windowsVerbatimArguments: true
+				} : {}
 			});
 			child.on("error", (error) => {
 				processError = error;
 			});
-			child.on("exit", () => {
-				setTimeout(() => {
-					exited = true;
-				}, 15e3);
+			child.on("exit", (code, signal) => {
+				processExitCode = code;
+				processSignal = signal;
+				if (code !== 0 || signal) processError = /* @__PURE__ */ new Error(`DevTools cli exited unexpectedly with code ${code ?? "null"}${signal ? ` and signal ${signal}` : ""}`);
 			});
 			child.unref();
 		} catch (error) {
 			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}` });
+				if (processError) return true;
+				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 (exited) throw new Error("Failed to launch wechat web devTools, please make sure http port is open");
+			if (lastConnectError) throw lastConnectError;
+			if (processExitCode !== null || processSignal) 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;
 	}