Android

Playwright 實驗性地 支援 Android 自動化。這包括 Android 版 Chrome 和 Android WebView。

需求條件

Android 裝置或 AVD 模擬器。
ADB daemon 執行中並已通過您的裝置驗證。通常執行 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.org/');
    console.log(await page.evaluate(() => window.location.href));
    await page.screenshot({ path: 'page.png' });

    await context.close();
  }

  // Close the device.
  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> (選填)#
  
  要與 web socket 連接請求一起傳送的其他 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({
    // 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.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#
  
  用於 web socket 的主機。它是選填的，如果省略，伺服器將接受未指定的 IPv6 位址 (::) (當 IPv6 可用時) 或未指定的 IPv4 位址 (0.0.0.0) (否則) 上的連線。考慮透過選取特定介面來強化它。
- omitDriverInstall boolean (選填)#
  
  防止在附加時自動安裝 playwright 驅動程式。假設驅動程式已安裝完成。
- port number (選填)#
  
  用於 web socket 的連接埠。預設值為 0，會選取任何可用的連接埠。
- wsPath string (選填)#
  
  用於提供 Android 伺服器的路徑。為了安全起見，預設值為無法猜測的字串。
  
  警告
  任何知道 wsPath 的程序或網頁 (包括在 Playwright 中執行的程序或網頁) 都可以控制 OS 使用者。因此，當您使用此選項時，應使用無法猜測的權杖。

傳回

Promise<BrowserServer>#

setDefaultTimeout

新增於：v1.9

android.setDefaultTimeout

此設定將變更所有接受 timeout 選項的方法的預設最長時程。

用法

android.setDefaultTimeout(timeout);

參數

timeout number #

最長時程 (以毫秒為單位)

方法​

connect​

devices​

launchServer​

setDefaultTimeout​

方法

connect

devices

launchServer

setDefaultTimeout