Android

Playwright 对 Android 自动化提供了实验性支持。这包括 Android 版 Chrome 和 Android WebView。

要求

Android 设备或 AVD 模拟器
运行 ADB 守护进程并与设备完成认证。通常只需运行 adb devices 即可
设备上安装 Chrome 87 或更新版本
在 chrome://flags 中启用 "Enable command line on non-rooted devices" 选项

已知限制

尚未支持原始 USB 操作，因此需要使用 ADB
设备需要保持唤醒状态才能截图。启用开发者模式中的 "Stay awake" 选项会有帮助
我们尚未在设备上运行所有测试，因此并非所有功能都可用

运行方法

以下是 Android 自动化脚本的示例：

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

(async () => {
  // 连接设备
  const [device] = await android.devices();
  console.log(`设备型号: ${device.model()}`);
  console.log(`序列号: ${device.serial()}`);
  // 截取整个设备的屏幕截图
  await device.screenshot({ path: 'device.png' });

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

    // 启动带有 WebView 的应用程序
    await device.shell('am force-stop org.chromium.webview_shell');
    await device.shell('am start org.chromium.webview_shell/.WebViewBrowserActivity');
    // 获取 WebView
    const webview = await device.webView({ pkg: 'org.chromium.webview_shell' });

    // 填写输入框
    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');

    // 像平常一样操作 WebView 的页面
    const page = await webview.page();
    await page.waitForNavigation({ url: /.*microsoft\/playwright.*/ });
    console.log(await page.title());
  }

  {
    // --------------------- 浏览器 -----------------------

    // 启动 Chrome 浏览器
    await device.shell('am force-stop com.android.chrome');
    const context = await device.launchBrowser();

    // 像平常一样使用 BrowserContext
    const page = await context.newPage();
    await page.goto('https://webkit.org/');
    console.log(await page.evaluate(() => window.location.href));
    await page.screenshot({ path: 'page.png' });

    await context.close();
  }

  // 关闭设备连接
  await device.close();
})();

方法

connect

添加于: 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>#

devices

添加于: 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>>#

launchServer

添加于: v1.28

android.launchServer

启动可供客户端连接的 Playwright Android 服务器。参考以下示例：

使用方法

服务端：

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

(async () => {
  const browserServer = await _android.launchServer({
    // 如果连接了多个设备并希望使用特定设备
    // 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.org/');
  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#
  
  用于 WebSocket 的主机地址。可选参数，如果省略，服务器将在 IPv6 可用时接受未指定的 IPv6 地址(::)连接，否则接受未指定的 IPv4 地址(0.0.0.0)连接。建议通过选择特定接口来加强安全性。
- omitDriverInstall boolean (可选)#
  
  防止在连接时自动安装 playwright 驱动。假设驱动已安装。
- port number (可选)#
  
  用于 WebSocket 的端口。默认为 0 表示自动选择可用端口。
- wsPath string (可选)#
  
  用于提供 Android 服务器服务的路径。出于安全考虑，默认使用不可猜测的字符串。
  
  注意
  任何知道 wsPath 的进程或网页（包括在 Playwright 中运行的）都可以控制操作系统用户。因此，使用此选项时应使用不可猜测的令牌。

返回值

Promise<BrowserServer>#

setDefaultTimeout

Added in: v1.9

android.setDefaultTimeout

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

用法

android.setDefaultTimeout(timeout);

参数

timeout number #

最大超时时间（毫秒）

方法​

connect​

devices​

launchServer​

setDefaultTimeout​

方法

connect

devices

launchServer

setDefaultTimeout