appium-devtools-plugin v0.1.1

Appium Devtools Plugin

This plugin is created to expose Chrome Devtools Protocol API from a mobile Android browser or a webview to the running Appium server. Afterwards this API could be used to establish a connection to it from an external client and to perform an extended automation, like performance metrics gathering or geolocation emulation.

Features

• Adds the following execute methods:
  • devtools: listTargets
  • devtools: proxyTarget
  • devtools: unproxyTarget
• Adds the following server HTTP endpoints:
  • GET /cdp/:uuid/:alias/json/version
  • GET /cdp/:uuid/:alias/json/list
  • GET /cdp/:uuid/:alias/json/
  • GET /cdp/:uuid/:alias/json/protocol
  • PUT /cdp/:uuid/:alias/json/new
  • GET /cdp/:uuid/:alias/json/activate/:targetId
  • GET /cdp/:uuid/:alias/json/close/:targetId
  • GET /cdp/:uuid/:alias/devtools/inspector.html
• Adds the following Websocket endpoints
  • /cdp/:uuid/:alias/devtools/browser
  • /cdp/:uuid/:alias/devtools/browser/:browserId
  • /cdp/:uuid/:alias/devtools/page/:pageId

Prerequisites

• Appium Server 2.0+
• UIAutomator2 or Espresso driver

Installation - Server

Install the plugin using Appium's plugin CLI:

appium plugin install --source git https://github.com/mykola-mokhnach/appium-devtools-plugin

Installation - Client

On the client side this plugin requires a proper the Chrome Devtools Protocol client implementation. For example, it should be included into the Selenium Java library.

Activation

The plugin will not be active unless turned on when invoking the Appium server:

appium --use-plugins=devtools

Execute Methods

devtools: listTargets

Scans if there are any active CDP sockets in the system and exposes the list of such sockets with their properties. Also, the API exposes which sockets are currently being proxied and which are not.

Returned Result

An object with a single targets property. This is a list of entries, where each has the following properties:

devtools: proxyTarget

Starts the proxy for the given CDP target name. An exception is thrown if the target is already being proxied or does not exist.

Arguments

Returned Result

If the corresponding CDP API has been forwarded successfully then the following map is returned

devtools: unproxyTarget

Stops the proxy for the given CDP target name. An exception is thrown if the target is not being proxied or does not exist.

Arguments

Usage

private AndroidDriver driver;
private static final Pattern BROWSER_MAJOR_VER_PATTERN = Pattern.compile("/(\\d+)");

@BeforeEach
void setup() {
  // Espresso driver is supported as well
  UiAutomator2Options options = new UiAutomator2Options();
  driver = new AndroidDriver(options);
}

@AfterEach
void teardown(){
  driver.quit();
}

private DevTools initDevTools(URI uri, String browserMajorVersion) {
  HttpClient.Factory factory = HttpClient.Factory.createDefault();
  HttpClient client = CdpEndpointFinder.getHttpClient(factory, uri);
  URI cdpUri = CdpEndpointFinder.getCdpEndPoint(client);
  Connection connection = new Connection(client, cdpUri.toString());
  CdpInfo cdpInfo = new CdpVersionFinder()
    .match(browserMajorVersion)
    .orElseThrow(
      () -> new RuntimeException(
        String.format(
          "Unable to find version of CDP to use for %s. You may need to include a"
              + " dependency on a specific version of the CDP using something"
              + " similar to `org.seleniumhq.selenium:selenium-devtools-v86:%s`"
              + " where the version (\"v86\") matches the version of the"
              + " chromium-based browser you're using and the version number of the"
              + " artifact is the same as Selenium's.",
          browserMajorVersion, new BuildInfo().getReleaseLabel()
        )
      );
    );
  return new DevTools(cdpInfo::getDomains, connection);
}

private String extractMajorBrowserVersion(String version) {
  Matcher matcher = BROWSER_MAJOR_VER_PATTERN.matcher(version);
  if (!matcher.find()) {
    throw new RuntimeException(String.format(
      "No major browser version could be parsed from '%s'", version
    ));
  }
  return matcher.group(1);
}

@Test
void verifyMobileCdp() {
  // ....
  // manipulate the App under test or the browser, so a web view is active
  // ....
  Map<String, Object> wvInfo = (Map<String, Object>) driver.executeScript("devtools: listTargets");
  List<Map<String, Object>> targets = (List<Map<String, Object>>) wvInfo.get("targets");
  // There might be multiple targets or none
  // depending on which web views are currently active and debuggable.
  // We just want to interact with the very first one in this example
  Map<String, Object> target = (Map<String, Object>) targets.get(0);
  String wvName = (String) target.get("name");
  Map<String, Object> proxyInfo = (Map<String, Object>) driver.executeScript(
    "devtools: proxyTarget",
    Map.of("name", wvName)
  );

  // Ususally, it looks like "Chrome/91.0.4472.114"
  String browserVersion = (String) target.get("Browser");
  try {
    DevTools devtools = initDevtools(
      Uri.parse((String) proxyInfo.get("root")),
      extractMajorBrowserVersion(browserVersion)
    );

    devTools.createSession();
    devTools.send(Network.clearBrowserCookies());
    devTools.send(Network.setCacheDisabled(true));
    // ...
    // Continue doing crazy stuff with the devtools object
    // ...
  } finally {
    // This will be done anyway automatically upon quitting the driver
    driver.executeScript(
      "devtools: unproxyTarget",
      Map.of("name", wvName)
    );
  }
}