@skrillex1224/playwright-toolkit 2.1.165 → 2.1.166

package/dist/index.cjs

@@ -2803,6 +2803,196 @@ var Mutation = {
     logger11.success("waitForStable", `DOM \u7A33\u5B9A, \u603B\u5171 ${result.mutationCount} \u6B21\u53D8\u5316${result.wasPaused ? ", \u66FE\u6682\u505C\u8BA1\u65F6" : ""}`);
     return result;
   },
+  /**
+   * 等待跨 root DOM 元素稳定（主文档 + iframe 内容）
+   * 通过轮询快照检测变化，适配 iframe / shadow 场景
+   *
+   * @param {import('playwright').Page} page - Playwright page 对象
+   * @param {string | string[]} selectors - 要监控的 CSS 选择器，单个或多个（建议传 iframe 选择器）
+   * @param {Object} [options] - 配置选项（签名与 waitForStable 保持一致）
+   * @param {number} [options.initialTimeout] - 等待元素出现的超时 (毫秒, 默认: 60000)
+   * @param {number} [options.stableTime] - 无变化持续时间后 resolve (毫秒, 默认: 10000)
+   * @param {number} [options.timeout] - 整体超时时间 (毫秒, 默认: 180000)
+   * @param {Function} [options.onMutation] - 变化时的回调钩子
+   * @returns {Promise<{ mutationCount: number, stableTime: number, wasPaused: boolean }>}
+   */
+  async waitForStableAcrossRoots(page, selectors, options = {}) {
+    const selectorList = Array.isArray(selectors) ? selectors : [selectors];
+    const selectorQuery = selectorList.join(",");
+    const initialTimeout = options.initialTimeout ?? 60 * 1e3;
+    const waitForStableTime = options.stableTime ?? 10 * 1e3;
+    const overallTimeout = options.timeout ?? 180 * 1e3;
+    const onMutation = options.onMutation;
+    const pollInterval = 500;
+    const sleep = (ms) => new Promise((resolve) => {
+      setTimeout(resolve, ms);
+    });
+    const truncate = (value, max = 800) => {
+      const text = String(value || "");
+      if (text.length <= max) return text;
+      return `${text.slice(0, max)}...`;
+    };
+    const buildState = async () => {
+      return await page.evaluate(({ selectorList: selectorList2 }) => {
+        const normalizeText = (value) => String(value || "").replace(/\s+/g, " ").trim();
+        const tail = (value, max = 512) => {
+          const text = String(value || "");
+          if (text.length <= max) return text;
+          return text.slice(text.length - max);
+        };
+        const safeFrameId = (frameEl) => {
+          const id = String(frameEl?.id || "").trim();
+          if (id) return id;
+          const name = String(frameEl?.name || "").trim();
+          if (name) return name;
+          return "no-id";
+        };
+        const items = [];
+        selectorList2.forEach((selector) => {
+          let nodes = [];
+          try {
+            nodes = Array.from(document.querySelectorAll(selector));
+          } catch {
+            return;
+          }
+          nodes.forEach((node, index) => {
+            const isIframe = node?.tagName === "IFRAME";
+            let text = "";
+            let html = "";
+            let source = "main";
+            let path = `${selector}[${index}]`;
+            if (isIframe) {
+              source = "iframe";
+              path = `${selector}[${index}]::iframe(${safeFrameId(node)})`;
+              try {
+                const frameDoc = node.contentDocument;
+                const frameRoot = frameDoc?.body || frameDoc?.documentElement;
+                if (frameRoot) {
+                  text = normalizeText(frameRoot.innerText || frameRoot.textContent || "");
+                  html = normalizeText(frameRoot.innerHTML || "");
+                }
+              } catch {
+              }
+            } else {
+              text = normalizeText(node?.innerText || node?.textContent || "");
+              html = normalizeText(node?.innerHTML || node?.outerHTML || "");
+            }
+            const snapshot = text || html;
+            items.push({
+              selector,
+              source,
+              path,
+              text,
+              html,
+              snapshot
+            });
+          });
+        });
+        const snapshotKey = items.map((item) => `${item.path}:${item.snapshot.length}:${tail(item.snapshot, 512)}`).join("||");
+        const summaryText = items.map((item) => item.snapshot || item.text).join("\n").trim();
+        const summaryHtml = items.map((item) => item.html).join("\n");
+        const hasMatched = items.length > 0;
+        const primary = items.length > 0 ? items[items.length - 1] : null;
+        return {
+          hasMatched,
+          snapshotKey,
+          text: summaryText,
+          html: summaryHtml,
+          snapshotLength: summaryText.length,
+          itemCount: items.length,
+          primaryPath: primary?.path || "",
+          mutationNodes: items.map((item) => ({
+            html: item.html,
+            text: item.snapshot || item.text,
+            mutationType: item.source
+          }))
+        };
+      }, { selectorList });
+    };
+    const invokeMutationCallback = async (context) => {
+      if (!onMutation) return "__CONTINUE__";
+      try {
+        const result = await onMutation(context);
+        return result === null || result === void 0 ? "__CONTINUE__" : "__PAUSE__";
+      } catch {
+        return "__CONTINUE__";
+      }
+    };
+    logger11.start(
+      "waitForStableAcrossRoots",
+      `\u76D1\u63A7 ${selectorList.length} \u4E2A\u9009\u62E9\u5668(\u8DE8 root), \u7A33\u5B9A\u65F6\u95F4=${waitForStableTime}ms`
+    );
+    if (initialTimeout > 0) {
+      try {
+        await page.waitForSelector(selectorQuery, { timeout: initialTimeout });
+        logger11.info(`waitForStableAcrossRoots \u5DF2\u68C0\u6D4B\u5230\u5143\u7D20: ${selectorQuery}`);
+      } catch (e) {
+        logger11.warning(`waitForStableAcrossRoots \u521D\u59CB\u7B49\u5F85\u8D85\u65F6 (${initialTimeout}ms): ${selectorQuery}`);
+        throw e;
+      }
+    }
+    let state = await buildState();
+    if (!state?.hasMatched) {
+      logger11.warning("waitForStableAcrossRoots \u672A\u627E\u5230\u53EF\u76D1\u63A7\u7684\u5143\u7D20");
+      return { mutationCount: 0, stableTime: 0, wasPaused: false };
+    }
+    let mutationCount = 0;
+    let stableSince = 0;
+    let isPaused = false;
+    let wasPaused = false;
+    let lastSnapshotKey = state.snapshotKey;
+    const applyPauseSignal = (signal) => {
+      const nextPaused = signal === "__PAUSE__";
+      if (nextPaused) {
+        if (!isPaused) wasPaused = true;
+        isPaused = true;
+        stableSince = 0;
+        return;
+      }
+      isPaused = false;
+      stableSince = Date.now();
+    };
+    const initialSignal = await invokeMutationCallback({
+      mutationCount: 0,
+      html: state.html || "",
+      text: state.text || "",
+      mutationNodes: state.mutationNodes || []
+    });
+    applyPauseSignal(initialSignal);
+    const deadline = Date.now() + overallTimeout;
+    let lastState = state;
+    while (Date.now() < deadline) {
+      await sleep(pollInterval);
+      lastState = await buildState();
+      if (!lastState?.hasMatched) {
+        continue;
+      }
+      if (lastState.snapshotKey !== lastSnapshotKey) {
+        lastSnapshotKey = lastState.snapshotKey;
+        mutationCount += 1;
+        logger11.info(
+          `waitForStableAcrossRoots \u53D8\u5316#${mutationCount}, len=${lastState.snapshotLength}, path=${lastState.primaryPath || "unknown"}, preview="${truncate(lastState.text, 120)}"`
+        );
+        const signal = await invokeMutationCallback({
+          mutationCount,
+          html: lastState.html || "",
+          text: lastState.text || "",
+          mutationNodes: lastState.mutationNodes || []
+        });
+        applyPauseSignal(signal);
+        continue;
+      }
+      if (!isPaused && stableSince > 0 && Date.now() - stableSince >= waitForStableTime) {
+        logger11.success("waitForStableAcrossRoots", `DOM \u7A33\u5B9A, \u603B\u5171 ${mutationCount} \u6B21\u53D8\u5316${wasPaused ? ", \u66FE\u6682\u505C\u8BA1\u65F6" : ""}`);
+        return {
+          mutationCount,
+          stableTime: waitForStableTime,
+          wasPaused
+        };
+      }
+    }
+    throw new Error(`waitForStableAcrossRoots \u8D85\u65F6 (${overallTimeout}ms), \u5DF2\u68C0\u6D4B\u5230 ${mutationCount} \u6B21\u53D8\u5316, isPaused=${isPaused}`);
+  },
   /**
    * 创建一个持续监控 DOM 变化的监控器（默认仅监听新增 DOM）
    *