Android

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

🌐 Playwright has experimental support for Android automation. This includes Chrome for Android and Android WebView.

要求

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

已知限制

尚不支持原始 USB 操作，因此你需要 ADB。
设备需要处于唤醒状态才能生成截图。启用“保持唤醒”开发者模式将有所帮助。
我们没有针对该设备运行所有测试，因此并非一切正常。

如何运行

Android 自动化脚本的示例如下：

🌐 An example of the Android automation script would be:

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.org/');
    console.log(await page.evaluate(() => window.location.href));
    await page.screenshot({ path: 'page.png' });

    await context.close();
  }

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

方法

🌐 Methods

connect

Added in: v1.28

android.connect

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

🌐 This methods attaches Playwright to an existing Android device. Use android.launchServer() to launch a new Android server instance.

用法

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

参数

wsEndpoint string #

要连接的浏览器 Websocket 端点。
options Object (optional)
- headers Object<string, string> (optional)#
  
  随 WebSocket 连接请求一起发送的其他 HTTP 头。可选。
- slowMo number (optional)#
  
  将 Playwright 操作延迟指定的毫秒数。这很有用，可以让你看到操作的过程。默认值为 0。
- timeout number (optional)#
  
  等待连接建立的最长时间（毫秒）。默认值为 30000（30 秒）。传入 0 可禁用超时。

Promise<AndroidDevice>#

devices

Added in: v1.9

android.devices

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

🌐 Returns the list of detected Android devices.

用法

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

参数

options Object (optional)
- host string (optional) Added in: v1.22#
  
  可选择的主机，用于建立 ADB 服务器连接。默认为 127.0.0.1。
- omitDriverInstall boolean (optional) Added in: v1.21#
  
  防止在附加时自动安装 Playwright 驱动。假设驱动已经安装好了。
- port number (optional) Added in: v1.20#
  
  可选择的端口，用于建立 ADB 服务器连接。默认为 5037。

Promise<Array<AndroidDevice>>#

launchServer

Added in: v1.28

android.launchServer

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

🌐 Launches Playwright Android server that clients can connect to. See the following example:

用法

服务器端：

🌐 Server Side:

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);
})();

客户端：

🌐 Client Side:

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 (optional)
- adbHost string (optional)#
  
  可选择的主机，用于建立 ADB 服务器连接。默认为 127.0.0.1。
- adbPort number (optional)#
  
  可选择的端口，用于建立 ADB 服务器连接。默认为 5037。
- deviceSerialNumber string (optional)#
  
  可选的设备序列号，用于启动浏览器。如果未指定，当连接多个设备时将会报错。
- host string (optional) Added in: v1.45#
  
  用于 Web Socket 的主机。此项可选，如果省略，服务器将在 IPv6 可用时接受未指定的 IPv6 地址 (::) 上的连接，否则接受未指定的 IPv4 地址 (0.0.0.0) 上的连接。可以通过选择特定的接口来增强安全性。
- omitDriverInstall boolean (optional)#
  
  防止在附加时自动安装 Playwright 驱动。假设驱动已经安装好了。
- port number (optional)#
  
  用于 WebSocket 的端口。默认值为 0，表示选择任意可用端口。
- wsPath string (optional)#
  
  用于提供 Android 服务器的路径。出于安全考虑，默认为一个难以猜测的字符串。
  
  warning
  任何进程或网页（包括在 Playwright 中运行的网页）只要知道 wsPath，都可以获取操作系统用户的控制权。因此，在使用此选项时，你应使用一个难以猜测的令牌。

Promise<BrowserServer>#

setDefaultTimeout

Added in: v1.9

android.setDefaultTimeout

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

🌐 This setting will change the default maximum time for all the methods accepting timeout option.

用法

android.setDefaultTimeout(timeout);

参数

timeout number #

最长时间（以毫秒为单位）

方法​

connect​

devices​

launchServer​

setDefaultTimeout​

方法

connect

devices

launchServer

setDefaultTimeout