Playwright Mobile App Testing for Android: A Comprehensive Guide

What is @playwright/test and Its Android Support?

@playwright/test is a go-to test runner for end-to-end testing, designed specifically for modern web applications. It provides a powerful API that allows you to write and run tests across different browsers and devices. With its experimental support for Android automation, you can now test Chrome for Android and Android WebView, which makes it an invaluable tool for mobile web app testing.

Please note: As of now, Playwright is primarily a testing framework for web applications. While you can automate WebView on Android, this is web-specific and there are currently no plans to add native mobile app testing. Check out this issue on Github for more information.

Getting Started with Android Testing

To start using @playwright/test for Android, make sure you have:

1. An Android device or AVD Emulator.
2. ADB daemon running and authenticated with your device. Just run adb devices.
3. Chrome 87 or newer installed on the device.
4. "Enable command line on non-rooted devices" enabled in chrome://flags.

Be Aware of the Limitations

The Android support in Playwright is experimental and hence, comes with a few limitations:

• Raw USB operation is not yet supported, so you'll need ADB.
• The device needs to be awake to produce screenshots. Turning on "Stay awake" in developer mode can help.
• Not all tests have been run against the device, so not everything may work as expected.

Also, Playwright currently doesn't support touch gestures such as swipe or pinch to zoom in/out. However, there have been some workaround attempts on Github that you might find helpful.

Your First Android Automation Script with @playwright/test

Here's a TypeScript example of an Android automation script using @playwright/test:

import { android } from '@playwright/test';

(async () => {
  const [device] = await android.devices();
  console.log(`Model: ${device.model()}`);
  console.log(`Serial: ${device.serial()}`);

  await device.screenshot({ path: 'device.png' });

  // WebView automation
  await device.shell('am force-stop org.chromium.webview_shell');
  await device.shell('am start org.chromium.webview_shell/.WebViewBrowserActivity');
  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');

  const page = await webview.page();
  await page.waitForNavigation({ url: /.*microsoft\/playwright.*/ });
  console.log(await page.title());

  // Chrome automation
  await device.shell('am force-stop com.android.chrome');
  const context = await device.launchBrowser();
  const pageChrome = await context.newPage();
  await pageChrome.goto('https://webkit.org/');
  console.log(await pageChrome.evaluate(() => window.location.href));
  await pageChrome.screenshot({ path: 'page.png' });

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

When testing Android, you don't need Playwright to install web browsers. So, you can skip browser download by setting the PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 environment variable during Playwright installation.

Connecting to an Existing Android Device

Playwright also allows you to attach to an existing Android device with android.connect(). Use android.launchServer() to launch a new Android server instance.

Here's a server side and client side example:

Server Side Example

import { _android } from '@playwright/test';

(async () => {
  const browserServer = await _android.launchServer();
  const wsEndpoint = browserServer.wsEndpoint();
  console.log(wsEndpoint);
})();

Client Side Example

import { _android } from '@playwright/test';

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

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

  const page = await context.newPage();
  await page.goto('https://ray.run/');
  console.log(await page.evaluate(() => window.location.href));

  await page.screenshot({ path: 'page-chrome-1.png' });
  await context.close();
})();

Customizing the Default Timeout

You can adjust the default maximum time for all methods accepting a timeout option using android.setDefaultTimeout(). This can be quite handy in controlling the overall execution time of your test suite.

android.setDefaultTimeout(timeout);

Emulating Real Devices with Playwright

Aside from Android automation, Playwright also offers more stable emulation. You can emulate real devices like mobile phones or tablets. Just configure the devices you want to emulate, and Playwright will simulate the browser behavior, such as "userAgent", "screenSize", "viewport", and if it "hasTouch" enabled. You can also emulate "geolocation", "locale", "timezone" for all tests or a specific test as well as set the "permissions" to show notifications or change the "colorScheme". This is usually close enough to replicate a real mobile device. Learn more about emulation on the official Playwright documentation.

Wrapping Up

In conclusion, @playwright/test presents a powerful and flexible solution for Android web app testing. With its experimental support for Android automation, it's an invaluable tool for improving the quality of your mobile web apps. Its potential is immense, and as the Android automation support continues to improve, we can expect even more capabilities and ease of use from @playwright/test.