playwright里兼容处理回放无界微前端内iframe内部元素事件和不在无界微前端内的iframe元素

背景

在Playwright中处理无界微前端（Wujie）内的iframe以及不在无界微前端内的iframe，需要分别考虑两种情况：

1. 无界微前端内的iframe：由于无界微前端可能采用shadow DOM或者特殊的iframe封装，我们需要通过无界提供的API或者特殊的选择器来定位内部的iframe。

2. 普通的iframe：即不在无界微前端内的iframe，可以直接使用Playwright的标准方法处理。

无界微前端在处理iframe时，可能会将子应用的iframe包裹在shadow DOM中，因此我们需要穿透shadow DOM来获取内部的iframe。

在Playwright中，我们可以使用以下方法来处理shadow DOM内的元素：

• 使用elementHandle.evaluateHandle来在元素内部执行选择器，穿透shadow DOM。

• 使用Playwright的>> 进行穿透（注意：这些选择器在Playwright中并不直接支持，但可以通过JavaScript表达式实现穿透）。

然而，对于无界微前端，根据其文档，它提供了一些属性和方法来访问子应用的window和document。但如果我们只是要操作iframe内部的元素，我们可以先获取到iframe元素，然后使用Playwright的frame相关方法。

解决方案

解决方案思路

1. 识别无界微前端环境：通过 CSS 选择器定位 Wujie 的 shadow host
2. 穿透 Shadow DOM ：使用 .elementHandle() 和 JavaScript 穿透 shadowRoot
3. 统一操作接口：封装通用方法处理两种 iframe
4. 等待机制：确保 iframe 和元素加载完成

import { Page, Frame, ElementHandle, Locator } from 'playwright';

/**
 * 获取无界微前端内的 iframe 或普通 iframe
 * @param page - Playwright 页面对象
 * @param wujieSelector - 无界容器选择器（默认：'wujie-app'）
 * @param iframeSelector - iframe 选择器
 * @param timeout - 超时时间（默认：30秒）
 */
async function getWujieFrame(
  page: Page,
  iframeSelector: string,
  wujieSelector: string = 'wujie-app',
  timeout: number = 30000
): Promise<Frame> {
  // 尝试直接获取普通 iframe
  const standardIframe = page.frameLocator(iframeSelector);
  if (await standardIframe.locator('body').isVisible({ timeout: 2000 }).catch(() => false)) {
    return standardIframe;
  }

  // 处理无界微前端内的 iframe
  const wujieApp = await page.waitForSelector(wujieSelector, { timeout });
  
  // 穿透 Shadow DOM 获取内部 iframe
  const wujieIframe = (await wujieApp.evaluateHandle((el: Element) => {
    const shadowRoot = el.shadowRoot;
    return shadowRoot?.querySelector('iframe');
  })) as ElementHandle<HTMLIFrameElement>;

  if (!wujieIframe) throw new Error('Wujie iframe not found in shadow DOM');
  
  // 等待 iframe 加载完成
  await wujieIframe.waitForElementState('stable', { timeout });
  
  // 返回 iframe 的 Frame 对象
  return wujieIframe.contentFrame() as Promise<Frame>;
}

/**
 * 在 iframe 内执行操作（兼容无界微前端）
 * @param page - Playwright 页面对象
 * @param iframeSelector - iframe 选择器
 * @param action - 需要在 iframe 内执行的回调函数
 * @param options - 配置选项
 */
export async function withinWujieFrame<T>(
  page: Page,
  iframeSelector: string,
  action: (frame: Frame) => Promise<T>,
  options: {
    wujieSelector?: string;
    timeout?: number;
    waitForElement?: string; // 可选：等待 iframe 内元素加载
  } = {}
): Promise<T> {
  const { wujieSelector = 'wujie-app', timeout = 30000, waitForElement } = options;
  
  const frame = await getWujieFrame(page, iframeSelector, wujieSelector, timeout);

  // 等待目标元素（如果指定）
  if (waitForElement) {
    await frame.waitForSelector(waitForElement, { timeout });
  }

  // 在 iframe 上下文中执行操作
  return action(frame);
}

使用示例

// 示例 1：点击无界微前端内的按钮
await withinWujieFrame(
  page,
  'iframe#micro-app', 
  async (frame) => {
    await frame.click('#submit-button');
  },
  {
    wujieSelector: 'wujie-app', // 可选，默认为 'wujie-app'
    waitForElement: '#submit-button' // 等待按钮出现
  }
);

// 示例 2：在普通 iframe 内输入文本
await withinWujieFrame(
  page,
  'iframe.standard-iframe',
  async (frame) => {
    await frame.fill('#username', 'testuser');
    await frame.fill('#password', 'securepass');
    await frame.click('#login-btn');
  }
);

// 示例 3：获取 iframe 内部文本（兼容两种环境）
const getHeaderText = async () => {
  return withinWujieFrame(
    page,
    'iframe.content-frame',
    async (frame) => {
      return frame.textContent('h1.title');
    }
  );
};

console.log(await getHeaderText());

关键点说明

1. 自动环境检测：

   • 优先尝试定位普通 iframe
   • 失败后自动穿透无界的 shadow DOM
   • 超时机制防止永久等待

2. Shadow DOM 穿透：

el.evaluateHandle((el) => el.shadowRoot?.querySelector('iframe'))

使用 evaluateHandle 直接访问 shadow DOM 内的元素

3. 智能等待策略：

   • 等待 iframe 进入 stable 状态
   • 可选等待内部特定元素加载
   • 双重超时控制（全局+元素级）

4. 统一接口：

   • 相同的 API 处理两种环境
   • 回调函数提供 Frame 上下文
   • 支持所有 Frame 操作方法（click/fill 等）

5. 错误处理：

   • 明确的错误消息定位问题
   • 超时自动抛出异常
   • 兼容 Playwright 的等待机制

常见问题处理

场景 1：动态加载的微前端

// 先等待容器出现
await page.waitForSelector('wujie-app', { state: 'attached' });

// 再等待 1 秒确保内容加载（根据实际网络调整）
await page.waitForTimeout(1000);

// 然后执行操作
await withinWujieFrame(/* ... */);

场景 2：多级嵌套 iframe

await withinWujieFrame(page, 'iframe#outer', async (outerFrame) => {
  // 在内部 iframe 中继续操作
  await withinWujieFrame(
    page, 
    'iframe#inner', 
    async (innerFrame) => {
      await innerFrame.click('#deep-button');
    },
    { wujieSelector: 'body' } // 内部 iframe 可能不在 shadow DOM
  );
});

场景 3：跨域 iframe 处理

// 启动浏览器时添加跨域支持
const browser = await chromium.launch({
  args: ['--disable-web-security'] // 仅测试环境使用
});

// 在回调中使用 try-catch 处理安全错误
await withinWujieFrame(page, 'iframe.cross-origin', async (frame) => {
  try {
    await frame.click('button');
  } catch (e) {
    console.warn('跨域操作受限，尝试替代方案');
    // 使用 JavaScript 注入方式操作
    await frame.evaluate(() => {
      document.querySelector('button')?.click();
    });
  }
});

此方案通过统一接口封装了无界微前端和普通 iframe 的操作差异，实现了：

• 自动环境检测
• Shadow DOM 穿透
• 健壮的等待机制
• 错误隔离处理
• 跨域场景降级方案

可根据实际项目需求调整选择器参数和超时时间，建议配合 Playwright 的测试报告功能监控 iframe 操作，在一定场景下能提高成功率。