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:
- 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:
| Name | Type | Description | Example |
|---|---|---|---|
| name | string | The name of the CDP socket. Usually starts with @
|
@chrome_devtools_remote |
| pages | map[] | The list of pages in this webview. The output of /json/list endpoint | [ {"description": "", "devtoolsFrontendUrl": "/devtools/inspector.html?ws=localhost:9222/devtools/page/DAB7FB6187B554E10B0BD18821265734", "id": "DAB7FB6187B554E10B0BD18821265734", "title": "Yahoo", "type": "page", "url": "https://www.yahoo.com/", "webSocketDebuggerUrl": "ws://localhost:9222/devtools/page/DAB7FB6187B554E10B0BD18821265734"} ] |
| info | map | The basic information about the current webview. This is the output of /json/version endpoint | {"Browser": "Chrome/72.0.3601.0", "Protocol-Version": "1.3", "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3601.0 Safari/537.36", "V8-Version": "7.2.233", "WebKit-Version": "537.36 (@cfede9db1d154de0468cb0538479f34c0755a0f4)", "webSocketDebuggerUrl": "ws://localhost:9222/devtools/browser/b0b8a4fb-bb17-4359-9533-a8d9f3908bd8"} |
| isProxied | boolean | Whether the current webview is being proxied | false |
| proxyInfo | map | The proxy information if the webview is being proxied, which consists of the following entries: alias, name, root, uuid. It is always null if isProxied is false. |
{"alias":"1ca57bc449240dfeb716e8a5adb95849bcfdd49f","name":"@chrome_devtools_remote","uuid": "ed3c4d2f-7b34-4563-9a3c-e6af20418500", "root":"http://127.0.0.1:4723/cdp/ed3c4d2f-7b34-4563-9a3c-e6af20418500/1ca57bc449240dfeb716e8a5adb95849bcfdd49f"} |
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
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| name | string | yes | The name of the webview socket to proxy. Usually starts with @. Could be retrieved from devtools: listTargets output |
@chrome_devtools_remote |
| port | number | no | The port number on the Appium server machine to be used for the proxy. The port must not be in use. If not provided then a random free port from the [15900, 16000] range will be selected. | 12345 |
Returned Result
If the corresponding CDP API has been forwarded successfully then the following map is returned
| Name | Type | Description | Example |
|---|---|---|---|
| name | string | The name of the webview being forwarded | @chrome_devtools_remote |
| alias | string | Unique alias for the given webview name. It is used to construct the forward URL | 1ca57bc449240dfeb716e8a5adb95849bcfdd49f |
| uuid | string | The unique identifier of the current plugin instance. It is used to construct the forward URL | ed3c4d2f-7b34-4563-9a3c-e6af20418500 |
| root | string | The forwarding root URL used as a base for all CDP endpoints | http://127.0.0.1:4723/cdp/ed3c4d2f-7b34-4563-9a3c-e6af20418500/1ca57bc449240dfeb716e8a5adb95849bcfdd49f |
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
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| name | string | yes | The name of the webview socket to stop the proxy for. Usually starts with @. Could be retrieved from devtools: listTargets output |
@chrome_devtools_remote |
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)
);
}
}