Android

Playwright 对 Android 自动化提供实验性支持。这包括适用于 Android 的 Chrome 和 Android WebView。

要求

• Android 设备或 AVD 模拟器。
• ADB 守护进程正在运行并已通过您的设备进行身份验证。通常，您只需运行 adb devices 即可。
• 设备上安装了 Chrome 87 或更高版本
• 在 chrome://flags 中启用了“在非 root 设备上启用命令行”。

已知限制

• 尚不支持原始 USB 操作，因此您需要 ADB。
• 设备需要处于唤醒状态才能生成屏幕截图。启用“保持唤醒”开发者模式会有所帮助。
• 我们没有针对设备运行所有测试，因此并非所有功能都有效。

如何运行

Android 自动化脚本的示例如下

const { _android: android } = require('playwright');

(async () => {
  // Connect to the device.
  const [device] = await android.devices();
  console.log(`Model: ${device.model()}`);
  console.log(`Serial: ${device.serial()}`);
  // Take screenshot of the whole device.
  await device.screenshot({ path: 'device.png' });

  {
    // --------------------- WebView -----------------------

    // Launch an application with WebView.
    await device.shell('am force-stop org.chromium.webview_shell');
    await device.shell('am start org.chromium.webview_shell/.WebViewBrowserActivity');
    // Get the WebView.
    const webview = await device.webView({ pkg: 'org.chromium.webview_shell' });

    // Fill the input box.
    await device.fill({
      res: 'org.chromium.webview_shell:id/url_field',
    }, 'github.com/microsoft/playwright');
    await device.press({
      res: 'org.chromium.webview_shell:id/url_field',
    }, 'Enter');

    // Work with WebView's page as usual.
    const page = await webview.page();
    await page.waitForNavigation({ url: /.*microsoft\/playwright.*/ });
    console.log(await page.title());
  }

  {
    // --------------------- Browser -----------------------

    // Launch Chrome browser.
    await device.shell('am force-stop com.android.chrome');
    const context = await device.launchBrowser();

    // Use BrowserContext as usual.
    const page = await context.newPage();
    await page.goto('https://webkit.ac.cn/');
    console.log(await page.evaluate(() => window.location.href));
    await page.screenshot({ path: 'page.png' });

    await context.close();
  }

  // Close the device.
  await device.close();
})();

---

方法

连接

新增于: v1.28 android.connect

此方法将 Playwright 附加到现有 Android 设备。使用 android.launchServer() 启动新的 Android 服务器实例。

用法

await android.connect(wsEndpoint);
await android.connect(wsEndpoint, options);

参数

• wsEndpoint string#

  要连接到的浏览器 websocket 端点。

• options Object (可选)

  • headers Object<string, string> (可选)#

    要随 WebSocket 连接请求发送的额外 HTTP 头。可选。

  • slowMo number (可选)#

    将 Playwright 操作减慢指定的毫秒数。有助于您查看正在发生的事情。默认为 0。

  • timeout number (可选)#

    等待连接建立的最大时间（毫秒）。默认为 30000（30 秒）。传递 0 禁用超时。

返回

• Promise<AndroidDevice>#

---

设备

添加于：v1.9 android.devices

返回检测到的 Android 设备列表。

用法

await android.devices();
await android.devices(options);

参数

• options Object (可选)

  • host string (可选)新增于: v1.22#

    用于建立 ADB 服务器连接的可选主机。默认为 127.0.0.1。

  • omitDriverInstall boolean (可选)添加于：v1.21#

    阻止在附加时自动安装 playwright 驱动程序。假设驱动程序已安装。

  • port number (可选)新增于: v1.20#

    用于建立 ADB 服务器连接的可选端口。默认为 5037。

返回

• Promise<Array<AndroidDevice>>#

---

启动服务器

新增于: v1.28 android.launchServer

启动 Playwright Android 服务器，客户端可以连接到该服务器。请参见以下示例

用法

服务器端

const { _android } = require('playwright');

(async () => {
  const browserServer = await _android.launchServer({
    // If you have multiple devices connected and want to use a specific one.
    // deviceSerialNumber: '<deviceSerialNumber>',
  });
  const wsEndpoint = browserServer.wsEndpoint();
  console.log(wsEndpoint);
})();

客户端

const { _android } = require('playwright');

(async () => {
  const device = await _android.connect('<wsEndpoint>');

  console.log(device.model());
  console.log(device.serial());
  await device.shell('am force-stop com.android.chrome');
  const context = await device.launchBrowser();

  const page = await context.newPage();
  await page.goto('https://webkit.ac.cn/');
  console.log(await page.evaluate(() => window.location.href));
  await page.screenshot({ path: 'page-chrome-1.png' });

  await context.close();
})();

参数

• options Object (可选)

  • adbHost string (可选)#

    用于建立 ADB 服务器连接的可选主机。默认为 127.0.0.1。

  • adbPort number (可选)#

    用于建立 ADB 服务器连接的可选端口。默认为 5037。

  • deviceSerialNumber string (可选)#

    用于启动浏览器的可选设备序列号。如果未指定，则在连接多个设备时会抛出错误。

  • host string (可选)新增于: v1.45#

    用于 web socket 的主机。它是可选的，如果省略，当 IPv6 可用时，服务器将接受未指定 IPv6 地址 (::) 的连接，否则接受未指定 IPv4 地址 (0.0.0.0) 的连接。考虑通过选择特定接口来加强它。

  • omitDriverInstall boolean (可选)#

    阻止在附加时自动安装 playwright 驱动程序。假设驱动程序已安装。

  • port number (可选)#

    用于 web socket 的端口。默认为 0，表示选择任何可用端口。

  • wsPath string (可选)#

    提供 Android 服务器的路径。出于安全考虑，此路径默认为一个无法猜测的字符串。

    警告

    任何知道 wsPath 的进程或网页（包括在 Playwright 中运行的进程或网页）都可以控制操作系统用户。因此，使用此选项时应使用无法猜测的令牌。

返回

• Promise<BrowserServer>#

---

设置默认超时

添加于：v1.9 android.setDefaultTimeout

此设置将更改所有接受 timeout 选项的方法的默认最大时间。

用法

android.setDefaultTimeout(timeout);

参数

• timeout number#

  最大时间（毫秒）